automake
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: multiple online manual versions


From: Mike Frysinger
Subject: Re: multiple online manual versions
Date: Tue, 18 Jan 2022 22:34:39 -0500

On 18 Jan 2022 19:27, Karl Berry wrote:
> Having multiple versions of the manual online sounds all to the good to
> me.  As long as it's being done at all, I wouldn't hesitate to put up
> the manuals for every release, not just the major releases. For 1.16.x,
> I'm afraid I rather broke the previous rules for major releases anyway.
> 
>   https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-<VER>/
> 
> What I don't like about this approach is that it redirects from the
> generic url to the versioned url. Also, the /savannah-checkouts/ seems
> pretty ugly.
> 
> I think it would be cleaner to create and commit
> <www>/automake/manual-<ver>/<files> for whatever <ver>s desired.
> Could probably get them out of CVS.
> 
> Then automake/manual/<files> could remain unchanged, as a copy of the
> current <ver>. FWIW ... --best, karl.

i agree that automake/manual/ should be canonical and the main entry point
to the documentation.  what should that page look like ?  i see two ways:
* the GCC method where it's a quick index of every version.  great for
  referencing, but i think might put too much emphasis on multiversion.
* the current page, but with an entry/link like "For older manuals, please
  see this index." and that takes you to the full version index akin to
  what GCC is using.  this does a good job of steering people into the
  latest version without them thinking about it.

in terms of layout after that, i'm of two minds.  on one hand, i agree
that it's kind of ugly that you're always redirected to the versioned
one, and there's never a canonical manual/<foo> base.  but on the other,
if people are copying & pasting links to the manual, everytime we make
changes to the manual the rename or reorder chapters, we're breaking
those historical links.  if it always redirected to a versioned URL,
people would be more likely to copy & paste links that are stable.

so i would lean towards everything being anchored/entered here:
        https://www.gnu.org/software/automake/manual/
we'd have the curated landing page & full versioned index in there.

the versions would be subdirs rather than parallel so as to keep the
higher automake/ dir a bit tidy.  so:
        https://www.gnu.org/software/automake/manual/1.15/
        https://www.gnu.org/software/automake/manual/1.16/
(or if you prefer, 1.15.x and such)

any other manual/<file> access would redirect to the latest version.
that way we don't break links already out in the wild.
-mike

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]