Re: GCC documentation: porting to Sphinx

[Joseph Myers <joseph@codesourcery.com>]

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.

* "` 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.

* 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.

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".

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.

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 /).

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.

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

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.

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

> - 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?

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.

> 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.

> 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.

> 4) Do we want a copyright header for the created .rst files?

Yes, all source files should have a copyright header.

-- 
Joseph S. Myers
joseph@codesourcery.com