Re: GCC documentation: porting to Sphinx
On 8/10/21 17:43, Martin Liška wrote:
Hello.
I've just pushed the rebased branch here:
https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;a=log;h=refs/users/marxin/heads/sphinx-v4
which I force push once I rebase it. One can fetch the branch with:
$ git fetch origin refs/users/marxin/heads/sphinx-v4
Hello.
There's updated version of the patch set sitting here:
refs/users/marxin/heads/sphinx-v5
Generated output (directly made from GCC source tree) can be seen here:
https://splichal.eu/gccsphinx-final/
And can be seen here.
Changes since the previous version:
1) rebased on the current master (including addition of new target hooks, etc.)
2) two new directive/roles were added in order to not abuse 'option' directive:
gcc-attr (function/label/... attribute) and gcc-param (--param foo=bar).
Addition was quite straightforward and we would benefit as these attributes
and parameters will be listed grouped in the Index:
https://splichal.eu/gccsphinx-final/html/gcc/genindex.html
3) default syntax language was set to 'none'; made issue for e.g. chunks in
license pages
where a random Python keywords were highlighted
Changes since the previous version:
1) Cross manual references are working. It works surprisingly well and we have
much more cross references now
(for things like options, ...).
2) I have a new version of update_web_docs_git that will be very simple:
make -C doc html/pdf SOURCEDIR=... BUILDDIR=...
3) URL link creating was updated in diagnostics.c
4) I have a patch candidate that skips links in Info format:
https://github.com/sphinx-doc/sphinx/pull/9578
5) default domain was switched to cpp and Sphinx community fixed various issues
mentioned in:
https://github.com/sphinx-doc/sphinx/issues/9535
6) I made one round of proof-reading of the manuals where I focused on the
formatting issues
What needs to be done (TODO list):
1) Cross manual references are missing - we have some of them and Sphinx has
nice support for it:
https://docs.readthedocs.io/en/stable/guides/intersphinx.html
2) Remove `Texinfo Manuals` section in GCC internal manual
3) Document required packages for PDF, MAN, HTML, ..
4) Write How to write documentation, we can take inspiration from Kernel:
https://www.kernel.org/doc/html/latest/doc-guide/index.html
5) Update update_web_docs_git - that will simply run Sphinx' Makefile
6) URL emission code needs to be changed in diagnostics.c
7) link emission should be ignored in Info builder
8) epub target should be added to Makefiles
9) function/struct/type attribute definition should be simplified as
:gcc-attr: attr_name ("options")
does not work with a reference to it: :gcc-atr:`attr_name`
An attribute format should be placed into the attr description.
10) default domain should be switched to cpp, will lead to warnings as seen
here:
https://github.com/sphinx-doc/sphinx/issues/9535
11) many function and macros in gccint should promoted to '.. function::' and
'.. macro::' directive
12) various smaller formatting issues need to be addressed
What needs to be done (TODO list):
1) Remove `Texinfo Manuals` section in GCC internal manual
2) Document required packages for PDF, MAN, HTML, ..
3) Write How to write documentation, we can take inspiration from Kernel:
https://www.kernel.org/doc/html/latest/doc-guide/index.html
4) epub target should be added to Makefiles
5) function/struct/type attribute definition should be simplified as
:gcc-attr: attr_name ("options")
does not work with a reference to it: :gcc-atr:`attr_name`
An attribute format should be placed into the attr description.
6) many function and macros in gccint should promoted to '.. function::' and
'.. macro::' directive (partialy done)
Thoughts about current status of the migration process?
Thanks,
Martin
Known limitations:
1) chapter description (in TOC listing) is dropped in info pages
2) PDF output puts item description on the same line as item definition -
noticed by Tamar
As previously mentioned, I'm willing to work on the majority of the points
mentioned in the TODO list.
Now I see the current patchset in a reasonable shape and I'm asking the
community for approval of the changes?
And I would appreciate a help with any of the items listed in the TODO list.
Thanks,
Martin
Re: GCC documentation: porting to Sphinx
Hello.
I've just pushed the rebased branch here:
https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;a=log;h=refs/users/marxin/heads/sphinx-v4
which I force push once I rebase it. One can fetch the branch with:
$ git fetch origin refs/users/marxin/heads/sphinx-v4
Generated output (directly made from GCC source tree) can be seen here:
https://splichal.eu/gccsphinx-final/
Changes since the previous version:
1) rebased on the current master (including addition of new target hooks, etc.)
2) two new directive/roles were added in order to not abuse 'option' directive:
gcc-attr (function/label/... attribute) and gcc-param (--param foo=bar).
Addition was quite straightforward and we would benefit as these attributes
and parameters will be listed grouped in the Index:
https://splichal.eu/gccsphinx-final/html/gcc/genindex.html
3) default syntax language was set to 'none'; made issue for e.g. chunks in
license pages
where a random Python keywords were highlighted
What needs to be done (TODO list):
1) Cross manual references are missing - we have some of them and Sphinx has
nice support for it:
https://docs.readthedocs.io/en/stable/guides/intersphinx.html
2) Remove `Texinfo Manuals` section in GCC internal manual
3) Document required packages for PDF, MAN, HTML, ..
4) Write How to write documentation, we can take inspiration from Kernel:
https://www.kernel.org/doc/html/latest/doc-guide/index.html
5) Update update_web_docs_git - that will simply run Sphinx' Makefile
6) URL emission code needs to be changed in diagnostics.c
7) link emission should be ignored in Info builder
8) epub target should be added to Makefiles
9) function/struct/type attribute definition should be simplified as
:gcc-attr: attr_name ("options")
does not work with a reference to it: :gcc-atr:`attr_name`
An attribute format should be placed into the attr description.
10) default domain should be switched to cpp, will lead to warnings as seen
here:
https://github.com/sphinx-doc/sphinx/issues/9535
11) many function and macros in gccint should promoted to '.. function::' and
'.. macro::' directive
12) various smaller formatting issues need to be addressed
Known limitations:
1) chapter description (in TOC listing) is dropped in info pages
2) PDF output puts item description on the same line as item definition -
noticed by Tamar
As previously mentioned, I'm willing to work on the majority of the points
mentioned in the TODO list.
Now I see the current patchset in a reasonable shape and I'm asking the
community for approval of the changes?
And I would appreciate a help with any of the items listed in the TODO list.
Thanks,
Martin
Re: GCC documentation: porting to Sphinx
On 6/29/21 5:54 PM, Arnaud Charlet wrote:
In particular can you explain the motivation behind all the changes in the
gcc/ada/doc directory?
Sure:
1) All Sphinx manuals live in a directory where index page is called index.rst.
That's why
I moved e.g. this: gcc/ada/doc/{gnat_rm.rst => gnat_rm/index.rst}
2) I moved latex_elements.py to ada_latex_elements.py as it clashes with Sphinx
global variable
you modify in Sphinx config files
3) I created a shared Ada config (adabaseconf.py) that extends doc/baseconf.py
and sets what
is shared in between 3 Ada manuals.
4) gnu_free_documentation_license.rst is taken from $root/doc/
OK, this is really lots of changes, if we could minimize these changes
that would be best (and sorry but posting a link to a tarball also doesn't
help reviews, it was actually better with a link to a git repo previously...
All right, ideally please pull my branch:
https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;a=log;h=refs/users/marxin/heads/sphinx-v4
which I force push once I rebase it. One can fetch the branch with:
$ git fetch origin refs/users/marxin/heads/sphinx-v4
At least the Ada part itself shouldn't be too big in particular once
simplified so could be posted standalone).
Sorry, but the patch is still 400 kB when using zstd -22. Actually, the change
is very small
if you ignore renames of the 3 files:
gcc/ada/gnat-style.texi| 954
gcc/ada/gnat_rm.texi | 29822
gcc/ada/gnat_ugn.texi | 29232
The only significant change is refactoring of the conf.py config.
Martin
Arno
Re: GCC documentation: porting to Sphinx
> >In particular can you explain the motivation behind all the changes in the
> >gcc/ada/doc directory?
>
> Sure:
> 1) All Sphinx manuals live in a directory where index page is called
> index.rst. That's why
> I moved e.g. this: gcc/ada/doc/{gnat_rm.rst => gnat_rm/index.rst}
> 2) I moved latex_elements.py to ada_latex_elements.py as it clashes with
> Sphinx global variable
> you modify in Sphinx config files
> 3) I created a shared Ada config (adabaseconf.py) that extends
> doc/baseconf.py and sets what
> is shared in between 3 Ada manuals.
> 4) gnu_free_documentation_license.rst is taken from $root/doc/
OK, this is really lots of changes, if we could minimize these changes
that would be best (and sorry but posting a link to a tarball also doesn't
help reviews, it was actually better with a link to a git repo previously...
At least the Ada part itself shouldn't be too big in particular once
simplified so could be posted standalone).
Arno
Re: GCC documentation: porting to Sphinx
On 6/28/21 12:23 PM, Arnaud Charlet wrote:
I've got something that is very close to be a patch candidate that can be
eventually merged. Right now, the patches are available here:
https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;a=log;h=refs/users/marxin/heads/sphinx-v3
FWIW I would prefer to review the changes posted here directly with all
the details.
Sure, I'm going to send a proper patch set in an hour or so. As mentioned, I
won't be able to attach
some of the patches as they will exceed 1MB email limit.
In particular can you explain the motivation behind all the changes in the
gcc/ada/doc directory?
Sure:
1) All Sphinx manuals live in a directory where index page is called index.rst.
That's why
I moved e.g. this: gcc/ada/doc/{gnat_rm.rst => gnat_rm/index.rst}
2) I moved latex_elements.py to ada_latex_elements.py as it clashes with Sphinx
global variable
you modify in Sphinx config files
3) I created a shared Ada config (adabaseconf.py) that extends doc/baseconf.py
and sets what
is shared in between 3 Ada manuals.
4) gnu_free_documentation_license.rst is taken from $root/doc/
That's lots of moving files around, so I'd like
to understand why and make sure these are not gratuituous changes, since
move files around is always tricky and I'd rather not have to undo it
later in case this causes troubles or have unexpected consequences.
Hope I explained all the reasonable changes?
Otherwise, glad to see the switch to sphinx finally moving in gcc!
You're welcome. I would be interested in testing your PRO configuration (based
on Gnat_Build_Type,
see get_gnat_build_type) and I'm curious if you're fine with Sphinx template
change?
It will be the same as for other manuals.
Cheers,
Martin
Arno
Re: GCC documentation: porting to Sphinx
> I've got something that is very close to be a patch candidate that can be > eventually merged. Right now, the patches are available here: > https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;a=log;h=refs/users/marxin/heads/sphinx-v3 FWIW I would prefer to review the changes posted here directly with all the details. In particular can you explain the motivation behind all the changes in the gcc/ada/doc directory? That's lots of moving files around, so I'd like to understand why and make sure these are not gratuituous changes, since move files around is always tricky and I'd rather not have to undo it later in case this causes troubles or have unexpected consequences. Otherwise, glad to see the switch to sphinx finally moving in gcc! Arno
Re: GCC documentation: porting to Sphinx
On 6/25/21 3:11 PM, Martin Liška wrote: List of known issues (planned to be fixed after merging): I forgot about: - diagnostics URL (for e.g. warnings) needs to be adjusted Martin
Re: GCC documentation: porting to Sphinx
Hello. I've got something that is very close to be a patch candidate that can be eventually merged. Right now, the patches are available here: https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;a=log;h=refs/users/marxin/heads/sphinx-v3 Changes since last version: - gdc manual was ported - 'make doc' works fine both with and w/o installed sphinx-build - 'make pdf' and 'make html' works fine - libgccjit was ported to the shared Makefile and configuration - likewise for 3 existing Ada manuals - .texi files are removed List of known issues (planned to be fixed after merging): - cross manual references are not working - update_web_docs_git needs to be changed - will simplify rapidly - Sphinx warnings should be addressed - remove texinfo references in Manuals - list package requirements for Sphinx manual generation I'm looking forward to a feedback. Thanks, Martin
Re: GCC documentation: porting to Sphinx
On 6/23/21 6:00 PM, Joseph Myers wrote: On Wed, 23 Jun 2021, Martin Liška wrote: @Joseph: Can you share your thoughts about the used Makefile integration? What do you suggest for 2) (note that explicit listing of all .rst file would be crazy)? You can write dependencies on e.g. doc/gcc/*.rst (which might be more files than actually are relevant in some cases, if the directory includes some common files shared by some but not all manuals, but should be conservatively safe if you list appropriate directories there), rather than needing to name all the individual files. Doing things with makefile dependencies seems better than relying on what sphinx-build does when rerun unnecessarily (if sphinx-build avoids rebuilding in some cases where the makefiles think a rebuild is needed, that's fine as an optimization). All right. I've just done that and it was easier than I expected. Now the dependencies are properly followed. It looks like this makefile integration loses some of the srcinfo / srcman support. That support should stay (be updated for the use of Sphinx) so that release tarballs (as generated by maintainer-scripts/gcc_release, which uses --enable-generated-files-in-srcdir) continue to include man pages / info files (and make sure that, if those files are present in the source directory, then building and installing GCC does install them even when sphinx-build is absent at build/install time). Oh, and I've just recovered this one as well. Pushed changes to the me/sphinx-v2 branch and I'm waiting for more feedback. In the meantime, I'm going to prepare further integration of other manuals and targets (PDF, HTML). Martin
Re: GCC documentation: porting to Sphinx
On Wed, 23 Jun 2021, Martin Liška wrote: > @Joseph: Can you share your thoughts about the used Makefile integration? What > do you suggest for 2) > (note that explicit listing of all .rst file would be crazy)? You can write dependencies on e.g. doc/gcc/*.rst (which might be more files than actually are relevant in some cases, if the directory includes some common files shared by some but not all manuals, but should be conservatively safe if you list appropriate directories there), rather than needing to name all the individual files. Doing things with makefile dependencies seems better than relying on what sphinx-build does when rerun unnecessarily (if sphinx-build avoids rebuilding in some cases where the makefiles think a rebuild is needed, that's fine as an optimization). It looks like this makefile integration loses some of the srcinfo / srcman support. That support should stay (be updated for the use of Sphinx) so that release tarballs (as generated by maintainer-scripts/gcc_release, which uses --enable-generated-files-in-srcdir) continue to include man pages / info files (and make sure that, if those files are present in the source directory, then building and installing GCC does install them even when sphinx-build is absent at build/install time). -- Joseph S. Myers jos...@codesourcery.com
Re: GCC documentation: porting to Sphinx
Hello. I've just made a first version of the patchset that sits in GCC source tree: https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;a=log;h=refs/users/marxin/heads/sphinx-v2 Changes since the last submission: 1) I made a brief proofreading and fixed most of the formatting and other issues 2) target hook documentation was ported to RST format and gcc/genhooks generated a tm.rst.in that is then used via .. include:: directives 3) sphinx-build detection is implemented in gcc/configure.ac 3) make integration is done (currently covering info and man pages) for gcc and gcc/fortran targets As before, one can see the result of generated output here: https://splichal.eu/scripts/sphinx/ Known limitations: 1) I found a bug in man page generation that is currently fixed: https://github.com/sphinx-doc/sphinx/issues/1860#issuecomment-861793094 Note the fix will appear in the upcoming 4.1.0 release. Without the patch, one can see wrong font selection in a generated manual page 2) Right now, I rely on caching capability of sphinx-build. That means when no source change is detected, sphinx-build exits immediately. However, it's not working for all targets (info, man) and I've suggested a patch for it: https://github.com/sphinx-doc/sphinx/issues/9359 3) I haven't prepared patch for .texi removal (should be quite easily doable). 4) the currently existing Sphinx manuals (Ada and libgccjit) are not integrated yet. @Joseph: Can you share your thoughts about the used Makefile integration? What do you suggest for 2) (note that explicit listing of all .rst file would be crazy)? Thoughts? Thanks, Martin
Re: GCC documentation: porting to Sphinx
> On Jun 11, 2021, at 11:50 AM, Joseph Myers wrote: > > ... > > "make" at top level should build all the info manuals and man pages, as at > present (if a suitable Sphinx version is installed), and "make install" > should install them, in the same directories as at present. > > "make html" at top level should build all the HTML manuals, and "make > install-html" should install them. > > "make pdf" and "make install-pdf" at top level should work likewise. > > "make install-html" and "make install-pdf" should put things under > $(DESTDIR)$(htmldir) and $(DESTDIR)$(pdfdir) as at present. And in addition, it would be nice to have additional make and make install- targets for other output formats that Sphinx can generate for us, at least some of them. "epub" comes to mind as an example I would like to have. paul
Re: GCC documentation: porting to Sphinx
On Fri, 11 Jun 2021, Martin Liška wrote: > > Where languages have their own manuals, I think it's more appropriate for > > those to go under the language-specific directories. > > So it will require the following folder structure: > > $gccroot/gcc/doc/gcc - for GCC documentation > $gccroot/gcc/doc/gccint - for GCC internal documentation > $gccroot/gcc/doc/gfortran - for Fortran documentation > $gccroot/gcc/doc/gccgo - for GO documentation I'm thinking of $gccroot/gcc/fortran/doc $gccroot/gcc/go/doc (or subdirectories thereof if desired) for the Fortran and Go manuals, so they go alongside the front end sources. > The Sphinx Makefile will be capable of e.g. My concern with makefiles is what the main GCC build system does, with "make" run at the top level of the build tree and with the targets defined by the GNU Coding Standards, not with what happens if someone manually does make in a subdirectory of the source or build tree. "make" at top level should build all the info manuals and man pages, as at present (if a suitable Sphinx version is installed), and "make install" should install them, in the same directories as at present. "make html" at top level should build all the HTML manuals, and "make install-html" should install them. "make pdf" and "make install-pdf" at top level should work likewise. "make install-html" and "make install-pdf" should put things under $(DESTDIR)$(htmldir) and $(DESTDIR)$(pdfdir) as at present. -- Joseph S. Myers jos...@codesourcery.com
Re: GCC documentation: porting to Sphinx
On 6/11/21 1:48 AM, Martin Sebor wrote: On 6/10/21 7:18 AM, Martin Liška wrote: On 6/10/21 11:07 AM, Martin Liška wrote: Doing that, one has 2 unique links, that would be needed for get_option_url function. Plus, both :option:`-Wfoo` and :option:`-Wno-foo` references are going to work. And I've actually did the transformation and one can see it e.g. here: https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wprio-ctor-dtor I find the style you have below right now clearer than keeping both options in the same heading and adding a Note explaining the default etc. I.e., this _ -Wchar-subscripts Warn if an array subscript has type char. This is a common cause of error, as programmers often forget that this type is signed on some machines. This warning is enabled by -Wall. -Wno-char-subscripts Default option value for -Wchar-subscripts. Yes, fully agree with you! Thanks, Martin on this page right now: https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wchar-subscripts seems better than this: _ -Wno-shift-overflow, -Wshift-overflow=n, -Wshift-overflow +--+ | (!) Note | +--- | Default value is -Wno-shift-overflow, -Wshift-overflow is | | enabled by -Wall. | +--+ These options control warnings about left shift overflows. and also better than the alternative with (non-default) after the option in the heading. https://splichal.eu/scripts/sphinx/demo/_build/html/#cmdoption-Wno-shift-overflow3 Martin Martin
Re: GCC documentation: porting to Sphinx
On 6/10/21 6:49 PM, Joseph Myers wrote:
On Thu, 10 Jun 2021, Martin Liška wrote:
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.
Where languages have their own manuals, I think it's more appropriate for
those to go under the language-specific directories.
So it will require the following folder structure:
$gccroot/gcc/doc/gcc - for GCC documentation
$gccroot/gcc/doc/gccint - for GCC internal documentation
$gccroot/gcc/doc/gfortran - for Fortran documentation
$gccroot/gcc/doc/gccgo - for GO documentation
...
$gccroot/doc/share - shared components
$gccroot/libgomp/doc - for libgomp documentation
...
Are you fine with that?
That doesn't stop the use of shared makefile code. Make-lang.in is a
fragment included from gcc/Makefile.in ("-include $(LANG_MAKEFRAGS)"). I
certainly expect it should be possible to write GNU make code in
gcc/Makefile.in for building and installing manuals, such that
subdirectories only need to define a few variables describing what manuals
they have and everything else is handled by common code.
The Sphinx Makefile will be capable of e.g.
make html -C $gccroot/gcc/doc/gcc BUILDDIR=`pwd/put_it_somewhere`
and the only configure dependency will VERSION_PACKAGE and BUGURL which will
be provided in env:
https://github.com/marxin/texi2rst-generated/blob/6cfcb7b8ae6497d49ea23a38262dfa26854bdb40/sphinx/baseconf.py#L38-L39
Martin
Re: GCC documentation: porting to Sphinx
On 6/10/21 7:18 AM, Martin Liška wrote: On 6/10/21 11:07 AM, Martin Liška wrote: Doing that, one has 2 unique links, that would be needed for get_option_url function. Plus, both :option:`-Wfoo` and :option:`-Wno-foo` references are going to work. And I've actually did the transformation and one can see it e.g. here: https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wprio-ctor-dtor I find the style you have below right now clearer than keeping both options in the same heading and adding a Note explaining the default etc. I.e., this _ -Wchar-subscripts Warn if an array subscript has type char. This is a common cause of error, as programmers often forget that this type is signed on some machines. This warning is enabled by -Wall. -Wno-char-subscripts Default option value for -Wchar-subscripts. on this page right now: https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wchar-subscripts seems better than this: _ -Wno-shift-overflow, -Wshift-overflow=n, -Wshift-overflow +--+ | (!) Note | +--- | Default value is -Wno-shift-overflow, -Wshift-overflow is| | enabled by -Wall.| +--+ These options control warnings about left shift overflows. and also better than the alternative with (non-default) after the option in the heading. https://splichal.eu/scripts/sphinx/demo/_build/html/#cmdoption-Wno-shift-overflow3 Martin Martin
Re: GCC documentation: porting to Sphinx
On Thu, 10 Jun 2021, Martin Liška wrote:
> 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.
Where languages have their own manuals, I think it's more appropriate for
those to go under the language-specific directories.
That doesn't stop the use of shared makefile code. Make-lang.in is a
fragment included from gcc/Makefile.in ("-include $(LANG_MAKEFRAGS)"). I
certainly expect it should be possible to write GNU make code in
gcc/Makefile.in for building and installing manuals, such that
subdirectories only need to define a few variables describing what manuals
they have and everything else is handled by common code.
--
Joseph S. Myers
jos...@codesourcery.com
Re: GCC documentation: porting to Sphinx
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-fo
Re: GCC documentation: porting to Sphinx
On 6/10/21 11:07 AM, Martin Liška wrote: Doing that, one has 2 unique links, that would be needed for get_option_url function. Plus, both :option:`-Wfoo` and :option:`-Wno-foo` references are going to work. And I've actually did the transformation and one can see it e.g. here: https://splichal.eu/scripts/sphinx/gcc/_build/html/gcc-command-options/options-to-request-or-suppress-warnings.html#cmdoption-Wprio-ctor-dtor Martin
Re: GCC documentation: porting to Sphinx
On 6/4/21 5:10 PM, Martin Sebor wrote: On 6/3/21 4:56 AM, Martin Liška wrote: On 6/2/21 10:41 PM, Martin Sebor wrote: On 5/31/21 7:25 AM, Martin Liška wrote: Hello. I've made quite some progress with the porting of the documentation and I would like to present it to the community now: https://splichal.eu/scripts/sphinx/ Hello. Thank you for the review. Just a few issues I noticed in the warnings section: The headings of some warnings mention the same option twice (e.g., -Wabi, -Wabi, -Wno-abi; -Wdouble-promotion, -Wdouble-promotion, -Wno-double-promotion; -Winit-self, -Winit-self, -Wno-init-self). This looks like a pretty pervasive problem. You are right, I fixed that. Looks good. Mentioning the -Wno-xxx option is redundant in a heading for -Wxxx. Yes. Good reason for that is that Sphinx can then generated properly links to the current non-documented version of the option. Hope it's improvement over the current situation? Hello. Back to this after some thinking. I think the linking is helpful. But for warnings, the documented convention is to only mention the one that's not the default: This manual lists only one of the two forms, whichever is not the default. so including both blurs this (IMO rather subtle) distinction. In addition, in options whose description says something like "This warning is enabled by -Wall." it's now less clear which one is the one the "this" refers to (see for example -Wchar-subscripts). Yes, that's really confusing and we should likely explicitly document both options as shown here (-Wno-shift-overflow3): https://splichal.eu/scripts/sphinx/demo/_build/html/#cmdoption-Wno-shift-overflow3 Doing that, one has 2 unique links, that would be needed for get_option_url function. Plus, both :option:`-Wfoo` and :option:`-Wno-foo` references are going to work. If the heading can't be changed at a minimum we'll need to update the convention above, e.g., by saying that the first option mentions is the default. But again, I think this is too subtle for the casual reader to pick up on. The fact that the sentence quoted above appears under -Wfatal-errors doesn't help. We should also work on updating the "This option is in -Wall." either to name the specific option it refers to, or consider moving that into a Note box like the one listing the languages the option applies to.) Yes, we should explicitly mark one of them as default value, something like "Default option value for -Wshift-overflow3."? And the corresponding counter-part should have "Enabled by -Wall.". I'm not fully convinced about usage of note as it's quite big visual component. The headings of some other warnings also mention options that are only remotely related to them. E.g., -Wformat has all these: -Wformat, -Wno-format, -ffreestanding, -fno-builtin, -Wformat= (I see the same problem in the attributes section where the headings for some attributes include option names). That seems quite puzzling. I assume it's a consequence of having index entries for the related options, but I don't think making them visible in the headings is helfpful. Oh, you are right. It was consequence of wrong parsing of index entries. It should be fixed now. Looks good. Headings that in the manual today include a level like -Wformat-overflow -Wformat-overflow=level don't mention the level in the Spinx manual: -Wformat-overflow, -Wno-format-overflow When the /level/ is then discussed in the rest of the text it's not clear what it refers to. Should be also fixed now. Also looks good. Can you please take a look at the current output and give me a feedback? I noticed another minor issue that may already have been pointed out by someone else. Under -Wall (and -Wextra), some option names are prefixed by :option: (e.g., (only with :option:-O2``). Looks like some sort of a transcription bug? Yes, that should be fixed now. Most comment root cause is that some inline roles are wrapped (that's not supported). And a couple of questions: References to options with an argument like -Warray-bounds=1 are rendered in a way that makes it look like there's a space before the equals: -Warray-bounds =1, with the =1 being in a different color and not part of the hyperlink. Is there a way to make it look like there is no space? Likely not. That's the best I was able to come up with. Reason why the '=1' argument is in :samp: is that :option:`-Wfoo=123` does not properly generate link to the option directive. And there's actually no space in HTML, it's only slightly visually separated and PDF version is fine for me. I like how options are automatically linked, and I'd like to see the same for other references like to attributes. Can that be automated as part of the migration or should we/I try to tackle it in a followup? Right now, I abuse a bit .. option:: my_attribute directive for them. For the future, yes, one can make a link to them with :option:`my_attri
Re: GCC documentation: porting to Sphinx
On 6/3/21 4:56 AM, Martin Liška wrote: On 6/2/21 10:41 PM, Martin Sebor wrote: On 5/31/21 7:25 AM, Martin Liška wrote: Hello. I've made quite some progress with the porting of the documentation and I would like to present it to the community now: https://splichal.eu/scripts/sphinx/ Hello. Thank you for the review. Just a few issues I noticed in the warnings section: The headings of some warnings mention the same option twice (e.g., -Wabi, -Wabi, -Wno-abi; -Wdouble-promotion, -Wdouble-promotion, -Wno-double-promotion; -Winit-self, -Winit-self, -Wno-init-self). This looks like a pretty pervasive problem. You are right, I fixed that. Looks good. Mentioning the -Wno-xxx option is redundant in a heading for -Wxxx. Yes. Good reason for that is that Sphinx can then generated properly links to the current non-documented version of the option. Hope it's improvement over the current situation? I think the linking is helpful. But for warnings, the documented convention is to only mention the one that's not the default: This manual lists only one of the two forms, whichever is not the default. so including both blurs this (IMO rather subtle) distinction. In addition, in options whose description says something like "This warning is enabled by -Wall." it's now less clear which one is the one the "this" refers to (see for example -Wchar-subscripts). If the heading can't be changed at a minimum we'll need to update the convention above, e.g., by saying that the first option mentions is the default. But again, I think this is too subtle for the casual reader to pick up on. The fact that the sentence quoted above appears under -Wfatal-errors doesn't help. We should also work on updating the "This option is in -Wall." either to name the specific option it refers to, or consider moving that into a Note box like the one listing the languages the option applies to.) The headings of some other warnings also mention options that are only remotely related to them. E.g., -Wformat has all these: -Wformat, -Wno-format, -ffreestanding, -fno-builtin, -Wformat= (I see the same problem in the attributes section where the headings for some attributes include option names). That seems quite puzzling. I assume it's a consequence of having index entries for the related options, but I don't think making them visible in the headings is helfpful. Oh, you are right. It was consequence of wrong parsing of index entries. It should be fixed now. Looks good. Headings that in the manual today include a level like -Wformat-overflow -Wformat-overflow=level don't mention the level in the Spinx manual: -Wformat-overflow, -Wno-format-overflow When the /level/ is then discussed in the rest of the text it's not clear what it refers to. Should be also fixed now. Also looks good. Can you please take a look at the current output and give me a feedback? I noticed another minor issue that may already have been pointed out by someone else. Under -Wall (and -Wextra), some option names are prefixed by :option: (e.g., (only with :option:-O2``). Looks like some sort of a transcription bug? And a couple of questions: References to options with an argument like -Warray-bounds=1 are rendered in a way that makes it look like there's a space before the equals: -Warray-bounds =1, with the =1 being in a different color and not part of the hyperlink. Is there a way to make it look like there is no space? I like how options are automatically linked, and I'd like to see the same for other references like to attributes. Can that be automated as part of the migration or should we/I try to tackle it in a followup? In any event, thanks for working so hard on making this turn out great! Martin Thanks, Martin Martin Note the documentation is automatically ([1]) generated from texinfo with a GitHub workflow ([2]). It's built on the devel/sphinx GCC branch which I periodically with the master branch. One can see the current source .rst files here: [3]. Changes made since the last time: - 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 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.
Re: GCC documentation: porting to Sphinx
On 6/3/21 7:16 PM, Joseph Myers wrote:
On Thu, 3 Jun 2021, Martin Liška wrote:
On 6/2/21 6:44 PM, Joseph Myers wrote:
On Wed, 2 Jun 2021, Joel Sherrill wrote:
For RTEMS, we switched from texinfo to Sphinx and the dependency
on Python3 for Sphinx has caused a bit of hassle. Is this going to be
an issue for GCC?
What Sphinx (and, thus, Python) versions does the GCC manual build work
with?
I've just tried version 1.7.6 which we use for libgccjit and it's fine:
https://gcc.gnu.org/onlinedocs/jit/
About Python version: I'm not planning supporting Python2, it's dead 10 years
already.
There should be appropriate configure checks to avoid building manuals
with too-old versions (i.e. disable the info/man manual build/install when
Sphinx, or the Python version it's using, is too old or missing, not fail
configure).
Sure, that makes sense.
Actually this code is depending on Python 3.6 or later because of the use
of an f-string in baseconf.py (without that f-string, it works with older
versions, even 2.7).
Yeah, I used the f-string syntax only at one place and it does not pay off.
Formally 3.5 and older are no longer supported
upstream, but certainly still present in some maintained long-term-support
distribution versions.
Makes sense.
I would recommend testing the build. You can simply clone:
https://github.com/marxin/texi2rst-generated
and simply run 'make html' or 'make latexpdf'. Basic dependencies are
mentioned here:
https://github.com/marxin/texi2rst-generated#requirements
It appears "make html" works (with lots of WARNINGs) with Sphinx 1.6.1 but
fails with 1.4 ("Theme error: unsupported theme option
'prev_next_buttons_location' given").
I checked that and the template needs at least version 1.6:
https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html#compatibility
so I added needs_sphinx to baseconf.py:
https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=conf.py#confval-needs_sphinx
The following message is displayed when one builds a manual:
$ make html
sphinx-build -b "html" -d _build/doctrees. "_build/html"
Running Sphinx v4.0.2
Sphinx version error:
This project needs at least Sphinx v66.6 and therefore cannot be built with
this version.
make: *** [Makefile:96: html] Error 2
Martin
Re: GCC documentation: porting to Sphinx
On Thu, 3 Jun 2021, Martin Liška wrote:
> On 6/2/21 6:44 PM, Joseph Myers wrote:
> > On Wed, 2 Jun 2021, Joel Sherrill wrote:
> >
> > > For RTEMS, we switched from texinfo to Sphinx and the dependency
> > > on Python3 for Sphinx has caused a bit of hassle. Is this going to be
> > > an issue for GCC?
> >
> > What Sphinx (and, thus, Python) versions does the GCC manual build work
> > with?
>
> I've just tried version 1.7.6 which we use for libgccjit and it's fine:
> https://gcc.gnu.org/onlinedocs/jit/
>
> About Python version: I'm not planning supporting Python2, it's dead 10 years
> already.
There should be appropriate configure checks to avoid building manuals
with too-old versions (i.e. disable the info/man manual build/install when
Sphinx, or the Python version it's using, is too old or missing, not fail
configure).
Actually this code is depending on Python 3.6 or later because of the use
of an f-string in baseconf.py (without that f-string, it works with older
versions, even 2.7). Formally 3.5 and older are no longer supported
upstream, but certainly still present in some maintained long-term-support
distribution versions.
> I would recommend testing the build. You can simply clone:
> https://github.com/marxin/texi2rst-generated
>
> and simply run 'make html' or 'make latexpdf'. Basic dependencies are
> mentioned here:
> https://github.com/marxin/texi2rst-generated#requirements
It appears "make html" works (with lots of WARNINGs) with Sphinx 1.6.1 but
fails with 1.4 ("Theme error: unsupported theme option
'prev_next_buttons_location' given").
--
Joseph S. Myers
jos...@codesourcery.com
Re: GCC documentation: porting to Sphinx
On 6/2/21 6:44 PM, Joseph Myers wrote: On Wed, 2 Jun 2021, Joel Sherrill wrote: For RTEMS, we switched from texinfo to Sphinx and the dependency on Python3 for Sphinx has caused a bit of hassle. Is this going to be an issue for GCC? What Sphinx (and, thus, Python) versions does the GCC manual build work with? I've just tried version 1.7.6 which we use for libgccjit and it's fine: https://gcc.gnu.org/onlinedocs/jit/ About Python version: I'm not planning supporting Python2, it's dead 10 years already. Can it work with e.g. any Sphinx versions from the past five years, or are there newer Sphinx features that are critical for the GCC manuals? The mentioned version is 3 years and I expect even older releases would work. No, I don't rely on any new feature. I would recommend testing the build. You can simply clone: https://github.com/marxin/texi2rst-generated and simply run 'make html' or 'make latexpdf'. Basic dependencies are mentioned here: https://github.com/marxin/texi2rst-generated#requirements Martin I've seen a need for frequent Sphinx updates being a pain when building other software using Sphinx for its manual. Also we rely on TexLive for PDF output and that's a bit of a pain to install. Tex was incorrectly packaged on some RHEL/CentOS versions. This is nothing new, since building PDF manuals from Texinfo sources also needs TeX.
Re: GCC documentation: porting to Sphinx
On 6/2/21 10:41 PM, Martin Sebor wrote: On 5/31/21 7:25 AM, Martin Liška wrote: Hello. I've made quite some progress with the porting of the documentation and I would like to present it to the community now: https://splichal.eu/scripts/sphinx/ Hello. Thank you for the review. Just a few issues I noticed in the warnings section: The headings of some warnings mention the same option twice (e.g., -Wabi, -Wabi, -Wno-abi; -Wdouble-promotion, -Wdouble-promotion, -Wno-double-promotion; -Winit-self, -Winit-self, -Wno-init-self). This looks like a pretty pervasive problem. You are right, I fixed that. Mentioning the -Wno-xxx option is redundant in a heading for -Wxxx. Yes. Good reason for that is that Sphinx can then generated properly links to the current non-documented version of the option. Hope it's improvement over the current situation? The headings of some other warnings also mention options that are only remotely related to them. E.g., -Wformat has all these: -Wformat, -Wno-format, -ffreestanding, -fno-builtin, -Wformat= (I see the same problem in the attributes section where the headings for some attributes include option names). That seems quite puzzling. I assume it's a consequence of having index entries for the related options, but I don't think making them visible in the headings is helfpful. Oh, you are right. It was consequence of wrong parsing of index entries. It should be fixed now. Headings that in the manual today include a level like -Wformat-overflow -Wformat-overflow=level don't mention the level in the Spinx manual: -Wformat-overflow, -Wno-format-overflow When the /level/ is then discussed in the rest of the text it's not clear what it refers to. Should be also fixed now. Can you please take a look at the current output and give me a feedback? Thanks, Martin Martin Note the documentation is automatically ([1]) generated from texinfo with a GitHub workflow ([2]). It's built on the devel/sphinx GCC branch which I periodically with the master branch. One can see the current source .rst files here: [3]. Changes made since the last time: - 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 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. 2) Do we want to generate fsf-funding, gpl and gfdl manual pages? 3) Do we want to preserve the current strange copy mechanism for ./gcc/doc/tm.texi.in ? 4) Do we want a copyright header for the created .rst files? Thoughts? Thanks, Martin [1] https://github.com/davidmalcolm/texi2rst [2] https://github.com/davidmalcolm/texi2rst/actions [3] https://github.com/marxin/texi2rst-generated/tree/master/sphinx [4] https://github.com/marxin/texi2rst-generated/tree/master/sphinx/share
Re: GCC documentation: porting to Sphinx
On 5/31/21 7:25 AM, Martin Liška wrote: Hello. I've made quite some progress with the porting of the documentation and I would like to present it to the community now: https://splichal.eu/scripts/sphinx/ Just a few issues I noticed in the warnings section: The headings of some warnings mention the same option twice (e.g., -Wabi, -Wabi, -Wno-abi; -Wdouble-promotion, -Wdouble-promotion, -Wno-double-promotion; -Winit-self, -Winit-self, -Wno-init-self). This looks like a pretty pervasive problem. Mentioning the -Wno-xxx option is redundant in a heading for -Wxxx. The headings of some other warnings also mention options that are only remotely related to them. E.g., -Wformat has all these: -Wformat, -Wno-format, -ffreestanding, -fno-builtin, -Wformat= (I see the same problem in the attributes section where the headings for some attributes include option names). That seems quite puzzling. I assume it's a consequence of having index entries for the related options, but I don't think making them visible in the headings is helfpful. Headings that in the manual today include a level like -Wformat-overflow -Wformat-overflow=level don't mention the level in the Spinx manual: -Wformat-overflow, -Wno-format-overflow When the /level/ is then discussed in the rest of the text it's not clear what it refers to. Martin Note the documentation is automatically ([1]) generated from texinfo with a GitHub workflow ([2]). It's built on the devel/sphinx GCC branch which I periodically with the master branch. One can see the current source .rst files here: [3]. Changes made since the last time: - 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 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. 2) Do we want to generate fsf-funding, gpl and gfdl manual pages? 3) Do we want to preserve the current strange copy mechanism for ./gcc/doc/tm.texi.in ? 4) Do we want a copyright header for the created .rst files? Thoughts? Thanks, Martin [1] https://github.com/davidmalcolm/texi2rst [2] https://github.com/davidmalcolm/texi2rst/actions [3] https://github.com/marxin/texi2rst-generated/tree/master/sphinx [4] https://github.com/marxin/texi2rst-generated/tree/master/sphinx/share
Re: GCC documentation: porting to Sphinx
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
Re: GCC documentation: porting to Sphinx
On Wed, 2 Jun 2021, Joel Sherrill wrote: > For RTEMS, we switched from texinfo to Sphinx and the dependency > on Python3 for Sphinx has caused a bit of hassle. Is this going to be > an issue for GCC? What Sphinx (and, thus, Python) versions does the GCC manual build work with? Can it work with e.g. any Sphinx versions from the past five years, or are there newer Sphinx features that are critical for the GCC manuals? I've seen a need for frequent Sphinx updates being a pain when building other software using Sphinx for its manual. > Also we rely on TexLive for PDF output and that's a bit of a pain to > install. Tex was incorrectly packaged on some RHEL/CentOS versions. This is nothing new, since building PDF manuals from Texinfo sources also needs TeX. -- Joseph S. Myers jos...@codesourcery.com
Re: GCC documentation: porting to Sphinx
For RTEMS, we switched from texinfo to Sphinx and the dependency on Python3 for Sphinx has caused a bit of hassle. Is this going to be an issue for GCC? Also we rely on TexLive for PDF output and that's a bit of a pain to install. Tex was incorrectly packaged on some RHEL/CentOS versions. This ignores a couple of plugins we use that I don't expect GCC to use. It works great but the host dependencies are sometimes a pain. We've ended up writing host OS specific advice/howto's to address this. Any expectations on host pain versus the pretty painless texinfo? Thanks. --joel RTEMS On Wed, Jun 2, 2021 at 2:37 AM Martin Liška wrote: > On 6/1/21 3:31 PM, Michael Matz wrote: > > Hello, > > > > On Tue, 1 Jun 2021, Martin Liška wrote: > > > >> On 5/31/21 5:49 PM, Michael Matz wrote: > >>> Hello Martin, > >>> > >>> On Mon, 31 May 2021, Martin Liška wrote: > >>> > I've made quite some progress with the porting of the documentation > and > I would like to present it to the community now: > https://splichal.eu/scripts/sphinx/ > Note the documentation is automatically ([1]) generated from > texinfo with > a > GitHub workflow ([2]). > >>> > >>> One other thing I was recently thinking about, in the Spinx vs. texinfo > >>> discussion: locally available documentation browsable/searchable in > >>> terminal with info(1) (or equivalents). > >> > >> Yes, that's handy. > >> > >>> I think the above (i.e. generating .rst from the texinfo file) would > >>> immediately nullify all my worries. So, just to be extra sure: your > >>> proposal now is to generate the .rst files, and that .texinfo remains > >>> the maintained sources, right? > >> > >> No, .texinfo files will be gone. However, Sphinx can output to info > >> format: > >> > https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-M > > > > I see, that's good to hear. > > > >> And I've just added the generated Info pages here: > >> https://splichal.eu/scripts/sphinx/ > > > > Okay, but there's something amiss, just compare a local gcc.info with > > that. The sphinx generated one seems to only contain command line > > options, but none of the other topics, in particular it seems to contain > > the "Invoking GCC" chapter (and only that) as top-level, and all other > > ones are missing (like "C implementation", "C++ implementation", "C > > extension", and so on). > > You are right, I reduced that to 'Invoking GCC', which is simply what 'man > gcc' > presents. However, I moved that back to the entire GCC manual what you can > see now in the info page. > > > > > Looking at gccint.info I also seem quite some confusion, it's unclear to > > me if content is missing or not. But e.g. the top-level structure has a > > different order (a less logical one, this one is btw. shared with the > > order of the HTML generated docu, so it's probably specific to sphinx > > setup or such). > > Yes, the organization was bad and I fixed that. Now it's much better. > > Martin > > > > > Ignoring that missing content what is there right now does seem somewhat > > acceptable for local use, though. > > > > > > Ciao, > > Michael. > > > >
Re: GCC documentation: porting to Sphinx
On 6/1/21 3:31 PM, Michael Matz wrote: Hello, On Tue, 1 Jun 2021, Martin Liška wrote: On 5/31/21 5:49 PM, Michael Matz wrote: Hello Martin, On Mon, 31 May 2021, Martin Liška wrote: I've made quite some progress with the porting of the documentation and I would like to present it to the community now: https://splichal.eu/scripts/sphinx/ Note the documentation is automatically ([1]) generated from texinfo with a GitHub workflow ([2]). One other thing I was recently thinking about, in the Spinx vs. texinfo discussion: locally available documentation browsable/searchable in terminal with info(1) (or equivalents). Yes, that's handy. I think the above (i.e. generating .rst from the texinfo file) would immediately nullify all my worries. So, just to be extra sure: your proposal now is to generate the .rst files, and that .texinfo remains the maintained sources, right? No, .texinfo files will be gone. However, Sphinx can output to info format: https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-M I see, that's good to hear. And I've just added the generated Info pages here: https://splichal.eu/scripts/sphinx/ Okay, but there's something amiss, just compare a local gcc.info with that. The sphinx generated one seems to only contain command line options, but none of the other topics, in particular it seems to contain the "Invoking GCC" chapter (and only that) as top-level, and all other ones are missing (like "C implementation", "C++ implementation", "C extension", and so on). You are right, I reduced that to 'Invoking GCC', which is simply what 'man gcc' presents. However, I moved that back to the entire GCC manual what you can see now in the info page. Looking at gccint.info I also seem quite some confusion, it's unclear to me if content is missing or not. But e.g. the top-level structure has a different order (a less logical one, this one is btw. shared with the order of the HTML generated docu, so it's probably specific to sphinx setup or such). Yes, the organization was bad and I fixed that. Now it's much better. Martin Ignoring that missing content what is there right now does seem somewhat acceptable for local use, though. Ciao, Michael.
Re: GCC documentation: porting to Sphinx
Hello, On Tue, 1 Jun 2021, Martin Liška wrote: > On 5/31/21 5:49 PM, Michael Matz wrote: > > Hello Martin, > > > > On Mon, 31 May 2021, Martin Liška wrote: > > > >> I've made quite some progress with the porting of the documentation and > >> I would like to present it to the community now: > >> https://splichal.eu/scripts/sphinx/ > >> Note the documentation is automatically ([1]) generated from texinfo with > >> a > >> GitHub workflow ([2]). > > > > One other thing I was recently thinking about, in the Spinx vs. texinfo > > discussion: locally available documentation browsable/searchable in > > terminal with info(1) (or equivalents). > > Yes, that's handy. > > > I think the above (i.e. generating .rst from the texinfo file) would > > immediately nullify all my worries. So, just to be extra sure: your > > proposal now is to generate the .rst files, and that .texinfo remains > > the maintained sources, right? > > No, .texinfo files will be gone. However, Sphinx can output to info > format: > https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-M I see, that's good to hear. > And I've just added the generated Info pages here: > https://splichal.eu/scripts/sphinx/ Okay, but there's something amiss, just compare a local gcc.info with that. The sphinx generated one seems to only contain command line options, but none of the other topics, in particular it seems to contain the "Invoking GCC" chapter (and only that) as top-level, and all other ones are missing (like "C implementation", "C++ implementation", "C extension", and so on). Looking at gccint.info I also seem quite some confusion, it's unclear to me if content is missing or not. But e.g. the top-level structure has a different order (a less logical one, this one is btw. shared with the order of the HTML generated docu, so it's probably specific to sphinx setup or such). Ignoring that missing content what is there right now does seem somewhat acceptable for local use, though. Ciao, Michael.
Re: GCC documentation: porting to Sphinx
On 5/31/21 5:49 PM, Michael Matz wrote: Hello Martin, On Mon, 31 May 2021, Martin Liška wrote: I've made quite some progress with the porting of the documentation and I would like to present it to the community now: https://splichal.eu/scripts/sphinx/ Note the documentation is automatically ([1]) generated from texinfo with a GitHub workflow ([2]). One other thing I was recently thinking about, in the Spinx vs. texinfo discussion: locally available documentation browsable/searchable in terminal with info(1) (or equivalents). Yes, that's handy. I think the above (i.e. generating .rst from the texinfo file) would immediately nullify all my worries. So, just to be extra sure: your proposal now is to generate the .rst files, and that .texinfo remains the maintained sources, right? No, .texinfo files will be gone. However, Sphinx can output to info format: https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-M And I've just added the generated Info pages here: https://splichal.eu/scripts/sphinx/ Hope it helps? Martin Ciao, Michael.
Re: GCC documentation: porting to Sphinx
Hello Martin, On Mon, 31 May 2021, Martin Liška wrote: > I've made quite some progress with the porting of the documentation and > I would like to present it to the community now: > https://splichal.eu/scripts/sphinx/ > > Note the documentation is automatically ([1]) generated from texinfo with a > GitHub workflow ([2]). One other thing I was recently thinking about, in the Spinx vs. texinfo discussion: locally available documentation browsable/searchable in terminal with info(1) (or equivalents). I think the above (i.e. generating .rst from the texinfo file) would immediately nullify all my worries. So, just to be extra sure: your proposal now is to generate the .rst files, and that .texinfo remains the maintained sources, right? Ciao, Michael.
GCC documentation: porting to Sphinx
Hello. I've made quite some progress with the porting of the documentation and I would like to present it to the community now: https://splichal.eu/scripts/sphinx/ Note the documentation is automatically ([1]) generated from texinfo with a GitHub workflow ([2]). It's built on the devel/sphinx GCC branch which I periodically with the master branch. One can see the current source .rst files here: [3]. Changes made since the last time: - 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 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. 2) Do we want to generate fsf-funding, gpl and gfdl manual pages? 3) Do we want to preserve the current strange copy mechanism for ./gcc/doc/tm.texi.in ? 4) Do we want a copyright header for the created .rst files? Thoughts? Thanks, Martin [1] https://github.com/davidmalcolm/texi2rst [2] https://github.com/davidmalcolm/texi2rst/actions [3] https://github.com/marxin/texi2rst-generated/tree/master/sphinx [4] https://github.com/marxin/texi2rst-generated/tree/master/sphinx/share
