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

 
 

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

Submitted by:  marvin greenberg <marvingreenberg>
Submitted on:  Mon Jan 31 18:06:42 2011  
Votes:  2  
 
Severity: 3 - NormalItem Group: Documentation
Status: NonePrivacy: Public
Assigned to: NoneOpen/Closed: Open
Component Version: 3.82Operating System: None
Fixed Release: NoneTriage Status: None

Add a New Comment (Rich MarkupRich Markup):
   

You are not logged in

Please log in, so followups can be emailed to you.

 

Sat Jul 2 23:24:37 2011, comment #5:

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

Anonymous
Tue May 3 15:47:56 2011, 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 May 3 05:56:23 2011, 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 May 2 15:16:49 2011, 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>
Project Administrator
Thu Mar 31 00:19:03 2011, 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 Jan 31 18:06:42 2011, 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 File(s):
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

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

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 2 encouragements so far.

    Only logged-in users can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follows 1 latest change.

    Date Changed By Updated Field Previous Value => Replaced By
    Thu Mar 31 00:10:25 2011intuitedCarbon-Copy-=>Added intuited

    Back to the top


    Powered by Savane 3.1-cleanup