On 5/14/19 11:17 AM, Peter Maydell wrote: > On Tue, 14 May 2019 at 07:46, Cédric Le Goater <c...@kaod.org> wrote: >> >> This documents the overall XIVE architecture and gives an overview of >> the QEMU models. It also provides documentation on the 'info pic' >> command. >> >> Signed-off-by: Cédric Le Goater <c...@kaod.org> >> --- >> docs/index.rst | 1 + >> docs/ppc/index.rst | 13 ++ >> docs/ppc/xive.rst | 344 +++++++++++++++++++++++++++++++++++++++++++++ >> MAINTAINERS | 1 + >> 4 files changed, 359 insertions(+) >> create mode 100644 docs/ppc/index.rst >> create mode 100644 docs/ppc/xive.rst > > Hi -- it's great to see this documentation. Unfortunately, > where you've put it doesn't match our intended layout for docs.
OK. I guess I need to split the file in multiple parts. > Each subdirectory of docs/ becomes its own manual, and > the intention is to eventually have five manuals > (as sketched out in https://wiki.qemu.org/Features/Documentation): > * QEMU user mode emulation -- docs/user > * QEMU full-system emulation user's guide -- docs/system Should we put the documentation of machine options under this directory ? > * QEMU full-system emulation management and interoperability guide -- > docs/interop There, I could put the 'info pic' documentation. > * QEMU full-system emulation guest hardware specifications -- docs/specs and there, the low level information on the XIVE controller. > * QEMU developer's guide -- docs/devel and finally, there, some of the documentation on QEMU modeling. > We don't want to have a separate PPC-specific manual. OK. > Currently we only have interop and devel. I have on > my todo list to try to sort out the others, including > figuring out how to transition from our current set > of texinfo-based manuals to this layout. > > I'm not sure exactly where this document should live. > From a quick scan it appears to be mixing together > information aimed at several different audiences -- > the "Overview of the QEMU models for XIVE" part looks > like information about QEMU internals which belongs > in docs/devel, but some other parts seem to be user > facing information which should go in one of the > other manuals. What is nice about the single file model is that you find all the information related to one topic in one place. Can manuals reference each another ? Thanks, C.
