Re: Benefits of using Sphinx documentation format

["Martin Liška" <mliska@suse.cz>]

On 7/12/21 3:39 PM, Eli Zaretskii 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
>>      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?

Texinfo does not emit them. See e.g. links in option listing (-O2, -Os, ...).

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

Good to know.

> 
>> 5) Sphinx is using RST which is quite minimal semantic markup language
> 
> Is it more minimal than Texinfo?

I would say that's pretty easy to learn, similarly complex as 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).

All right, then we likely do an extra work right now.

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

No, majority of the documentation is pretty simple: basic formatting, links, tables and
code examples.

Martin

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