taskGNU Astronomy Utilities - Tasks: task #13897, Revision history for the manual

 
 

You are not allowed to post comments on this tracker with your current authentication level.

task #13897: Revision history for the manual

Submitted by:  Mohammad Akhlaghi <makhlaghi>
Submitted on:  Wed 17 Feb 2016 07:08:35 AM UTC  
 
Should Start On: Tue 16 Feb 2016 03:00:00 PM UTCShould be Finished on: Tue 16 Feb 2016 03:00:00 PM UTC
Category: BookPriority: 5 - Normal
Item Group: EnhancementStatus: Postponed
Privacy: PublicPercent Complete: 0%
Assigned to: NoneOpen/Closed: Open
Effort: 0.00

Sun 01 May 2016 06:56:09 AM UTC, comment #2:

Now that I read the initial post again, I see that it contains too many "should"s and apparently doesn't allow any flexibility! This task was not intended to be an order (to my self or others), it was meant to be a suggestion and open to discussion so we can implement it later after some thought. So sorry for the bad tone.

The file keeping the variable information is indeed not tracked in my initial idea. The basic implementation I had in mind was something like how we use doc/findversion.sh. In that script, the version numbers are read from the main.h file in all the utilities to generate an output (which is read by Texinfo). We keep a history of (or track) doc/findversion.sh, but we don't keep a history of its output (since it isn't a hand-written file).

The manual is often created after all the commits have been done and none of the manual output formats are version controlled. Let's assume the script is called genrevhistory.sh. We can add the output of this script as a dependency for gnuastro.texi in doc/Makefile.am (just like findversions.sh). So as you mentioned, adding the hash, or date or any other name/number can be easily done without tracking it.

I agree that the hash is not very useful within the documentation, and the important thing is the date. The main thing I was thinking about was to help an interested person find the associated commit easily. But now that I think more about it, I agree with your point: it just adds to complexity (for a reader who doesn't know what a hash or version control is). If someone is interested in the commit, the date and commit title/details are enough to allow them to find the commit easily. So we can ignore the hash as you suggested. Thank you.

Mohammad Akhlaghi <makhlaghi>
Project Administrator
Sat 30 Apr 2016 02:09:54 PM UTC, comment #1:

I don't know if you plan putting the file holding the hash under revision control. If so, it's pretty tricky to add the hash of a git commit in a tracked file before the commit itself, and the hash is arguably of little use if someone quickly wants to know when the manual was written. I would use instead a timestamp (with Emacs it's super easy to do that automatically, see https://www.emacswiki.org/emacs/TimeStamp).

If instead you plan to put the has into a non tracked file, both the hash and the timestamp can be easily used.

Mosè Giordano <giordano>
Project Member
Wed 17 Feb 2016 07:08:35 AM UTC, original submission:

The Gnuastro manual is going to be used as a reference and while its primary purpose is to be for new readers, probably previous readers will also be accessing it a lot. As explained in the developing chapter, the documentaion is written in such a way that any change will be completely invisible (or fully blended in so a first time reader has no idea).

To help with people who have read the manual once before and want to see what has changed, we should add some thing like an "Update Record", or "Rivision History" which has a list of all the changes. Using git, we can make such a table automatically, to include the names of people who made the change along with the commit hash, date, and the title of the commit message as an explanation. It might also be useful to say which sections where changed, but section numbers are not stable and might change (with the addition of new sections before them). Also it might not be easy to get the section name from the git search.

Also the commit hash of the commit should be included in the copyright message and the copyright year should be changed into a variable to be automatic.

All of these can be done with a relatively simple script using Texinfo variables.

Mohammad Akhlaghi <makhlaghi>
Project Administrator

 

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 giordano (Posted a comment)
  • -unavailable- added by makhlaghi (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 0 encouragements so far.

    Only logged-in users can vote.

     

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

     

     

    No Changes Have Been Made to This Item

    Back to the top


    Powered by Savane 3.1-cleanup1