include date of build and git hash in documentation

Create issue
Issue #2330 resolved
Roland Haas created an issue

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.

Comments (8)

  1. 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.

  2. Roland Haas reporter

    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).

  3. Roland Haas reporter

    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)

  4. 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.

  5. Log in to comment