GNU bug report logs - #72024
documentation suggestion: make old versions of docs easily available

Previous Next

To reply to this bug, email your comments to 72024 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: <mark.yagnatinsky <at> barclays.com>
To: <bug-coreutils <at> gnu.org>
Subject: documentation suggestion: make old versions of docs easily available
Date: Tue, 9 Jul 2024 21:18:25 +0000

[Message part 1 (text/plain, inline)]

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 message is for information purposes only. It is not a recommendation, advice, offer or solicitation to buy or sell a product or service, nor an official confirmation of any transaction. It is directed at persons who are professionals and is intended for the recipient(s) only. It is not directed at retail customers. This message is subject to the terms at: https://www.ib.barclays/disclosures/web-and-email-disclaimer.html. 

For important disclosures, please see: https://www.ib.barclays/disclosures/sales-and-trading-disclaimer.html regarding marketing commentary from Barclays Sales and/or Trading desks, who are active market participants; https://www.ib.barclays/disclosures/barclays-global-markets-disclosures.html regarding our standard terms for Barclays Investment Bank where we trade with you in principal-to-principal wholesale markets transactions; and in respect to Barclays Research, including disclosures relating to specific issuers, see: https://publicresearch.barclays.com.
__________________________________________________________________________________ 
If you are incorporated or operating in Australia, read these important disclosures: https://www.ib.barclays/disclosures/important-disclosures-asia-pacific.html.
__________________________________________________________________________________
For more details about how we use personal information, see our privacy notice: https://www.ib.barclays/disclosures/personal-information-use.html. 
__________________________________________________________________________________

[Message part 2 (text/html, inline)]

Message #8 received at 72024 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: mark.yagnatinsky <at> barclays.com, 72024 <at> debbugs.gnu.org
Subject: Re: bug#72024: documentation suggestion: make old versions of docs
 easily available
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.

Message #11 received at 72024 <at> debbugs.gnu.org (full text, mbox):

From: <mark.yagnatinsky <at> barclays.com>
To: <P <at> draigBrady.com>, <72024 <at> debbugs.gnu.org>
Subject: RE: bug#72024: documentation suggestion: make old versions of docs
 easily available
Date: Wed, 10 Jul 2024 11:53:35 +0000

Oh wow, manned.org is NICE ... I did not know about this!

-----Original Message-----
From: Pádraig Brady <pixelbeat <at> gmail.com> On Behalf Of Pádraig Brady
Sent: Wednesday, July 10, 2024 4:48 AM
To: Yagnatinsky, Mark : IT (NYK) <mark.yagnatinsky <at> barclays.com>; 72024 <at> debbugs.gnu.org
Subject: Re: bug#72024: documentation suggestion: make old versions of docs easily available


CAUTION: This email originated from outside our organisation - P <at> draigBrady.com Do not click on links, open attachments, or respond unless you recognize the sender and can validate the content is safe.
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://clicktime.symantec.com/15t5pR6kwQqcecLKd3QvS?h=a5ldoPPebCg7QcLk8Y1D4W7IWUsz0u5AdCm5wV9uXkc=&u=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://clicktime.symantec.com/15t5ZvWuZZnqQmrYzNDUa?h=UvwZKu_D0uYE30Nv8hFYkasSpduaBwetcz35pUV4cQ4=&u=https://man.freebsd.org/cgi/man.cgi?query%3Dtimeout

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://clicktime.symantec.com/15t5jauUUoA2EfWQ5V1mp?h=H7AIcCUHsewDyiVTPXCAwaqkbnuXwkxQufl9UOIjbzU=&u=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://clicktime.symantec.com/15t5ekiC2BURpigUXvcdC?h=bAOQjRwh0OPke16ah2Sji_RZI_rP6-sPfjwIZGX3P5o=&u=https://manned.org/

cheers,
Pádraig.
This message is for information purposes only. It is not a recommendation, advice, offer or solicitation to buy or sell a product or service, nor an official confirmation of any transaction. It is directed at persons who are professionals and is intended for the recipient(s) only. It is not directed at retail customers. This message is subject to the terms at: https://www.ib.barclays/disclosures/web-and-email-disclaimer.html. 

For important disclosures, please see: https://www.ib.barclays/disclosures/sales-and-trading-disclaimer.html regarding marketing commentary from Barclays Sales and/or Trading desks, who are active market participants; https://www.ib.barclays/disclosures/barclays-global-markets-disclosures.html regarding our standard terms for Barclays Investment Bank where we trade with you in principal-to-principal wholesale markets transactions; and in respect to Barclays Research, including disclosures relating to specific issuers, see: https://publicresearch.barclays.com.
__________________________________________________________________________________ 
If you are incorporated or operating in Australia, read these important disclosures: https://www.ib.barclays/disclosures/important-disclosures-asia-pacific.html.
__________________________________________________________________________________
For more details about how we use personal information, see our privacy notice: https://www.ib.barclays/disclosures/personal-information-use.html. 
__________________________________________________________________________________

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.