Re: [PATCH v3 05/33] qemu-doc: split qemu-doc.texi in multiple files

["Alex Bennée" <alex.bennee@linaro.org>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Mon, 2 Mar 2020 at 11:22, Alex Bennée <alex.bennee@linaro.org> wrote:
>>
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>
>> > From: Paolo Bonzini <pbonzini@redhat.com>
>> >
>> > In order to facilitate the reorganization of qemu-doc.texi content,
>> > as well as the conversion to rST/Sphinx, split it in multiple .texi
>> > files that are included from docs/system.
>> >
>> > The "other devices" section is renamed to ivshmem and placed last.
>> >
>> > Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
>> > Message-id: 20200226113034.6741-6-pbonzini@redhat.com
>> > Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
>> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>> > ---
>> >  Makefile                         |   16 +
>> >  docs/system/build-platforms.texi |   67 ++
>> >  docs/system/gdb.texi             |   71 ++
>>
>> The gdb test would be better served in docs/core if we could have
>> optional sections on invocation rendering depending on if it's built
>> with system emulation or linux-user docs. Is that something that's
>> already supported?
>
> No, for three reasons:
>
> (1) we build all the docs, always -- there's no concept
> of "skip some bits of docs if some configure feature was
> disabled"
>
> (2) there is no docs/core -- the subdirectories of docs/
> correspond to the "manuals" which we want to present to
> the user, like "Manual for system emulation users" and
> "Manual for user-mode users" and "Manual for the
> standalone tools"; a "core" manual wouldn't fit into this
> classification, and we already have slightly more manuals
> than I'm entirely comfortable with.

I wasn't clear. I don't want an additional document but I'd like to
include information on the gdbstub in both the system and linux-user
manuals. Another candidate for documentation which is common to both
would be the notes about TCG CPU emulation.

> (3) Sphinx's support for conditional documentation is
> not very good, as it is implemented at the "wrong"
> end of the pipeline (ie it's not like a preprocessor
> ifdef, but instead is just "suppress the output", so
> manual pieces inside a disabled ifdef still turn up
> in places like the index and table of contents). The
> best you can do is to mess around with the include
> directive, but if we do that too much then things get
> awkward to understand and maintain. (We do it a bit
> in this series to handle "manpage vs manual" stuff.)

In the case of the gdbstub the only real difference is the invocation
section (-s vs -g). I guess we could just reference both in the section.
It's not like the linux-user documents can't acknowledge the existence
of system emulation and visa-versa.

>
> thanks
> -- PMM


-- 
Alex Bennée