Update man pages with current date and curl/libcurl version number when running maketgz #1058

Closed
wants to merge 5 commits into
from

Projects

None yet

3 participants

@sbrokenshire
Contributor

Added scripts/updatemanpages.pl script to update (with exception of docs/mk-ca-bundle.1 and docs/libcurl/opts/template.3) the man pages with the current date and curl/libcurl version passed to it from maketgz.

Only issue of git picking up that the man pages have changed with the updated .TH section.

(TODO Section 3.1)

@sbrokenshire, thanks for your PR! By analyzing the history of the files in this pull request, we identified @bagder, @captain-caveman2k and @yangtse to be potential reviewers.

Contributor
sbrokenshire commented Oct 7, 2016 edited

Whoops. Hold on with this one. Just noticed the packages don't include the script I've added. :/

Edit: Now fixed.

Owner
bagder commented Oct 7, 2016

My only hesitation about doing this, is that it makes it harder for users who want to run diff to see what changed and this scripts unconditionally updates all man pages disregarding if they are identical or not.

Would it make sense to also mark the page somehow that it was updated (and then we can commit the updates too) so that repeated runs only would update those that actually were changed since the previous run?

@bagder bagder added the documentation label Oct 7, 2016
Contributor

Hmm... having given some thought about it...

What about having a file that has a list of man pages with hashes, compare with the hash in the list with the hash for the actual file. If it has changed then update otherwise leave alone?

Also have the script check for deleted man pages and remove them from the list as needed when it runs.

Owner
bagder commented Oct 12, 2016

Oh hey, I came to think of another approach!

If we assume or require that the user who runs this script does it in the checked-out git repo (which I think is a fair requirement), then we can just check with git if there has been any changes in the given file since the date used in the file! Like this:

  1. Extract $date from the existing $manpage
  2. Check git log --oneline --since="$date" $manpage
  3. if (2) had output, update $manpage to the current date, or possibly to the last update mentioned in (2)

It has the nice upside that anyone can run the script at any time without having to store any additional hashes or similar.

Contributor
sbrokenshire commented Oct 12, 2016 edited

Altered script to use the git repository and update the man pages if needed.

Edit: Eek. A bit too long that commit message. :/

Owner
bagder commented Oct 14, 2016

I played around with this a bit and I've thought about some things:

  1. it quickly becomes obvious that it is much more convenient if the script extracts the date from the last update from git (especially for those man pages that haven't been updated for ages). See the attached patch for a shot at this:
    0001-updatemanpages.pl-set-the-date-found-in-git.patch
    This of course makes a lovely catch-22 since if we push the date update to git, that date will become the new latest change so next run will find the current date because "git log --since [today]" will show today.
  2. Related to the first issue, we don't want maketgz to modify files that are version controlled as that makes it messy. But we can perhaps instead make the script update the files to be included in the tarball without changing the source files. That also solves the date issue in step (1). We already have a system in place to do this automatically, so the only thing the script needs to do differently is to generate the updated files with a ".dist" extension and then the 'make dist' procedure will pick those files instead of the files without that extension (but they are placed into the tarball using the file names without ".dist").

The downside with (2) would be that it doesn't update the date/version in git, but I'm not sure that matters a whole lot.

If there would be anything else, it would be that this script uses different indenting and slightly different code style than other perl scripts in our repo do.

Thoughts?

Contributor

I've applied your patch and made a couple of alterations to the script and it now generates the updated man pages with the ".dist" extension.

At the moment, I have an issue with certain man pages when it runs git log in that it returns data each time when it shouldn't.

If I do LC_TIME=C git log -1 --date="format:%B %d, %Y" --since="August 16, 2016" docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 | grep ^Date: on the command line it returns Date: August 16, 2016 when it shouldn't. It doesn't return any data when the value for --since is set to September 04, 2016 or later.

I'll bring the code style of the script into line with the other perl scripts in the repo and then push those changes to my local repo.

Owner
bagder commented Oct 24, 2016

This starts to look really good. Can you please squash the commits so that we can review the current state (and merge) easier?

Contributor

Great! I'll squash my commits. Can I also group/reword my commits together (as I did a bit of pulling for other changes) when doing the rebase or is that going to cause issues when merging?

Owner
bagder commented Oct 25, 2016

You're free to squash and rearrange them as you want to make the commit(s) look nice and tidy, then you just push -f the cleaned up set to the branch.

Contributor
sbrokenshire commented Oct 25, 2016 edited

I've squashed the commits and pushed them. There are two commits for the Makefile.am files since squashing them doesn't make sense for me.

Edit: Forgot to ask... five commits okay or is one commit prefered?

sbrokenshire added some commits Oct 7, 2016
@sbrokenshire sbrokenshire updatemanpages.pl: Update man pages to use current date and versions
Added script to update man pages to use the current date and
curl/libcurl versions.

updatemanpages.pl has three arrays: list of directories to look in,
list of extensions to process, list of files to exclude from
processing.

Check man page in git repoistory using the date from the existing man
page before updating to avoid updating the man page if no change is
made.

If data is received from the git command then update the man page with
the current date and version otherwise leave alone.

Applied patch from badger to make the date argument optional, change the
git command used, added date argument to processfile subroutine and
print to STDERR if no date is found in a man page.

Added code to process the changed man page into a new man page with
.dist added to the filename to keep the original source files unchanged.
Updated POD documentation to reflect that the date argument optional.

Code style is in line with CODE_STYLE.md.

Directories: docs/ docs/libcurl/ docs/libcurl/opts/ tests/
Extensions: .1 .3
Excluded files: mk-ca-bundle.1 template.3

(TODO Section 3.1)
83d5e18
@sbrokenshire sbrokenshire Makefile.am: Added scripts/updatemanpages.pl to EXTRA_DIST e24db6c
@sbrokenshire sbrokenshire Makefile.am: Remove distribution man pages when running 'make clean' d8d7d47
@sbrokenshire sbrokenshire gitignore: Ignore man page dist files
Ignore man page dist files generated by scripts/updatemanpages.pl
7955d41
@sbrokenshire sbrokenshire maketgz: Run updatemanpages.pl to update man pages
maketgz now runs scripts/updatemanpages.pl to update the man pages .TH
section to use the current date and curl/libcurl version.

(TODO Section 3.1)
c13748b
Contributor

As it's been a while since I've worked on this... is there anything else that should be added?

Owner
bagder commented Mar 7, 2017

Thanks for bringing back my attention to this PR and for your patience. Things look fine and I will merge!

@bagder bagder added a commit that closed this pull request Mar 7, 2017
@sbrokenshire @bagder sbrokenshire + bagder maketgz: Run updatemanpages.pl to update man pages
maketgz now runs scripts/updatemanpages.pl to update the man pages .TH
section to use the current date and curl/libcurl version.

(TODO Section 3.1)

Closes #1058
beff139
@bagder bagder closed this in beff139 Mar 7, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment