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 31 Jan 2011 06:06:42 PM UTC  
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 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>
Project 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 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 31 Mar 2011 12:10:25 AM UTCintuitedCarbon-Copy-=>Added intuited

    Back to the top


    Powered by Savane 3.1-cleanup