This reinstates
<https://lists.gnu.org/archive/html/qemu-devel/2020-09/msg09228.html>,
which was committed at some point but reverted many years later in
cleanups that followed the migration from Texinfo sources to the
ReStructuredText (RST) format.  It's still nice to leave the option for
users to easily generate a QEMU manual in the Texinfo format, taking
advantage of the Sphinx texinfo backend.

The Texinfo format is structured and info readers provide advanced
navigation capabilities such as jumping to indexed topics or nodes and
is usable even in environments lacking a graphical session.

* docs/meson.build (texi, info): New targets.

Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
---

 docs/meson.build | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/meson.build b/docs/meson.build
index 9040f860ae..2ae7886fcb 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -98,4 +98,26 @@ if build_docs
   alias_target('sphinxdocs', sphinxdocs)
   alias_target('html', sphinxdocs)
   alias_target('man', sphinxmans)
+
+  # Add a target to build and install a Texinfo version of the QEMU
+  # manual, if 'makeinfo' is available.
+  makeinfo = find_program(['texi2any', 'makeinfo'])
+  if makeinfo.found()
+    sphinxtexi = custom_target(
+      'qemu.texi',
+      output: ['qemu.texi', 'sphinxtexi.stamp'],
+      depfile: 'sphinxtexi.d',
+      command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@',
+               '-Ddepfile_stamp=@OUTPUT1@', '-b', 'texinfo',
+               '-d', private_dir, input_dir, meson.current_build_dir()])
+    sphinxinfo = custom_target(
+      'qemu.info',
+      input: sphinxtexi,
+      output: 'qemu.info',
+      install: true,
+      install_dir: get_option('infodir'),
+      command: [makeinfo, '--no-split', '--output=@OUTPUT@', '@INPUT0@'])
+    alias_target('texi', sphinxtexi)
+    alias_target('info', sphinxinfo)
+  endif
 endif

base-commit: ba49d760eb04630e7b15f423ebecf6c871b8f77b
-- 
2.41.0

On Mon, 18 Mar 2024 at 03:05, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
>
> This reinstates
> <https://lists.gnu.org/archive/html/qemu-devel/2020-09/msg09228.html>,
> which was committed at some point but reverted many years later in
> cleanups that followed the migration from Texinfo sources to the
> ReStructuredText (RST) format.  It's still nice to leave the option for
> users to easily generate a QEMU manual in the Texinfo format, taking
> advantage of the Sphinx texinfo backend.

As far as I can tell, we never committed that patch, because
(as noted in the discussion there) we don't particularly want
to generate texinfo output (and also because it was missing a
signed-off-by line). So this isn't a regression: we've never
generated info docs since we switched away from texinfo to
rst as our source format.

I don't think my position personally has changed on this one
since your previous patch submission. Other QEMU developers
are welcome to weigh in and disagree with me.

(If we do enable this we might want to see whether we need to
set texinfo_documents in conf.py or if the defaults are OK.)

thanks
-- PMM

Hi Peter,

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

> On Mon, 18 Mar 2024 at 03:05, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
>>
>> This reinstates
>> <https://lists.gnu.org/archive/html/qemu-devel/2020-09/msg09228.html>,
>> which was committed at some point but reverted many years later in
>> cleanups that followed the migration from Texinfo sources to the
>> ReStructuredText (RST) format.  It's still nice to leave the option for
>> users to easily generate a QEMU manual in the Texinfo format, taking
>> advantage of the Sphinx texinfo backend.
>
> As far as I can tell, we never committed that patch, because
> (as noted in the discussion there) we don't particularly want
> to generate texinfo output (and also because it was missing a
> signed-off-by line). So this isn't a regression: we've never
> generated info docs since we switched away from texinfo to
> rst as our source format.

I see.  For the record, very similar changes were contributed and
successfully merged into the Linux [0] and U-Boot [1] projects.  No
problems appear to have been caused by these in more than 2 years time.

[0]  https://lwn.net/ml/linux-doc/20221116190210.28407-1-maxim.cournoyer@gmail.com/
     merged with commit 1f050e904d

[1]  https://lists.denx.de/pipermail/u-boot/2022-December/502355.html
     merged with commit 7fa4c27a2e

