Re: RFC: Experimental use of Sphinx for GCC documentation

[David Malcolm <dmalcolm at redhat dot com>]

On Mon, 2015-11-09 at 16:54 +0000, 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-<arch> 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...]