Re: [PATCH v2 0/5] A small Texinfo refinement

["Arsen Arsenović" <arsen@aarsen.me>]

[-- Attachment #1: Type: text/plain, Size: 4632 bytes --]


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.
-- 
Arsen Arsenović

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 381 bytes --]