From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 80DF33858417 for ; Tue, 23 Apr 2024 15:41:00 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 80DF33858417 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 80DF33858417 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713886865; cv=none; b=MOkKIx0kSdHC+PUhs1HBn3Y+97OzibB9iDhVh7sGYKsokBTmsomSE8D/Tl4IYsMpibO6BSDZInMyrAHWZY6Woef75XeaR7Fi7DbdxXMuYZYgek5eOiPw2l2SQbMXaqVEIS5IZ8h0RQBRH5Hez5sn0R2YaclCJgmVoHs1aBTKLzY= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713886865; c=relaxed/simple; bh=y17BZgCxDVaFiBSV7ThRXorE4CfyiTQXTCOkEiv5s8U=; h=DKIM-Signature:Message-ID:Subject:From:To:Date:MIME-Version; b=sHFAo70GqydZQ6cu4xShxwQA/3cdPku23Jo7ZkW31xMcNX8EABjuDotMc1lw1Iu89zqpiHETmw3jpvNBEULPERA1XBNmu0ncR/Mr7syxAjMUlLmrN4+bFHJCoQUpx/yMkbktzSZTLH9iX5pcpgZ2AX2T92Eb7aLGdWEz4YzfC8o= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1713886860; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=5tQqGPkd/+zKDwUBettF8XOWCdBGWwFSUHPumFENSSg=; b=gKo4knA3flxl4XcNDulhvxz4p9r1oawJtSBLx55V1ouT8vHOujyBfgFMOyLGAYTvAqw7Ys 6YD5QLhH+yLk/gzUaUAVXOoEEp/Xqc0l8uzANEeNz8MOkV+8MTNuwGCXc25CHzHJ3r/TyJ FrNEmXoUW8zlapPdavaqLLRHwqz7aoM= Received: from mail-qk1-f198.google.com (mail-qk1-f198.google.com [209.85.222.198]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-539-tR_bBI4NPaqiG4dc1Wip9Q-1; Tue, 23 Apr 2024 11:40:58 -0400 X-MC-Unique: tR_bBI4NPaqiG4dc1Wip9Q-1 Received: by mail-qk1-f198.google.com with SMTP id af79cd13be357-79067807374so515830685a.2 for ; Tue, 23 Apr 2024 08:40:58 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1713886858; x=1714491658; h=mime-version:user-agent:content-transfer-encoding:references :in-reply-to:date:cc:to:from:subject:message-id:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=5tQqGPkd/+zKDwUBettF8XOWCdBGWwFSUHPumFENSSg=; b=cCtkcljawtabzZLqirgSiU5wqxI8kIHK5RAZ0JjaVZzNsmbxbvz+nSNBLqgisJCFqG YRJMASgjz+l7YYI49A7JwhWWUgvNok1qcZVVA0DmO3PAGpXAdMdhlzfBuo4lw4+vuSRl ndbVyv7K5A0lTHabnw6gYZjHUbmzS31w+RPxDLcYp62A9Vkz3cbIY0h93KBwVoaWf0XK NbvAuU/q1m8t1zAOWSywdOph4+eUzM+2YXMKV/q/qi2n+62gpeqyLfuuNEddZ/RJmWq2 Fd4xapDl2F8EKO2fNl4yW0PRERtvJvMiwUUSij810KcYvpNWBaitKPKJnAowxRRigp2E f/Fg== X-Gm-Message-State: AOJu0YyDD69TjxUVul19V0DovEjQ9qohgnvqeko83obnuW9o6IWkCQ8K KJmwoTufMr0DczEmnUXg0iOFy/x894p+zRkiyvhtl0I6SaQlH8gzkyufK6mK6/b0DaHufvNT7k+ NPxbw41mM3MmQLiNNaF+zZkC99NNwh56DURJ56tSJMCFjRJHDGUqgjd0= X-Received: by 2002:a05:620a:8107:b0:78d:6398:d684 with SMTP id os7-20020a05620a810700b0078d6398d684mr14387868qkn.64.1713886857800; Tue, 23 Apr 2024 08:40:57 -0700 (PDT) X-Google-Smtp-Source: AGHT+IFFtq6GhrAU+2ZpiYZ8JvO+ErdbtVoHf991NronDsBgoCD9z8a2T8LxINQgTX+qsJ/DqbOftA== X-Received: by 2002:a05:620a:8107:b0:78d:6398:d684 with SMTP id os7-20020a05620a810700b0078d6398d684mr14387844qkn.64.1713886857373; Tue, 23 Apr 2024 08:40:57 -0700 (PDT) Received: from t14s.localdomain (c-76-28-97-5.hsd1.ma.comcast.net. [76.28.97.5]) by smtp.gmail.com with ESMTPSA id cz6-20020a05620a36c600b0078d7213de13sm5272962qkb.136.2024.04.23.08.40.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 23 Apr 2024 08:40:56 -0700 (PDT) Message-ID: Subject: Re: [PATCH] DOCUMENTATION_ROOT_URL vs. release branches [PR114738] From: David Malcolm To: Jakub Jelinek , Mark Wielaard Cc: gcc-patches@gcc.gnu.org Date: Tue, 23 Apr 2024 11:40:55 -0400 In-Reply-To: References: User-Agent: Evolution 3.44.4 (3.44.4-2.fc36) MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-4.1 required=5.0 tests=BAYES_00,BODY_8BITS,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,KAM_SHORT,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H4,RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,SPF_NONE,TXREP autolearn=ham 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 Wed, 2024-04-17 at 13:16 +0200, Jakub Jelinek wrote: > Hi! >=20 > Starting with GCC 14 we have the nice URLification of the options > printed > in diagnostics, say for in > test.c:4:23: warning: format =E2=80=98%d=E2=80=99 expects argument of typ= e =E2=80=98int=E2=80=99, but > argument 2 has type =E2=80=98long int=E2=80=99 [-Wformat=3D] > the -Wformat=3D is underlined in some terminals and hovering on it > shows > https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wformat > link. That isn't new in GCC 14; we've provided the URLs for the option guarding a warning since GCC 10, I think. What's new is that we now "urlify" any quoted text that mentions an option, and that the option URLs are now based on the anchors in the generated HTML (and thus more likely to be correct). >=20 > This works nicely on the GCC trunk, where the online documentation is > regenerated every day from a cron job and more importantly, people > rarely > use the trunk snapshots for too long, so it is unlikely that further > changes > in the documentation will make too many links stale, because users > will > simply regularly update to newer snapshots. >=20 > I think it doesn't work properly on release branches though. > Some users only use the relased versions (i.e. MAJOR.MINOR.0) from > tarballs > but can use them for a couple of years, others use snapshots from the > release branches, but again they could be in use for months or years > and > the above mentioned online docs which represent just the GCC trunk > might > diverge significantly. >=20 > Now, for the relases we always publish also online docs for the > release, > which unlike the trunk online docs will not change further, under > e.g. > https://gcc.gnu.org/onlinedocs/gcc-14.1.0/gcc/Warning-Options.html#index-= Wformat > or > https://gcc.gnu.org/onlinedocs/gcc-14.2.0/gcc/Warning-Options.html#index-= Wformat > etc. >=20 > So, I think at least for the MAJOR.MINOR.0 releases we want to use > URLs like above rather than the trunk ones and we can use the same > process > of updating *.opt.urls as well for that. Would it make sense to instead update the default value in gcc/configure.ac for DOCUMENTATION_ROOT_URL when branching or releasing, from https://gcc.gnu.org/onlinedocs/ to https://gcc.gnu.org/onlinedocs/gcc-MAJOR-MINOR.0/ ? Before this patch the DOCUMENTATION_ROOT_URL expresses the location of a built texinfo html tree of docs, and the url suffixes express the path within that tree. As the patch is written, if a distributor overrides --with- documentation-root-url=3D at configure time, then they need to mirror the structure of our website on their website, which seems like a burden. >=20 > For the snapshots from release branches, we don't have such docs. > One option (implemented in the patch below for the URL printing side) > is > point to the MAJOR.MINOR.0 docs even for MAJOR.MINOR.1 snapshots. > Most of the links will work fine, for options newly added on the > release > branches (rare thing but still happens) can have until the next > release > no URLs for them and get them with the next point release. > The question is what to do about make regenerate-opt-urls for the > release > branch snapshots.=C2=A0 Either just document that users shouldn't > make regenerate-opt-urls on release branches (and filter out > *.opt.urls > changes from their commits), add make regenerate-opt-urls task be RM > responsibility before making first release candidate from a branch > and > adjust the autoregen CI to know about that.=C2=A0 Or add a separate goal > which instead of relying on make html created files would download > copy of the html files from the last release from web (kind of web > mirroring the https://gcc.gnu.org/onlinedocs/gcc-14.1.0/=C2=A0subtree > locally) > and doing regenerate-opt-urls on top of that?=C2=A0 But how to catch the > point when first release candidate is made and we want to update to > what will be the URLs once the release is made (but will be stale > URLs > for a week or so)? >=20 > Another option would be to add to cron daily regeneration of the > online > docs for the release branches.=C2=A0 I don't think that is a good idea > though, > because as I wrote earlier, not all users update to the latest > snapshot > frequently, so there can be users that use gcc 13.1.1 20230525 for > months > or years, and other users which use gcc 13.1.1 20230615 for years > etc. >=20 > Another question is what is most sensible for users who want to > override > the default root and use the --with-documentation-root-url=3D configure > option.=C2=A0 Do we expect them to grab the whole onlinedocs tree or for > release > branches at least include gcc-14.1.0/ subdirectory under the root? > If so, the patch below deals with that.=C2=A0 Or should we just change th= e > default documentation root url, so if user doesn't specify > --with-documentation-root-url=3D and we are on a release branch, > default that > to https://gcc.gnu.org/onlinedocs/gcc-14.1.0/=C2=A0or > https://gcc.gnu.org/onlinedocs/gcc-14.2.0/=C2=A0etc. and don't add any > infix in > get_option_url/make_doc_url, but when people supply their own, let > them > point to the root of the tree which contains the right docs? > Then such changes would go into gcc/configure.ac, some case based on > "$gcc_version", from that decide if it is a release branch or trunk. I think changing the default for DOCUMENTATION_ROOT_URL makes much more sense. Dave >=20 > 2024-04-17=C2=A0 Jakub Jelinek=C2=A0 >=20 > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0PR other/114738 > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0* opts.cc (get_option_url= ): On release branches append > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0gcc-MAJOR.MINOR.0/ after = DOCUMENTATION_ROOT_URL. > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0* gcc-urlifier.cc (gcc_ur= lifier::make_doc_url): Likewise. >=20 > --- gcc/opts.cc.jj=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A02024-01-05 08:35:13= .600828652 +0100 > +++ gcc/opts.cc=C2=A02024-04-17 12:03:10.961525141 +0200 > @@ -3761,7 +3761,19 @@ get_option_url (const diagnostic_context > =C2=A0=C2=A0=C2=A0=C2=A0 { > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 label_text url_suffix =3D get_option= _url_suffix (option_index, > lang_mask); > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 if (url_suffix.get ()) > -=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0return concat (DOCUMENTATION_R= OOT_URL, url_suffix.get (), > nullptr); > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0{ > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 char infix[32]; > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 /* On release branches,= append to DOCUMENTATION_ROOT_URL > the > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 subdi= rectory with documentation of the latest release > made > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 from = the branch.=C2=A0 */ > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 if (BUILDING_GCC_MINOR = !=3D 0 && BUILDING_GCC_PATCHLEVEL <=3D > 1U) > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 sprintf (in= fix, "gcc-%u.%u.0/", > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 BUILDING_GCC_MAJOR, BUILDING_GCC= _MINOR); > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 else > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 infix[0] = =3D '\0'; > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 return concat (DOCUMENT= ATION_ROOT_URL, infix, > url_suffix.get (), > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0= =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 nullptr)= ; > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0} > =C2=A0=C2=A0=C2=A0=C2=A0 } > =C2=A0 > =C2=A0=C2=A0 return nullptr; > --- gcc/gcc-urlifier.cc.jj=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A02024-01-10 = 17:15:31.851855587 +0100 > +++ gcc/gcc-urlifier.cc=C2=A02024-04-17 12:14:47.902706021 +0200 > @@ -26,6 +26,7 @@ along with GCC; see the file COPYING3. > =C2=A0#include "gcc-urlifier.h" > =C2=A0#include "opts.h" > =C2=A0#include "options.h" > +#include "diagnostic-core.h" > =C2=A0#include "selftest.h" > =C2=A0 > =C2=A0namespace { > @@ -208,7 +209,16 @@ gcc_urlifier::make_doc_url (const char * > =C2=A0=C2=A0 if (!doc_url_suffix) > =C2=A0=C2=A0=C2=A0=C2=A0 return nullptr; > =C2=A0 > -=C2=A0 return concat (DOCUMENTATION_ROOT_URL, doc_url_suffix, nullptr); > +=C2=A0 char infix[32]; > +=C2=A0 /* On release branches, append to DOCUMENTATION_ROOT_URL the > +=C2=A0=C2=A0=C2=A0=C2=A0 subdirectory with documentation of the latest r= elease made > +=C2=A0=C2=A0=C2=A0=C2=A0 from the branch.=C2=A0 */ > +=C2=A0 if (BUILDING_GCC_MINOR !=3D 0 && BUILDING_GCC_PATCHLEVEL <=3D 1U) > +=C2=A0=C2=A0=C2=A0 sprintf (infix, "gcc-%u.%u.0/", > +=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 BUILD= ING_GCC_MAJOR, BUILDING_GCC_MINOR); > +=C2=A0 else > +=C2=A0=C2=A0=C2=A0 infix[0] =3D '\0'; > +=C2=A0 return concat (DOCUMENTATION_ROOT_URL, infix, doc_url_suffix, > nullptr); > =C2=A0} > =C2=A0 > =C2=A0} // anonymous namespace >=20 > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0Jakub >=20