Peter Maydell <peter.mayd...@linaro.org> writes:
> On Mon, 2 Mar 2020 at 11:22, Alex Bennée <alex.ben...@linaro.org> wrote: >> >> >> Peter Maydell <peter.mayd...@linaro.org> writes: >> >> > From: Paolo Bonzini <pbonz...@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 <pbonz...@redhat.com> >> > Message-id: 20200226113034.6741-6-pbonz...@redhat.com >> > Reviewed-by: Peter Maydell <peter.mayd...@linaro.org> >> > Signed-off-by: Peter Maydell <peter.mayd...@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
