Re: [PATCH] DOCUMENTATION_ROOT_URL vs. release branches [PR114738]

[Richard Biener <richard.guenther@gmail.com>]

On Wed, Apr 17, 2024 at 1:17 PM Jakub Jelinek <jakub@redhat.com> wrote:
>
> 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 ‘%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.

I think this patch is sensible and an improvement over the current situation.
I guess we'll have to see how things evolve on the branch and adapt.

So, OK.

Thanks,
Richard.

> 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.
>
> --- 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 = 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;
> --- 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 != 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
>
>         Jakub
>