On 8/29/19 1:41 AM, Thomas Huth wrote:
> On 28/08/2019 21.18, John Snow wrote:
>>
>>
>> On 8/28/19 5:34 AM, Thomas Huth wrote:
>>> In our documentation, we use a mix of "$QEMU", "qemu-system-i386" and
>>> "qemu-system-x86_64" when we give examples to the users how to run
>>> QEMU. Some more consistency would be good here. Also some distributions
>>> use different names for the QEMU binary (e.g. "qemu-kvm" in RHEL), so
>>> providing more flexibility here would also be good. Thus let's define
>>> some variables for the names of the QEMU command and use those in the
>>> documentation instead: @value{qemu_system} for generic examples, and
>>> @value{qemu_system_x86} for examples that only work with the x86
>>> binaries.
>>>
>>> Signed-off-by: Thomas Huth <th...@redhat.com>
>>
>> Makes sense to me, but do we want a definitions.texi or similar that can
>> be used globally (and is easy to find and edit by e.g. distro
>> packagers), or is it better to re-define them per-each file as you've done?
>
> Hmm, as long as it's just one or two variables, it seems a little bit
> excessive to me, but if we'd have more config knobs, that would
> certainly be the right way to go ... but currently we do not have any
> more variables, do we?
>
Not that I'm aware of. We might find more as we embark on the
ReSTification of our docs.
I only bring it up because it might not be clear in which documents and
in how many places this definition needs to be changed by a package
maintainer; if our end goal is one big unified manual then I think we
need a central configuration for it, too. Maybe that only shows up for
the Sphinx manual.
(Maybe a yaml file that conf.py can consume and uses to generate ReST
definitions that can be used throughout the rest of the docs would be an
appropriate thing to do.)
I won't insist, because creating new infrastructure for texi docs seems
lateral. Your patch doesn't make anything I'm pointing out worse than it
already was, though, so:
Reviewed-by: John Snow <js...@redhat.com>
--js
