bugmake - Bugs: bug #32307, Documentation does not identify...

 
 

bug #32307: Documentation does not identify versions at which new features became available

Submitter:  marvin greenberg <marvingreenberg>
Submitted:  Mon 31 Jan 2011 06:06:42 PM UTC
Votes: 2
 
Severity:  3 - Normal Item Group:  Documentation
Status:  None Privacy:  Public
Assigned to:  None Open/Closed:  Open
Component Version:  3.82 Operating System:  None
Fixed Release:  None Triage Status:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Sat 02 Jul 2011 11:24:37 PM UTC, comment #5: 

I agree this would be extremely useful. Thank you, Luca Fascione

Anonymous
Tue 03 May 2011 03:47:56 PM UTC, comment #4: 

Option 3 is the one that satisfies my requirements best (supporting environments with multiple versions of make).   I don't really see a different requirement for a printed manual, but mixing 3 and 1 seems fine too.

Would you like me to do the work to create a patch on the documentation sources, using approach 3 and 1?

marvin greenberg <marvingreenberg>
Tue 03 May 2011 05:56:23 AM UTC, comment #3: 

A combination of alternatives 1 and 3 seems like it could work well: use footnotes in the printed presentation, and present version information with each feature in the online version.

Python's documentation might serve as a good example of how to render the online documentation.  Functions or other elements which have been recently added or changed are noted as such in a single italicized line at the end of that entity's documentation.  For example, see the first two functions at <http://docs.python.org/library/functools.html>.

Ted Tibbetts <intuited>
Mon 02 May 2011 03:16:49 PM UTC, comment #2: 

The primary intent of the GNU make manual is to be printed into a paper book.  Maybe that's anachronistic now, but I still am not terribly jazzed about the idea of sprinkling little parenthetical comments throughout the text such as "(added in version 3.81)" or whatever.

I can see a few alternatives:

1. Make use of footnotes.  I wouldn't mind having a footnote marker next to a feature that, in the footnote, said "Added in GNU make 3.81" or whatever.  But that might not be so convenient for online reading?

2. Add a new chapter to the GNU make manual that was essentially a shortened, cleaned up version of the NEWS file with new features only.  This would collect all the information in one place.

3. Add the "added in .." text using markup to ensure it's only present in the online formats, not in the printed formats.

Paul D. Smith <psmith>
Group administrator
Thu 31 Mar 2011 12:19:03 AM UTC, comment #1: 

This seems especially important since new features are often added in versions which do not, based on their version numbers, seem particularly significant.  I myself was confused about why .ONESHELL (added in v.3.82) wasn't working.  I guess I should have been reading the docs installed in my system, but it was more convenient to just go to the website to read them.

Ted Tibbetts <intuited>
Mon 31 Jan 2011 06:06:42 PM UTC, original submission:  

Many versions of make are still in circulation, driven by the frameworks (cygwin) and operating systems that include make.  Although it is possible to always upgrade to make.latest, it may not be practical.

Conditionals $(and) and $(or) were added with make 3.81, $(eval) and $(value) with 3.80, various others presumably.

Propose that new features or changes behavior be documented with a small comment like (Conditionals 'and' and 'or' were added at version 3.81).  This is similar to the approach taken by python and java.

Essentially the same information IS available in a source distribution in NEWS, but adding this information to the documentation would make supporting makefiles in the presence of multiple versions of GNU make more natural.

I suppose I should attach a patch.  Maybe I'll do that if there is any support for the idea.

marvin greenberg <marvingreenberg>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by psmith (Posted a comment)
  • -email is unavailable- added by intuited (Posted a comment)
  • -email is unavailable- added by intuited (Voted in favor of this item)
  • -email is unavailable- added by marvingreenberg (Submitted the item)
  •  

    There are 2 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follows 1 latest change.

    Date Changed by Updated Field Previous Value => Replaced by
    2011-03-31 intuited Carbon-Copy- Added intuited

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code