Re: Benefits of using Sphinx documentation format

[Jonathan Wakely <jwakely.gcc@gmail.com>]

On Mon, 12 Jul 2021 at 14:41, Eli Zaretskii via Gcc <gcc@gcc.gnu.org> wrote:
>
> > Cc: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com
> > From: Martin Liška <mliska@suse.cz>
> > Date: Mon, 12 Jul 2021 15:25:47 +0200
> >
> > Let's make it a separate sub-thread where we can discuss motivation why
> > do I want moving to Sphinx format.
>
> Thanks for starting this discussion.
>
> > Benefits:
> > 1) modern looking HTML output (before: [1], after: [2]):
> >     a) syntax highlighting for examples (code, shell commands, etc.)
> >     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 ¶)
> >     d) internal links are working, e.g. one can easily jump from listing of options

For me, these items are enough justification to switch away from
texinfo, which produces crap HTML pages with crap anchors. You can't
find out the anchors without inspecting (and searching) the HTML
source. That's utterly stupid. And even after you do that, the anchor
is at the wrong place:
https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c
As somebody who spends a lot of time helping users on the mailing
list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo
HTML has angered me for many years.

Yes, some people like texinfo, but some people also dislike it and
there are serious usability problems with the output. I support
replacing texinfo with anything that isn't texinfo.


> >     e) left menu navigation provides better orientation in the manual
> >     f) Sphinx provides internal search capability: [3]
> > 2) internal links are also provided in PDF version of the manual
>
> How is this different from Texinfo?
>
> > 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
>
> Texinfo likewise supports many output formats.  Someone presented a
> very simple package to produce epub format from it.
>
> > 5) Sphinx is using RST which is quite minimal semantic markup language
>
> Is it more minimal than Texinfo?
>
> > 6) TOC is automatically generated - no need for manual navigation like seen here: [5]
>
> That is not needed in Texinfo as well, since long ago.  Nowadays, you
> just say
>
>   @node Whatever
>
> and the rest is done automatically, as long as the manual's structure
> is a proper tree (which it normally is, I know of only one manual that
> is an exception).
>
> > 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)
>
>  4) The need to learn yet another markup language.
>     While this is not a problem for simple text, it does require a
>     serious study of RST and Sphinx to use the more advanced features.

This is a problem with texinfo too.

>
>  5) Lack of macros.
>     AFAIK, only simple textual substitution is available, no macros
>     with arguments.

Is this a problem for GCC docs though?