Re: RFC: Experimental use of Sphinx for GCC documentation

[Joseph Myers]

On Mon, 9 Nov 2015, Sandra Loosemore wrote:

> If we're going to switch documentation formats, I'd rather we used DocBook.
> I've had to use "restructured text" before and found it really awkward.

I should perhaps note that the Sphinx extensions to reST are a lot better 
documented than the ZWiki ones!

-- 
Joseph S. Myers
jos...@codesourcery.com

Re: RFC: Experimental use of Sphinx for GCC documentation

[David Malcolm]

On Mon, 2015-11-09 at 16:37 -0700, Sandra Loosemore wrote:
> On 11/08/2015 06:55 AM, David Malcolm wrote:
> > I've been experimenting with using Sphinx [1] for GCC's documentation.
> >
> > [snip]
> >
> > The primary advantages of .rst/sphinx over .texi/texinfo I see are in
> > the generated HTML:
> >
> > * sane, stable URLs (so e.g. there is a reliable URL for the docs for,
> > say, "-Wall").
> >
> > * a page-splitting structure that make sense, to me, at least [3]
> >
> > * much more use of markup, with restrained and well-chosen CSS
> > (texinfo's HTML seems to ignore much of the inline markup in
> > the .texinfo file)
> >
> > * autogenerated internal links, so that almost everything is clickable,
> > and will take you somewhere sane, by default
> >
> > * syntax-highlighting of code examples, with support for multiple
> > programming languages (note the mixture of C, C++, Fortran, etc in the
> > docs for the gcc options).
> >
> > * looks modern and fresh (IMHO), letting casual observers see that the
> > project is alive and kicking.
> >
> >
> > Thoughts?
> 
> If we're going to switch documentation formats, I'd rather we used 
> DocBook.  I've had to use "restructured text" before and found it really 
> awkward.

My own preference is the opposite; I've used DocBook and rst, and I find
DocBook to be the awkward one [1].  I think DocBook may be OK as an
interchange format, but I find it overly verbose to author and to read
in plain-text form.

(I'm not so fond of some parts of .rst's inline markup syntax, but I
find its structural aspects to be extremely expressive and concise;
overall I find it a joy to work with).

> But, personal preferences aside, I also think it's more important that 
> we commit documentation-person resources to making the content more 
> correct, readable, and better organized, than to making the HTML output 
> look "modern and fresh", or worse yet, translating the docs to another 
> format and having to proofread them for conversion goofs.

Correct, readable and well-organized documentation are laudable goals...
but I think that, to a first approximation, we're already there: I just
feel that the content is hidden behind a poor tool chain.

I believe that no matter how good we make the .texi files, the issues
with URLs, HTML page-splitting, etc with how texinfo's HTML generation
works will hold gcc back.

> BTW, Mentor Graphics' toolchains ship with a custom HTML stylesheet for 
> the generated manuals, to make them a little "prettier".  Maybe 
> something like that would go a long way towards solving the perceived 
> problems here? 

I'm interested in seeing that, though presumably the URL and
page-splitting issues would remain (is this at the CSS level, or do you
make deeper changes to the HTML generation?)


> Or improvements to texinfo's HTML generation.

texinfo is implemented in Perl, and FWIW, for me to help, that's a
showstopper (sprry; I've tried several times to get my head around Perl,
but my brain seems incompatible with it).


