On Tue, 7 Sept 2021 at 16:56, Paolo Bonzini <[email protected]> wrote: > > Man pages in docs/system use file inclusion heavily. Use headings with > overlines in the main files, so that the same included file work well > from both manuals and man pages. > > This style of heading is a bit more heavy-weight, so it is not used by > the other man pages in interop/ and tools/. If in the future they > are changed to use include files, for example to avoid having sections > named "synopsis" or "description", they can switch to --- with overline > as well.
I did have a go a little while back at using include files consistently for all our manpages (my motivation at the time was trying to add a standard footer in the manpages mentioning the license). This runs aground on a Sphinx issue -- Sphinx always builds all files, so if you have thingy-manpage.rst thingy-html-page.rst thingy-contents.rst.inc included from both the above and thingy-contents defines a label, then Sphinx will complain about "duplicate labels" in thingy-manpage and thingy-html-page, even though no output ever wants to have both rst files. There's no way to tell Sphinx "only build this for this builder" :-( We get away with our current handling of qemu-manpage.rst only because none of the files it includes happen to define labels, I think. Anyway, Reviewed-by: Peter Maydell <[email protected]> thanks -- PMM
