GNU 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
Submitter: | Mohammad Akhlaghi <makhlaghi> | ||
Submitted: | Wed 17 Feb 2016 07:08:35 AM UTC | ||
Should Start On: | Tue 16 Feb 2016 03:00:00 PM UTC | Should be Finished on: | Tue 16 Feb 2016 03:00:00 PM UTC |
Category: | Book | Priority: | 5 - Normal |
Item Group: | Enhancement | Status: | Postponed |
Privacy: | Public | Percent Complete: | 0% |
Assigned to: | None | Open/Closed: | Open |
Effort: | 0.00 |
Sun 01 May 2016 06:56:09 AM UTC, comment #2: |
Mohammad Akhlaghi <makhlaghi>![]() |
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).
|
Mosè Giordano <giordano>![]() |
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).
|
Mohammad Akhlaghi <makhlaghi>![]() |
No files currently attached
Depends on the following items: None found
Items that depend on this one: None found
There are 0 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.
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.