> Cc: gcc@gcc.gnu.org, gcc-patc...@gcc.gnu.org, jos...@codesourcery.com
> From: Martin Liška <mli...@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?
> 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.
5) Lack of macros.
AFAIK, only simple textual substitution is available, no macros
with arguments.
