Benefits of using Sphinx documentation format

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

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]):
    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
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
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).

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