On Wed, Apr 17, 2024 at 1:17 PM Jakub Jelinek <ja...@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 <ja...@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
>
