Re: [PATCH] build: Build and install the info manual.

[Maxim Cournoyer]

Hello Peter,

Peter Maydell <peter.maydell@linaro.org> writes:

> On Fri, 25 Sep 2020 at 07:27, Maxim Cournoyer <maxim.cournoyer@gmail.com> 
> wrote:
>>
>> Take advantage of the Sphinx texinfo backend to generate a QEMU info
>> manual.  The texinfo format allows for more structure and info readers
>> provide more advanced navigation capabilities compared to manpages
>> readers.
>
> Not providing an info manual (or indeed any format other than HTML
> and manpages) was a deliberate design choice. The rationale is that
> checking that multiple document formats all ended up rendering
> correctly is more work than people will in practice put in (as
> demonstrated by various errors in the old HTML rendering, for
> instance).

It seems to me that any problem found in the texinfo rendering produced
by Sphinx would be a bug in Sphinx, which could simply be forwarded
upstream when encountered.  My experience with Sphinx-generated texinfo
manuals is rather good.  The CMake project allows producing an info
manual that way, for example, and the result is at least as usable as
their HTML-based doc (as an avid info user, I'd say more usable, given
most commands are indexed).

>> * configure (infodir): Add the --infodir option, which allows
>> configuring the directory under which the info manuals are installed.
>> * docs/index.rst: Include the top level documents to prevent
>> warnings (treated as errors by sphinx-build).
>
> This isn't the right thing. You should be pointing sphinx-build
> at each of the individual manuals (system, interop, etc) and
> generating one info file for each. This is because we generate
> manuals for each of these including the 'devel' manual, but
> we don't want to install 'devel', because it's developer-facing
> and not needed by end-users of QEMU.

Is this the only reason individual manuals are being generated?  It
makes sense for the manpages (which have their own macros), but
otherwise (for HTML and info) introduces a lot of complexity for not
much gain, in my opinion.  Users not wanting to know about devel
internals can simply skip that section; no harm done.

The individual manuals are all stitched back together using a top
index.html page (derived from index.html.in), anyway.  That'd be better
taken care of by Sphinx automatically upon generating the whole doc
tree, in my opinion, as it seems to be the way it was designed to work
and simplifies things all around.

I initially went the individual manual route and devised complicated
Make macros and got individual info manuals produced, only to find out I
wanted to replicate that index.html.in in the texinfo format (Texinfo is
as navigable as HTML, so having every QEMU manual under the same node as
different sections makes more sense in my opinion).  The individually
produced info manual were also all named 'QEMU Documentation' rather
than with their own more accurate names, because of directives in the
included the top-level conf.py.

> won't find you have problems with the orphan top level documents.
>
> (We really need to move those orphan docs into the right places
> in the manual structure at some point.)

We could simply put them in another section called "Others" as a
starting point.  For this patch we can also choose to ignore them rather
than include them, but if someone went to the length of writing those
docs, I'd argue it was to be read rather than forgotten :-).

>> * docs/meson.build (sphinxinfo): Add new target.
>
> You've forgotten your Signed-off-by: line.

I've added it in my local tree; will wait for your feedback on my above
comments before sending an updated patch.

Thanks for the review,

Maxim