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.
