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 jos...@codesourcery.com
