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

[Peter Maydell]

On Mon, 2 Mar 2020 at 11:22, Alex Bennée <address@hidden> wrote:
>
>
> Peter Maydell <address@hidden> writes:
>
> > From: Paolo Bonzini <address@hidden>
> >
> > 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 <address@hidden>
> > Message-id: address@hidden
> > Reviewed-by: Peter Maydell <address@hidden>
> > Signed-off-by: Peter Maydell <address@hidden>
> > ---
> >  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.

(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.)

thanks
-- PMM