Re: [PATCH 3/5] docs/system: standardize docs/system man page sections to --- with overline

[Peter Maydell]

On Tue, 7 Sept 2021 at 16:56, Paolo Bonzini <pbonzini@redhat.com> 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 <peter.maydell@linaro.org>

thanks
-- PMM