Re: Benefits of using Sphinx documentation format

[Gavin Smith <gavinsmith0123@gmail.com>]

(Sending mail again, without attachments this time in the hope it gets through.)

I had the discussion about moving documentation of gcc from Sphinx to
Texinfo brought to my attention.

https://gcc.gnu.org/pipermail/gcc/2021-July/236731.html

Speaking as the Texinfo maintainer, I hope to add my views and
understandings of things to this discussion to improve your
understanding of the facts and possibilities, although of course it's
up to you whether you use Texinfo or not.

I will work through the points made in that email but haven't read any
of the subsequent discussion yet - I'll follow up on anything else
afterwards.

> Benefits:
> 1) modern looking HTML output (before: [1], after: [2]):

>    a) syntax highlighting for examples (code, shell commands, etc.)

Syntax highlighting has been achieved with Texinfo before. See

https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html

and

https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00004.html

With Texinfo 6.8, syntax highlighting in multiple languages is easier
to achieve by giving an argument to the @example command
(https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040example.html).
This puts a class attribute on the HTML element which can then be
picked up by a post-processor. It might also be possible to achieve
syntax highlighting with a customization file used by the Texinfo
tools themselves: see
https://lists.gnu.org/archive/html/bug-texinfo/2021-01/msg00031.html.

>    b) precise anchors, the current Texinfo anchors are not displayed (start with first line of an option)
>    c) one can easily copy a link to an anchor (displayed as ¶)

Similar anchors were implemented in Texinfo 6.8. See
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Invoking-texi2any.html
and hover any of the options there with your mouse; you will see the
pilcrow sign appear.

>    e) left menu navigation provides better orientation in the manual

Left menu navigation is possible with the new JavaScript interface, in
Texinfo 6.8. There is still a demo at

https://per.bothner.com/tmp/Kawa-txjs-plain/Community.html

and

https://per.bothner.com/tmp/Kawa-txjs/Community.html

However, I would say that it isn't necessarily always an improvement,
if it is going to be buggy. When I click on the link
https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing
the browser doesn't scroll the sidebar so to show the active ToC entry
(although it
is displayed correctly when I refresh the page).

The more sophisticated the HTML/JS becomes the more likely there are
these little nits.

>    f) Sphinx provides internal search capability: [3]

There is a global search facility with the JavaScript interface
although different to that provided by Sphinx, only showing one match
at a time.

Try

https://per.bothner.com/tmp/Kawa-txjs/index.html

and then press "s" on your keyboard, type in your search string (e.g.
"composable") and it will search through the manual for that string.
To go to the next match, press "s" then Return.

The proviso about "sophisticated" HTML still applies here, though.

> 2) internal links are also provided in PDF version of the manual

Links already work when viewing a PDF on a computer.

If you want to add additional links that only appear in PDF and HTML
and not in Info, this is easily achieved with a conditional macro,
like

@ifset morelinks
@macro link{arg}
@ref{\arg\}
@end macro
@end ifset
@ifclear morelinks
@macro link{arg}
\arg\
@end macro
@end ifclear

followed by "@set morelinks" or "@clear morelinks" as required.

> 5) Sphinx is using RST which is quite minimal semantic markup language

This is really an ineffable question of taste on which it is hard to
be convinced, but I have to point out that Texinfo is minimalistic,
with only three special characters (@, { and }).

> 6) TOC is automatically generated - no nee6d for manual navigation like seen here: [5]
> 5] @comment node-name,     next,          previous, up
>     @node    Installing GCC, Binaries, , Top

This is a completely bogus point with these explicit "pointers" being
optional. I couldn't find out easily how long ago these pointers
became optional, but it is at least twenty years ago.

A couple of other points, not mentioned in the original email:
* One possible disadvantage of moving away from Texinfo which might be
easily missed is support for reliable web links between different
manuals. If you change format you should make sure that these work,
e.g. if you reference the glibc manual the web link to that should
work correctly (as well as the link working in the Info format).
* A disadvantage of focusing on HTML output is that locally installed
documentation gets sidelined: although locally installed HTML
documentation is possible, it tends not to happen and people refer to
the web version instead, with all of its disadvantages (slow speed,
may be the wrong version or disappear off the web, lack of user
privacy). Another disadvantage of HTML is that links can only go to
one place, while with the Info format you can have manuals installed
in several places, even more than one version of a manual installed at
once.

Some people don't realise that Texinfo is actively maintained and
there is a mailing list at bug-texinfo@gnu.org
(https://lists.gnu.org/mailman/listinfo/bug-texinfo); this is a place
for people to discuss their needs as to what they need from the
system. I wonder if some of the desiderata can be satisfied with
existing facilities in Texinfo or if not if we could accommodate them
with not too much difficulty.