One other approach might be to retain .texi as the canonical format, but
have a optional custom HTML generator (perhaps using texi2rst to
generate .rst for sphinx, this time as an intermediate step during "make
html", rather than as a one-time conversion).  The main thing I think
it's missing is a way to express the language of embedded source
examples, so that they can be syntax-highlighted.


Thanks; I hope this is constructive.
Dave

[1] fwiw, my opinion on this has changed; a decade or so ago I worked on
a DocBook editor,  http://conglomerate.org/ 

Re: RFC: Experimental use of Sphinx for GCC documentation

[Sandra Loosemore]

[resending, gcc-patches won't allow a screenshot attachment]

On 11/10/2015 03:27 PM, David Malcolm wrote:


Correct, readable and well-organized documentation are laudable goals...
but I think that, to a first approximation, we're already there: I just
feel that the content is hidden behind a poor tool chain.


Hmmm, I just searched bugzilla for "documentation", and got 539 bugs 
back.  :-S  (Bugzilla doesn't seem to have a component keyword for 
"docs" or "manual" or anything like that, so the doc issues aren't 
really tagged as such in any way.)



I believe that no matter how good we make the .texi files, the issues
with URLs, HTML page-splitting, etc with how texinfo's HTML generation
works will hold gcc back.


I don't see these problems as being so severe that it's worth losing 
edit history by reformatting the whole document, and the time/effort it 
would take to do and proofread the conversion.



BTW, Mentor Graphics' toolchains ship with a custom HTML stylesheet for
the generated manuals, to make them a little "prettier".  Maybe
something like that would go a long way towards solving the perceived
problems here?


I'm interested in seeing that, though presumably the URL and
page-splitting issues would remain (is this at the CSS level, or do you
make deeper changes to the HTML generation?)


Yes, CSS.  It's nothing fancy; we specify some fonts and colors, and put 
a shaded box around code examples to set them off better.  I'm not sure 
we have any online examples of HTML manuals accessible outside Mentor. 
Probably we could contribute the .css file if anybody wants to hack it 
up further to improve GCC's default manual formatting, but I'd have to 
check that we don't consider that shade of blue proprietary or anything 
like that.  ;-)


-Sandra

Re: RFC: Experimental use of Sphinx for GCC documentation

[Kyrill Tkachov]

Hi David,

On 08/11/15 13:55, David Malcolm wrote:

I've been experimenting with using Sphinx [1] for GCC's documentation.

You can see an HTML sample of GCC docs built with Sphinx here:
https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/gcc.html
(it's a work-in-progress; i.e. there are bugs).

Compare with:
  https://gcc.gnu.org/onlinedocs/gcc/index.html


In particular, note how options get stable, clickable URLs:
https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/option-summary.html


FWIW, I think this all looks much better than the existing formatting.
One weird artifact I noticed while looking at the ARM options:
https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/hardware-models-and-configurations.html#arm-options
In particular for -mcpu where it gives an explanation of what 
-mcpu=generic- is equivalent to, there seems
to be something weird going on.
The .texi source is:
@option{-mcpu=generic-@var{arch}} is also permissible, and is equivalent to 
@option{-march=@var{arch} -mtune=generic-@var{arch}}.

Whereas the output looks something like:
-mcpu=generic-``arch`` is also permissible, and is equivalent to -march=``arch` 
-mtune=generic-arch`

The backticks look somewhat inconsistent. But that may be due to invalid use of 
the @var and @option
constructs in the source. I'm not very familiar with the details.

Thanks,
Kyrill


as compared to:
https://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html#Option-Summary


Example of an option URL, for "-ftree-loop-if-convert-stores" (also
showing syntax-highlighted example code):
https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/options-that-control-optimization.html#cmdoption-ftree-loop-if-convert-stores

as compared to:
https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-ftree-loop-if-convert-1054 (where I 
had to use via "View Source" to find that URL, and what's up with that "-1054" 
wart? note also that the number can change, making the URL unstable)


Example of a stable URL for "What does -O2 do?":
https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/options-that-control-optimization.html#cmdoption-O2

...etc


Every HTML page also gets a "Show Source" link, showing the input
markup.


Sphinx is a modern, well-maintained documentation toolchain, implemented
in Python.  The input format is an easy minimal-markup "semantic"
format; the output is high-quality HTML, with PDF and texinfo supported
amongst other output formats.   It was created for documenting the
Python programming language, and is in use by many FLOSS projects for
their docs, including e.g. LLVM (http://llvm.org/docs/).  See also:
http://sphinx-doc.org/examples.html (though this list is far from
complete).   It's BSD-licensed.

We are currently using Sphinx for libgccjit:
   https://gcc.gnu.org/onlinedocs/jit/index.html
and, I believe, for Ada:
https://docs.adacore.com/gnat_ugn-docs/html/gnat_ugn/gnat_ugn.html [2]

I've also used it for generating slides for Cauldron presentations:
https://dmalcolm.fedorapeople.org/presentations/cauldron-2014/rtl/
https://dmalcolm.fedorapeople.org/presentations/cauldron-2014/jit/

and for gcc-python-plugin:
  https://gcc-python-plugin.readthedocs.org/en/latest/



I've written a tool called texi2rst which attempts to convert a .texi
based document to .rst ("restructured text", the input format for
Sphinx):
  https://github.com/davidmalcolm/texi2rst

This is what generated the examples above.

It doesn't *quite* do a direct .texi to .rst conversion yet: it can take
the XML output from texinfo's "makeinfo --xml", and generate either one
big .rst file, or a group of smaller .rst files.

My hope was that for every gcc/docs/foo.texi file we have, my tool would
be able to generate a gcc/docs/foo.rst (maybe retaining the name, to
allow for sane diff and hence sane patch review).

Unfortunately, "makeinfo --xml" resolves includes and conditional
processing, so the underlying input structure of .texinfo files is lost
at that point.

To fix that, I've been working on a frontend from texi2rst that
re-implements the .texi to xml processing, retaining information on
includes, and directives, so that I can translate them to
corresponding .rst directives.  Unfortunately it's clear that I'm not
going to finish that before stage 1 closes - but I think it's feasible
in the stage3 timeframe.

Hence in the example posted above, the doc is split into pages based on
nodes, named after the nodes, and thus get rather long names e.g.
options-that-control-optimization.html, generated from
options-that-control-optimization.rst.  In a more polished version,
these names would be saner.

The primary advantages of .rst/sphinx over .texi/texinfo I see are in
the generated HTML:

* sane, stable URLs (so e.g. there is a reliable URL for the docs for,
say, "-Wall").

* a page-splitting structure that make sense, to me, at least [3]

* much more use of markup, with restrained and well-chosen CSS
(texinfo's HTML seems 

Re: RFC: Experimental use of Sphinx for GCC documentation

[Arnaud Charlet]

> > We do have also a texi2rst script which handles 90% of the work, the
> > rest requiring manual adaptations. I can send the script we've used if
> > this can help.
> 
> I'm interested in seeing your script.  Can you post/upload it somewhere?

Yes I will. Let me get the latest version we've used and get back to you.

Arno

Re: RFC: Experimental use of Sphinx for GCC documentation

[David Malcolm]

On Mon, 2015-11-09 at 16:54 +, Kyrill Tkachov wrote:
> Hi David,
> 
> On 08/11/15 13:55, David Malcolm wrote:
> > I've been experimenting with using Sphinx [1] for GCC's documentation.
> >
> > You can see an HTML sample of GCC docs built with Sphinx here:
> > https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/gcc.html
> > (it's a work-in-progress; i.e. there are bugs).
> >
> > Compare with:
> >   https://gcc.gnu.org/onlinedocs/gcc/index.html
> >
> >
> > In particular, note how options get stable, clickable URLs:
> > https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/option-summary.html
> 
> FWIW, I think this all looks much better than the existing formatting.
> One weird artifact I noticed while looking at the ARM options:
> https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/hardware-models-and-configurations.html#arm-options
> In particular for -mcpu where it gives an explanation of what 
> -mcpu=generic- is equivalent to, there seems
> to be something weird going on.
> The .texi source is:
> @option{-mcpu=generic-@var{arch}} is also permissible, and is equivalent to 
> @option{-march=@var{arch} -mtune=generic-@var{arch}}.
> 
> Whereas the output looks something like:
> -mcpu=generic-``arch`` is also permissible, and is equivalent to 
> -march=``arch` -mtune=generic-arch`
> 
> The backticks look somewhat inconsistent. But that may be due to invalid use 
> of the @var and @option
> constructs in the source. I'm not very familiar with the details.

Thanks; I've filed this for myself as:
  https://github.com/davidmalcolm/texi2rst/issues/10

[...snip...]

Re: RFC: Experimental use of Sphinx for GCC documentation

[David Malcolm]

On Sun, 2015-11-08 at 16:16 +0100, Arnaud Charlet wrote:
> We've switched the Ada doc to sphinx indeed, so can only be
> in favor of this change for the rest of GCC.
> 
> We do have also a texi2rst script which handles 90% of the work, the
> rest requiring manual adaptations. I can send the script we've used if
> this can help.

I'm interested in seeing your script.  Can you post/upload it somewhere?

Thanks
Dave

Re: RFC: Experimental use of Sphinx for GCC documentation

[Arnaud Charlet]

> > > We do have also a texi2rst script which handles 90% of the work, the
> > > rest requiring manual adaptations. I can send the script we've used if
> > > this can help.
> > 
> > I'm interested in seeing your script.  Can you post/upload it somewhere?
> 
> Yes I will. Let me get the latest version we've used and get back to you.

Here it is. We've used it to convert many docs at AdaCore (including
gnat_ugn and gnat_rm.texi). It does require manual postprocessing but gives
a good headstart.

Arno
#!/usr/bin/python
# -*- coding: utf-8 -*-

"""Splits an existing .texinfo file into components suitable for
   makeinfo.py
   If "-node " is specified, only that node and its children are
   kept
"""

import re
import sys
import optparse
import os.path


def finish_section(out, section, section_node, marker, with_label):
if section_node == '' or section_node == 'Top':
return

# Create a label
if with_label:
out.write('.. _%s:\n\n' % section_node.replace(' ', '_'))

# Create header

if len(marker) == 2:
out.write(marker[0] * len(section_node) + '\n')

out.write(section_node + '\n')

out.write(marker[0] * len(section_node) + '\n\n')

list_level = 0
prev_was_blank = False
in_example = False
in_table = 0
in_menu = False
example_end = ''
table_marker = '*'

def word(line, index=1):
s = line.lstrip().split()
if len(s) >= index:
return s[index - 1]
else:
return ""

for line in section.strip().splitlines():
if word(line, 1) in ('@itemize', '@enumerate'):
list_level = list_level + 1
if not prev_was_blank:
out.write('\n')
prev_was_blank = False

elif line.lstrip().startswith('@end itemize') \
or line.lstrip().startswith('@end enumerate'):
list_level = list_level - 1
prev_was_blank = False

elif word(line, 1) == '@table':
out.write("\n")
table_marker = '*'
in_table += 1
prev_was_blank = True

elif in_table > 0 and line.lstrip().startswith('@end table'):
in_table -= 1
prev_was_blank = False

elif line.lstrip().startswith('@menu'):
out.write('.. toctree::\n')
out.write('   :numbered:\n')
out.write('   :maxdepth: 3\n')
out.write('\n')
in_menu = True

elif in_menu:
if line.startswith('@end menu'):
in_menu = False
else:
entry = re.sub('::.*', '', line)
entry = re.sub('^\* ', '', entry.strip())
entry = entry.replace(' ', '_').replace('/', '_')
out.write('   ' + entry + '\n')

elif word(line, 1) in (
"@deffn", "@defmethod", "@deftp", "@deftypemethod",
"@deffnx", "@defmethodx", "@deftypefn", "@defun"):

out.write(".. index:: %s\n\n" % line.lstrip().split(' ', 1)[1])
out.write(line.split(' ', 1)[1].strip() + '\n')

in_table += 1
table_marker = '`'

elif in_table > 0 \
and word(line, 1) in ("@end") \
and word(line, 2) in (
   "deffn", "defmethod", "deftp", "deftypemethod",
   "deffnx", "defmethodx", "deftypefn", "defun"):
in_table -= 1

elif word(line, 1) in ('@item', '@itemx'):
line = line.lstrip().replace('@itemx', '')
line = line.replace('@item', '')

if in_table > 0:
if line.strip().startswith(table_marker):
# Avoid lines like  "**Bold* text*" which of course
# sphinx doesn't like
table_marker = ""

out.write('\n%s%s%s\n' % (
table_marker, line.strip(), table_marker))
prev_was_blank = True
else:
out.write('  ' * (list_level - 1) + '* ' + line.strip() + '\n')
prev_was_blank = False

elif line.strip() == '':
if not prev_was_blank:
out.write('\n')
prev_was_blank = True

else:
if '@example' in line:
in_example = True
example_end = '@end example'
out.write('  ' * list_level + '::\n\n')
continue
elif '@smallexample' in line:
in_example = True
example_end = '@end smallexample'
out.write('\n' + '  ' * list_level + '::\n\n')
continue
elif '@CODESAMPLE{' in line:
line = line.replace("@CODESAMPLE{", "")
example_end = '}'
in_example = True
out.write('\n')
out.write('  ' * list_level + ".. highlight:: ada\n\n")
out.write('  ' * list_level + '::\n\n')

elif 

Re: RFC: Experimental use of Sphinx for GCC documentation

[Sandra Loosemore]

On 11/08/2015 06:55 AM, David Malcolm wrote:

I've been experimenting with using Sphinx [1] for GCC's documentation.

[snip]

The primary advantages of .rst/sphinx over .texi/texinfo I see are in
the generated HTML:

* sane, stable URLs (so e.g. there is a reliable URL for the docs for,
say, "-Wall").

* a page-splitting structure that make sense, to me, at least [3]

* much more use of markup, with restrained and well-chosen CSS
(texinfo's HTML seems to ignore much of the inline markup in
the .texinfo file)

* autogenerated internal links, so that almost everything is clickable,
and will take you somewhere sane, by default

* syntax-highlighting of code examples, with support for multiple
programming languages (note the mixture of C, C++, Fortran, etc in the
docs for the gcc options).

* looks modern and fresh (IMHO), letting casual observers see that the
project is alive and kicking.


Thoughts?


If we're going to switch documentation formats, I'd rather we used 
DocBook.  I've had to use "restructured text" before and found it really 
awkward.


But, personal preferences aside, I also think it's more important that 
we commit documentation-person resources to making the content more 
correct, readable, and better organized, than to making the HTML output 
look "modern and fresh", or worse yet, translating the docs to another 
format and having to proofread them for conversion goofs.


BTW, Mentor Graphics' toolchains ship with a custom HTML stylesheet for 
the generated manuals, to make them a little "prettier".  Maybe 
something like that would go a long way towards solving the perceived 
problems here?  Or improvements to texinfo's HTML generation.


-Sandra

Re: RFC: Experimental use of Sphinx for GCC documentation

[Joseph Myers]

On Sun, 8 Nov 2015, David Malcolm wrote:

> I've been experimenting with using Sphinx [1] for GCC's documentation.
> 
> You can see an HTML sample of GCC docs built with Sphinx here:
> https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/gcc.html
> (it's a work-in-progress; i.e. there are bugs).

Observations:

* Could you provide the PDF version there as well?

* The option summary 

 
seems a complete mess.

* The indexes are missing.

> It doesn't *quite* do a direct .texi to .rst conversion yet: it can take
> the XML output from texinfo's "makeinfo --xml", and generate either one
> big .rst file, or a group of smaller .rst files.
> 
> My hope was that for every gcc/docs/foo.texi file we have, my tool would
> be able to generate a gcc/docs/foo.rst (maybe retaining the name, to
> allow for sane diff and hence sane patch review).
> 
> Unfortunately, "makeinfo --xml" resolves includes and conditional
> processing, so the underlying input structure of .texinfo files is lost
> at that point.
> 
> To fix that, I've been working on a frontend from texi2rst that
> re-implements the .texi to xml processing, retaining information on
> includes, and directives, so that I can translate them to
> corresponding .rst directives.  Unfortunately it's clear that I'm not
> going to finish that before stage 1 closes - but I think it's feasible
> in the stage3 timeframe.

You do of course need to convert documentation fragments in target.def 
in-place and adapt genhooks (preserving the arrangements of both tm.rst.in 
and tm.rst being checked in, or some other such arrangement that ensures 
there are always both GPL and GFDL copies of the hook documentation 
checked in, with genhooks dealing with keeping them in sync).  Other 
things to consider: preserving comments (where applicable); preserving 
@ignore contents (where the function is to comment out text); keeping 
manpage generation (which currently uses @c man comments together with 
@ignore) working; keeping --with-pkgversion and --with-bugurl working; 
keeping the principle that BASE-VER is the only checked-in file with the 
version number and everything else gets the version number at build time; 
dealing with the INTERNALS conditionals in files used in multiple manuals 
(and some others such as cppmanual conditionals).

-- 
Joseph S. Myers
jos...@codesourcery.com

Re: RFC: Experimental use of Sphinx for GCC documentation

[Arnaud Charlet]

We've switched the Ada doc to sphinx indeed, so can only be
in favor of this change for the rest of GCC.

We do have also a texi2rst script which handles 90% of the work, the
rest requiring manual adaptations. I can send the script we've used if
this can help.

Arno

RFC: Experimental use of Sphinx for GCC documentation

[David Malcolm]

I've been experimenting with using Sphinx [1] for GCC's documentation.

You can see an HTML sample of GCC docs built with Sphinx here:
https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/gcc.html
(it's a work-in-progress; i.e. there are bugs).

Compare with:
 https://gcc.gnu.org/onlinedocs/gcc/index.html


In particular, note how options get stable, clickable URLs:
https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/option-summary.html

as compared to:
https://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html#Option-Summary


Example of an option URL, for "-ftree-loop-if-convert-stores" (also
showing syntax-highlighted example code):
https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/options-that-control-optimization.html#cmdoption-ftree-loop-if-convert-stores

as compared to:
https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-ftree-loop-if-convert-1054
 (where I had to use via "View Source" to find that URL, and what's up with 
that "-1054" wart? note also that the number can change, making the URL 
unstable)


Example of a stable URL for "What does -O2 do?":
https://dmalcolm.fedorapeople.org/gcc/2015-08-31/rst-experiment/options-that-control-optimization.html#cmdoption-O2

...etc


Every HTML page also gets a "Show Source" link, showing the input
markup.


Sphinx is a modern, well-maintained documentation toolchain, implemented
in Python.  The input format is an easy minimal-markup "semantic"
format; the output is high-quality HTML, with PDF and texinfo supported
amongst other output formats.   It was created for documenting the
Python programming language, and is in use by many FLOSS projects for
their docs, including e.g. LLVM (http://llvm.org/docs/).  See also:
http://sphinx-doc.org/examples.html (though this list is far from
complete).   It's BSD-licensed.

We are currently using Sphinx for libgccjit:
  https://gcc.gnu.org/onlinedocs/jit/index.html
and, I believe, for Ada:
https://docs.adacore.com/gnat_ugn-docs/html/gnat_ugn/gnat_ugn.html [2]

I've also used it for generating slides for Cauldron presentations:
https://dmalcolm.fedorapeople.org/presentations/cauldron-2014/rtl/
https://dmalcolm.fedorapeople.org/presentations/cauldron-2014/jit/

and for gcc-python-plugin:
 https://gcc-python-plugin.readthedocs.org/en/latest/



I've written a tool called texi2rst which attempts to convert a .texi
based document to .rst ("restructured text", the input format for
Sphinx):
 https://github.com/davidmalcolm/texi2rst

This is what generated the examples above.

It doesn't *quite* do a direct .texi to .rst conversion yet: it can take
the XML output from texinfo's "makeinfo --xml", and generate either one
big .rst file, or a group of smaller .rst files.

My hope was that for every gcc/docs/foo.texi file we have, my tool would
be able to generate a gcc/docs/foo.rst (maybe retaining the name, to
allow for sane diff and hence sane patch review).

Unfortunately, "makeinfo --xml" resolves includes and conditional
processing, so the underlying input structure of .texinfo files is lost
at that point.

To fix that, I've been working on a frontend from texi2rst that
re-implements the .texi to xml processing, retaining information on
includes, and directives, so that I can translate them to
corresponding .rst directives.  Unfortunately it's clear that I'm not
going to finish that before stage 1 closes - but I think it's feasible
in the stage3 timeframe.

Hence in the example posted above, the doc is split into pages based on
nodes, named after the nodes, and thus get rather long names e.g.
options-that-control-optimization.html, generated from
options-that-control-optimization.rst.  In a more polished version,
these names would be saner.

The primary advantages of .rst/sphinx over .texi/texinfo I see are in
the generated HTML:

* sane, stable URLs (so e.g. there is a reliable URL for the docs for,
say, "-Wall").

* a page-splitting structure that make sense, to me, at least [3]

* much more use of markup, with restrained and well-chosen CSS
(texinfo's HTML seems to ignore much of the inline markup in
the .texinfo file)

* autogenerated internal links, so that almost everything is clickable,
and will take you somewhere sane, by default

* syntax-highlighting of code examples, with support for multiple
programming languages (note the mixture of C, C++, Fortran, etc in the
docs for the gcc options).

* looks modern and fresh (IMHO), letting casual observers see that the
project is alive and kicking.


Thoughts?
Dave

[1] http://sphinx-doc.org/
[2] I couldn't find Sphinx-built HTML for Ada on the gcc website, just
the Texinfo output here:
https://gcc.gnu.org/onlinedocs/gnat_ugn/index.html
[3] I have never fathomed the way texinfo's navigation works, for HTML,
at least, and I believe I'm not the only one; I generally pick the
all-in-one-HTML-page option when viewing texinfo-html docs and do
textual searches, since otherwise I usually can't find the thing I'm
looking for (or have