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

[David Malcolm <dmalcolm@redhat.com>]

On Tue, 2024-04-23 at 17:45 +0200, Jakub Jelinek wrote:
> On Tue, Apr 23, 2024 at 11:40:55AM -0400, David Malcolm wrote:
> > > 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= at configure time, then they need to mirror
> > the
> > structure of our website on their website, which seems like a
> > burden.
> 
> Sure, that is doable (of course, it shouldn't be done by updating
> gcc/configure.ac but by adjusting the default in there based on
> gcc_version,
> I'll post a patch tomorrow).

That sounds like a better approach; thanks.

> 
> Still, what do you think we should do on the release branches
> (recommend to
> developers and check with the post-commit CI)?

My hope is that the URL suffixes don't change: we shouldn't be adding
new command-line options on the release branches, and I'd hope that
texinfo doesn't change the generated anchors from run to run.

> No regeneration of *.urls except before doing a new release
> candidate,
> or a different make goal that would grab html files from the web and
> regenerate against that?

That sounds overcomplicated. 

If the anchors do change, it's fairly trivial to run "make regenerate-
opt-urls" locally, isn't it?

As mentioned above, I like the idea of having the
DOCUMENTATION_ROOT_URL express the location of a tree of docs built
with texinfo, and for the url suffixes to be relative to that.  We can
update the default in gcc/configure.ac for released branches, and drop
the logic from your previous patch.  So if a distributor wants to
upload their docs for a particular version to their own location,
they're responsible for providing a suitable value for  --with-
documentation-root-url= at configure time.

Or am I missing something here?

Dave