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
