| Message ID | 20230223102714.3606058-1-arsen@aarsen.me |
|---|---|
| Headers | show |
| Series | A small Texinfo refinement | expand |
Hi Arsen! Thanks for caring about the documentation infrastructure! On 2023-02-23T11:27:09+0100, Arsen Arsenović via Gcc-patches <gcc-patches@gcc.gnu.org> wrote: > The commit "docs: Reorder @opindex to be before corresponding options" > https://gcc.gnu.org/pipermail/gcc-patches/2023-February/612616.html > His idea of automatically checking for this error pattern will be > implemented separately, after I figure out how best to do that. The > code that was involved in making this patchset is too primitive to > apply globally. But please don't spend too much time on that idea, if that turns out to require non-trivial Texinfo parsing. Given that you've now fixed up the existing disordered instances, I suppose not many new ones are going be introduced, assuming that people extend the documentation by looking at the existing, now-good context. Grüße Thomas ----------------- Siemens Electronic Design Automation GmbH; Anschrift: Arnulfstraße 201, 80634 München; Gesellschaft mit beschränkter Haftung; Geschäftsführer: Thomas Heurung, Frank Thürauf; Sitz der Gesellschaft: München; Registergericht München, HRB 106955
Hi Thomas, Thomas Schwinge <thomas@codesourcery.com> writes: > Hi Arsen! > > Thanks for caring about the documentation infrastructure! > > On 2023-02-23T11:27:09+0100, Arsen Arsenović via Gcc-patches <gcc-patches@gcc.gnu.org> wrote: >> The commit "docs: Reorder @opindex to be before corresponding options" > >> https://gcc.gnu.org/pipermail/gcc-patches/2023-February/612616.html >> His idea of automatically checking for this error pattern will be >> implemented separately, after I figure out how best to do that. The >> code that was involved in making this patchset is too primitive to >> apply globally. > > But please don't spend too much time on that idea, if that turns out to > require non-trivial Texinfo parsing. My intention was to do it in texi2any, since there's already a nice and convenient parse tree that can be used there. Alternatively, texi2any can export the parse tree for external tools consumption, if some heuristic ends up not being general enough for all Texinfo manuals. I'd like to figure out something general, though, as time permits. > Given that you've now fixed up the existing disordered instances, I > suppose not many new ones are going be introduced, assuming that people > extend the documentation by looking at the existing, now-good context. Yes, I think so too. In either case, I'll try to catch errors before they get merged, at least for now. > > Grüße > Thomas > ----------------- > Siemens Electronic Design Automation GmbH; Anschrift: Arnulfstraße 201, 80634 München; Gesellschaft mit beschränkter Haftung; Geschäftsführer: Thomas Heurung, Frank Thürauf; Sitz der Gesellschaft: München; Registergericht München, HRB 106955 Have a lovely day.
On 2/23/23 03:27, Arsen Arsenović via Gcc-patches wrote: > I've rerendered the updated documentation with latest development > Texinfo (as some of the changes I made for the purposes of the GCC > manual still aren't in releases) at: > > https://www.aarsen.me/~arsen/final/ Ummm. I don't think GCC's documentation should depend on an unreleased version of Texinfo. Currently install.texi documents that version 4.7 or later is required, 4.8 for "make pdf"; did I miss something in your patch set that bumps this requirement? Exactly what features do you depend on that are not yet supported by an official Texinfo release? -Sandra
Sandra Loosemore <sandra@codesourcery.com> writes: > On 2/23/23 03:27, Arsen Arsenović via Gcc-patches wrote: >> I've rerendered the updated documentation with latest development >> Texinfo (as some of the changes I made for the purposes of the GCC >> manual still aren't in releases) at: >> https://www.aarsen.me/~arsen/final/ > > Ummm. I don't think GCC's documentation should depend on an unreleased version > of Texinfo. Currently install.texi documents that version 4.7 or later is > required, 4.8 for "make pdf"; did I miss something in your patch set that bumps > this requirement? Exactly what features do you depend on that are not yet > supported by an official Texinfo release? This patch should still build with older Texinfo versions (albeit, I hadn't tested 4.7, I missed that requirement). The unreleased version should be installed on the server building HTML documentation as it produces better results w.r.t clickable anchors and index-in-table handling. It should not be a hard dependency, and should only degrade to its current state should in-dev Texinfo be missing. It might be worth bumping the minimum, 4.7 is a version from 2004; in the meanwhile, I'll try a few older versions too. Thanks, have a lovely day.
On 3/8/23 02:11, Arsen Arsenović wrote: > > Sandra Loosemore <sandra@codesourcery.com> writes: > >> On 2/23/23 03:27, Arsen Arsenović via Gcc-patches wrote: >>> I've rerendered the updated documentation with latest development >>> Texinfo (as some of the changes I made for the purposes of the GCC >>> manual still aren't in releases) at: >>> https://www.aarsen.me/~arsen/final/ >> >> Ummm. I don't think GCC's documentation should depend on an unreleased version >> of Texinfo. Currently install.texi documents that version 4.7 or later is >> required, 4.8 for "make pdf"; did I miss something in your patch set that bumps >> this requirement? Exactly what features do you depend on that are not yet >> supported by an official Texinfo release? > > This patch should still build with older Texinfo versions (albeit, I > hadn't tested 4.7, I missed that requirement). The unreleased version > should be installed on the server building HTML documentation as it > produces better results w.r.t clickable anchors and index-in-table > handling. It should not be a hard dependency, and should only degrade > to its current state should in-dev Texinfo be missing. Hmmm, OK. We presently have Texinfo version 6.7 installed here, so I'll give that a try. I'm not sure I'd be able to detect problems with incorrect HTML anchors or whatever, though. Most people building GCC from source probably use whatever versions of build dependencies are provided by their OS distribution. In our group we need reproducible builds for long-term support so we maintain our own list of dependencies and normally update to the latest stable versions only once every few years unless there is a hard requirement to upgrade some particular tool meanwhile. I personally do not know how the manuals for the GCC web site are built, but it seems kind of important to make sure that works as intended since it's the main online resource for ordinary GCC users. > It might be worth bumping the minimum, 4.7 is a version from 2004; in > the meanwhile, I'll try a few older versions too. I agree that it's unlikely anyone is building current GCC with a Texinfo version as old as 4.7 any more, and it may be that the manual doesn't even build properly with such an old release due to existing unintentional dependencies on newer features, independently of your patch. If we do update the version, there's a version check in configure.ac and some hack for "makeinfo 4.7 brokenness" in doc/install.texi2html that need to be changed, as well as install.texi. -Sandra
Sandra Loosemore <sandra@codesourcery.com> writes: > On 3/8/23 02:11, Arsen Arsenović wrote: >> Sandra Loosemore <sandra@codesourcery.com> writes: >> >>> On 2/23/23 03:27, Arsen Arsenović via Gcc-patches wrote: >>>> I've rerendered the updated documentation with latest development >>>> Texinfo (as some of the changes I made for the purposes of the GCC >>>> manual still aren't in releases) at: >>>> https://www.aarsen.me/~arsen/final/ >>> >>> Ummm. I don't think GCC's documentation should depend on an unreleased version >>> of Texinfo. Currently install.texi documents that version 4.7 or later is >>> required, 4.8 for "make pdf"; did I miss something in your patch set that bumps >>> this requirement? Exactly what features do you depend on that are not yet >>> supported by an official Texinfo release? >> This patch should still build with older Texinfo versions (albeit, I >> hadn't tested 4.7, I missed that requirement). The unreleased version >> should be installed on the server building HTML documentation as it >> produces better results w.r.t clickable anchors and index-in-table >> handling. It should not be a hard dependency, and should only degrade >> to its current state should in-dev Texinfo be missing. > > Hmmm, OK. We presently have Texinfo version 6.7 installed here, so I'll give > that a try. I'm not sure I'd be able to detect problems with incorrect HTML > anchors or whatever, though. As an example, let's take this link: https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/Warning-Options.html#index-Wpedantic This should place you below the item line this index entry refers to, and there aren't any copiable anchors (see equivalent in my render for an example of those), both of which were often named as annoyances with the onlinedocs while the Sphinx experiment was taking place. A similar thing happens in the standalone and Emacs info viewers (but that's less noticeable there since the cursor is placed in the middle of the screen when jumping to an index entry there). Try, for instance, 'info gcc Wpedantic' (your cursor will be placed just below the item line). The fix for the first of these issues should already be applied by Gerald (in the reordering commits, IIRC at least, save for one that I created later because someone snuck in new "misplaced" indices), and that fix should also fix up previous versions of Texinfo. Even with this change, the copiable anchors will remain missing since released Texinfo versions lack some AST transformations that enable those. Otherwise, manuals should work fine with older releases, unless I missed something when refactoring @defbuiltin and removing @gols (which I do believe are superfluous with current versions of texinfo.tex, which is why I bumped that too). To be clear, the anchor-related stuff is entirely specific to HTML output. > Most people building GCC from source probably use whatever versions of build > dependencies are provided by their OS distribution. In our group we need > reproducible builds for long-term support so we maintain our own list of > dependencies and normally update to the latest stable versions only once every > few years unless there is a hard requirement to upgrade some particular tool > meanwhile. I personally do not know how the manuals for the GCC web site are > built, but it seems kind of important to make sure that works as intended since > it's the main online resource for ordinary GCC users. Yes, I can get behind this sentiment too. I don't mean to impose a hard dependency on the bleeding edge of Texinfo. My target was indeed the GCC website and ordinary users. >> It might be worth bumping the minimum, 4.7 is a version from 2004; in >> the meanwhile, I'll try a few older versions too. > > I agree that it's unlikely anyone is building current GCC with a Texinfo > version as old as 4.7 any more, and it may be that the manual doesn't even > build properly with such an old release due to existing unintentional > dependencies on newer features, independently of your patch. If we do update > the version, there's a version check in configure.ac and some hack for > "makeinfo 4.7 brokenness" in doc/install.texi2html that need to be changed, as > well as install.texi. FWIW, I (briefly) tested with Texinfo 6.0, and output seems okay. On 5.0, I got a few warnings, but I think even 6.0 is apt considering its age. I haven't given it a proper scrutiny, though (workdays are busy this time of year..). > -Sandra Thanks, have a lovely evening.
On 3/8/23 14:22, Arsen Arsenović wrote: > > Sandra Loosemore <sandra@codesourcery.com> writes: > >> On 3/8/23 02:11, Arsen Arsenović wrote: >>> Sandra Loosemore <sandra@codesourcery.com> writes: >>> >>>> On 2/23/23 03:27, Arsen Arsenović via Gcc-patches wrote: >>>>> I've rerendered the updated documentation with latest development >>>>> Texinfo (as some of the changes I made for the purposes of the GCC >>>>> manual still aren't in releases) at: >>>>> https://www.aarsen.me/~arsen/final/ >>>> >>>> Ummm. I don't think GCC's documentation should depend on an unreleased version >>>> of Texinfo. Currently install.texi documents that version 4.7 or later is >>>> required, 4.8 for "make pdf"; did I miss something in your patch set that bumps >>>> this requirement? Exactly what features do you depend on that are not yet >>>> supported by an official Texinfo release? >>> This patch should still build with older Texinfo versions (albeit, I >>> hadn't tested 4.7, I missed that requirement). The unreleased version >>> should be installed on the server building HTML documentation as it >>> produces better results w.r.t clickable anchors and index-in-table >>> handling. It should not be a hard dependency, and should only degrade >>> to its current state should in-dev Texinfo be missing. >> >> Hmmm, OK. We presently have Texinfo version 6.7 installed here, so I'll give >> that a try. I'm not sure I'd be able to detect problems with incorrect HTML >> anchors or whatever, though. > > As an example, let's take this link: > https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/Warning-Options.html#index-Wpedantic > > This should place you below the item line this index entry refers to, > and there aren't any copiable anchors (see equivalent in my render for > an example of those), both of which were often named as annoyances with > the onlinedocs while the Sphinx experiment was taking place. > > A similar thing happens in the standalone and Emacs info viewers (but > that's less noticeable there since the cursor is placed in the middle of > the screen when jumping to an index entry there). Try, for instance, > 'info gcc Wpedantic' (your cursor will be placed just below the item > line). > > The fix for the first of these issues should already be applied by > Gerald (in the reordering commits, IIRC at least, save for one that I > created later because someone snuck in new "misplaced" indices), and > that fix should also fix up previous versions of Texinfo. > > Even with this change, the copiable anchors will remain missing since > released Texinfo versions lack some AST transformations that enable > those. OK, I can see the difference there between the current online docs, the set you produced with the unreleased Texinfo support, and what I got building with Texinfo 6.7. > Otherwise, manuals should work fine with older releases, unless I missed > something when refactoring @defbuiltin and removing @gols (which I do > believe are superfluous with current versions of texinfo.tex, which is > why I bumped that too). I did a few spot-checks here and there of those changes. I saw a couple of line break problems but they turn out to be due to existing errors in the .texi files that were not introduced by your (mostly mechanical) changes. >> Most people building GCC from source probably use whatever versions of build >> dependencies are provided by their OS distribution. In our group we need >> reproducible builds for long-term support so we maintain our own list of >> dependencies and normally update to the latest stable versions only once every >> few years unless there is a hard requirement to upgrade some particular tool >> meanwhile. I personally do not know how the manuals for the GCC web site are >> built, but it seems kind of important to make sure that works as intended since >> it's the main online resource for ordinary GCC users. > > Yes, I can get behind this sentiment too. I don't mean to impose a hard > dependency on the bleeding edge of Texinfo. My target was indeed the > GCC website and ordinary users. > >>> It might be worth bumping the minimum, 4.7 is a version from 2004; in >>> the meanwhile, I'll try a few older versions too. >> >> I agree that it's unlikely anyone is building current GCC with a Texinfo >> version as old as 4.7 any more, and it may be that the manual doesn't even >> build properly with such an old release due to existing unintentional >> dependencies on newer features, independently of your patch. If we do update >> the version, there's a version check in configure.ac and some hack for >> "makeinfo 4.7 brokenness" in doc/install.texi2html that need to be changed, as >> well as install.texi. > > FWIW, I (briefly) tested with Texinfo 6.0, and output seems okay. On > 5.0, I got a few warnings, but I think even 6.0 is apt considering its > age. I haven't given it a proper scrutiny, though (workdays are busy > this time of year..). Texinfo 6.0 was released in 2015, 5.0 in 2013. FWIW, Trusty Tahr (the current oldest Ubuntu LTS release) has 5.2. 4.7 was released in 2004, I don't know why anyone would still be trying to use that unless it's needed for building legacy code from the same era. I think we could do away with the requirement for a specific minimum version, and make install.texi say something similar to what it says for e.g. awk -- just use a "recent" version, and note that new versions produce better output and very old ones may produce diagnostics. I'll add that do my own todo list. -Sandra
On Wed, Mar 8, 2023 at 5:09 PM Sandra Loosemore <sandra@codesourcery.com> wrote: > > On 3/8/23 14:22, Arsen Arsenović wrote: > > > > Sandra Loosemore <sandra@codesourcery.com> writes: > > > >> On 3/8/23 02:11, Arsen Arsenović wrote: > >>> Sandra Loosemore <sandra@codesourcery.com> writes: > >>> > >>>> On 2/23/23 03:27, Arsen Arsenović via Gcc-patches wrote: > >>>>> I've rerendered the updated documentation with latest development > >>>>> Texinfo (as some of the changes I made for the purposes of the GCC > >>>>> manual still aren't in releases) at: > >>>>> https://www.aarsen.me/~arsen/final/ > >>>> > >>>> Ummm. I don't think GCC's documentation should depend on an unreleased version > >>>> of Texinfo. Currently install.texi documents that version 4.7 or later is > >>>> required, 4.8 for "make pdf"; did I miss something in your patch set that bumps > >>>> this requirement? Exactly what features do you depend on that are not yet > >>>> supported by an official Texinfo release? > >>> This patch should still build with older Texinfo versions (albeit, I > >>> hadn't tested 4.7, I missed that requirement). The unreleased version > >>> should be installed on the server building HTML documentation as it > >>> produces better results w.r.t clickable anchors and index-in-table > >>> handling. It should not be a hard dependency, and should only degrade > >>> to its current state should in-dev Texinfo be missing. > >> > >> Hmmm, OK. We presently have Texinfo version 6.7 installed here, so I'll give > >> that a try. I'm not sure I'd be able to detect problems with incorrect HTML > >> anchors or whatever, though. > > > > As an example, let's take this link: > > https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/Warning-Options.html#index-Wpedantic > > > > This should place you below the item line this index entry refers to, > > and there aren't any copiable anchors (see equivalent in my render for > > an example of those), both of which were often named as annoyances with > > the onlinedocs while the Sphinx experiment was taking place. > > > > A similar thing happens in the standalone and Emacs info viewers (but > > that's less noticeable there since the cursor is placed in the middle of > > the screen when jumping to an index entry there). Try, for instance, > > 'info gcc Wpedantic' (your cursor will be placed just below the item > > line). > > > > The fix for the first of these issues should already be applied by > > Gerald (in the reordering commits, IIRC at least, save for one that I > > created later because someone snuck in new "misplaced" indices), and > > that fix should also fix up previous versions of Texinfo. > > > > Even with this change, the copiable anchors will remain missing since > > released Texinfo versions lack some AST transformations that enable > > those. > > OK, I can see the difference there between the current online docs, the > set you produced with the unreleased Texinfo support, and what I got > building with Texinfo 6.7. > > > Otherwise, manuals should work fine with older releases, unless I missed > > something when refactoring @defbuiltin and removing @gols (which I do > > believe are superfluous with current versions of texinfo.tex, which is > > why I bumped that too). > > I did a few spot-checks here and there of those changes. I saw a couple > of line break problems but they turn out to be due to existing errors in > the .texi files that were not introduced by your (mostly mechanical) > changes. > > >> Most people building GCC from source probably use whatever versions of build > >> dependencies are provided by their OS distribution. In our group we need > >> reproducible builds for long-term support so we maintain our own list of > >> dependencies and normally update to the latest stable versions only once every > >> few years unless there is a hard requirement to upgrade some particular tool > >> meanwhile. I personally do not know how the manuals for the GCC web site are > >> built, but it seems kind of important to make sure that works as intended since > >> it's the main online resource for ordinary GCC users. > > > > Yes, I can get behind this sentiment too. I don't mean to impose a hard > > dependency on the bleeding edge of Texinfo. My target was indeed the > > GCC website and ordinary users. > > > >>> It might be worth bumping the minimum, 4.7 is a version from 2004; in > >>> the meanwhile, I'll try a few older versions too. > >> > >> I agree that it's unlikely anyone is building current GCC with a Texinfo > >> version as old as 4.7 any more, and it may be that the manual doesn't even > >> build properly with such an old release due to existing unintentional > >> dependencies on newer features, independently of your patch. If we do update > >> the version, there's a version check in configure.ac and some hack for > >> "makeinfo 4.7 brokenness" in doc/install.texi2html that need to be changed, as > >> well as install.texi. > > > > FWIW, I (briefly) tested with Texinfo 6.0, and output seems okay. On > > 5.0, I got a few warnings, but I think even 6.0 is apt considering its > > age. I haven't given it a proper scrutiny, though (workdays are busy > > this time of year..). > > Texinfo 6.0 was released in 2015, 5.0 in 2013. FWIW, Trusty Tahr (the > current oldest Ubuntu LTS release) has 5.2. 4.7 was released in 2004, I > don't know why anyone would still be trying to use that unless it's > needed for building legacy code from the same era. CentOS/RHEL 7 includes texinfo 5.1. That is the oldest distro I think mostly supports building with. That is the oldest I do builds of GCC with even for the trunk. Thanks, Andrew > > I think we could do away with the requirement for a specific minimum > version, and make install.texi say something similar to what it says for > e.g. awk -- just use a "recent" version, and note that new versions > produce better output and very old ones may produce diagnostics. I'll > add that do my own todo list. > > -Sandra
On Thu, Mar 9, 2023 at 2:20 AM Andrew Pinski via Gcc-patches <gcc-patches@gcc.gnu.org> wrote: > > On Wed, Mar 8, 2023 at 5:09 PM Sandra Loosemore <sandra@codesourcery.com> wrote: > > > > On 3/8/23 14:22, Arsen Arsenović wrote: > > > > > > Sandra Loosemore <sandra@codesourcery.com> writes: > > > > > >> On 3/8/23 02:11, Arsen Arsenović wrote: > > >>> Sandra Loosemore <sandra@codesourcery.com> writes: > > >>> > > >>>> On 2/23/23 03:27, Arsen Arsenović via Gcc-patches wrote: > > >>>>> I've rerendered the updated documentation with latest development > > >>>>> Texinfo (as some of the changes I made for the purposes of the GCC > > >>>>> manual still aren't in releases) at: > > >>>>> https://www.aarsen.me/~arsen/final/ > > >>>> > > >>>> Ummm. I don't think GCC's documentation should depend on an unreleased version > > >>>> of Texinfo. Currently install.texi documents that version 4.7 or later is > > >>>> required, 4.8 for "make pdf"; did I miss something in your patch set that bumps > > >>>> this requirement? Exactly what features do you depend on that are not yet > > >>>> supported by an official Texinfo release? > > >>> This patch should still build with older Texinfo versions (albeit, I > > >>> hadn't tested 4.7, I missed that requirement). The unreleased version > > >>> should be installed on the server building HTML documentation as it > > >>> produces better results w.r.t clickable anchors and index-in-table > > >>> handling. It should not be a hard dependency, and should only degrade > > >>> to its current state should in-dev Texinfo be missing. > > >> > > >> Hmmm, OK. We presently have Texinfo version 6.7 installed here, so I'll give > > >> that a try. I'm not sure I'd be able to detect problems with incorrect HTML > > >> anchors or whatever, though. > > > > > > As an example, let's take this link: > > > https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/Warning-Options.html#index-Wpedantic > > > > > > This should place you below the item line this index entry refers to, > > > and there aren't any copiable anchors (see equivalent in my render for > > > an example of those), both of which were often named as annoyances with > > > the onlinedocs while the Sphinx experiment was taking place. > > > > > > A similar thing happens in the standalone and Emacs info viewers (but > > > that's less noticeable there since the cursor is placed in the middle of > > > the screen when jumping to an index entry there). Try, for instance, > > > 'info gcc Wpedantic' (your cursor will be placed just below the item > > > line). > > > > > > The fix for the first of these issues should already be applied by > > > Gerald (in the reordering commits, IIRC at least, save for one that I > > > created later because someone snuck in new "misplaced" indices), and > > > that fix should also fix up previous versions of Texinfo. > > > > > > Even with this change, the copiable anchors will remain missing since > > > released Texinfo versions lack some AST transformations that enable > > > those. > > > > OK, I can see the difference there between the current online docs, the > > set you produced with the unreleased Texinfo support, and what I got > > building with Texinfo 6.7. > > > > > Otherwise, manuals should work fine with older releases, unless I missed > > > something when refactoring @defbuiltin and removing @gols (which I do > > > believe are superfluous with current versions of texinfo.tex, which is > > > why I bumped that too). > > > > I did a few spot-checks here and there of those changes. I saw a couple > > of line break problems but they turn out to be due to existing errors in > > the .texi files that were not introduced by your (mostly mechanical) > > changes. > > > > >> Most people building GCC from source probably use whatever versions of build > > >> dependencies are provided by their OS distribution. In our group we need > > >> reproducible builds for long-term support so we maintain our own list of > > >> dependencies and normally update to the latest stable versions only once every > > >> few years unless there is a hard requirement to upgrade some particular tool > > >> meanwhile. I personally do not know how the manuals for the GCC web site are > > >> built, but it seems kind of important to make sure that works as intended since > > >> it's the main online resource for ordinary GCC users. > > > > > > Yes, I can get behind this sentiment too. I don't mean to impose a hard > > > dependency on the bleeding edge of Texinfo. My target was indeed the > > > GCC website and ordinary users. > > > > > >>> It might be worth bumping the minimum, 4.7 is a version from 2004; in > > >>> the meanwhile, I'll try a few older versions too. > > >> > > >> I agree that it's unlikely anyone is building current GCC with a Texinfo > > >> version as old as 4.7 any more, and it may be that the manual doesn't even > > >> build properly with such an old release due to existing unintentional > > >> dependencies on newer features, independently of your patch. If we do update > > >> the version, there's a version check in configure.ac and some hack for > > >> "makeinfo 4.7 brokenness" in doc/install.texi2html that need to be changed, as > > >> well as install.texi. > > > > > > FWIW, I (briefly) tested with Texinfo 6.0, and output seems okay. On > > > 5.0, I got a few warnings, but I think even 6.0 is apt considering its > > > age. I haven't given it a proper scrutiny, though (workdays are busy > > > this time of year..). > > > > Texinfo 6.0 was released in 2015, 5.0 in 2013. FWIW, Trusty Tahr (the > > current oldest Ubuntu LTS release) has 5.2. 4.7 was released in 2004, I > > don't know why anyone would still be trying to use that unless it's > > needed for building legacy code from the same era. > > CentOS/RHEL 7 includes texinfo 5.1. That is the oldest distro I think > mostly supports building with. > That is the oldest I do builds of GCC with even for the trunk. SLES 12 has texinfo 4.13a, SLES 15 has texinfo 6.5. We still provide up-to-date GCC for SLES 12 but we can probably manage in some ways when the texinfo requirement gets bumped. Richard. > Thanks, > Andrew > > > > > I think we could do away with the requirement for a specific minimum > > version, and make install.texi say something similar to what it says for > > e.g. awk -- just use a "recent" version, and note that new versions > > produce better output and very old ones may produce diagnostics. I'll > > add that do my own todo list. > > > > -Sandra
On Wed, 8 Mar 2023, Sandra Loosemore wrote: > I personally do not know how the manuals for the GCC web site are built gcc.gnu.org has texinfo 6.5. (It's a RHEL 8.7 system.) > If we do update the version, there's a version check in configure.ac and > some hack for "makeinfo 4.7 brokenness" in doc/install.texi2html that > need to be changed, as well as install.texi. The note in doc/install.texi2html isn't specific to version 4.7. Rather it's about a design decision made then to encode dashes as _002d which essentially solved a non-issue and isn't practial at all. Good point - I'll see to update that comment. Gerald
Sandra Loosemore <sandra@codesourcery.com> writes: >> As an example, let's take this link: >> https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/Warning-Options.html#index-Wpedantic >> This should place you below the item line this index entry refers to, >> and there aren't any copiable anchors (see equivalent in my render for >> an example of those), both of which were often named as annoyances with >> the onlinedocs while the Sphinx experiment was taking place. >> A similar thing happens in the standalone and Emacs info viewers (but >> that's less noticeable there since the cursor is placed in the middle of >> the screen when jumping to an index entry there). Try, for instance, >> 'info gcc Wpedantic' (your cursor will be placed just below the item >> line). >> The fix for the first of these issues should already be applied by >> Gerald (in the reordering commits, IIRC at least, save for one that I >> created later because someone snuck in new "misplaced" indices), and >> that fix should also fix up previous versions of Texinfo. >> Even with this change, the copiable anchors will remain missing since >> released Texinfo versions lack some AST transformations that enable >> those. > > OK, I can see the difference there between the current online docs, the set you > produced with the unreleased Texinfo support, and what I got building with > Texinfo 6.7. > >> Otherwise, manuals should work fine with older releases, unless I missed >> something when refactoring @defbuiltin and removing @gols (which I do >> believe are superfluous with current versions of texinfo.tex, which is >> why I bumped that too). > > I did a few spot-checks here and there of those changes. I saw a couple of > line break problems but they turn out to be due to existing errors in the .texi > files that were not introduced by your (mostly mechanical) changes. Thanks. I tried to check all usage sites of @gol in PDF output too, to make sure its removal didn't have a negative impact, but I only tested new makeinfo and the texinfo.tex I pushed to my branch (2023-01-17.19). I expect the version of makeinfo to have no impact for that output, since it should just offload to texi2dvi. >> FWIW, I (briefly) tested with Texinfo 6.0, and output seems okay. On >> 5.0, I got a few warnings, but I think even 6.0 is apt considering its >> age. I haven't given it a proper scrutiny, though (workdays are busy >> this time of year..). > > Texinfo 6.0 was released in 2015, 5.0 in 2013. FWIW, Trusty Tahr (the current > oldest Ubuntu LTS release) has 5.2. 4.7 was released in 2004, I don't know why > anyone would still be trying to use that unless it's needed for building legacy > code from the same era. Heh, I hadn't realized how far back LTS releases go.. I don't think there's any new language constructs that the GCC manual could make use of currently, so it shouldn't be too difficult to retain at least a "builds with diagnostics" level of support for those versions. > I think we could do away with the requirement for a specific minimum version, > and make install.texi say something similar to what it says for e.g. awk -- > just use a "recent" version, and note that new versions produce better output > and very old ones may produce diagnostics. I'll add that do my own todo list. That seems reasonable, thanks. > -Sandra
On 3/9/23 01:26, Richard Biener wrote: > SLES 12 has texinfo 4.13a, SLES 15 has texinfo 6.5. We still provide > up-to-date GCC for SLES 12 but we can probably manage in some ways > when the texinfo requirement gets bumped. OK, this seems to be the oldest version anyone admits to actually using. I built the manual with Arsen's patches using 4.13a; the build was successful, and I didn't see any obvious issues with the @gol removal in either the PDF or HTML output, so I think we are OK for backward compatibility. I will work up a patch to remove the references to version 4.7 and replace it with some generic language as I suggested earlier, that won't be so prone to bit rot. -Sandra
Hi all, > On 9 Mar 2023, at 23:35, Sandra Loosemore via Gcc-patches <gcc-patches@gcc.gnu.org> wrote: > > On 3/9/23 01:26, Richard Biener wrote: > >> SLES 12 has texinfo 4.13a, SLES 15 has texinfo 6.5. We still provide >> up-to-date GCC for SLES 12 but we can probably manage in some ways >> when the texinfo requirement gets bumped. > > OK, this seems to be the oldest version anyone admits to actually using. I built the manual with Arsen's patches using 4.13a; the build was successful, and I didn't see any obvious issues with the @gol removal in either the PDF or HTML output, so I think we are OK for backward compatibility. FWIW macOS/Darwin (as delivered by Apple) is stuck on 4.8 (and, presumably, very unlikely to advance), but I would expect most macOS FOSS users have something newer installed, either self-built or via macposrts/homebrew etc. so the “admits to actually using” applies here too I think (personally, I am using 6.7 but not for any special reason other than it was current when I updated my local toolset). So I think Darwin can also manage with a newer requirement. thanks Iain > I will work up a patch to remove the references to version 4.7 and replace it with some generic language as I suggested earlier, that won't be so prone to bit rot. > > -Sandra
On 3/10/23 01:50, Iain Sandoe wrote: > Hi all, > >> On 9 Mar 2023, at 23:35, Sandra Loosemore via Gcc-patches >> <gcc-patches@gcc.gnu.org> wrote: >> >> On 3/9/23 01:26, Richard Biener wrote: >> >>> SLES 12 has texinfo 4.13a, SLES 15 has texinfo 6.5. We still >>> provide up-to-date GCC for SLES 12 but we can probably manage in >>> some ways when the texinfo requirement gets bumped. >> >> OK, this seems to be the oldest version anyone admits to actually >> using. I built the manual with Arsen's patches using 4.13a; the >> build was successful, and I didn't see any obvious issues with the >> @gol removal in either the PDF or HTML output, so I think we are OK >> for backward compatibility. > > FWIW macOS/Darwin (as delivered by Apple) is stuck on 4.8 (and, > presumably, very unlikely to advance), but I would expect most macOS > FOSS users have something newer installed, either self-built or via > macposrts/homebrew etc. so the “admits to actually using” applies > here too I think (personally, I am using 6.7 but not for any special > reason other than it was current when I updated my local toolset). > So I think Darwin can also manage with a newer requirement. Well, with 4.8 being too old to produce PDF output, that does kind of kill my idea of replacing the existing requirement for a specific Texinfo version with "the version that comes with your OS distribution is good enough". :-( AFAIK we have not knowingly changed any specific requirements beyond the stated 4.7 and 4.9 for PDF output, but it concerns me that nobody is likely to be using versions that old on a regular basis to make sure they continue to work and we haven't unknowingly introduced dependencies on newer Texinfo features. Anyway, I think I will leave the existing requirement alone for now, and just add a note that newer versions produce better output. -Sandra
On 3/10/23 10:51, Sandra Loosemore wrote: > On 3/10/23 01:50, Iain Sandoe wrote: >> Hi all, >> >>> On 9 Mar 2023, at 23:35, Sandra Loosemore via Gcc-patches >>> <gcc-patches@gcc.gnu.org> wrote: >>> >>> On 3/9/23 01:26, Richard Biener wrote: >>> >>>> SLES 12 has texinfo 4.13a, SLES 15 has texinfo 6.5. We still >>>> provide up-to-date GCC for SLES 12 but we can probably manage in >>>> some ways when the texinfo requirement gets bumped. >>> >>> OK, this seems to be the oldest version anyone admits to actually >>> using. I built the manual with Arsen's patches using 4.13a; the >>> build was successful, and I didn't see any obvious issues with the >>> @gol removal in either the PDF or HTML output, so I think we are OK >>> for backward compatibility. >> >> FWIW macOS/Darwin (as delivered by Apple) is stuck on 4.8 (and, >> presumably, very unlikely to advance), but I would expect most macOS >> FOSS users have something newer installed, either self-built or via >> macposrts/homebrew etc. so the “admits to actually using” applies >> here too I think (personally, I am using 6.7 but not for any special >> reason other than it was current when I updated my local toolset). >> So I think Darwin can also manage with a newer requirement. > > Well, with 4.8 being too old to produce PDF output, that does kind of > kill my idea of replacing the existing requirement for a specific > Texinfo version with "the version that comes with your OS distribution > is good enough". :-( > > AFAIK we have not knowingly changed any specific requirements beyond the > stated 4.7 and 4.9 for PDF output, but it concerns me that nobody is > likely to be using versions that old on a regular basis to make sure > they continue to work and we haven't unknowingly introduced dependencies > on newer Texinfo features. > > Anyway, I think I will leave the existing requirement alone for now, and > just add a note that newer versions produce better output. Oh, I need to take that back -- looking now, it's 4.8 for PDF output, not 4.9 like I was thinking before I had enough caffeine in my bloodstream. I'll leave the version check in place but add some text suggesting a more recent version, anyway. -Sandra
On Fri, 10 Mar 2023, Sandra Loosemore wrote: > AFAIK we have not knowingly changed any specific requirements beyond the > stated 4.7 and 4.9 for PDF output, but it concerns me that nobody is > likely to be using versions that old on a regular basis to make sure > they continue to work and we haven't unknowingly introduced dependencies > on newer Texinfo features. I'm generally very interested in ensuring we do not hurt users who do not have the latest and greatest of the day. On the other hand, if there's a few people using (more or less deliberately abandonware) we should not feel too bad if something breaks. > Anyway, I think I will leave the existing requirement alone for now, and > just add a note that newer versions produce better output. With Richi mentioning that SLE 12 (which was first released 9 years ago) uses texinfo 4.13a and Andrew mentioning that RHEL 7 uses texinfo 5.1 I would feel very comfortable making either 4.13 or even 5.1 the new minimum. (Not because we need to cater to those two Enterprise Linux distros, rather since they tend to fall on the conversative side.) Gerald
On Fri, Mar 10, 2023 at 8:00 PM Gerald Pfeifer <gerald@pfeifer.com> wrote: > > On Fri, 10 Mar 2023, Sandra Loosemore wrote: > > AFAIK we have not knowingly changed any specific requirements beyond the > > stated 4.7 and 4.9 for PDF output, but it concerns me that nobody is > > likely to be using versions that old on a regular basis to make sure > > they continue to work and we haven't unknowingly introduced dependencies > > on newer Texinfo features. > > I'm generally very interested in ensuring we do not hurt users who do not > have the latest and greatest of the day. On the other hand, if there's a > few people using (more or less deliberately abandonware) we should not > feel too bad if something breaks. > > > Anyway, I think I will leave the existing requirement alone for now, and > > just add a note that newer versions produce better output. > > With Richi mentioning that SLE 12 (which was first released 9 years ago) > uses texinfo 4.13a and Andrew mentioning that RHEL 7 uses texinfo 5.1 I > would feel very comfortable making either 4.13 or even 5.1 the new minimum. > > (Not because we need to cater to those two Enterprise Linux distros, > rather since they tend to fall on the conversative side.) We could also opt to ship generated pdf documentation with the release tarballs - the pre-built info format plus manual pages is probably of less use these days? Richard. > Gerald
Richard Biener <richard.guenther@gmail.com> writes: > On Fri, Mar 10, 2023 at 8:00 PM Gerald Pfeifer <gerald@pfeifer.com> wrote: >> >> On Fri, 10 Mar 2023, Sandra Loosemore wrote: >> > AFAIK we have not knowingly changed any specific requirements beyond the >> > stated 4.7 and 4.9 for PDF output, but it concerns me that nobody is >> > likely to be using versions that old on a regular basis to make sure >> > they continue to work and we haven't unknowingly introduced dependencies >> > on newer Texinfo features. >> >> I'm generally very interested in ensuring we do not hurt users who do not >> have the latest and greatest of the day. On the other hand, if there's a >> few people using (more or less deliberately abandonware) we should not >> feel too bad if something breaks. >> >> > Anyway, I think I will leave the existing requirement alone for now, and >> > just add a note that newer versions produce better output. >> >> With Richi mentioning that SLE 12 (which was first released 9 years ago) >> uses texinfo 4.13a and Andrew mentioning that RHEL 7 uses texinfo 5.1 I >> would feel very comfortable making either 4.13 or even 5.1 the new minimum. >> >> (Not because we need to cater to those two Enterprise Linux distros, >> rather since they tend to fall on the conversative side.) > > We could also opt to ship generated pdf documentation with the > release tarballs - the pre-built info format plus manual pages is > probably of less use these days? They're still widely installed and I suspect many open the manpages as a quick reference. I guess that fewer open the info pages, but it's not nobody (I certainly do, but I also have texinfo installed so I can generate them anyway, as I do for the weekly snapshots that I have installed). > Richard. > >> Gerald
On Fri, Mar 10, 2023, 14:00 Gerald Pfeifer <gerald@pfeifer.com> wrote: > On Fri, 10 Mar 2023, Sandra Loosemore wrote: > > AFAIK we have not knowingly changed any specific requirements beyond the > > stated 4.7 and 4.9 for PDF output, but it concerns me that nobody is > > likely to be using versions that old on a regular basis to make sure > > they continue to work and we haven't unknowingly introduced dependencies > > on newer Texinfo features. > > I'm generally very interested in ensuring we do not hurt users who do not > have the latest and greatest of the day. On the other hand, if there's a > few people using (more or less deliberately abandonware) we should not > feel too bad if something breaks. > Can you include texinfo in a top-level directory and have it built with the build, like you can with dejagnu? That's generally a decent path for building new gcc on older systems. >
Hi, NightStrike <nightstrike@gmail.com> writes: > Can you include texinfo in a top-level directory and have it built with the > build, like you can with dejagnu? That's generally a decent path for > building new gcc on older systems. Note that the Texinfo requirement wasn't bumped, so nothing changed in this regard, however, I believe that this is already done, as I see the following in Makefile.def: host_modules= { module= texinfo; no_install= true; }; (... and some relevant logic in configure.ac) I'm not a fan of building dependencies in-tree, but I can see the usefulness; I believe a superior solution would be one that adds .info (et al.) files to all generated tarballs (including snapshots), hence eliminating any extra deps anyway. These files aren't system-specific, after all, as they are neither code nor conditionally compiled. This is also assumed practice in other packages. Have a lovely day.
n 5/29/23 11:26, Arsen Arsenović wrote: > Hi, > > NightStrike <nightstrike@gmail.com> writes: > >> Can you include texinfo in a top-level directory and have it built >> with the build, like you can with dejagnu? That's generally a >> decent path for building new gcc on older systems. > > Note that the Texinfo requirement wasn't bumped, so nothing changed > in this regard, [snip] That is correct. The only change we ended up making was to the build instructions, which now point out that new versions of Texinfo produce better HTML output, but that the version of Texinfo packaged with your OS distribution is adequate for building GCC otherwise. We have GCC developers using quite old LTS distros with even older versions of Texinfo, so we would find out about it if something broke backward compatibility of the documentation. -Sandra
Morning, (as said in <https://inbox.sourceware.org/gcc-patches/86ilfsemnr.fsf@aarsen.me/>) This is a rebase + slight amendment of the previous patch series visible at: https://inbox.sourceware.org/gcc-patches/cover.1674777149.git.arsen@aarsen.me/ The commit "docs: Reorder @opindex to be before corresponding options" was already applied, and so, is dropped. To reiterate and address comments from v1: - OK from Iain Buclaw for the D changes: https://gcc.gnu.org/pipermail/gcc-patches/2023-January/610724.html - Thomas Schwinge noted that the commit message for 2/5 lacks context. This should be addressed in this revision. https://gcc.gnu.org/pipermail/gcc-patches/2023-February/612616.html His idea of automatically checking for this error pattern will be implemented separately, after I figure out how best to do that. The code that was involved in making this patchset is too primitive to apply globally. Some of the commits have been squashed into 2/5 also, as they were split arbitrarily to avoid hitting email size constraints, but, turns out the commits that were split weren't the problem in the first place :-). This patchset still needs the wwwdocs change at: https://inbox.sourceware.org/gcc-patches/20230127003224.717347-1-arsen@aarsen.me/ to add the stylesheet referenced in 5/5. I've rerendered the updated documentation with latest development Texinfo (as some of the changes I made for the purposes of the GCC manual still aren't in releases) at: https://www.aarsen.me/~arsen/final/ ... and the entire patchset can also be fetched from: https://git.sr.ht/~arsen/gcc texinfo_improvements Arsen Arsenović (5): docs: Create Indices appendix **/*.texi: Reorder index entries doc: Add @defbuiltin family of helpers, set documentlanguage Update texinfo.tex, remove the @gol macro/alias update_web_docs_git: Update CSS reference to new manual CSS gcc/d/implement-d.texi | 66 +- gcc/doc/cfg.texi | 12 +- gcc/doc/cpp.texi | 12 +- gcc/doc/cppenv.texi | 4 +- gcc/doc/cppopts.texi | 8 +- gcc/doc/extend.texi | 2564 ++++---- gcc/doc/gcc.texi | 36 +- gcc/doc/generic.texi | 2 +- gcc/doc/implement-c.texi | 2 +- gcc/doc/include/gcc-common.texi | 26 +- gcc/doc/include/texinfo.tex | 7599 +++++++++++++++--------- gcc/doc/install.texi | 6 +- gcc/doc/invoke.texi | 2854 ++++----- gcc/doc/md.texi | 25 +- gcc/doc/rtl.texi | 8 +- gcc/doc/sourcebuild.texi | 4 - gcc/doc/tm.texi | 4 +- gcc/doc/tm.texi.in | 4 +- gcc/doc/trouble.texi | 8 +- gcc/fortran/intrinsic.texi | 722 +-- gcc/fortran/invoke.texi | 284 +- gcc/go/gccgo.texi | 34 +- maintainer-scripts/update_web_docs_git | 2 +- 23 files changed, 8030 insertions(+), 6256 deletions(-) Thanks in advance, have a lovely day.