On Mon, 2021-07-12 at 15:25 +0200, Martin Liška wrote: > Hello. > > Let's make it a separate sub-thread where we can discuss motivation > why > do I want moving to Sphinx format. > > Benefits: > 1) modern looking HTML output (before: [1], after: [2]):
"modern looking" is rather subjective; I'd rate Sphinx's output as looking like it's from 2010s (last decade), whereas Texinfos' looks like it's from the 1990s. In theory this ought not to matter, but every time I look at our documentation it gives me a depressing feeling, reminiscent of a graveyard, that discourages me from fixing things. > a) syntax highlighting for examples (code, shell commands, etc.) ...with support for multiple programming languages, potentially on the same page. For example, in the libgccjit docs: https://gcc.gnu.org/onlinedocs/jit/intro/tutorial02.html we can have a mixture of C, assembler and shell on one page, and each example is syntax-highlighted accordingly. It's not clear to me how to do that in texinfo, since there needs to be a way to express what language an example is in. > b) precise anchors, the current Texinfo anchors are not displayed > (start with first line of an option) ...and the URLs are sane and stable (so e.g. there is a reliable, guessable, readable URL for the docs for say, "-Wall"). > c) one can easily copy a link to an anchor (displayed as ¶) > d) internal links are working, e.g. one can easily jump from > listing of options > e) left menu navigation provides better orientation in the manual > f) Sphinx provides internal search capability: [3] ...also (quoting myself in places here from 2015 https://gcc.gnu.org/pipermail/gcc-patches/2015-November/434055.html ): * the ability to include fragments of files: libgccjit's documentation uses directives to include code from the test suite, so that all of the code examples are also part of the test suite, and are thus known to compile), allowing for (almost) literate programming. [That said, the build of libgccjit's docs on gcc.gnu.org seems to be missing those fragments; I wonder if there's a path or version issue?] * a page-splitting structure that make sense, to me, at least (I have never fathomed the way texinfo's navigation works, for HTML, at least, and I believe I'm not the only one; I generally pick the all-in-one- HTML-page option when viewing texinfo-html docs and do textual searches, since otherwise I usually can't find the thing I'm looking for (or have to resort to a brute-force depth-first search of clicking through the links).) * much more use of markup, with restrained and well-chosen CSS (texinfo's HTML seems to ignore much of the inline markup in the .texinfo file) > 2) internal links are also provided in PDF version of the manual > 3) some existing GCC manuals are already written in Sphinx (GNAT > manuals and libgccjit) > 4) support for various output formats, some people are interested in > ePUB format > 5) Sphinx is using RST which is quite minimal semantic markup language Sphinx is also used by many high-profile FLOSS projects (e.g. the Linux kernel, LLVM, and the Python community), so it reduces the barrier to entry for new contributors, relative to texinfo. > 6) TOC is automatically generated - no need for manual navigation > like seen here: [5] > > Disadvantages: > > 1) info pages are currently missing Page description in TOC > 2) rich formatting is leading to extra wrapping in info output - > beings partially addresses in [4] > 3) one needs e.g. Emacs support for inline links (rendered as notes) > > I'm willing to address issue 1) in next weeks and I tend to skip > emission of links as mentioned in 3). > Generally speaking, I'm aware that some people still use Info, but I > think we should more focus > on more modern documentation formats. That's HTML (and partially > PDF). I think the output formats we need to support are: - HTML - PDF - man page (hardly "modern", but still used) I regared "info" as merely "nice to have" - I don't know anyone who uses it other than some core GNU contributors. Dave > > Martin > > [1] > https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing > [2] > https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing > [3] > https://splichal.eu/gccsphinx-final/html/gcc/search.html?q=-fipa-icf&check_keywords=yes&area=default# > [4] https://github.com/sphinx-doc/sphinx/pull/9391 > [5] @comment node-name, next, previous, up > @node Installing GCC, Binaries, , Top >
