Subject: bug#72024: documentation suggestion: make old versions of docs easily available

From: Pádraig Brady <[email-masked]>
Date: Wed, 10 Jul 2024 09:47:50 +0100

On 09/07/2024 22:18, mark.yagnatinsky--- via GNU coreutils Bug Reports wrote:
> If go to the website of say, Perl or Python, and I see there's a cool function I want to use, then often there will be a note "new in version X.Y".
> Then I know that if I need to support versions older than that, I can't use it, and otherwise I can.
> If there is no such note, then I also have the option of easily pulling up old versions of the docs.
> So I can quickly grab the docs for the oldest version I care about, and see if the function exists there.
> 
> Most GNU software (e.g., bash, coreutils, etc.) makes the latest version easily available on the website, but not older versions.
> (The older versions are indeed available, but not require downloading and unzipping the full source distribution, or a similar level of annoyance.)
> This is sometimes fine, since if I need to support some ancient version, then presumably I have access to at least one machine where that version is installed, and that machine will often have docs installed too.
> But it's still nice to know whether I'm "skating close to the edge" or whether I'm using stuff that was already supported last century.
> 
> Just my two cents.
> Mark.

This is a fair point.

Now there should be less interface churn from version to version,
than a larger API surface like python etc., but it's still a valid point.
Currently one way to glean this info would be from the NEWS file:
https://raw.githubusercontent.com/coreutils/coreutils/master/NEWS
But that is awkward to search, and you're not sure did you miss
an item, or that it was always present.

Presenting this version info inline in the docs would be
too invasive I think, given it's not usually required,
but presenting versions to select would be a useful service.
Along the lines of the FreeBSD project for example:
https://man.freebsd.org/cgi/man.cgi?query=timeout

Now the above is more useful as it's a complete distro,
which suggests it may be more appropriate for each distro
to provide complete versioned online man pages.
Debian does in fact do this with selectable distro versions:
https://manpages.debian.org/

Actually I now see a distro agnostic versioned man page repo,
which would be the most general way to determine portability constraints:
https://manned.org/

cheers,
Pádraig.