(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-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.
