On 3/8/23 14:22, Arsen Arsenović wrote:
Sandra Loosemore <san...@codesourcery.com> writes:
On 3/8/23 02:11, Arsen Arsenović wrote:
Sandra Loosemore <san...@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
