On 7/12/21 7:49 PM, Gavin Smith via Gcc wrote:
(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.
Hello.
Appreciate your time spent working on the tool and I'm going to briefly reply
your points.
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.
If I understand correctly, that would need a further post-processing of the HTML
elements. Sphinx works out of the box and the same output is achieved also for
PDF output.
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.
Good.
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
To be honest, it looks still quite legacy and I don't want to spend more working
on a custom CSS template and reasonable JS functionality. I would like to take
an existing theme that looks nice and provides reasonable capability. That's
for me
https://github.com/readthedocs/sphinx_rtd_theme
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).
If I open a new tab, a browser correctly scrolls to the option documentation.
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.
As said, it's a limitation to me.
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.
All right, that would likely require providing more anchors in the existing GCC
documentation.
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.
Got that, thus we use unnecessary syntax right now.
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).
Good point, I'm not aware of any cross links. If there are any, I'm willing
to update them.
* 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.
Totally misleading. I don't see why would anybody install HTML documentation
locally.
Our motivation is to have HTML documentation on our site, where we can update it
and Google can index it for people using full text search.
Some people don't realise that Texinfo is actively maintained and
there is a mailing list at bug-texi...@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.
As mentioned, I appreciate your work. On the other hand, Sphinx documentation
community
is much bigger and the list of projects using the tool is pretty huge:
https://www.sphinx-doc.org/en/master/examples.html (include huge FOSS projects
like
LLVM, or Linux kernel). That makes me believe the transition makes sense and we
will
benefit from it as project.
Martin
