include date of build and git hash in documentation

[Roland Haas]

While using subversion the LaTeX sources of the documentation files used $Id$ and $date$ to include the revision and date of the Cactus version for which the documentation was built. Git does not (in any useful manner) support these types of tags, yet it would be good to have some indication of when documentation was built and to which Cactus version it applies.

Pull request:

https://bitbucket.org/cactuscode/cactus/pull-requests/86/include-date-and-git-commit-hash-in-title/diff

uses LaTeX’s \today to include the date the documentation was build (not the date of the last commit the way subversion would have done) and the git hash of the current HEAD (ie the version of Cactus checked out).

It is a pure LaTeX solution so works with (at this point) with both the PDF and the HTML docs when generated through the makefile and also when running pdflatex directly on ReferenceGuide.tex.

[Roland Haas]

Please review.

[Zach Etienne]

Thanks for creating this patch! One comment: Are we sure we want to use \today, and not the date of the git commit id? If the latter is impossible, then maybe we could just make clear that the documentation was generated \today.

[Roland Haas]

The date of the commit would be nicer, unfortunately I do not know of a way to access it without running git. Running git from within LaTeX requires the use of the \write18 primitive which by default (for obvious security reasons) is disabled. So it is not impossible, but tricky. Eg this file roughly demonstrates what would need to be done:

\documentclass{article}

\begin{document}


\immediate\write18{git log --format=\%ad --date=format:\%Y-\%m-\%d -n 1 HEAD >HEAD.date}

\IfFileExists{./HEAD.date}{
  % file found
  commit date \input{HEAD.date}
}{
  % file not found
  documentation build \today
}

\end{document}

which however will not work as expected if you use just pdflatex:

pdflatex git.tex
This is pdfTeX, Version 3.14159265-2.6-1.40.20 (TeX Live 2019/Debian) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
(./git.tex
LaTeX2e <2019-10-01> patch level 3
(/usr/share/texlive/texmf-dist/tex/latex/base/article.cls
Document Class: article 2019/10/25 v1.4k Standard LaTeX document class
(/usr/share/texlive/texmf-dist/tex/latex/base/size10.clo)) (./git.aux)
(./HEAD.date) [1{/var/lib/texmf/fonts/map/pdftex/updmap/pdftex.map}] (./git.aux
) )</usr/share/texlive/texmf-dist/fonts/type1/public/amsfonts/cm/cmr10.pfb>
Output written on git.pdf (1 page, 12383 bytes).
Transcript written on git.log.

which will produce a pdf file that says “documentation build XXX” using \today. On order to actually make this call git you need to pass the ocumentation build option to pdflatex

pdflatex -enable-write18 git.tex

which will produce the desired “commit date XXX” output.

Fragile things about this:

• it requires an extra option to be passed to pdftex. This option differs between TeX distributions and I have no idea what its equivalent for htlatex (for the HTML docs) is: https://linux.die.net/man/1/tex4ht
• it’s fragile as any existing file “HEAD.date” will be used when -enable-write18 is not passed

There’s no way to pipe output from a command into TeX as far as I know (which I find not terribly surprising given how ancient TeX is and how many OS it needs to support).

[Roland Haas]

pdftex actually does have a pipe option: https://tex.stackexchange.com/a/20566 which would significantly simplify things:

\begin{document}

\begingroup
\catcode`\%=11 \input|"git log --format=%ad --date=format:%Y-%m-%d -n 1 HEAD"
\endgroup

% foo bar

\end{document}

but this syntax is also not known to htlatex (and also requires the -enable-write18 command line option)

[Zach Etienne]

Okay, I didn’t realize it would be so complicated. As a workaround I would suggest:

+\cactustitlepage{Reference Manual}{commit \gitrevision{../../.git}}{\today}

be adjusted to

+\cactustitlepage{Reference Manual}{commit \gitrevision{../../.git}}{Documentation compiled on: \today}

or something like this, just to make clear that the date should be associated with the date of documentation compilation, and not the git commit.

[Roland Haas]

Git hash 649eff10 "Cactus: be more explicit what date is shown in the title" of cactus adds explicit text “Documentation compiled on: \today” to make the meaning of the date given explicit. Is this enough to “approve” this pull request on https://bitbucket.org/cactuscode/cactus/pull-requests/86/include-date-and-git-commit-hash-in-title/diff

[Zach Etienne]

Yes, approved. Thanks Roland!

[Roland Haas]

Applied as git hash ac461ced "Cactus: mention \gitrevision macro in thorndoc template" of cactus

[Roland Haas]

I must have been sleeping when I wrote that patch. While git does not provide the full set of $Foo$ tags that svn provides, the one it does provide is $Id$ which resolves to the git hash. So really instead of the overly complex TeX code I could have just as well put $Id$ into the LaTeX file, and added

*.tex ident

to .gitattributes. This is described in https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes#_keyword_expansion and I had even read that page before / while writing the code in the pull request.

[Roland Haas]

The simpler version is here: https://bitbucket.org/cactuscode/cactus/pull-requests/93 with it one checkout git will generate a string like $Id: 57702847595f9879e6d743a66c483770450e3e53 $ wherever $Id$ was found. Before committing / computing diffs it filters out the bits between $Id: and $ so that the file is not constantly changed (this is the same behaviour as svn).

[Roland Haas]

Applied as git hash 7b4c6b4b "Cactus: remove gitrevision LaTeX command" of cactus