Re: [PATCH] docs: other issues with parallel BSD make (was: Re: bug#9245: FreeBSD make in concurrent mode report spurious success in automake-generated tests harness)

[Bob Friesenhahn]

On Tue, 16 Aug 2011, Stefano Lattarini wrote:
> > What is useful information today may become 'lore' in a few years so
> > it would be good to add additional data so that the reader (and
> > documentation maintainer) knows the vintage of the information.
> That's a good point.  Do you think it would be OK to put such information
> only in Texinfo comments for the moment, and then, as a second and later
> step, devise a way to report it in the final manual too?  This second step
> wouldn't be trivial IMHO, since we would need to present such version
> information in a way that is at the same time clear, non-obtrusive and
> complete (mabe we could take a look at how Gnulib does this?).  Finally,
> as a third step, we might try to revisit the existing examples of bugs
> and portability pitfalls, and try to pin-point them to a precise version
> of the system/tools used (in case this version is not already reported).

Perhaps specifying the OS release version the issue was noticed on 
(not all-inclusive) or the date that the issue was noticed would be 
sufficient?  For example "FreeBSD 8.2" rather than "FreeBSD"? or 
"FreeBSD (2011)" rather than "FreeBSD"?  The drawback of this might be 
that someone may assume that the issues are particular to that release 
only.

Hardly anyone reads the raw Texinfo so comments in the Texinfo do not 
seem very useful for the common reader.  If the reader knows that the 
current version of FreeBSD is 12.8, then he might want to check to see 
if claims made about 8.2 (totally defunct by then) are still 
applicable. Comments in the raw Texinfo from the authors regarding 
versions when the issue was checked (or rechecked) would be useful.

Bob
--
Bob Friesenhahn
address@hidden, http://www.simplesystems.org/users/bfriesen/
GraphicsMagick Maintainer,    http://www.GraphicsMagick.org/