Re: GCC documentation: porting to Sphinx

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

On 6/2/21 7:27 PM, Joseph Myers wrote:
> On Mon, 31 May 2021, Martin Liška wrote:
> 
>> https://splichal.eu/scripts/sphinx/
> 
> Looking at some examples there:
> 
> https://splichal.eu/scripts/sphinx/gcc/_build/html/c-implementation-defined-behavior/preprocessing-directives.html
> has some conversion problems:
> 
> * "See Implementation-defined behavior, for details of these aspects of
> implementation-defined behavior." is missing the link to the relevant
> section of the cpp manual that's present in the Texinfo source.

Yes, I'm aware of various cross-manual links that are currently not working.
It will likely require an extension called Intersphinx:
https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

> 
> * "` character before the :samp:`" is a misconversion (whether from
> Texinfo to RST or from RST to HTML) of the Texinfo source
> 
>    @samp{\} character before the @samp{\}
> 
> which will need to be fixed.

Yes, I fixed various :samp:, :option: leftovers all over the documentation.

> 
> * The corresponding PDF has the same issues as above (so probably they are
> issues with the conversion to RST, not with Sphinx itself).  In addition,
> the PDF manual ought to be using fixed-width fonts for literal code,
> command-line options, etc., just like the HTML manual, and the
> Texinfo-generated PDF manual, are.

Hm, I think the generated PDF properly uses a fixed-width font for option names,
commands and so one. Moreover, option directives are bold, while links to them
use normal font. I see the default font selection made by Sphinx readable.

> 
> https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/passing-options-to-the-assembler.html
> shows headings such as "-Wa,option, -Wa".  The ", -Wa" doesn't make sense,
> this option is just "-Wa,option".

I fixed various these issues.

> 
> https://splichal.eu/scripts/sphinx/gcc/_build/html/gcov-a-test-coverage-program.html
> has a hyphen between "gcov" and "a Test Coverage Program" in the heading.
> It should be an em dash, as in Texinfo.

Oh yeah. Apparently, we can use "smart quotes" (-- and ---) for dashes:
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-smartquotes

Fixed that in the current version.

> 
> https://splichal.eu/scripts/sphinx/gcc/_build/html/language-standards-supported-by-gcc/c%2B%2B-language.html
> has doubled slashes in various URLs where the Texinfo source has /@/
> (Texinfo @/ means "allow line break", it should not be translated to /).

Good point, also fixed.

> 
> https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/machine-dependent-options/aarch64-options.html
> shows different formatting for the headings for "-mlow-precision-div,
> -mno-low-precision-div" and "-mtrack-speculation -mno-track-speculation".
> The formatting should be identical.  The only difference in the Texinfo
> source seems to be that the latter is missing @opindex directives.  And
> while it's a bug in the Texinfo source that those directives are missing,
> the presence or absence of index entries should not affect the formatting
> of the documentation for those options.

As discussed with Martin Sebor, I emitted non-default option directive.

> 
> On that same page, the output for -march=name is broken, containing a
> literal :samp:{feature} (in general, checking for any places where RST
> directives such as :samp: appear in the HTML output might be a good idea
> to look for broken conversions).  The Texinfo source here has
> 
> @option{-march=@var{arch}@r{@{}+@r{[}no@r{]}@var{feature}@r{@}*}}
> 
> (where the use of @r{...} is to put the {}[]* characters in a
> variable-width font, since they are not literally part of the option,
> while the other characters that are literally part of the option should be
> in a variable-width font).

Also fixed.

> 
> https://splichal.eu/scripts/sphinx/gcc/_build/html/language-standards-supported-by-gcc/references-for-other-languages.html
> has literal unconverted "@c man" and "@include" and other Texinfo
> directives.  Searching for such things in the HTML output (or the RST
> sources) is a good idea, just like searching for literal RST directives in
> the HTML output, to find other such conversion bugs.

Clean up these.