> I don't think my position personally has changed on this one
> since your previous patch submission. Other QEMU developers
> are welcome to weigh in and disagree with me.

My position is also unchanged re-reading the past thread; that the
maintenance burden would mostly be on the Sphinx project rather than
QEMU.  The info target doesn't even need to be tested by upstream; my
opinion is that there's value in making it easily available for
downstream users such as GNU Guix to use.  The target is not built
unless 'texinfo' is available in the environment, so your CI can
continue not producing it, if this is preferred.

Of course, GNU Guix can continue to maintain it as a custom patch
applied to QEMU, but I think it'd be nicer if it lived in the QEMU tree,
potentially benefiting others.

> (If we do enable this we might want to see whether we need to
> set texinfo_documents in conf.py or if the defaults are OK.)

The defaults appear to be fine.  The output file is 'qemu.info', and
'qemu' is a fine name for an Info manual.

-- 
Thanks,
Maxim

On Tue, Mar 19, 2024 at 11:47:59AM +0000, Peter Maydell wrote:
> On Mon, 18 Mar 2024 at 03:05, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
> >
> > This reinstates
> > <https://lists.gnu.org/archive/html/qemu-devel/2020-09/msg09228.html>,
> > which was committed at some point but reverted many years later in
> > cleanups that followed the migration from Texinfo sources to the
> > ReStructuredText (RST) format.  It's still nice to leave the option for
> > users to easily generate a QEMU manual in the Texinfo format, taking
> > advantage of the Sphinx texinfo backend.
> 
> As far as I can tell, we never committed that patch, because
> (as noted in the discussion there) we don't particularly want
> to generate texinfo output (and also because it was missing a
> signed-off-by line). So this isn't a regression: we've never
> generated info docs since we switched away from texinfo to
> rst as our source format.
> 
> I don't think my position personally has changed on this one
> since your previous patch submission. Other QEMU developers
> are welcome to weigh in and disagree with me.

I tend to agree with your point in that thread above. It is already
a big enough burden for maintainers to ensure that the HTML output
for their docs is rendered effectively. Adding an 'info' docs output
increases that burden for negligible benefit. HTML is the most
broadly consumable docs format, so it makes sense to focus our effort
on that.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Hi Daniel,

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Tue, Mar 19, 2024 at 11:47:59AM +0000, Peter Maydell wrote:
>> On Mon, 18 Mar 2024 at 03:05, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
>> >
>> > This reinstates
>> > <https://lists.gnu.org/archive/html/qemu-devel/2020-09/msg09228.html>,
>> > which was committed at some point but reverted many years later in
>> > cleanups that followed the migration from Texinfo sources to the
>> > ReStructuredText (RST) format.  It's still nice to leave the option for
>> > users to easily generate a QEMU manual in the Texinfo format, taking
>> > advantage of the Sphinx texinfo backend.
>> 
>> As far as I can tell, we never committed that patch, because
>> (as noted in the discussion there) we don't particularly want
>> to generate texinfo output (and also because it was missing a
>> signed-off-by line). So this isn't a regression: we've never
>> generated info docs since we switched away from texinfo to
>> rst as our source format.
>> 
>> I don't think my position personally has changed on this one
>> since your previous patch submission. Other QEMU developers
>> are welcome to weigh in and disagree with me.
>
> I tend to agree with your point in that thread above. It is already
> a big enough burden for maintainers to ensure that the HTML output
> for their docs is rendered effectively. Adding an 'info' docs output
> increases that burden for negligible benefit. HTML is the most
> broadly consumable docs format, so it makes sense to focus our effort
> on that.

For me, the value in Texinfo is that it can be consistently be used from
both headless environment (pseudo-terminal) and in graphical
environments with more capable viewers (Emacs, Yelp, ...).  Its viewers
typically offer better search capabilities than man pages viewers or
most HTML browsers (e.g. jumping to topics via their index or node
names, or searching for a regexp in the whole document), and its on disk
small size means it can easily be shipped along the program itself,
ensuring the documentation stays in sync with the documented program.

Using GNU Guix for years, where Texinfo is used as the standard
documentation system and where its enabled in most packages that support
it, has allowed me to appreciate the qualities of Texinfo as a
documentation system that I don't find in either man or pages or HTML
documentation.

-- 
Thanks,
Maxim