From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from esa1.mentor.iphmx.com (esa1.mentor.iphmx.com [68.232.129.153]) by sourceware.org (Postfix) with ESMTPS id 168F83858D33 for ; Thu, 9 Mar 2023 01:09:10 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 168F83858D33 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com X-IronPort-AV: E=Sophos;i="5.98,244,1673942400"; d="scan'208";a="103643995" Received: from orw-gwy-02-in.mentorg.com ([192.94.38.167]) by esa1.mentor.iphmx.com with ESMTP; 08 Mar 2023 17:09:08 -0800 IronPort-SDR: hdL+2MpX3wlmINyOkgAV7WCuNK59YXHeRowhBU4Wx9VNgm996O2H7flDHP6wi/8lrPuj38I1p4 AVEOwHiq3Lh/jkVd6lArch0jhzqZUhms1BEx152khUhzTQkzrMP2D0uFqG/G5RoBw3uwo/0GNE nF5GroquzvWhQ1zGiEKrsThRmWCIyC5TlcHSZMhXZxuaPQ/RFAy0EzYXUzODIXWiRRPNVi2ZbJ 2DazSuUpymJSu/6ZoWf+rCn+TVCqAdfceEmB3PHZ5jYEWmkmhQRKCTtxOPM2rquzH5pHzMFrED s90= Message-ID: <708c48a9-a64d-6485-3e42-1ef9d97ffc7e@codesourcery.com> Date: Wed, 8 Mar 2023 18:09:04 -0700 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.7.1 Subject: Re: [PATCH v2 0/5] A small Texinfo refinement Content-Language: en-US To: =?UTF-8?Q?Arsen_Arsenovi=c4=87?= CC: , Gerald Pfeifer , "Joseph Myers" References: <20230223102714.3606058-1-arsen@aarsen.me> <76f92bd2-7d4b-15ba-12ca-8de44e91b886@codesourcery.com> <86lek7txey.fsf@aarsen.me> <86a60m98dz.fsf@aarsen.me> From: Sandra Loosemore In-Reply-To: <86a60m98dz.fsf@aarsen.me> Content-Type: text/plain; charset="UTF-8"; format=flowed Content-Transfer-Encoding: 8bit X-ClientProxiedBy: svr-orw-mbx-15.mgc.mentorg.com (147.34.90.215) To svr-orw-mbx-13.mgc.mentorg.com (147.34.90.213) X-Spam-Status: No, score=-3.5 required=5.0 tests=BAYES_00,HEADER_FROM_DIFFERENT_DOMAINS,KAM_DMARC_STATUS,KAM_INFOUSMEBIZ,KAM_SHORT,NICE_REPLY_A,SPF_HELO_PASS,SPF_PASS,TXREP autolearn=no autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: On 3/8/23 14:22, Arsen Arsenović wrote: > > Sandra Loosemore writes: > >> On 3/8/23 02:11, Arsen Arsenović wrote: >>> Sandra Loosemore 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