* Re: Benefits of using Sphinx documentation format [not found] ` <CAKPWYQ3EobaPGskg9kq5gYtHFoGNXFLtCOcrcFouxg4skvJRxA@mail.gmail.com> @ 2021-07-12 17:49 ` Gavin Smith 2021-08-09 12:04 ` Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Gavin Smith @ 2021-07-12 17:49 UTC (permalink / raw) To: gcc (Sending mail again, without attachments this time in the hope it gets through.) I had the discussion about moving documentation of gcc from Sphinx to Texinfo brought to my attention. https://gcc.gnu.org/pipermail/gcc/2021-July/236731.html Speaking as the Texinfo maintainer, I hope to add my views and understandings of things to this discussion to improve your understanding of the facts and possibilities, although of course it's up to you whether you use Texinfo or not. I will work through the points made in that email but haven't read any of the subsequent discussion yet - I'll follow up on anything else afterwards. > Benefits: > 1) modern looking HTML output (before: [1], after: [2]): > a) syntax highlighting for examples (code, shell commands, etc.) Syntax highlighting has been achieved with Texinfo before. See https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html and https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00004.html With Texinfo 6.8, syntax highlighting in multiple languages is easier to achieve by giving an argument to the @example command (https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040example.html). This puts a class attribute on the HTML element which can then be picked up by a post-processor. It might also be possible to achieve syntax highlighting with a customization file used by the Texinfo tools themselves: see https://lists.gnu.org/archive/html/bug-texinfo/2021-01/msg00031.html. > b) precise anchors, the current Texinfo anchors are not displayed (start with first line of an option) > c) one can easily copy a link to an anchor (displayed as ¶) Similar anchors were implemented in Texinfo 6.8. See https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Invoking-texi2any.html and hover any of the options there with your mouse; you will see the pilcrow sign appear. > e) left menu navigation provides better orientation in the manual Left menu navigation is possible with the new JavaScript interface, in Texinfo 6.8. There is still a demo at https://per.bothner.com/tmp/Kawa-txjs-plain/Community.html and https://per.bothner.com/tmp/Kawa-txjs/Community.html However, I would say that it isn't necessarily always an improvement, if it is going to be buggy. When I click on the link https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing the browser doesn't scroll the sidebar so to show the active ToC entry (although it is displayed correctly when I refresh the page). The more sophisticated the HTML/JS becomes the more likely there are these little nits. > f) Sphinx provides internal search capability: [3] There is a global search facility with the JavaScript interface although different to that provided by Sphinx, only showing one match at a time. Try https://per.bothner.com/tmp/Kawa-txjs/index.html and then press "s" on your keyboard, type in your search string (e.g. "composable") and it will search through the manual for that string. To go to the next match, press "s" then Return. The proviso about "sophisticated" HTML still applies here, though. > 2) internal links are also provided in PDF version of the manual Links already work when viewing a PDF on a computer. If you want to add additional links that only appear in PDF and HTML and not in Info, this is easily achieved with a conditional macro, like @ifset morelinks @macro link{arg} @ref{\arg\} @end macro @end ifset @ifclear morelinks @macro link{arg} \arg\ @end macro @end ifclear followed by "@set morelinks" or "@clear morelinks" as required. > 5) Sphinx is using RST which is quite minimal semantic markup language This is really an ineffable question of taste on which it is hard to be convinced, but I have to point out that Texinfo is minimalistic, with only three special characters (@, { and }). > 6) TOC is automatically generated - no nee6d for manual navigation like seen here: [5] > 5] @comment node-name, next, previous, up > @node Installing GCC, Binaries, , Top This is a completely bogus point with these explicit "pointers" being optional. I couldn't find out easily how long ago these pointers became optional, but it is at least twenty years ago. A couple of other points, not mentioned in the original email: * One possible disadvantage of moving away from Texinfo which might be easily missed is support for reliable web links between different manuals. If you change format you should make sure that these work, e.g. if you reference the glibc manual the web link to that should work correctly (as well as the link working in the Info format). * A disadvantage of focusing on HTML output is that locally installed documentation gets sidelined: although locally installed HTML documentation is possible, it tends not to happen and people refer to the web version instead, with all of its disadvantages (slow speed, may be the wrong version or disappear off the web, lack of user privacy). Another disadvantage of HTML is that links can only go to one place, while with the Info format you can have manuals installed in several places, even more than one version of a manual installed at once. Some people don't realise that Texinfo is actively maintained and there is a mailing list at bug-texinfo@gnu.org (https://lists.gnu.org/mailman/listinfo/bug-texinfo); this is a place for people to discuss their needs as to what they need from the system. I wonder if some of the desiderata can be satisfied with existing facilities in Texinfo or if not if we could accommodate them with not too much difficulty. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 17:49 ` Benefits of using Sphinx documentation format Gavin Smith @ 2021-08-09 12:04 ` Martin Liška 0 siblings, 0 replies; 32+ messages in thread From: Martin Liška @ 2021-08-09 12:04 UTC (permalink / raw) To: Gavin Smith, gcc On 7/12/21 7:49 PM, Gavin Smith via Gcc wrote: > (Sending mail again, without attachments this time in the hope it gets through.) > > I had the discussion about moving documentation of gcc from Sphinx to > Texinfo brought to my attention. > > https://gcc.gnu.org/pipermail/gcc/2021-July/236731.html > > Speaking as the Texinfo maintainer, I hope to add my views and > understandings of things to this discussion to improve your > understanding of the facts and possibilities, although of course it's > up to you whether you use Texinfo or not. Hello. Appreciate your time spent working on the tool and I'm going to briefly reply your points. > > I will work through the points made in that email but haven't read any > of the subsequent discussion yet - I'll follow up on anything else > afterwards. > >> Benefits: >> 1) modern looking HTML output (before: [1], after: [2]): > >> a) syntax highlighting for examples (code, shell commands, etc.) > > Syntax highlighting has been achieved with Texinfo before. See > > https://guix.gnu.org/manual/devel/en/html_node/Using-the-Configuration-System.html > > and > > https://lists.gnu.org/archive/html/bug-texinfo/2019-11/msg00004.html > > With Texinfo 6.8, syntax highlighting in multiple languages is easier > to achieve by giving an argument to the @example command > (https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040example.html). > This puts a class attribute on the HTML element which can then be > picked up by a post-processor. It might also be possible to achieve > syntax highlighting with a customization file used by the Texinfo > tools themselves: see > https://lists.gnu.org/archive/html/bug-texinfo/2021-01/msg00031.html. If I understand correctly, that would need a further post-processing of the HTML elements. Sphinx works out of the box and the same output is achieved also for PDF output. > >> b) precise anchors, the current Texinfo anchors are not displayed (start with first line of an option) >> c) one can easily copy a link to an anchor (displayed as ¶) > > Similar anchors were implemented in Texinfo 6.8. See > https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Invoking-texi2any.html > and hover any of the options there with your mouse; you will see the > pilcrow sign appear. Good. > >> e) left menu navigation provides better orientation in the manual > > Left menu navigation is possible with the new JavaScript interface, in > Texinfo 6.8. There is still a demo at > > https://per.bothner.com/tmp/Kawa-txjs-plain/Community.html > > and > > https://per.bothner.com/tmp/Kawa-txjs/Community.html To be honest, it looks still quite legacy and I don't want to spend more working on a custom CSS template and reasonable JS functionality. I would like to take an existing theme that looks nice and provides reasonable capability. That's for me https://github.com/readthedocs/sphinx_rtd_theme > > However, I would say that it isn't necessarily always an improvement, > if it is going to be buggy. When I click on the link > https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing > the browser doesn't scroll the sidebar so to show the active ToC entry > (although it > is displayed correctly when I refresh the page). If I open a new tab, a browser correctly scrolls to the option documentation. > > The more sophisticated the HTML/JS becomes the more likely there are > these little nits. > >> f) Sphinx provides internal search capability: [3] > > There is a global search facility with the JavaScript interface > although different to that provided by Sphinx, only showing one match > at a time. As said, it's a limitation to me. > > Try > > https://per.bothner.com/tmp/Kawa-txjs/index.html > > and then press "s" on your keyboard, type in your search string (e.g. > "composable") and it will search through the manual for that string. > To go to the next match, press "s" then Return. > > The proviso about "sophisticated" HTML still applies here, though. > >> 2) internal links are also provided in PDF version of the manual > > Links already work when viewing a PDF on a computer. > > If you want to add additional links that only appear in PDF and HTML > and not in Info, this is easily achieved with a conditional macro, > like > > @ifset morelinks > @macro link{arg} > @ref{\arg\} > @end macro > @end ifset > @ifclear morelinks > @macro link{arg} > \arg\ > @end macro > @end ifclear > > followed by "@set morelinks" or "@clear morelinks" as required. All right, that would likely require providing more anchors in the existing GCC documentation. > >> 5) Sphinx is using RST which is quite minimal semantic markup language > > This is really an ineffable question of taste on which it is hard to > be convinced, but I have to point out that Texinfo is minimalistic, > with only three special characters (@, { and }). > >> 6) TOC is automatically generated - no nee6d for manual navigation like seen here: [5] >> 5] @comment node-name, next, previous, up >> @node Installing GCC, Binaries, , Top > > This is a completely bogus point with these explicit "pointers" being > optional. I couldn't find out easily how long ago these pointers > became optional, but it is at least twenty years ago. Got that, thus we use unnecessary syntax right now. > > A couple of other points, not mentioned in the original email: > * One possible disadvantage of moving away from Texinfo which might be > easily missed is support for reliable web links between different > manuals. If you change format you should make sure that these work, > e.g. if you reference the glibc manual the web link to that should > work correctly (as well as the link working in the Info format). Good point, I'm not aware of any cross links. If there are any, I'm willing to update them. > * A disadvantage of focusing on HTML output is that locally installed > documentation gets sidelined: although locally installed HTML > documentation is possible, it tends not to happen and people refer to > the web version instead, with all of its disadvantages (slow speed, > may be the wrong version or disappear off the web, lack of user > privacy). Another disadvantage of HTML is that links can only go to > one place, while with the Info format you can have manuals installed > in several places, even more than one version of a manual installed at > once. Totally misleading. I don't see why would anybody install HTML documentation locally. Our motivation is to have HTML documentation on our site, where we can update it and Google can index it for people using full text search. > > Some people don't realise that Texinfo is actively maintained and > there is a mailing list at bug-texinfo@gnu.org > (https://lists.gnu.org/mailman/listinfo/bug-texinfo); this is a place > for people to discuss their needs as to what they need from the > system. I wonder if some of the desiderata can be satisfied with > existing facilities in Texinfo or if not if we could accommodate them > with not too much difficulty. As mentioned, I appreciate your work. On the other hand, Sphinx documentation community is much bigger and the list of projects using the tool is pretty huge: https://www.sphinx-doc.org/en/master/examples.html (include huge FOSS projects like LLVM, or Linux kernel). That makes me believe the transition makes sense and we will benefit from it as project. Martin ^ permalink raw reply [flat|nested] 32+ messages in thread
[parent not found: <1446990946.2994.192.camel@surprise>]
* Re: RFC: Sphinx for GCC documentation @ 2021-05-13 11:45 ` Martin Liška 2021-05-31 13:25 ` GCC documentation: porting to Sphinx Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-05-13 11:45 UTC (permalink / raw) To: David Malcolm, gcc-patches; +Cc: GCC Development On 4/1/21 3:30 PM, Martin Liška wrote: > That said, I'm asking the GCC community for a green light before I invest > more time on it? Hello. So far, I've received just a small feedback about the transition. In most cases positive. May I understand it as green light for the transition? Thanks, Martin [1] https://splichal.eu/scripts/sphinx/ ^ permalink raw reply [flat|nested] 32+ messages in thread
* GCC documentation: porting to Sphinx 2021-05-13 11:45 ` RFC: Sphinx for GCC documentation Martin Liška @ 2021-05-31 13:25 ` Martin Liška 2021-06-02 17:27 ` Joseph Myers 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-05-31 13:25 UTC (permalink / raw) To: David Malcolm, gcc-patches; +Cc: GCC Development, Joseph S. Myers 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: GCC documentation: porting to Sphinx 2021-05-31 13:25 ` GCC documentation: porting to Sphinx Martin Liška @ 2021-06-02 17:27 ` Joseph Myers 2021-06-10 14:06 ` Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Joseph Myers @ 2021-06-02 17:27 UTC (permalink / raw) To: Martin Liška; +Cc: David Malcolm, gcc-patches, GCC Development 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: GCC documentation: porting to Sphinx 2021-06-02 17:27 ` Joseph Myers @ 2021-06-10 14:06 ` Martin Liška 2021-06-10 16:49 ` Joseph Myers 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-06-10 14:06 UTC (permalink / raw) To: Joseph Myers; +Cc: David Malcolm, gcc-patches, GCC Development 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: GCC documentation: porting to Sphinx 2021-06-10 14:06 ` Martin Liška @ 2021-06-10 16:49 ` Joseph Myers 2021-06-11 14:33 ` Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Joseph Myers @ 2021-06-10 16:49 UTC (permalink / raw) To: Martin Liška; +Cc: GCC Development, gcc-patches 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 joseph@codesourcery.com ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: GCC documentation: porting to Sphinx 2021-06-10 16:49 ` Joseph Myers @ 2021-06-11 14:33 ` Martin Liška 2021-06-11 15:50 ` Joseph Myers 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-06-11 14:33 UTC (permalink / raw) To: Joseph Myers; +Cc: GCC Development, gcc-patches 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: GCC documentation: porting to Sphinx 2021-06-11 14:33 ` Martin Liška @ 2021-06-11 15:50 ` Joseph Myers 2021-06-23 13:13 ` Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Joseph Myers @ 2021-06-11 15:50 UTC (permalink / raw) To: Martin Liška; +Cc: GCC Development, gcc-patches 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 joseph@codesourcery.com ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: GCC documentation: porting to Sphinx 2021-06-11 15:50 ` Joseph Myers @ 2021-06-23 13:13 ` Martin Liška 2021-06-23 16:00 ` Joseph Myers 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-06-23 13:13 UTC (permalink / raw) To: Joseph Myers; +Cc: GCC Development, gcc-patches 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: GCC documentation: porting to Sphinx 2021-06-23 13:13 ` Martin Liška @ 2021-06-23 16:00 ` Joseph Myers 2021-06-24 14:08 ` Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Joseph Myers @ 2021-06-23 16:00 UTC (permalink / raw) To: Martin Liška; +Cc: GCC Development, gcc-patches 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 joseph@codesourcery.com ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: GCC documentation: porting to Sphinx 2021-06-23 16:00 ` Joseph Myers @ 2021-06-24 14:08 ` Martin Liška 2021-06-25 13:11 ` Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-06-24 14:08 UTC (permalink / raw) To: Joseph Myers; +Cc: GCC Development, gcc-patches 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: GCC documentation: porting to Sphinx 2021-06-24 14:08 ` Martin Liška @ 2021-06-25 13:11 ` Martin Liška 2021-06-28 12:01 ` [PATCH] Port GCC documentation " Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-06-25 13:11 UTC (permalink / raw) To: Joseph Myers; +Cc: GCC Development, gcc-patches, David Malcolm, Arnaud Charlet 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* [PATCH] Port GCC documentation to Sphinx 2021-06-25 13:11 ` Martin Liška @ 2021-06-28 12:01 ` Martin Liška 2021-06-28 15:33 ` Joseph Myers 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-06-28 12:01 UTC (permalink / raw) To: Joseph Myers; +Cc: GCC Development, gcc-patches Hello. I'm sending the complete patch set that includes ChangeLog entries. Unfortunately, majority of the patches are huge, that's why I sent like to a tarball: https://splichal.eu/tmp/port-to-sphinx-v1.tar The tarball contains the following patches: 19e06194746 Ada: port to Sphinx. 9a744ca431d Remove unused TEX files. e624967b5e8 Port jit to new Sphinx layout. 8c4717b262a Build system: support Sphinx d102880437e Add include directives for target macros. 08c3d3f0d8d Add RST files with config files. Thanks, Martin ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [PATCH] Port GCC documentation to Sphinx 2021-06-28 12:01 ` [PATCH] Port GCC documentation " Martin Liška @ 2021-06-28 15:33 ` Joseph Myers 2021-06-29 10:09 ` Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Joseph Myers @ 2021-06-28 15:33 UTC (permalink / raw) To: Martin Liška; +Cc: GCC Development, gcc-patches Are formatted manuals (HTML, PDF, man, info) corresponding to this patch version also available for review? -- Joseph S. Myers joseph@codesourcery.com ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [PATCH] Port GCC documentation to Sphinx 2021-06-28 15:33 ` Joseph Myers @ 2021-06-29 10:09 ` Martin Liška 2021-06-29 16:57 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-06-29 10:09 UTC (permalink / raw) To: Joseph Myers; +Cc: GCC Development, gcc-patches On 6/28/21 5:33 PM, Joseph Myers wrote: > Are formatted manuals (HTML, PDF, man, info) corresponding to this patch > version also available for review? I've just uploaded them here: https://splichal.eu/gccsphinx-final/ Martin ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [PATCH] Port GCC documentation to Sphinx 2021-06-29 10:09 ` Martin Liška @ 2021-06-29 16:57 ` Eli Zaretskii 2021-06-30 10:11 ` Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-06-29 16:57 UTC (permalink / raw) To: Martin Liška; +Cc: joseph, gcc, gcc-patches > From: Martin Liška <mliska@suse.cz> > Date: Tue, 29 Jun 2021 12:09:23 +0200 > Cc: GCC Development <gcc@gcc.gnu.org>, gcc-patches@gcc.gnu.org > > On 6/28/21 5:33 PM, Joseph Myers wrote: > > Are formatted manuals (HTML, PDF, man, info) corresponding to this patch > > version also available for review? > > I've just uploaded them here: > https://splichal.eu/gccsphinx-final/ Thanks. I'm an Info junkie, so I grabbed gcc.info from there and skimmed through it. Please allow me a few unsolicited comments: 1. It sounds like Sphinx is heavily biased towards HTML format, and as result uglifies the Info format? For example, many cross-references (AFAIU introduced as part of migration to Sphinx) make the text illegible in Emacs. Example: This standard, in both its forms, is commonly known as `C89', or occasionally as `C90', from the dates of ratification. To select this standard in GCC, use one of the options *note -ansi *note -std .‘=c90’ or *note -std.‘=iso9899:1990’; to obtain all the diagnostics required by the standard, you should also specify *note -pedantic. (or *note -pedantic-errors. if you want them to be errors rather than warnings). See *note Options Controlling C Dialect. [...] An amendment to the 1990 standard was published in 1995. This amendment added digraphs and ‘__STDC_VERSION__’ to the language, but otherwise concerned the library. This amendment is commonly known as `AMD1'; the amended standard is sometimes known as `C94' or `C95'. To select this standard in GCC, use the option *note -std.‘=iso9899:199409’ (with, as for other standard versions, *note -pedantic. to receive all required diagnostics). Or how about this: `Overall Options' See Options Controlling the Kind of Output. *note -c. *note -S. *note -E. *note -o. ‘`file'’ *note -dumpbase. ‘`dumpbase'’ *note -dumpbase-ext. ‘`auxdropsuf'’ *note -dumpdir. ‘`dumppfx'’ ‘-x’ ‘`language'’ *note -v. *note -###. *note –help.‘[=`class'[,...]]’ *note –target-help. *note –version. *note -pass-exit-codes . *note -pipe. *note -specs.‘=`file'’ *note -wrapper .‘@`file'’ *note -ffile-prefix-map.‘=`old'=`new'’ *note -fplugin.‘=`file'’ ‘-fplugin-arg-’‘`name'=`arg'’ ‘-fdump-ada-spec’‘[-`slim']’ *note -fada-spec-parent.‘=`unit'’ *note -fdump-go-spec.‘=`file'’ In the first line, the emphasis became quotes, which sounds sub-optimal. In the second line, the hyperlink was lost. And the rest is not really readable. Compare this with the original: _Overall Options_ *Note Options Controlling the Kind of Output. -c -S -E -o FILE -x LANGUAGE -v -### --help[=CLASS[,...]] --target-help --version -pass-exit-codes -pipe -specs=FILE -wrapper @FILE -ffile-prefix-map=OLD=NEW -fplugin=FILE -fplugin-arg-NAME=ARG -fdump-ada-spec[-slim] -fada-spec-parent=UNIT -fdump-go-spec=FILE (Admittedly, Emacs by default hides some of the text of a cross-reference, but not hiding them in this case produces an even less legible text.) In general, it is a well-known rule that Texinfo documentation should NOT use @ref{foo} as if @ref will disappear without a trace, leaving just the hyperlink to 'foo'. Looks like the rewritten manual uses that a lot. This "see" consistently gets in the way throughout the entire manual. A few more examples: -- Option: -flocal-ivars Default option value for *note -fno-local-ivars. ... For example *note -std.‘=gnu90 -Wpedantic’ warns about C++ style ‘//’ comments, while *note -std.‘=gnu99 -Wpedantic’ does not. ... If this option is not provided but *note -Wabi.‘=`n'’ is, that version is used for compatibility aliases. ... Below *note -std.‘=c++20’, *note -fconcepts. enables support for the C++ Extensions for Concepts Technical Specification, ISO 19217 (2015). ... gcov [ *note -v. | *note –version. ] [ ‘-h’ | *note –help. ] 2. The translation of @var produces double-quoting in Info, here's an example: The usual way to run GCC is to run the executable called ‘gcc’, or ‘`machine'-gcc’ when cross-compiling, or ‘`machine'-gcc-`version'’ to run a specific version of GCC. vs, the old The usual way to run GCC is to run the executable called 'gcc', or 'MACHINE-gcc' when cross-compiling, or 'MACHINE-gcc-VERSION' to run a specific version of GCC. I think the new variant is less readable and more confusing, because it isn't clear whether the quotes are part of the text. Here's an extreme example: ‘@`file'’ Read command-line options from ‘`file'’. The options read are inserted in place of the original ‘@`file'’ option. If ‘`file'’ does not exist, or cannot be read, then the option will be treated literally, and not removed. 3. Some cross-references lost the hyperlinks: See option-index, for an index to GCC’s options. ("option-index" was a hyperlink to the corresponding index section). 4. Menus lost the short descriptions of the sub-sections. Example: * Designated Initializers * Case Ranges * Cast to a Union Type * Mixed Declarations, Labels and Code * Declaring Attributes of Functions vs * Designated Inits:: Labeling elements of initializers. * Case Ranges:: 'case 1 ... 9' and such. * Cast to Union:: Casting to union type from any member of the union. * Mixed Declarations:: Mixing declarations and code. * Function Attributes:: Declaring that functions have no side effects, or that they can never return. Looks like some bug to me. Note also that nodes are now called by the same name as the section, which means node names generally got much longer. Is that really a good idea? 5. There's some strange bug with symbols inside parentheses. For example: In GNU C and C++, you can use function attributes to specify certain function properties that may help the compiler optimize calls or check code more carefully for correctness. For example, you can use attributes to specify that a function never returns ( ‘noreturn’ ), returns a value depending only on the values of its arguments ( ‘const’ ), or has ‘printf’ -style arguments ( ‘format’ ). See the extra blanks inside parens? The old format was nicer: In GNU C and C++, you can use function attributes to specify certain function properties that may help the compiler optimize calls or check code more carefully for correctness. For example, you can use attributes to specify that a function never returns ('noreturn'), returns a value depending only on the values of its arguments ('const'), or has 'printf'-style arguments ('format'). 6. Something's wrong with the second footnote below: ---------- Footnotes ---------- (1) https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt (2) (1) A ‘call-used’ register is a register whose contents can be changed by a function call; therefore, a caller cannot assume that the register has the same contents on return from the function as it had before calling the function. Such registers are also called ‘call-clobbered’, ‘caller-saved’, or ‘volatile’. Why does the 2nd footnote have 2 note numbers? 7. Lines that shouldn't be broken, are: ‘`type' __sync_fetch_and_add (`type' *ptr, `type' value, ...)’ ‘`type' __sync_fetch_and_sub (`type' *ptr, `type' value, ...)’ ‘`type' __sync_fetch_and_or (`type' *ptr, `type' value, ...)’ ‘`type' __sync_fetch_and_and (`type' *ptr, `type' value, ...)’ ‘`type' __sync_fetch_and_xor (`type' *ptr, `type' value, ...)’ ‘`type' __sync_fetch_and_nand (`type' *ptr, `type' value, ...)’ vs 'TYPE __sync_fetch_and_add (TYPE *ptr, TYPE value, ...)' 'TYPE __sync_fetch_and_sub (TYPE *ptr, TYPE value, ...)' 'TYPE __sync_fetch_and_or (TYPE *ptr, TYPE value, ...)' 'TYPE __sync_fetch_and_and (TYPE *ptr, TYPE value, ...)' 'TYPE __sync_fetch_and_xor (TYPE *ptr, TYPE value, ...)' 'TYPE __sync_fetch_and_nand (TYPE *ptr, TYPE value, ...)' HTH ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [PATCH] Port GCC documentation to Sphinx 2021-06-29 16:57 ` Eli Zaretskii @ 2021-06-30 10:11 ` Martin Liška 2021-06-30 13:09 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-06-30 10:11 UTC (permalink / raw) To: Eli Zaretskii; +Cc: joseph, gcc, gcc-patches On 6/29/21 6:57 PM, Eli Zaretskii wrote: >> From: Martin Liška <mliska@suse.cz> >> Date: Tue, 29 Jun 2021 12:09:23 +0200 >> Cc: GCC Development <gcc@gcc.gnu.org>, gcc-patches@gcc.gnu.org >> >> On 6/28/21 5:33 PM, Joseph Myers wrote: >>> Are formatted manuals (HTML, PDF, man, info) corresponding to this patch >>> version also available for review? >> >> I've just uploaded them here: >> https://splichal.eu/gccsphinx-final/ > > Thanks. Hey! > > I'm an Info junkie, so I grabbed gcc.info from there and skimmed > through it. Please allow me a few unsolicited comments: I really welcome them! > > 1. It sounds like Sphinx is heavily biased towards HTML format, and as > result uglifies the Info format? Hopefully not :) > > For example, many cross-references (AFAIU introduced as part of > migration to Sphinx) make the text illegible in Emacs. Example: > > This standard, in both its forms, is commonly known as `C89', or > occasionally as `C90', from the dates of ratification. To select this > standard in GCC, use one of the options *note -ansi *note -std > .‘=c90’ or *note -std.‘=iso9899:1990’; to obtain all the diagnostics > required by the standard, you should also specify *note -pedantic. > (or *note -pedantic-errors. if you want them to be errors rather > than warnings). See *note Options Controlling C Dialect. > [...] > An amendment to the 1990 standard was published in 1995. This amendment > added digraphs and ‘__STDC_VERSION__’ to the language, but otherwise > concerned the library. This amendment is commonly known as `AMD1'; the > amended standard is sometimes known as `C94' or `C95'. To select this > standard in GCC, use the option *note -std.‘=iso9899:199409’ (with, > as for other standard versions, *note -pedantic. to receive all > required diagnostics). > > Or how about this: > > `Overall Options' > > See Options Controlling the Kind of Output. > > *note -c. *note -S. *note -E. *note -o. ‘`file'’ > *note -dumpbase. ‘`dumpbase'’ *note -dumpbase-ext. > ‘`auxdropsuf'’ *note -dumpdir. ‘`dumppfx'’ ‘-x’ ‘`language'’ > *note -v. *note -###. *note –help.‘[=`class'[,...]]’ > *note –target-help. *note –version. *note -pass-exit-codes > . *note -pipe. *note -specs.‘=`file'’ *note -wrapper > .‘@`file'’ *note -ffile-prefix-map.‘=`old'=`new'’ *note > -fplugin.‘=`file'’ ‘-fplugin-arg-’‘`name'=`arg'’ > ‘-fdump-ada-spec’‘[-`slim']’ *note -fada-spec-parent.‘=`unit'’ > *note -fdump-go-spec.‘=`file'’ > > In the first line, the emphasis became quotes, which sounds sub-optimal. > In the second line, the hyperlink was lost. > And the rest is not really readable. > > Compare this with the original: > > _Overall Options_ > *Note Options Controlling the Kind of Output. > -c -S -E -o FILE -x LANGUAGE > -v -### --help[=CLASS[,...]] --target-help --version > -pass-exit-codes -pipe -specs=FILE -wrapper > @FILE -ffile-prefix-map=OLD=NEW > -fplugin=FILE -fplugin-arg-NAME=ARG > -fdump-ada-spec[-slim] -fada-spec-parent=UNIT -fdump-go-spec=FILE > > (Admittedly, Emacs by default hides some of the text of a > cross-reference, but not hiding them in this case produces an even > less legible text.) If I'm correct, it's exactly what's documented in Sphinx FAQ here: https://www.sphinx-doc.org/en/master/faq.html#displaying-links and there's a suggested Emacs code snippet that should help with links. Does it help? > > In general, it is a well-known rule that Texinfo documentation should > NOT use @ref{foo} as if @ref will disappear without a trace, leaving > just the hyperlink to 'foo'. Looks like the rewritten manual uses > that a lot. > > This "see" consistently gets in the way throughout the entire manual. > A few more examples: > > -- Option: -flocal-ivars > > Default option value for *note -fno-local-ivars. > ... > For example *note -std.‘=gnu90 -Wpedantic’ warns about C++ style > ‘//’ comments, while *note -std.‘=gnu99 -Wpedantic’ does not. > ... > If this option is not provided but *note -Wabi.‘=`n'’ is, that > version is used for compatibility aliases. > ... > Below *note -std.‘=c++20’, *note -fconcepts. enables > support for the C++ Extensions for Concepts Technical > Specification, ISO 19217 (2015). > ... > gcov [ *note -v. | *note –version. ] [ ‘-h’ | *note –help. ] > > > 2. The translation of @var produces double-quoting in Info, here's an > example: > > The usual way to run GCC is to run the executable called ‘gcc’, or > ‘`machine'-gcc’ when cross-compiling, or ‘`machine'-gcc-`version'’ to > run a specific version of GCC. > > vs, the old > > The usual way to run GCC is to run the executable called 'gcc', or > 'MACHINE-gcc' when cross-compiling, or 'MACHINE-gcc-VERSION' to run a > specific version of GCC. > > I think the new variant is less readable and more confusing, because > it isn't clear whether the quotes are part of the text. Here's an > extreme example: > > ‘@`file'’ > > Read command-line options from ‘`file'’. The options read are > inserted in place of the original ‘@`file'’ option. If ‘`file'’ > does not exist, or cannot be read, then the option will be treated > literally, and not removed. I can confirm that, so e.g. Show :samp:`Samp with a {variable}.` is transformed into: Show @code{Samp with a @emph{variable}.} Default info formatting is selected as: @definfoenclose strong,`,' @definfoenclose emph,`,' We can adjust 'emph' formatting to nil, what do you think? > > 3. Some cross-references lost the hyperlinks: > > See option-index, for an index to GCC’s options. > > ("option-index" was a hyperlink to the corresponding index section). That's removed in latest version. > > 4. Menus lost the short descriptions of the sub-sections. Example: > > * Designated Initializers > * Case Ranges > * Cast to a Union Type > * Mixed Declarations, Labels and Code > * Declaring Attributes of Functions > > vs > > * Designated Inits:: Labeling elements of initializers. > * Case Ranges:: 'case 1 ... 9' and such. > * Cast to Union:: Casting to union type from any member of the union. > * Mixed Declarations:: Mixing declarations and code. > * Function Attributes:: Declaring that functions have no side effects, > or that they can never return. > > Looks like some bug to me. > > Note also that nodes are now called by the same name as the section, > which means node names generally got much longer. Is that really a > good idea? Well, I intentionally removed these and used simple TOC tree links which take display text for a section title. > > 5. There's some strange bug with symbols inside parentheses. For > example: > > In GNU C and C++, you can use function attributes to specify certain > function properties that may help the compiler optimize calls or check > code more carefully for correctness. For example, you can use > attributes to specify that a function never returns ( ‘noreturn’ ), > returns a value depending only on the values of its arguments ( ‘const’ > ), or has ‘printf’ -style arguments ( ‘format’ ). > > See the extra blanks inside parens? The old format was nicer: > > In GNU C and C++, you can use function attributes to specify certain > function properties that may help the compiler optimize calls or check > code more carefully for correctness. For example, you can use > attributes to specify that a function never returns ('noreturn'), > returns a value depending only on the values of its arguments ('const'), > or has 'printf'-style arguments ('format'). > > 6. Something's wrong with the second footnote below: > > ---------- Footnotes ---------- > > (1) > https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt > > (2) (1) A ‘call-used’ register is a register whose contents can be > changed by a function call; therefore, a caller cannot assume that the > register has the same contents on return from the function as it had > before calling the function. Such registers are also called > ‘call-clobbered’, ‘caller-saved’, or ‘volatile’. > > Why does the 2nd footnote have 2 note numbers? I can confirm the following code snippet: Note1: ([#]_) Note2: ([#]_) .. [#] Future versions of GCC may zero-extend, or use a target-defined ``ptr_extend`` pattern. Do not rely on sign extension. .. [#] I am note 2. emits the following texinfo: Note1: (@footnote{@w{(1)} Future versions of GCC may zero-extend, or use a target-defined @code{ptr_extend} pattern. Do not rely on sign extension. }) Note2: (@footnote{@w{(2)} I am note 2. }) Seems correct to be, but it's likely not. Let me investigate that. > > 7. Lines that shouldn't be broken, are: > > ‘`type' __sync_fetch_and_add (`type' *ptr, `type' value, ...)’ ‘`type' > __sync_fetch_and_sub (`type' *ptr, `type' value, ...)’ ‘`type' > __sync_fetch_and_or (`type' *ptr, `type' value, ...)’ ‘`type' > __sync_fetch_and_and (`type' *ptr, `type' value, ...)’ ‘`type' > __sync_fetch_and_xor (`type' *ptr, `type' value, ...)’ ‘`type' > __sync_fetch_and_nand (`type' *ptr, `type' value, ...)’ > > vs > > 'TYPE __sync_fetch_and_add (TYPE *ptr, TYPE value, ...)' > 'TYPE __sync_fetch_and_sub (TYPE *ptr, TYPE value, ...)' > 'TYPE __sync_fetch_and_or (TYPE *ptr, TYPE value, ...)' > 'TYPE __sync_fetch_and_and (TYPE *ptr, TYPE value, ...)' > 'TYPE __sync_fetch_and_xor (TYPE *ptr, TYPE value, ...)' > 'TYPE __sync_fetch_and_nand (TYPE *ptr, TYPE value, ...)' Yes, I can confirm that, it's on my TODO list right now. Thanks for useful comments. Martin > > HTH > ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [PATCH] Port GCC documentation to Sphinx 2021-06-30 10:11 ` Martin Liška @ 2021-06-30 13:09 ` Eli Zaretskii 2021-07-02 23:53 ` Hans-Peter Nilsson 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-06-30 13:09 UTC (permalink / raw) To: Martin Liška; +Cc: joseph, gcc, gcc-patches > Cc: joseph@codesourcery.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org > From: Martin Liška <mliska@suse.cz> > Date: Wed, 30 Jun 2021 12:11:03 +0200 > > > (Admittedly, Emacs by default hides some of the text of a > > cross-reference, but not hiding them in this case produces an even > > less legible text.) > > If I'm correct, it's exactly what's documented in Sphinx FAQ here: > https://www.sphinx-doc.org/en/master/faq.html#displaying-links > > and there's a suggested Emacs code snippet that should help with links. > Does it help? It helps some, but not all of the issues disappear. For example, stuff like this is still hard to read: To select this standard in GCC, use one of the options -ansi ----- -std.‘=c90’ or -std.‘=iso9899:1990’ ---- ---- The quotes around the option values don't help. Also, using the method proposed by Sphinx FAQ would need a change in Emacs, which will take time to propagate. So my suggestion is to minimize the use of such "inline" hyperlinks. > > ‘@`file'’ > > > > Read command-line options from ‘`file'’. The options read are > > inserted in place of the original ‘@`file'’ option. If ‘`file'’ > > does not exist, or cannot be read, then the option will be treated > > literally, and not removed. > > I can confirm that, so e.g. > Show :samp:`Samp with a {variable}.` > > is transformed into: > Show @code{Samp with a @emph{variable}.} > > Default info formatting is selected as: > > @definfoenclose strong,`,' > @definfoenclose emph,`,' > > We can adjust 'emph' formatting to nil, what do you think? Something like that, yes. But the problem is: how will you format it instead? The known alternatives, _foo_ and *foo* both use punctuation characters, which will get in the way similarly to the quotes. Can you format those in caps, like makeinfo does? > > 4. Menus lost the short descriptions of the sub-sections. Example: > > > > * Designated Initializers > > * Case Ranges > > * Cast to a Union Type > > * Mixed Declarations, Labels and Code > > * Declaring Attributes of Functions > > > > vs > > > > * Designated Inits:: Labeling elements of initializers. > > * Case Ranges:: 'case 1 ... 9' and such. > > * Cast to Union:: Casting to union type from any member of the union. > > * Mixed Declarations:: Mixing declarations and code. > > * Function Attributes:: Declaring that functions have no side effects, > > or that they can never return. > > > > Looks like some bug to me. > > > > Note also that nodes are now called by the same name as the section, > > which means node names generally got much longer. Is that really a > > good idea? > > Well, I intentionally removed these and used simple TOC tree links > which take display text for a section title. I would suggest to discuss these decisions first, perhaps on the Texinfo mailing list? I'm accustomed to these short descriptions, but I'm not sure how important they are for others. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: [PATCH] Port GCC documentation to Sphinx 2021-06-30 13:09 ` Eli Zaretskii @ 2021-07-02 23:53 ` Hans-Peter Nilsson 2021-07-12 13:25 ` Benefits of using Sphinx documentation format Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Hans-Peter Nilsson @ 2021-07-02 23:53 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Martin Liška, gcc, gcc-patches, joseph On Wed, 30 Jun 2021, Eli Zaretskii via Gcc-patches wrote: > > Cc: joseph@codesourcery.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org > > From: Martin Li?ka <mliska@suse.cz> > > Date: Wed, 30 Jun 2021 12:11:03 +0200 > > > 4. Menus lost the short descriptions of the sub-sections. Example: > > > > > > * Designated Initializers > > > * Case Ranges > > > * Cast to a Union Type > > > * Mixed Declarations, Labels and Code > > > * Declaring Attributes of Functions > > > > > > vs > > > > > > * Designated Inits:: Labeling elements of initializers. > > > * Case Ranges:: 'case 1 ... 9' and such. > > > * Cast to Union:: Casting to union type from any member of the union. > > > * Mixed Declarations:: Mixing declarations and code. > > > * Function Attributes:: Declaring that functions have no side effects, > > > or that they can never return. > > > > > > Looks like some bug to me. > > > > > > Note also that nodes are now called by the same name as the section, > > > which means node names generally got much longer. Is that really a > > > good idea? > > > > Well, I intentionally removed these and used simple TOC tree links > > which take display text for a section title. > > I would suggest to discuss these decisions first, perhaps on the > Texinfo mailing list? I'm accustomed to these short descriptions, but > I'm not sure how important they are for others. I'd miss them, and they're helpful when the title or term is not familiar, when looking for a concept you know is documented in there. I've read the discussion downthread, but I seem to miss (a recap of) the benefits of moving to Sphinx. Maybe other have too and it'd be a good idea to repeat them? Otherwise, the impression is not so good, as all I see is bits here and there getting lost in translation. brgds, H-P ^ permalink raw reply [flat|nested] 32+ messages in thread
* Benefits of using Sphinx documentation format 2021-07-02 23:53 ` Hans-Peter Nilsson @ 2021-07-12 13:25 ` Martin Liška 2021-07-12 13:39 ` Eli Zaretskii 2021-07-12 16:36 ` David Malcolm 0 siblings, 2 replies; 32+ messages in thread From: Martin Liška @ 2021-07-12 13:25 UTC (permalink / raw) To: Hans-Peter Nilsson, Eli Zaretskii; +Cc: gcc, gcc-patches, joseph Hello. Let's make it a separate sub-thread where we can discuss motivation why do I want moving to Sphinx format. Benefits: 1) modern looking HTML output (before: [1], after: [2]): a) syntax highlighting for examples (code, shell commands, etc.) b) precise anchors, the current Texinfo anchors are not displayed (start with first line of an option) c) one can easily copy a link to an anchor (displayed as ¶) d) internal links are working, e.g. one can easily jump from listing of options e) left menu navigation provides better orientation in the manual f) Sphinx provides internal search capability: [3] 2) internal links are also provided in PDF version of the manual 3) some existing GCC manuals are already written in Sphinx (GNAT manuals and libgccjit) 4) support for various output formats, some people are interested in ePUB format 5) Sphinx is using RST which is quite minimal semantic markup language 6) TOC is automatically generated - no need for manual navigation like seen here: [5] Disadvantages: 1) info pages are currently missing Page description in TOC 2) rich formatting is leading to extra wrapping in info output - beings partially addresses in [4] 3) one needs e.g. Emacs support for inline links (rendered as notes) I'm willing to address issue 1) in next weeks and I tend to skip emission of links as mentioned in 3). Generally speaking, I'm aware that some people still use Info, but I think we should more focus on more modern documentation formats. That's HTML (and partially PDF). Martin [1] https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing [2] https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing [3] https://splichal.eu/gccsphinx-final/html/gcc/search.html?q=-fipa-icf&check_keywords=yes&area=default# [4] https://github.com/sphinx-doc/sphinx/pull/9391 [5] @comment node-name, next, previous, up @node Installing GCC, Binaries, , Top ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 13:25 ` Benefits of using Sphinx documentation format Martin Liška @ 2021-07-12 13:39 ` Eli Zaretskii 2021-07-12 13:53 ` Jonathan Wakely 2021-07-12 14:37 ` Martin Liška 2021-07-12 16:36 ` David Malcolm 1 sibling, 2 replies; 32+ messages in thread From: Eli Zaretskii @ 2021-07-12 13:39 UTC (permalink / raw) To: Martin Liška; +Cc: hp, gcc, gcc-patches, joseph > Cc: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com > From: Martin Liška <mliska@suse.cz> > Date: Mon, 12 Jul 2021 15:25:47 +0200 > > Let's make it a separate sub-thread where we can discuss motivation why > do I want moving to Sphinx format. Thanks for starting this discussion. > Benefits: > 1) modern looking HTML output (before: [1], after: [2]): > a) syntax highlighting for examples (code, shell commands, etc.) > b) precise anchors, the current Texinfo anchors are not displayed (start with first line of an option) > c) one can easily copy a link to an anchor (displayed as ¶) > d) internal links are working, e.g. one can easily jump from listing of options > e) left menu navigation provides better orientation in the manual > f) Sphinx provides internal search capability: [3] > 2) internal links are also provided in PDF version of the manual How is this different from Texinfo? > 3) some existing GCC manuals are already written in Sphinx (GNAT manuals and libgccjit) > 4) support for various output formats, some people are interested in ePUB format Texinfo likewise supports many output formats. Someone presented a very simple package to produce epub format from it. > 5) Sphinx is using RST which is quite minimal semantic markup language Is it more minimal than Texinfo? > 6) TOC is automatically generated - no need for manual navigation like seen here: [5] That is not needed in Texinfo as well, since long ago. Nowadays, you just say @node Whatever and the rest is done automatically, as long as the manual's structure is a proper tree (which it normally is, I know of only one manual that is an exception). > Disadvantages: > > 1) info pages are currently missing Page description in TOC > 2) rich formatting is leading to extra wrapping in info output - beings partially addresses in [4] > 3) one needs e.g. Emacs support for inline links (rendered as notes) 4) The need to learn yet another markup language. While this is not a problem for simple text, it does require a serious study of RST and Sphinx to use the more advanced features. 5) Lack of macros. AFAIK, only simple textual substitution is available, no macros with arguments. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 13:39 ` Eli Zaretskii @ 2021-07-12 13:53 ` Jonathan Wakely 2021-07-12 14:05 ` Jonathan Wakely 2021-07-12 14:12 ` Eli Zaretskii 2021-07-12 14:37 ` Martin Liška 1 sibling, 2 replies; 32+ messages in thread From: Jonathan Wakely @ 2021-07-12 13:53 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Martin Liška, gcc, gcc-patches, Joseph S. Myers On Mon, 12 Jul 2021 at 14:41, Eli Zaretskii via Gcc <gcc@gcc.gnu.org> wrote: > > > Cc: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com > > From: Martin Liška <mliska@suse.cz> > > Date: Mon, 12 Jul 2021 15:25:47 +0200 > > > > Let's make it a separate sub-thread where we can discuss motivation why > > do I want moving to Sphinx format. > > Thanks for starting this discussion. > > > Benefits: > > 1) modern looking HTML output (before: [1], after: [2]): > > a) syntax highlighting for examples (code, shell commands, etc.) > > b) precise anchors, the current Texinfo anchors are not displayed (start with first line of an option) > > c) one can easily copy a link to an anchor (displayed as ¶) > > d) internal links are working, e.g. one can easily jump from listing of options For me, these items are enough justification to switch away from texinfo, which produces crap HTML pages with crap anchors. You can't find out the anchors without inspecting (and searching) the HTML source. That's utterly stupid. And even after you do that, the anchor is at the wrong place: https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c As somebody who spends a lot of time helping users on the mailing list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo HTML has angered me for many years. Yes, some people like texinfo, but some people also dislike it and there are serious usability problems with the output. I support replacing texinfo with anything that isn't texinfo. > > e) left menu navigation provides better orientation in the manual > > f) Sphinx provides internal search capability: [3] > > 2) internal links are also provided in PDF version of the manual > > How is this different from Texinfo? > > > 3) some existing GCC manuals are already written in Sphinx (GNAT manuals and libgccjit) > > 4) support for various output formats, some people are interested in ePUB format > > Texinfo likewise supports many output formats. Someone presented a > very simple package to produce epub format from it. > > > 5) Sphinx is using RST which is quite minimal semantic markup language > > Is it more minimal than Texinfo? > > > 6) TOC is automatically generated - no need for manual navigation like seen here: [5] > > That is not needed in Texinfo as well, since long ago. Nowadays, you > just say > > @node Whatever > > and the rest is done automatically, as long as the manual's structure > is a proper tree (which it normally is, I know of only one manual that > is an exception). > > > Disadvantages: > > > > 1) info pages are currently missing Page description in TOC > > 2) rich formatting is leading to extra wrapping in info output - beings partially addresses in [4] > > 3) one needs e.g. Emacs support for inline links (rendered as notes) > > 4) The need to learn yet another markup language. > While this is not a problem for simple text, it does require a > serious study of RST and Sphinx to use the more advanced features. This is a problem with texinfo too. > > 5) Lack of macros. > AFAIK, only simple textual substitution is available, no macros > with arguments. Is this a problem for GCC docs though? ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 13:53 ` Jonathan Wakely @ 2021-07-12 14:05 ` Jonathan Wakely 2021-07-12 14:16 ` Eli Zaretskii 2021-07-12 14:12 ` Eli Zaretskii 1 sibling, 1 reply; 32+ messages in thread From: Jonathan Wakely @ 2021-07-12 14:05 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Martin Liška, gcc, gcc-patches, Joseph S. Myers On Mon, 12 Jul 2021 at 14:53, Jonathan Wakely wrote: > For me, these items are enough justification to switch away from > texinfo, which produces crap HTML pages with crap anchors. You can't > find out the anchors without inspecting (and searching) the HTML > source. That's utterly stupid. And even after you do that, the anchor > is at the wrong place: > https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c > As somebody who spends a lot of time helping users on the mailing > list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo > HTML has angered me for many years. To be clear, I give links to users frequently (several times a week, every week, for decades) and prefer to give them a link to specific options. Obviously I link to the online HTML docs rather than telling them an 'info' command to run, because most people don't use info pages or know how to navigate them. That means I can't provide decent links, because the actual option name I'm trying to link to is always off the top of the page. This is simply unacceptable IMHO. Texinfo must go. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:05 ` Jonathan Wakely @ 2021-07-12 14:16 ` Eli Zaretskii 2021-07-12 14:34 ` Martin Liška 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-07-12 14:16 UTC (permalink / raw) To: Jonathan Wakely; +Cc: mliska, gcc, gcc-patches, joseph > From: Jonathan Wakely <jwakely.gcc@gmail.com> > Date: Mon, 12 Jul 2021 15:05:11 +0100 > Cc: Martin Liška <mliska@suse.cz>, > "gcc@gcc.gnu.org" <gcc@gcc.gnu.org>, gcc-patches <gcc-patches@gcc.gnu.org>, > "Joseph S. Myers" <joseph@codesourcery.com> > > To be clear, I give links to users frequently (several times a week, > every week, for decades) and prefer to give them a link to specific > options. Obviously I link to the online HTML docs rather than telling > them an 'info' command to run, because most people don't use info > pages or know how to navigate them. That means I can't provide decent > links, because the actual option name I'm trying to link to is always > off the top of the page. This is simply unacceptable IMHO. Texinfo > must go. "Texinfo must go" is one possible conclusion from your description. But it isn't the only one. An alternative is "the Texinfo source of the GCC manual must be improved to fix this problem." And yes, this problem does have a solution in Texinfo. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:16 ` Eli Zaretskii @ 2021-07-12 14:34 ` Martin Liška 2021-07-12 17:09 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-07-12 14:34 UTC (permalink / raw) To: Eli Zaretskii, Jonathan Wakely; +Cc: gcc, gcc-patches, joseph On 7/12/21 4:16 PM, Eli Zaretskii wrote: >> From: Jonathan Wakely <jwakely.gcc@gmail.com> >> Date: Mon, 12 Jul 2021 15:05:11 +0100 >> Cc: Martin Liška <mliska@suse.cz>, >> "gcc@gcc.gnu.org" <gcc@gcc.gnu.org>, gcc-patches <gcc-patches@gcc.gnu.org>, >> "Joseph S. Myers" <joseph@codesourcery.com> >> >> To be clear, I give links to users frequently (several times a week, >> every week, for decades) and prefer to give them a link to specific >> options. Obviously I link to the online HTML docs rather than telling >> them an 'info' command to run, because most people don't use info >> pages or know how to navigate them. That means I can't provide decent >> links, because the actual option name I'm trying to link to is always >> off the top of the page. This is simply unacceptable IMHO. Texinfo >> must go. > > "Texinfo must go" is one possible conclusion from your description. > But it isn't the only one. An alternative is "the Texinfo source of > the GCC manual must be improved to fix this problem." And yes, this > problem does have a solution in Texinfo. No, the alternative is more powerful output given by Texinfo, in particular more modern HTML pages. Martin ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:34 ` Martin Liška @ 2021-07-12 17:09 ` Eli Zaretskii 0 siblings, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2021-07-12 17:09 UTC (permalink / raw) To: Martin Liška; +Cc: jwakely.gcc, gcc, gcc-patches, joseph > Cc: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com > From: Martin Liška <mliska@suse.cz> > Date: Mon, 12 Jul 2021 16:34:11 +0200 > > > "Texinfo must go" is one possible conclusion from your description. > > But it isn't the only one. An alternative is "the Texinfo source of > > the GCC manual must be improved to fix this problem." And yes, this > > problem does have a solution in Texinfo. > > No, the alternative is more powerful output given by Texinfo, in particular > more modern HTML pages. Please see the response by Gavin: it sounds like at least some of that was resolved in Texinfo, sometimes long ago. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 13:53 ` Jonathan Wakely 2021-07-12 14:05 ` Jonathan Wakely @ 2021-07-12 14:12 ` Eli Zaretskii 2021-07-12 14:30 ` Martin Liška 2021-07-12 14:52 ` Jonathan Wakely 1 sibling, 2 replies; 32+ messages in thread From: Eli Zaretskii @ 2021-07-12 14:12 UTC (permalink / raw) To: Jonathan Wakely; +Cc: mliska, gcc, gcc-patches, joseph > From: Jonathan Wakely <jwakely.gcc@gmail.com> > Date: Mon, 12 Jul 2021 14:53:44 +0100 > Cc: Martin Liška <mliska@suse.cz>, > "gcc@gcc.gnu.org" <gcc@gcc.gnu.org>, gcc-patches <gcc-patches@gcc.gnu.org>, > "Joseph S. Myers" <joseph@codesourcery.com> > > For me, these items are enough justification to switch away from > texinfo, which produces crap HTML pages with crap anchors. If we want to have a serious discussion with useful conclusions, I suggest to avoid "loaded" terminology. I get it that you dislike the HTML produced by Texinfo, but without some examples of such bad HTML it is impossible to know what exactly do you dislike and why. > You can't find out the anchors without inspecting (and searching) > the HTML source. That's utterly stupid. I don't think I follow: find out the anchors with which means and for what purposes? > And even after you do that, the anchor > is at the wrong place: > https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c IME, the anchor is where you put it. If you show me the source of that HTMl, maybe we can have a more useful discussion of the issue. > As somebody who spends a lot of time helping users on the mailing > list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo > HTML has angered me for many years. As somebody who spends a lot of time helping users on every possible forum, and as someone who has wrote a lot of Texinfo, I don't understand what angers you. Please elaborate. > Yes, some people like texinfo, but some people also dislike it and > there are serious usability problems with the output. I support > replacing texinfo with anything that isn't texinfo. "Anything"? Even plain text? I hope not. See, such "arguments" don't help to have a useful discussion. > > 4) The need to learn yet another markup language. > > While this is not a problem for simple text, it does require a > > serious study of RST and Sphinx to use the more advanced features. > > This is a problem with texinfo too. Not for someone who already knows Texinfo. We are talking about switching away of it, so I'm thinking about people who contributed patches for the manual in the past. They already know Texinfo, at least to some extent, and some of them know it very well. > > 5) Lack of macros. > > AFAIK, only simple textual substitution is available, no macros > > with arguments. > > Is this a problem for GCC docs though? I don't know. It could be, even if it isn't now. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:12 ` Eli Zaretskii @ 2021-07-12 14:30 ` Martin Liška 2021-07-12 14:54 ` Matthias Kretz 2021-07-12 14:52 ` Jonathan Wakely 1 sibling, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-07-12 14:30 UTC (permalink / raw) To: Eli Zaretskii, Jonathan Wakely; +Cc: gcc, gcc-patches, joseph On 7/12/21 4:12 PM, Eli Zaretskii wrote: >> From: Jonathan Wakely <jwakely.gcc@gmail.com> >> Date: Mon, 12 Jul 2021 14:53:44 +0100 >> Cc: Martin Liška <mliska@suse.cz>, >> "gcc@gcc.gnu.org" <gcc@gcc.gnu.org>, gcc-patches <gcc-patches@gcc.gnu.org>, >> "Joseph S. Myers" <joseph@codesourcery.com> >> >> For me, these items are enough justification to switch away from >> texinfo, which produces crap HTML pages with crap anchors. > > If we want to have a serious discussion with useful conclusions, I > suggest to avoid "loaded" terminology. > > I get it that you dislike the HTML produced by Texinfo, but without > some examples of such bad HTML it is impossible to know what exactly > do you dislike and why. Please follow my 1) from Benefits and *read* bullet points a) to f). That will give you an answer. > >> You can't find out the anchors without inspecting (and searching) >> the HTML source. That's utterly stupid. > > I don't think I follow: find out the anchors with which means and for > what purposes? Benefits, 1c). > >> And even after you do that, the anchor >> is at the wrong place: >> https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c > > IME, the anchor is where you put it. If you show me the source of > that HTMl, maybe we can have a more useful discussion of the issue. Problem is that Texinfo emits poor HTML where # link points to a wrong place. Open the given page, view source and search for <dd><a name="index-c"></a>. > >> As somebody who spends a lot of time helping users on the mailing >> list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo >> HTML has angered me for many years. > > As somebody who spends a lot of time helping users on every possible > forum, and as someone who has wrote a lot of Texinfo, I don't > understand what angers you. Please elaborate. You can't point to an option documentation. > >> Yes, some people like texinfo, but some people also dislike it and >> there are serious usability problems with the output. I support >> replacing texinfo with anything that isn't texinfo. > > "Anything"? Even plain text? I hope not. > > See, such "arguments" don't help to have a useful discussion. > >>> 4) The need to learn yet another markup language. >>> While this is not a problem for simple text, it does require a >>> serious study of RST and Sphinx to use the more advanced features. >> >> This is a problem with texinfo too. > > Not for someone who already knows Texinfo. We are talking about > switching away of it, so I'm thinking about people who contributed > patches for the manual in the past. They already know Texinfo, at > least to some extent, and some of them know it very well. Yes, people will have to learn a new syntax. Similarly to transition of SVN, people also had to learn with a more modern tool. > >>> 5) Lack of macros. >>> AFAIK, only simple textual substitution is available, no macros >>> with arguments. >> >> Is this a problem for GCC docs though? > > I don't know. It could be, even if it isn't now. Then it's not an argument, sorry. Martin ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:30 ` Martin Liška @ 2021-07-12 14:54 ` Matthias Kretz 2021-07-12 17:03 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Matthias Kretz @ 2021-07-12 14:54 UTC (permalink / raw) To: gcc Hi. I'm commenting as a long-time GCC user and reader of the manual (never via info reader, mostly via DuckDuckGo / Google -> HTML docs) who recently started contributing more than just PRs. On Monday, 12 July 2021 16:30:23 CEST Martin Liška wrote: > On 7/12/21 4:12 PM, Eli Zaretskii wrote: > > I get it that you dislike the HTML produced by Texinfo, but without > > some examples of such bad HTML it is impossible to know what exactly > > do you dislike and why. I believe Martin made a really good list. But FWIW, when I reach the GCC HTML docs it's like a blast from the past. It looks more or less exactly like web pages looked in the 90ies. To me, that gives GCC an image of an old and sluggishly moving project. And to me that's a high priority issue. I have to size down the browser window so that line lengths are bearable. I have to scroll to the top/bottom of the page for navigation. Navigating through the tree of pages requires you to learn how it works; it's not intuitive at all. If the decision for how to write and read documentation places 'info' in higher priority than HTML then that would emphasize "the image of an old and sluggishly moving project" even more than the sight of the HTML pages. Who is the target audience? > >>> 4) The need to learn yet another markup language. > >>> > >>> While this is not a problem for simple text, it does require a > >>> serious study of RST and Sphinx to use the more advanced features. > >> > >> This is a problem with texinfo too. > > > > Not for someone who already knows Texinfo. We are talking about > > switching away of it, so I'm thinking about people who contributed > > patches for the manual in the past. They already know Texinfo, at > > least to some extent, and some of them know it very well. > > Yes, people will have to learn a new syntax. Similarly to transition of SVN, > people also had to learn with a more modern tool. Same issue. Is the goal to accommodate only seasoned GNU contributors? Basically everyone nowadays knows and uses Markdown. RST is not far from that. So it opens up the project for way more people to contribute. I wrote documentation patches recently. I found it really awkward to write. Markup languages have gotten better and I really hope we can move on! > >>> 5) Lack of macros. > >>> > >>> AFAIK, only simple textual substitution is available, no macros > >>> with arguments. I don't recall for sure, but I think I did that with RST at some point. Best, Matthias -- ────────────────────────────────────────────────────────────────────────── Dr. Matthias Kretz https://mattkretz.github.io GSI Helmholtz Centre for Heavy Ion Research https://gsi.de std::experimental::simd https://github.com/VcDevel/std-simd ────────────────────────────────────────────────────────────────────────── ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:54 ` Matthias Kretz @ 2021-07-12 17:03 ` Eli Zaretskii 2021-07-12 17:15 ` Jonathan Wakely 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-07-12 17:03 UTC (permalink / raw) To: Matthias Kretz; +Cc: gcc > From: Matthias Kretz <m.kretz@gsi.de> > Date: Mon, 12 Jul 2021 16:54:50 +0200 > > On Monday, 12 July 2021 16:30:23 CEST Martin Liška wrote: > > On 7/12/21 4:12 PM, Eli Zaretskii wrote: > > > I get it that you dislike the HTML produced by Texinfo, but without > > > some examples of such bad HTML it is impossible to know what exactly > > > do you dislike and why. > > I believe Martin made a really good list. Gavin Smith, the GNU Texinfo maintainer, responded in detail to that list. However, his message didn't get through to the list, for some reason. Can someone please see why, and release his message? I think he makes some important points, and his message does deserve being posted and read as part of this discussion. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 17:03 ` Eli Zaretskii @ 2021-07-12 17:15 ` Jonathan Wakely 2021-07-12 17:23 ` Eli Zaretskii 2021-07-13 6:24 ` Richard Biener 0 siblings, 2 replies; 32+ messages in thread From: Jonathan Wakely @ 2021-07-12 17:15 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Matthias Kretz, gcc On Mon, 12 Jul 2021 at 18:04, Eli Zaretskii via Gcc <gcc@gcc.gnu.org> wrote: > > > From: Matthias Kretz <m.kretz@gsi.de> > > Date: Mon, 12 Jul 2021 16:54:50 +0200 > > > > On Monday, 12 July 2021 16:30:23 CEST Martin Liška wrote: > > > On 7/12/21 4:12 PM, Eli Zaretskii wrote: > > > > I get it that you dislike the HTML produced by Texinfo, but without > > > > some examples of such bad HTML it is impossible to know what exactly > > > > do you dislike and why. > > > > I believe Martin made a really good list. > > Gavin Smith, the GNU Texinfo maintainer, responded in detail to that > list. However, his message didn't get through to the list, for some > reason. It did: https://gcc.gnu.org/pipermail/gcc/2021-July/236744.html https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574987.html The HTML attachment has been stripped though. The relevant part of the HTML looks like this: <dt id='index-_002d_002dgreeting'><span><samp>--greeting=<var>text</var></samp><a href='#index-_002d_002dgreeting' class='copiable-anchor'> ¶</a></span></dt> <dt><span><samp>-g <var>text</var></samp></span></dt> <dd><span id="index-_002dg"></span> <p>Output <var>text</var> instead of the default greeting. </p> </dd> Note the <a ...> ¶ </a> anchor that is part of the <dt> element, not the <dd> (where the index-__002d anchor is still located). > Can someone please see why, and release his message? I think > he makes some important points, and his message does deserve being > posted and read as part of this discussion. He shows that some of the linking issues are addressed in the latest texinfo release, which is great. But it doesn't negate all Martin's other points. GCC devs and users who frequently modify or refer to the HTML docs want to replace texinfo. One vocal objector who just keeps repeating that texinfo is fine should not block that progress. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 17:15 ` Jonathan Wakely @ 2021-07-12 17:23 ` Eli Zaretskii 2021-07-12 17:33 ` Jonathan Wakely 2021-07-13 6:24 ` Richard Biener 1 sibling, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-07-12 17:23 UTC (permalink / raw) To: Jonathan Wakely; +Cc: m.kretz, gcc > From: Jonathan Wakely <jwakely.gcc@gmail.com> > Date: Mon, 12 Jul 2021 18:15:26 +0100 > Cc: Matthias Kretz <m.kretz@gsi.de>, "gcc@gcc.gnu.org" <gcc@gcc.gnu.org> > > > Gavin Smith, the GNU Texinfo maintainer, responded in detail to that > > list. However, his message didn't get through to the list, for some > > reason. > > It did: > https://gcc.gnu.org/pipermail/gcc/2021-July/236744.html > https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574987.html That's not the message I was talking about. Gavin sent another, which didn't get posted. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 17:23 ` Eli Zaretskii @ 2021-07-12 17:33 ` Jonathan Wakely 0 siblings, 0 replies; 32+ messages in thread From: Jonathan Wakely @ 2021-07-12 17:33 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Matthias Kretz, gcc On Mon, 12 Jul 2021 at 18:24, Eli Zaretskii wrote: > > > From: Jonathan Wakely <jwakely.gcc@gmail.com> > > Date: Mon, 12 Jul 2021 18:15:26 +0100 > > Cc: Matthias Kretz <m.kretz@gsi.de>, "gcc@gcc.gnu.org" <gcc@gcc.gnu.org> > > > > > Gavin Smith, the GNU Texinfo maintainer, responded in detail to that > > > list. However, his message didn't get through to the list, for some > > > reason. > > > > It did: > > https://gcc.gnu.org/pipermail/gcc/2021-July/236744.html > > https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574987.html > > That's not the message I was talking about. Gavin sent another, which > didn't get posted. Ah, then he'll have to try resending it. There's nothing to "release", if the mail didn't get through then it's gone, not in a mod queue. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 17:15 ` Jonathan Wakely 2021-07-12 17:23 ` Eli Zaretskii @ 2021-07-13 6:24 ` Richard Biener 2021-07-13 11:52 ` Eli Zaretskii 2021-07-13 14:19 ` Jonathan Wakely 1 sibling, 2 replies; 32+ messages in thread From: Richard Biener @ 2021-07-13 6:24 UTC (permalink / raw) To: Jonathan Wakely; +Cc: Eli Zaretskii, gcc On Mon, Jul 12, 2021 at 7:20 PM Jonathan Wakely via Gcc <gcc@gcc.gnu.org> wrote: > > On Mon, 12 Jul 2021 at 18:04, Eli Zaretskii via Gcc <gcc@gcc.gnu.org> wrote: > > > > > From: Matthias Kretz <m.kretz@gsi.de> > > > Date: Mon, 12 Jul 2021 16:54:50 +0200 > > > > > > On Monday, 12 July 2021 16:30:23 CEST Martin Liška wrote: > > > > On 7/12/21 4:12 PM, Eli Zaretskii wrote: > > > > > I get it that you dislike the HTML produced by Texinfo, but without > > > > > some examples of such bad HTML it is impossible to know what exactly > > > > > do you dislike and why. > > > > > > I believe Martin made a really good list. > > > > Gavin Smith, the GNU Texinfo maintainer, responded in detail to that > > list. However, his message didn't get through to the list, for some > > reason. > > It did: > https://gcc.gnu.org/pipermail/gcc/2021-July/236744.html > https://gcc.gnu.org/pipermail/gcc-patches/2021-July/574987.html > > The HTML attachment has been stripped though. The relevant part of the > HTML looks like this: > > <dt id='index-_002d_002dgreeting'><span><samp>--greeting=<var>text</var></samp><a > href='#index-_002d_002dgreeting' class='copiable-anchor'> > ¶</a></span></dt> > <dt><span><samp>-g <var>text</var></samp></span></dt> > <dd><span id="index-_002dg"></span> > <p>Output <var>text</var> instead of the default greeting. > </p> > </dd> > > Note the <a ...> ¶ </a> anchor that is part of the <dt> element, > not the <dd> (where the index-__002d anchor is still located). > > > > Can someone please see why, and release his message? I think > > he makes some important points, and his message does deserve being > > posted and read as part of this discussion. > > He shows that some of the linking issues are addressed in the latest > texinfo release, which is great. But it doesn't negate all Martin's > other points. > > GCC devs and users who frequently modify or refer to the HTML docs > want to replace texinfo. One vocal objector who just keeps repeating > that texinfo is fine should not block that progress. You mean one very vocal and one active developers want to replace it? I actually like texinfo (well, because I know it somewhat, compare to sphinx). I think it produces quite decent PDF manuals. I never use the html output (in fact I read our manual using grep & vim in the original .texi form ...). But then I'm mostly of the who-does-the-work-decides attitude - so if there are people driving a transition to sphinx because they want to improve sth and they don't manage to do that with texinfo (for whatever reason) then OK. As long as it doesn't regress my personal usecase (I hope the sphinx docs are still digestable in source form, which I understand they are). Just I really suggest to not claim its texinfos fault. It's likely not. It's likely the fault of GCCs manual being "old" and hasn't catched up with new texinfo features. And where texinfo has bugs they likely can be fixed. Just my (final) 2c to this discussion. Richard. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-13 6:24 ` Richard Biener @ 2021-07-13 11:52 ` Eli Zaretskii 2021-07-13 12:46 ` Richard Biener 2021-08-09 12:12 ` Martin Liška 2021-07-13 14:19 ` Jonathan Wakely 1 sibling, 2 replies; 32+ messages in thread From: Eli Zaretskii @ 2021-07-13 11:52 UTC (permalink / raw) To: Richard Biener; +Cc: jwakely.gcc, gcc > From: Richard Biener <richard.guenther@gmail.com> > Date: Tue, 13 Jul 2021 08:24:17 +0200 > Cc: Eli Zaretskii <eliz@gnu.org>, "gcc@gcc.gnu.org" <gcc@gcc.gnu.org> > > I actually like texinfo (well, because I know it somewhat, compare to sphinx). > I think it produces quite decent PDF manuals. I never use the html > output (in fact I read our manual using grep & vim in the original > .texi form ...). FTR, I almost exclusively use the (Emacs) Info reader to read the manuals in Info format. I never understood those who prefer reading HTML-formatted docs in a Web browser. The advanced features of Info: the index-search with powerful completion built-in, seamless cross-references between manuals, the ability to search all of the manuals installed on my system and then browse the results, the ability to have Emacs land me at the documentation of the symbol under the cursor regardless of its language/package/library, no dependency on connectivity, to mention just a few -- all those are tremendous productivity boosters. I rarely spend more than a few seconds to find the piece of documentation I need (not including reading it, of course). (And yes, grep-style regexp search through the entire manual is also available, although I only need to use it in rare and exceptional circumstances.) So I never understood people, let alone developers, who are willing to throw such power out the window and use HTML. I only do that when there's a manual I don't have installed in the Info format (a rare phenomenon) or some other similarly exceptional cases. But I get it that there are strange people who prefer HTML nonetheless. More importantly, the Texinfo developers understand that, and actively work towards making the Texinfo HTML better, with some impressive progress already there, see the latest release 6.8 of Texinfo (Gavin mentioned some of the advances). ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-13 11:52 ` Eli Zaretskii @ 2021-07-13 12:46 ` Richard Biener 2021-07-13 12:55 ` Eli Zaretskii 2021-08-09 12:12 ` Martin Liška 1 sibling, 1 reply; 32+ messages in thread From: Richard Biener @ 2021-07-13 12:46 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Jonathan Wakely, GCC Development On Tue, Jul 13, 2021 at 1:52 PM Eli Zaretskii <eliz@gnu.org> wrote: > > > From: Richard Biener <richard.guenther@gmail.com> > > Date: Tue, 13 Jul 2021 08:24:17 +0200 > > Cc: Eli Zaretskii <eliz@gnu.org>, "gcc@gcc.gnu.org" <gcc@gcc.gnu.org> > > > > I actually like texinfo (well, because I know it somewhat, compare to sphinx). > > I think it produces quite decent PDF manuals. I never use the html > > output (in fact I read our manual using grep & vim in the original > > .texi form ...). > > FTR, I almost exclusively use the (Emacs) Info reader to read the > manuals in Info format. I never understood those who prefer reading > HTML-formatted docs in a Web browser. The advanced features of Info: > the index-search with powerful completion built-in, seamless > cross-references between manuals, the ability to search all of the > manuals installed on my system and then browse the results, the > ability to have Emacs land me at the documentation of the symbol under > the cursor regardless of its language/package/library, no dependency > on connectivity, to mention just a few -- all those are tremendous > productivity boosters. I rarely spend more than a few seconds to find > the piece of documentation I need (not including reading it, of > course). (And yes, grep-style regexp search through the entire manual > is also available, although I only need to use it in rare and > exceptional circumstances.) > > So I never understood people, let alone developers, who are willing to > throw such power out the window and use HTML. I only do that when > there's a manual I don't have installed in the Info format (a rare > phenomenon) or some other similarly exceptional cases. But I get it > that there are strange people who prefer HTML nonetheless. More > importantly, the Texinfo developers understand that, and actively work > towards making the Texinfo HTML better, with some impressive progress > already there, see the latest release 6.8 of Texinfo (Gavin mentioned > some of the advances). I can very well understand the use of the html manual when you want to share pointers to specific parts of the documentation in communications. I think that's the main motivation here - users are nowadays familiar with mouse-clicking and the web, not so much with emacs or any other way to consume texinfo documentation. I'm also not sure if there's some texinfo URI that could be used to share documentation pointers. Richard. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-13 12:46 ` Richard Biener @ 2021-07-13 12:55 ` Eli Zaretskii 0 siblings, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2021-07-13 12:55 UTC (permalink / raw) To: Richard Biener; +Cc: jwakely.gcc, gcc > From: Richard Biener <richard.guenther@gmail.com> > Date: Tue, 13 Jul 2021 14:46:33 +0200 > Cc: Jonathan Wakely <jwakely.gcc@gmail.com>, GCC Development <gcc@gcc.gnu.org> > I can very well understand the use of the html manual when you want > to share pointers to specific parts of the documentation in communications. In the Emacs community, we have a notation for a pointer to an Info node FOO in the manual BAR that Emacs understands -- you just hit a key, and Emacs lands you there. So if you use the Emacs Info reader, this issue doesn't exist. > I'm also not sure if there's some texinfo URI that could be used to > share documentation pointers. Another Emacs command automatically produces a pointer to the current node in an Info manuals in the above format. So if I want to share a pointer with you, I invoke that command, paste the result into an email message, and you on your end invoke that other command. Problem solved. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-13 11:52 ` Eli Zaretskii 2021-07-13 12:46 ` Richard Biener @ 2021-08-09 12:12 ` Martin Liška 1 sibling, 0 replies; 32+ messages in thread From: Martin Liška @ 2021-08-09 12:12 UTC (permalink / raw) To: Eli Zaretskii, Richard Biener; +Cc: gcc On 7/13/21 1:52 PM, Eli Zaretskii via Gcc wrote: >> From: Richard Biener <richard.guenther@gmail.com> >> Date: Tue, 13 Jul 2021 08:24:17 +0200 >> Cc: Eli Zaretskii <eliz@gnu.org>, "gcc@gcc.gnu.org" <gcc@gcc.gnu.org> >> >> I actually like texinfo (well, because I know it somewhat, compare to sphinx). >> I think it produces quite decent PDF manuals. I never use the html >> output (in fact I read our manual using grep & vim in the original >> .texi form ...). > > FTR, I almost exclusively use the (Emacs) Info reader to read the > manuals in Info format. I never understood those who prefer reading > HTML-formatted docs in a Web browser. It's very easy. HTML output is much nice from the visual point of view and everybody uses a browser nowadays. Moreover, one can easily Google for e.g. option name, or provide a link at pages like StackOverflow. That's reality. > > So I never understood people, let alone developers, who are willing to > throw such power out the window and use HTML. I only do that when > there's a manual I don't have installed in the Info format (a rare > phenomenon) or some other similarly exceptional cases. But I get it > that there are strange people who prefer HTML nonetheless. More > importantly, the Texinfo developers understand that, and actively work > towards making the Texinfo HTML better, with some impressive progress > already there, see the latest release 6.8 of Texinfo (Gavin mentioned > some of the advances). > I've read that and yes, there's a progress. However, I still see a rapid gap in what can be achieved by a mode modern tool like Sphinx. Martin ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-13 6:24 ` Richard Biener 2021-07-13 11:52 ` Eli Zaretskii @ 2021-07-13 14:19 ` Jonathan Wakely 1 sibling, 0 replies; 32+ messages in thread From: Jonathan Wakely @ 2021-07-13 14:19 UTC (permalink / raw) To: Richard Biener; +Cc: Eli Zaretskii, gcc On Tue, 13 Jul 2021 at 07:24, Richard Biener wrote: > > On Mon, Jul 12, 2021 at 7:20 PM Jonathan Wakely via Gcc <gcc@gcc.gnu.org> wrote: > > GCC devs and users who frequently modify or refer to the HTML docs > > want to replace texinfo. One vocal objector who just keeps repeating > > that texinfo is fine should not block that progress. > > You mean one very vocal and one active developers want to replace it? Both Dave Malcolm and Martin have actually done the work to migrate to Sphinx, so that's already two before I even added my voice in favour. > I actually like texinfo (well, because I know it somewhat, compare to sphinx). > I think it produces quite decent PDF manuals. I never use the html > output (in fact I read our manual using grep & vim in the original > .texi form ...). > > But then I'm mostly of the who-does-the-work-decides attitude - so if there > are people driving a transition to sphinx because they want to improve sth > and they don't manage to do that with texinfo (for whatever reason) then OK. > As long as it doesn't regress my personal usecase (I hope the sphinx > docs are still > digestable in source form, which I understand they are). Sure, it's very much intended to be readable in the "raw" form, not just the generated output. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:12 ` Eli Zaretskii 2021-07-12 14:30 ` Martin Liška @ 2021-07-12 14:52 ` Jonathan Wakely 2021-07-12 14:54 ` Jonathan Wakely 2021-07-12 15:03 ` Jonathan Wakely 1 sibling, 2 replies; 32+ messages in thread From: Jonathan Wakely @ 2021-07-12 14:52 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Martin Liška, gcc, gcc-patches, Joseph S. Myers On Mon, 12 Jul 2021 at 15:13, Eli Zaretskii <eliz@gnu.org> wrote: > > > From: Jonathan Wakely <jwakely.gcc@gmail.com> > > Date: Mon, 12 Jul 2021 14:53:44 +0100 > > Cc: Martin Liška <mliska@suse.cz>, > > "gcc@gcc.gnu.org" <gcc@gcc.gnu.org>, gcc-patches <gcc-patches@gcc.gnu.org>, > > "Joseph S. Myers" <joseph@codesourcery.com> > > > > For me, these items are enough justification to switch away from > > texinfo, which produces crap HTML pages with crap anchors. > > If we want to have a serious discussion with useful conclusions, I > suggest to avoid "loaded" terminology. But the results *are* crap. > > I get it that you dislike the HTML produced by Texinfo, but without > some examples of such bad HTML it is impossible to know what exactly > do you dislike and why. > > > You can't find out the anchors without inspecting (and searching) > > the HTML source. That's utterly stupid. > > I don't think I follow: find out the anchors with which means and for > what purposes? I want to point a user at the documentation for the -c option. I can't do that without examining the HTML source to find the anchor, then manually editing the URL to append the anchor. It's a tedious process, and the result is an anchor that doesn't even point to the option but to the text following it. The process is unnecessarily difficult and the results are bad. You participated in a discussion about this very topic previously: https://lists.gnu.org/archive/html/help-texinfo/2019-02/msg00000.html > > > And even after you do that, the anchor > > is at the wrong place: > > https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c > > IME, the anchor is where you put it. If you show me the source of > that HTMl, maybe we can have a more useful discussion of the issue. @item -c @opindex c Compile or assemble the source files, but do not link. The linking stage simply is not done. The ultimate output is in the form of an object file for each source file. Putting the @opindex before the @item causes the anchor to be placed on the previous item, which is not desirable. > > > As somebody who spends a lot of time helping users on the mailing > > list, IRC, stackoverflow, and elsewhere, this "feature" of the texinfo > > HTML has angered me for many years. > > As somebody who spends a lot of time helping users on every possible > forum, and as someone who has wrote a lot of Texinfo, I don't > understand what angers you. Please elaborate. I don't know what part of my email you don't understand. The HTML anchors that texinfo creates are in the wrong place, and not "discoverable". If you don't understand that, then you're clearly not using the GCC HTML docs, and so I'm not surprised you think there's no reason to ditch texinfo. As a regular user of the HTML (for myself and end users of GCC), the HTML output has major usability problems. > > Yes, some people like texinfo, but some people also dislike it and > > there are serious usability problems with the output. I support > > replacing texinfo with anything that isn't texinfo. > > "Anything"? Even plain text? I hope not. Plain text with a tool to generate good HTML might be better than texinfo. > See, such "arguments" don't help to have a useful discussion. Your insistence that texinfo is fine doesn't either. It's not fine. > > > 4) The need to learn yet another markup language. > > > While this is not a problem for simple text, it does require a > > > serious study of RST and Sphinx to use the more advanced features. > > > > This is a problem with texinfo too. > > Not for someone who already knows Texinfo. We are talking about > switching away of it, so I'm thinking about people who contributed > patches for the manual in the past. They already know Texinfo, at > least to some extent, and some of them know it very well. I've contributed dozens of patches to the manual, and I don't want to have to use texinfo to do it in future. > > > 5) Lack of macros. > > > AFAIK, only simple textual substitution is available, no macros > > > with arguments. > > > > Is this a problem for GCC docs though? > > I don't know. It could be, even if it isn't now. So not a problem then. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:52 ` Jonathan Wakely @ 2021-07-12 14:54 ` Jonathan Wakely 2021-07-12 17:14 ` Eli Zaretskii 2021-07-12 15:03 ` Jonathan Wakely 1 sibling, 1 reply; 32+ messages in thread From: Jonathan Wakely @ 2021-07-12 14:54 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Martin Liška, gcc, gcc-patches, Joseph S. Myers On Mon, 12 Jul 2021 at 15:52, Jonathan Wakely <jwakely.gcc@gmail.com> wrote: > > On Mon, 12 Jul 2021 at 15:13, Eli Zaretskii <eliz@gnu.org> wrote: > > > > > From: Jonathan Wakely <jwakely.gcc@gmail.com> > > > This is a problem with texinfo too. > > > > Not for someone who already knows Texinfo. We are talking about > > switching away of it, so I'm thinking about people who contributed > > patches for the manual in the past. They already know Texinfo, at > > least to some extent, and some of them know it very well. > > I've contributed dozens of patches to the manual, and I don't want to > have to use texinfo to do it in future. And some of the people already know sphinx, and some know it very well. And it seems likely that future contributors are more likely to know a more modern tool than they are to know texinfo. You like texinfo. We get it. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:54 ` Jonathan Wakely @ 2021-07-12 17:14 ` Eli Zaretskii 0 siblings, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2021-07-12 17:14 UTC (permalink / raw) To: Jonathan Wakely; +Cc: mliska, gcc, gcc-patches, joseph > From: Jonathan Wakely <jwakely.gcc@gmail.com> > Date: Mon, 12 Jul 2021 15:54:49 +0100 > Cc: Martin Liška <mliska@suse.cz>, > "gcc@gcc.gnu.org" <gcc@gcc.gnu.org>, gcc-patches <gcc-patches@gcc.gnu.org>, > "Joseph S. Myers" <joseph@codesourcery.com> > > You like texinfo. We get it. Would you please drop the attitude? ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:52 ` Jonathan Wakely 2021-07-12 14:54 ` Jonathan Wakely @ 2021-07-12 15:03 ` Jonathan Wakely 2021-07-12 16:00 ` Gavin Smith 1 sibling, 1 reply; 32+ messages in thread From: Jonathan Wakely @ 2021-07-12 15:03 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Martin Liška, gcc, gcc-patches, Joseph S. Myers On Mon, 12 Jul 2021 at 15:52, Jonathan Wakely <jwakely.gcc@gmail.com> wrote: > > On Mon, 12 Jul 2021 at 15:13, Eli Zaretskii <eliz@gnu.org> wrote: > > I get it that you dislike the HTML produced by Texinfo, but without > > some examples of such bad HTML it is impossible to know what exactly > > do you dislike and why. > > > > > You can't find out the anchors without inspecting (and searching) > > > the HTML source. That's utterly stupid. > > > > I don't think I follow: find out the anchors with which means and for > > what purposes? > > I want to point a user at the documentation for the -c option. I can't > do that without examining the HTML source to find the anchor, then > manually editing the URL to append the anchor. It's a tedious process, > and the result is an anchor that doesn't even point to the option but > to the text following it. The process is unnecessarily difficult and > the results are bad. > > You participated in a discussion about this very topic previously: > https://lists.gnu.org/archive/html/help-texinfo/2019-02/msg00000.html > > > > > > And even after you do that, the anchor > > > is at the wrong place: > > > https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html#index-c > > > > IME, the anchor is where you put it. If you show me the source of > > that HTMl, maybe we can have a more useful discussion of the issue. > > @item -c > @opindex c > Compile or assemble the source files, but do not link. The linking > stage simply is not done. The ultimate output is in the form of an > object file for each source file. > > Putting the @opindex before the @item causes the anchor to be placed > on the previous item, which is not desirable. GNU Hello has the same problem with its docs: https://www.gnu.org/software/hello/manual/hello.html#index-_002dg That URL is garbage because of the URL-encoded %2d character, and the fact it links to the wrong place (the description of the option, not the option itself). The former is no longer an issue for GCC (it was for many years) but the latter is still a problem. If you don't know where to find it yourself, the source is visible here: https://github.com/yugui/example/blob/master/doc/hello.texi#L208 If GNU Hello and GCC can't get this right using texinfo, maybe texinfo is not fit for purpose? ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 15:03 ` Jonathan Wakely @ 2021-07-12 16:00 ` Gavin Smith 2021-07-12 16:15 ` Jonathan Wakely 0 siblings, 1 reply; 32+ messages in thread From: Gavin Smith @ 2021-07-12 16:00 UTC (permalink / raw) To: Jonathan Wakely; +Cc: Eli Zaretskii, gcc, gcc-patches, Joseph S. Myers On Mon, Jul 12, 2021 at 4:04 PM Jonathan Wakely via Gcc <gcc@gcc.gnu.org> wrote: > GNU Hello has the same problem with its docs: > https://www.gnu.org/software/hello/manual/hello.html#index-_002dg > That URL is garbage because of the URL-encoded %2d character, and the > fact it links to the wrong place (the description of the option, not > the option itself). The former is no longer an issue for GCC (it was > for many years) but the latter is still a problem. > > If you don't know where to find it yourself, the source is visible here: > https://github.com/yugui/example/blob/master/doc/hello.texi#L208 I downloaded the source for the "hello" manual and recreated it with Texinfo 6.8 (running " texi2any --html hello.texi --no-split"). I've attached the results. The current output doesn't exhibit the problem with the scrolling being at the wrong place - this problem has evidently resolved itself since the time when the online "hello" manual was generated. (I don't remember many complaints about it on the mailing list, though: if we don't know about problems, we can't fix them.) The URL is mangled because index entries can have more characters in them than what is suitable for a URL. A space character becomes a "-", so a "-" has to become something else. They have to be distinguished because there may be two separate index entries in different places which wouldn't be distinguishable otherwise. However, I find that adding an extra index entry means you can use hello.html#index-greeting instead: @item --greeting=@var{text} @itemx -g @var{text} @opindex greeting @opindex --greeting @opindex -g Output @var{text} instead of the default greeting. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 16:00 ` Gavin Smith @ 2021-07-12 16:15 ` Jonathan Wakely 0 siblings, 0 replies; 32+ messages in thread From: Jonathan Wakely @ 2021-07-12 16:15 UTC (permalink / raw) To: Gavin Smith; +Cc: Eli Zaretskii, gcc, gcc-patches, Joseph S. Myers On Mon, 12 Jul 2021 at 17:01, Gavin Smith wrote: > > On Mon, Jul 12, 2021 at 4:04 PM Jonathan Wakely via Gcc <gcc@gcc.gnu.org> wrote: > > GNU Hello has the same problem with its docs: > > https://www.gnu.org/software/hello/manual/hello.html#index-_002dg > > That URL is garbage because of the URL-encoded %2d character, and the > > fact it links to the wrong place (the description of the option, not > > the option itself). The former is no longer an issue for GCC (it was > > for many years) but the latter is still a problem. > > > > If you don't know where to find it yourself, the source is visible here: > > https://github.com/yugui/example/blob/master/doc/hello.texi#L208 > > I downloaded the source for the "hello" manual and recreated it with > Texinfo 6.8 (running " texi2any --html hello.texi --no-split"). I've > attached the results. The current output doesn't exhibit the problem > with the scrolling being at the wrong place - this problem has > evidently resolved itself since the time when the online "hello" > manual was generated. (I don't remember many complaints about it on > the mailing list, though: if we don't know about problems, we can't > fix them.) The "copyable link" does work as I would expect. The #index-_002dg anchor still seems to be in the "wrong" place, i.e. in the <dd> element not the <dt> element. But the addition of the copyable link nicely solves the problem of needing to easily obtain a link to the right position. > The URL is mangled because index entries can have more characters in > them than what is suitable for a URL. A space character becomes a "-", > so a "-" has to become something else. Yes, I understand the reason. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 13:39 ` Eli Zaretskii 2021-07-12 13:53 ` Jonathan Wakely @ 2021-07-12 14:37 ` Martin Liška 2021-07-12 17:12 ` Eli Zaretskii 1 sibling, 1 reply; 32+ messages in thread From: Martin Liška @ 2021-07-12 14:37 UTC (permalink / raw) To: Eli Zaretskii; +Cc: hp, gcc, gcc-patches, joseph On 7/12/21 3:39 PM, Eli Zaretskii wrote: >> Cc: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, joseph@codesourcery.com >> From: Martin Liška <mliska@suse.cz> >> Date: Mon, 12 Jul 2021 15:25:47 +0200 >> >> Let's make it a separate sub-thread where we can discuss motivation why >> do I want moving to Sphinx format. > > Thanks for starting this discussion. > >> Benefits: >> 1) modern looking HTML output (before: [1], after: [2]): >> a) syntax highlighting for examples (code, shell commands, etc.) >> b) precise anchors, the current Texinfo anchors are not displayed (start with first line of an option) >> c) one can easily copy a link to an anchor (displayed as ¶) >> d) internal links are working, e.g. one can easily jump from listing of options >> e) left menu navigation provides better orientation in the manual >> f) Sphinx provides internal search capability: [3] >> 2) internal links are also provided in PDF version of the manual > > How is this different from Texinfo? Texinfo does not emit them. See e.g. links in option listing (-O2, -Os, ...). > >> 3) some existing GCC manuals are already written in Sphinx (GNAT manuals and libgccjit) >> 4) support for various output formats, some people are interested in ePUB format > > Texinfo likewise supports many output formats. Someone presented a > very simple package to produce epub format from it. Good to know. > >> 5) Sphinx is using RST which is quite minimal semantic markup language > > Is it more minimal than Texinfo? I would say that's pretty easy to learn, similarly complex as Texinfo. > >> 6) TOC is automatically generated - no need for manual navigation like seen here: [5] > > That is not needed in Texinfo as well, since long ago. Nowadays, you > just say > > @node Whatever > > and the rest is done automatically, as long as the manual's structure > is a proper tree (which it normally is, I know of only one manual that > is an exception). All right, then we likely do an extra work right now. > >> Disadvantages: >> >> 1) info pages are currently missing Page description in TOC >> 2) rich formatting is leading to extra wrapping in info output - beings partially addresses in [4] >> 3) one needs e.g. Emacs support for inline links (rendered as notes) > > 4) The need to learn yet another markup language. > While this is not a problem for simple text, it does require a > serious study of RST and Sphinx to use the more advanced features. No, majority of the documentation is pretty simple: basic formatting, links, tables and code examples. Martin > > 5) Lack of macros. > AFAIK, only simple textual substitution is available, no macros > with arguments. > ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 14:37 ` Martin Liška @ 2021-07-12 17:12 ` Eli Zaretskii 0 siblings, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2021-07-12 17:12 UTC (permalink / raw) To: Martin Liška; +Cc: hp, gcc, gcc-patches, joseph > Cc: hp@bitrange.com, gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org, > joseph@codesourcery.com > From: Martin Liška <mliska@suse.cz> > Date: Mon, 12 Jul 2021 16:37:00 +0200 > > > 4) The need to learn yet another markup language. > > While this is not a problem for simple text, it does require a > > serious study of RST and Sphinx to use the more advanced features. > > No, majority of the documentation is pretty simple: basic formatting, links, tables and > code examples. We also have documentation of APIs (a.k.a. "functions"). I actually tried to find in the Sphinx docs how to do that and got lost. So, not really "very simple". ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 13:25 ` Benefits of using Sphinx documentation format Martin Liška 2021-07-12 13:39 ` Eli Zaretskii @ 2021-07-12 16:36 ` David Malcolm 2021-07-12 18:23 ` Koning, Paul 1 sibling, 1 reply; 32+ messages in thread From: David Malcolm @ 2021-07-12 16:36 UTC (permalink / raw) To: Martin Liška, Hans-Peter Nilsson, Eli Zaretskii Cc: gcc, gcc-patches, joseph On Mon, 2021-07-12 at 15:25 +0200, Martin Liška wrote: > Hello. > > Let's make it a separate sub-thread where we can discuss motivation > why > do I want moving to Sphinx format. > > Benefits: > 1) modern looking HTML output (before: [1], after: [2]): "modern looking" is rather subjective; I'd rate Sphinx's output as looking like it's from 2010s (last decade), whereas Texinfos' looks like it's from the 1990s. In theory this ought not to matter, but every time I look at our documentation it gives me a depressing feeling, reminiscent of a graveyard, that discourages me from fixing things. > a) syntax highlighting for examples (code, shell commands, etc.) ...with support for multiple programming languages, potentially on the same page. For example, in the libgccjit docs: https://gcc.gnu.org/onlinedocs/jit/intro/tutorial02.html we can have a mixture of C, assembler and shell on one page, and each example is syntax-highlighted accordingly. It's not clear to me how to do that in texinfo, since there needs to be a way to express what language an example is in. > b) precise anchors, the current Texinfo anchors are not displayed > (start with first line of an option) ...and the URLs are sane and stable (so e.g. there is a reliable, guessable, readable URL for the docs for say, "-Wall"). > c) one can easily copy a link to an anchor (displayed as ¶) > d) internal links are working, e.g. one can easily jump from > listing of options > e) left menu navigation provides better orientation in the manual > f) Sphinx provides internal search capability: [3] ...also (quoting myself in places here from 2015 https://gcc.gnu.org/pipermail/gcc-patches/2015-November/434055.html ): * the ability to include fragments of files: libgccjit's documentation uses directives to include code from the test suite, so that all of the code examples are also part of the test suite, and are thus known to compile), allowing for (almost) literate programming. [That said, the build of libgccjit's docs on gcc.gnu.org seems to be missing those fragments; I wonder if there's a path or version issue?] * a page-splitting structure that make sense, to me, at least (I have never fathomed the way texinfo's navigation works, for HTML, at least, and I believe I'm not the only one; I generally pick the all-in-one- HTML-page option when viewing texinfo-html docs and do textual searches, since otherwise I usually can't find the thing I'm looking for (or have to resort to a brute-force depth-first search of clicking through the links).) * much more use of markup, with restrained and well-chosen CSS (texinfo's HTML seems to ignore much of the inline markup in the .texinfo file) > 2) internal links are also provided in PDF version of the manual > 3) some existing GCC manuals are already written in Sphinx (GNAT > manuals and libgccjit) > 4) support for various output formats, some people are interested in > ePUB format > 5) Sphinx is using RST which is quite minimal semantic markup language Sphinx is also used by many high-profile FLOSS projects (e.g. the Linux kernel, LLVM, and the Python community), so it reduces the barrier to entry for new contributors, relative to texinfo. > 6) TOC is automatically generated - no need for manual navigation > like seen here: [5] > > Disadvantages: > > 1) info pages are currently missing Page description in TOC > 2) rich formatting is leading to extra wrapping in info output - > beings partially addresses in [4] > 3) one needs e.g. Emacs support for inline links (rendered as notes) > > I'm willing to address issue 1) in next weeks and I tend to skip > emission of links as mentioned in 3). > Generally speaking, I'm aware that some people still use Info, but I > think we should more focus > on more modern documentation formats. That's HTML (and partially > PDF). I think the output formats we need to support are: - HTML - PDF - man page (hardly "modern", but still used) I regared "info" as merely "nice to have" - I don't know anyone who uses it other than some core GNU contributors. Dave > > Martin > > [1] > https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing > [2] > https://splichal.eu/gccsphinx-final/html/gcc/gcc-command-options/options-that-control-optimization.html#cmdoption-fstrict-aliasing > [3] > https://splichal.eu/gccsphinx-final/html/gcc/search.html?q=-fipa-icf&check_keywords=yes&area=default# > [4] https://github.com/sphinx-doc/sphinx/pull/9391 > [5] @comment node-name, next, previous, up > @node Installing GCC, Binaries, , Top > ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Benefits of using Sphinx documentation format 2021-07-12 16:36 ` David Malcolm @ 2021-07-12 18:23 ` Koning, Paul 0 siblings, 0 replies; 32+ messages in thread From: Koning, Paul @ 2021-07-12 18:23 UTC (permalink / raw) To: David Malcolm Cc: Martin Liška, Hans-Peter Nilsson, Eli Zaretskii, GCC Development, GCC Patches, joseph > On Jul 12, 2021, at 12:36 PM, David Malcolm via Gcc-patches <gcc-patches@gcc.gnu.org> wrote: > > On Mon, 2021-07-12 at 15:25 +0200, Martin Liška wrote: >> ... > > I think the output formats we need to support are: > - HTML > - PDF > - man page (hardly "modern", but still used) Also info format (for the Emacs info reader). And ebook formats (epub and/or mobi). Having good quality ebook output is a major benefit in my view; it would be very good for the standard makefiles to offer make targets for these formats. paul ^ permalink raw reply [flat|nested] 32+ messages in thread
end of thread, other threads:[~2021-08-09 12:12 UTC | newest] Thread overview: 32+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- [not found] <CAKPWYQ0QEqE1v3kv_gvRXEEJOPd8j6FetAU_wh7Vssw81DTj4Q@mail.gmail.com> [not found] ` <CAKPWYQ3EobaPGskg9kq5gYtHFoGNXFLtCOcrcFouxg4skvJRxA@mail.gmail.com> 2021-07-12 17:49 ` Benefits of using Sphinx documentation format Gavin Smith 2021-08-09 12:04 ` Martin Liška [not found] <1446990946.2994.192.camel@surprise> 2021-05-13 11:45 ` RFC: Sphinx for GCC documentation Martin Liška 2021-05-31 13:25 ` GCC documentation: porting to Sphinx Martin Liška 2021-06-02 17:27 ` Joseph Myers 2021-06-10 14:06 ` Martin Liška 2021-06-10 16:49 ` Joseph Myers 2021-06-11 14:33 ` Martin Liška 2021-06-11 15:50 ` Joseph Myers 2021-06-23 13:13 ` Martin Liška 2021-06-23 16:00 ` Joseph Myers 2021-06-24 14:08 ` Martin Liška 2021-06-25 13:11 ` Martin Liška 2021-06-28 12:01 ` [PATCH] Port GCC documentation " Martin Liška 2021-06-28 15:33 ` Joseph Myers 2021-06-29 10:09 ` Martin Liška 2021-06-29 16:57 ` Eli Zaretskii 2021-06-30 10:11 ` Martin Liška 2021-06-30 13:09 ` Eli Zaretskii 2021-07-02 23:53 ` Hans-Peter Nilsson 2021-07-12 13:25 ` Benefits of using Sphinx documentation format Martin Liška 2021-07-12 13:39 ` Eli Zaretskii 2021-07-12 13:53 ` Jonathan Wakely 2021-07-12 14:05 ` Jonathan Wakely 2021-07-12 14:16 ` Eli Zaretskii 2021-07-12 14:34 ` Martin Liška 2021-07-12 17:09 ` Eli Zaretskii 2021-07-12 14:12 ` Eli Zaretskii 2021-07-12 14:30 ` Martin Liška 2021-07-12 14:54 ` Matthias Kretz 2021-07-12 17:03 ` Eli Zaretskii 2021-07-12 17:15 ` Jonathan Wakely 2021-07-12 17:23 ` Eli Zaretskii 2021-07-12 17:33 ` Jonathan Wakely 2021-07-13 6:24 ` Richard Biener 2021-07-13 11:52 ` Eli Zaretskii 2021-07-13 12:46 ` Richard Biener 2021-07-13 12:55 ` Eli Zaretskii 2021-08-09 12:12 ` Martin Liška 2021-07-13 14:19 ` Jonathan Wakely 2021-07-12 14:52 ` Jonathan Wakely 2021-07-12 14:54 ` Jonathan Wakely 2021-07-12 17:14 ` Eli Zaretskii 2021-07-12 15:03 ` Jonathan Wakely 2021-07-12 16:00 ` Gavin Smith 2021-07-12 16:15 ` Jonathan Wakely 2021-07-12 14:37 ` Martin Liška 2021-07-12 17:12 ` Eli Zaretskii 2021-07-12 16:36 ` David Malcolm 2021-07-12 18:23 ` Koning, Paul
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).