From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-lf1-x12b.google.com (mail-lf1-x12b.google.com [IPv6:2a00:1450:4864:20::12b]) by sourceware.org (Postfix) with ESMTPS id 5B4B63858D20 for ; Wed, 17 Apr 2024 12:44:28 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 5B4B63858D20 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gmail.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 5B4B63858D20 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2a00:1450:4864:20::12b ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713357871; cv=none; b=bk/J6fPN3PsPQTexP7iCUvK0YDBWMXur7DpYtlQazp6biLwLSKwg4kVoPj/tn5dOiVlM5TVgBDej3MjbiW+P31zfPIgxIBLKRmQMyuppt22W0SQH+ajpA9bS7M8XY6ySgYS+uSiUisRyRKmOMqIvpOPcKEuyAUfFlcqPf9xeBNM= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1713357871; c=relaxed/simple; bh=wMJvBJUH6NMZpgzdE6m1KckqBfvNT0rlQewz01sl6u0=; h=DKIM-Signature:MIME-Version:From:Date:Message-ID:Subject:To; b=a5icofLlDvgDP+b+f6cqUmeVPnPOkiFcknhsK4D/z1dRv5AKwwJjfm6TzUiZL4t5aGnmYUx0JjSgMP2PB6dJ+CBGHMKbEdleqV7+h1QpuJ9K6/qCmmeTh5sxxVuru2OCVFu7F0I4JANxIMHcVgOZ0R+xEOZ7xKY/8eNByz74glI= ARC-Authentication-Results: i=1; server2.sourceware.org Received: by mail-lf1-x12b.google.com with SMTP id 2adb3069b0e04-5171a529224so7055161e87.0 for ; Wed, 17 Apr 2024 05:44:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1713357867; x=1713962667; darn=gcc.gnu.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=36Vixt81/UG0JfK9oFNIvQYls/EmCeXDSTkzOwvyWJA=; b=S7lAfihtYNTf2XeW4tE7ZNM4ijTEQBDb3YIGC5+n25uym86PLBrGzDm1mw/kurxDlr U6XPQ3A0KTb3eWzDtWobWMelHHS6mqrSiYQY0CO1gfPKLZBIbggFuuzeoqhLjhSr+Lu3 W2Q1A9Vc10E5qzGDpz2BWS6g22dkHm5vKO4MZRAbf9Ytw+S+X9Qk9TI6aVrhQNIk9Snd oTDR4rNBu1XYmnoHoM/PAt+YKkcl2HNo6ZQmJk1BBxY/BhUCCsUF4b1z1AwQls2SZvBY Oxi4mL0gM5RZlLJ8rfWA+MCLrsBkVcH73c8oi4ftUOMF0JRT7Q9tKl3kqPtgBRefvhG1 /nyw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1713357867; x=1713962667; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=36Vixt81/UG0JfK9oFNIvQYls/EmCeXDSTkzOwvyWJA=; b=Rbl8pCReqP3jXndrCAyoAvuJOY+ZcVx0q7LgEhCpGAEzDsBec5EBJErzoiHiJh7DQp 8hg8H19p/xy8ZHCAmjrmgbo8GoXTfuxvwiIkqYfThXh1K3KtOyQkZsknq0GWU3sUsNqc bKWyHp7UGbhpV5iJVQdI+w1zdlgJEypzsYBLjjgvbuKW+NY4JY4rD/Mt/P7/ntSd7xm3 1Ad2lr9lNMgK72TpH/t6a/B8SP7l1Z5qtWXxGUEzbh2UF+tiOWJGE+KDQQfljdArnWse 8xecbdwEnotWcRzqySxlHsr/3eXeT/fK6+TAiVMQHnA3t929srtptMiGdWL7Q1aS3jp9 cBXg== X-Forwarded-Encrypted: i=1; AJvYcCVKH2s7CIVzKNmy7XoSva7wHRQVQ4W7GBSsAbJbaTrhu/Uq/bi42ujYB4c9FXba9RdBrmiyEEZAdLlomMBgyLR9lgqZG9MV9g== X-Gm-Message-State: AOJu0Yy4akWXMn7OWH+WovxHuvjfvUsjVeHiFdRZeliI+j3JCxg1taDH ZDW0w72xIb3S293dgjwyCmdHn+eRbigeD9CqwUTEFiD0nMAphXcyyK/yZC2d+9nBY+8cNBSZvlk S7iERw9wO2FJOdBO3cPUHSUS6pgw= X-Google-Smtp-Source: AGHT+IESh5E4OAHXWuKybe6Htwv+vSm4Nz/MLaL+82XKzw5iMxPIzovJ1qtYrL4dqiFNxAAizY+u+V++ZwGi+KWIa4Y= X-Received: by 2002:a05:6512:32b4:b0:513:d884:7aac with SMTP id q20-20020a05651232b400b00513d8847aacmr10007146lfe.21.1713357866408; Wed, 17 Apr 2024 05:44:26 -0700 (PDT) MIME-Version: 1.0 References: In-Reply-To: From: Richard Biener Date: Wed, 17 Apr 2024 14:44:15 +0200 Message-ID: Subject: Re: [PATCH] DOCUMENTATION_ROOT_URL vs. release branches [PR114738] To: Jakub Jelinek Cc: David Malcolm , Mark Wielaard , gcc-patches@gcc.gnu.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-1.6 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,KAM_SHORT,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS,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, Apr 17, 2024 at 1:17=E2=80=AFPM Jakub Jelinek wr= ote: > > Hi! > > 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. > > 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 chan= ges > in the documentation will make too many links stale, because users will > simply regularly update to newer snapshots. > > I think it doesn't work properly on release branches though. > Some users only use the relased versions (i.e. MAJOR.MINOR.0) from tarbal= ls > 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. > > 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. > > 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 proces= s > of updating *.opt.urls as well for that. > > 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. 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. 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/ subtree locally) > and doing regenerate-opt-urls on top of that? 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)? > > Another option would be to add to cron daily regeneration of the online > docs for the release branches. 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. > > 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. Do we expect them to grab the whole onlinedocs tree or for relea= se > branches at least include gcc-14.1.0/ subdirectory under the root? > If so, the patch below deals with that. Or should we just change the > 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/ or > https://gcc.gnu.org/onlinedocs/gcc-14.2.0/ etc. and don't add any infix i= n > 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 this patch is sensible and an improvement over the current situatio= n. I guess we'll have to see how things evolve on the branch and adapt. So, OK. Thanks, Richard. > 2024-04-17 Jakub Jelinek > > PR other/114738 > * opts.cc (get_option_url): On release branches append > gcc-MAJOR.MINOR.0/ after DOCUMENTATION_ROOT_URL. > * gcc-urlifier.cc (gcc_urlifier::make_doc_url): Likewise. > > --- gcc/opts.cc.jj 2024-01-05 08:35:13.600828652 +0100 > +++ gcc/opts.cc 2024-04-17 12:03:10.961525141 +0200 > @@ -3761,7 +3761,19 @@ get_option_url (const diagnostic_context > { > label_text url_suffix =3D get_option_url_suffix (option_index, lan= g_mask); > if (url_suffix.get ()) > - return concat (DOCUMENTATION_ROOT_URL, url_suffix.get (), nullptr= ); > + { > + char infix[32]; > + /* On release branches, append to DOCUMENTATION_ROOT_URL the > + subdirectory with documentation of the latest release made > + from the branch. */ > + if (BUILDING_GCC_MINOR !=3D 0 && BUILDING_GCC_PATCHLEVEL <=3D 1= U) > + sprintf (infix, "gcc-%u.%u.0/", > + BUILDING_GCC_MAJOR, BUILDING_GCC_MINOR); > + else > + infix[0] =3D '\0'; > + return concat (DOCUMENTATION_ROOT_URL, infix, url_suffix.get ()= , > + nullptr); > + } > } > > return nullptr; > --- gcc/gcc-urlifier.cc.jj 2024-01-10 17:15:31.851855587 +0100 > +++ gcc/gcc-urlifier.cc 2024-04-17 12:14:47.902706021 +0200 > @@ -26,6 +26,7 @@ along with GCC; see the file COPYING3. > #include "gcc-urlifier.h" > #include "opts.h" > #include "options.h" > +#include "diagnostic-core.h" > #include "selftest.h" > > namespace { > @@ -208,7 +209,16 @@ gcc_urlifier::make_doc_url (const char * > if (!doc_url_suffix) > return nullptr; > > - return concat (DOCUMENTATION_ROOT_URL, doc_url_suffix, nullptr); > + char infix[32]; > + /* On release branches, append to DOCUMENTATION_ROOT_URL the > + subdirectory with documentation of the latest release made > + from the branch. */ > + if (BUILDING_GCC_MINOR !=3D 0 && BUILDING_GCC_PATCHLEVEL <=3D 1U) > + sprintf (infix, "gcc-%u.%u.0/", > + BUILDING_GCC_MAJOR, BUILDING_GCC_MINOR); > + else > + infix[0] =3D '\0'; > + return concat (DOCUMENTATION_ROOT_URL, infix, doc_url_suffix, nullptr)= ; > } > > } // anonymous namespace > > Jakub >