DOCUMENTATION_ROOT_URL vs. release branches [PR114738]

Starting with GCC 14 we have the nice URLification of the options printed
in diagnostics, say for in
test.c:4:23: warning: format ‘%d’ expects argument of type ‘int’, but argument 2 has type ‘long int’ [-Wformat=]
the -Wformat= 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 changes
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 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.

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 process
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= configure
option.  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.  Or should we just change the
default documentation root url, so if user doesn't specify
--with-documentation-root-url= 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 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.

2024-04-17  Jakub Jelinek  <jakub@redhat.com>

	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.

diff --git a/gcc/gcc-urlifier.cc b/gcc/gcc-urlifier.cc
index be6459e8d7c14e2aabe0d60580753dc34a41e176..ff8c3f65ac569882255817ab62c79ce4b76d8f5d 100644 (file)
--- a/gcc/gcc-urlifier.cc
+++ b/gcc/gcc-urlifier.cc
@@ -26,6 +26,7 @@ along with GCC; see the file COPYING3.  If not see
 #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 *doc_url_suffix)
   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 != 0 && BUILDING_GCC_PATCHLEVEL <= 1U)
+    sprintf (infix, "gcc-%u.%u.0/",
+            BUILDING_GCC_MAJOR, BUILDING_GCC_MINOR);
+  else
+    infix[0] = '\0';
+  return concat (DOCUMENTATION_ROOT_URL, infix, doc_url_suffix, nullptr);
 }
 
 } // anonymous namespace

diff --git a/gcc/opts.cc b/gcc/opts.cc
index 3333600e0ea24bdfd0a097de3d74b94105831404..a90dc57f8b5ba9b6f920442f45ace864fed9cefe 100644 (file)
--- a/gcc/opts.cc
+++ b/gcc/opts.cc
@@ -3761,7 +3761,19 @@ get_option_url (const diagnostic_context *,
     {
       label_text url_suffix = get_option_url_suffix (option_index, lang_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 != 0 && BUILDING_GCC_PATCHLEVEL <= 1U)
+           sprintf (infix, "gcc-%u.%u.0/",
+                    BUILDING_GCC_MAJOR, BUILDING_GCC_MINOR);
+         else
+           infix[0] = '\0';
+         return concat (DOCUMENTATION_ROOT_URL, infix, url_suffix.get (),
+                        nullptr);
+       }
     }
 
   return nullptr;