> 
> https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options.html
> says "See option-index", another case with a link that didn't get
> converted properly.  It also has raw :samp: uses indicating a
> misconversion.
> 
> I'm not sure how you're determining languages for code-block, but
> https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-control-diagnostic-messages-formatting.html
> certainly shows some cases where they have been misidentified (e.g. random
> C++ keywords highlighted in the default GCC_COLORS, some JSON being
> highlighted as such but other JSON not).

I fixed all code-block warnings. Some of JSON syntax highlighting was not working because
the JSON syntax was invalid. Should be fine:
https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-control-diagnostic-messages-formatting.html#cmdoption-fdiagnostics-format

> 
>> - a shared content is factored out ([4])
>> - conditional build is fully supported (even for shared parts)
>> - manual pages look reasonable well
>> - folders are created for files which have >= 5 TOC tree entries
>> - various formatting issues were resolved
>> - baseconf.py reads BASE-VER, DEV-PHASE, .. files
> 
> Could you give more detailed descriptions of how each of the various
> issues I listed in 2015 are addressed here?

Sure:

1) documentation fragments in target.def
I've got a script that rewrites them to RST format and we'll use the slightly modified
gcc/genhooks.c for replacement.

2) comments
Are preserved by the conversion tool.

3) man pages support and @ignore
That's done, we have shared content and conditional build (..only directive).

4) support for BASE-VER, DATESTAMP, DEV-PHASE

It's read right now in baseconf.py, we need to add support for bugurl and package_version,
it won't be difficult.

> 
> https://gcc.gnu.org/legacy-ml/gcc-patches/2015-11/msg01139.html
> 
>> I've got couple of questions:
>>
>> 1) Do we have to you the following cover text?
>>         Copyright (c) 1988-2020 Free Software Foundation, Inc.
>>
>>         Permission is granted to copy, distribute and/or modify this document
>> under the terms of the GNU Free Documentation License, Version 1.3 or any
>> later version published by the Free Software Foundation; with the Invariant
>> Sections being "GNU General Public
>>         License" and "Funding Free Software", the Front-Cover texts being (a)
>> (see below), and with the Back-Cover Texts being (b) (see below).  A copy of
>> the license is included in the gfdl(7) man page.
>>
>>         (a) The FSF's Front-Cover Text is:
>>
>>              A GNU Manual
>>
>>         (b) The FSF's Back-Cover Text is:
>>
>>              You have freedom to copy and modify this GNU Manual, like GNU
>>              software.  Copies published by the Free Software Foundation raise
>>              funds for GNU development.
> 
> We need to keep the Cover Texts and Invariant Sections, in the absence of
> FSF approval to remove them.

Added that to copyright.rst file.

> 
>> 2) Do we want to generate fsf-funding, gpl and gfdl manual pages?
> 
> Yes, this is how the set of man pages as a whole keeps the invariant
> sections.

Done.

> 
>> 3) Do we want to preserve the current strange copy mechanism for
>> ./gcc/doc/tm.texi.in ?
> 
> Yes, this is how we ensure we have both GPL and GFDL copies of the target
> hook documentation checked in and that someone copying from one place to
> another makes sure they have any relevant permissions.

As mentioned, it will be supported.

> 
>> 4) Do we want a copyright header for the created .rst files?
> 
> Yes, all source files should have a copyright header.
> 

Done.

@Joseph: May I ask you for another round of review? The generated pages are quite fine,
I addressed various smaller issues. Hopefully we are quite close to something that can
be send to gcc-patches.

Another set of questions I have:

1) Can we organize the new documentation in $gccroot/doc folder similarly to what
I have in texi2rst-generated repo? Would be beneficial as we can have a single Makefile
and shared content will be in a same depth to the individual manuals.

2) About libiberty - who's in charge of the library? Is it GCC community? I'm asking
if we want to migrate to Sphinx as well?

Thanks,
Martin