On 7/12/21 3:39 PM, Eli Zaretskii wrote:
Cc: g...@gcc.gnu.org, gcc-patches@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?
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.
