gitinfo2 (4oct14)

git-svn-id: svn://tug.org/texlive/trunk@35310 c570f23f-e606-0410-a88d-b1316a301751

5 files changed, 199 insertions, 76 deletions

diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin b/Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin
index 59764bc60ab..28dafc236a9 100644
--- a/Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin
+++ b/Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin
@@ -1,17 +1,17 @@
 \usepackage[%
-        shash={39d3087},
-        lhash={39d3087dd45197466bfba8587dd4a4a2aa811b18},
+        shash={e981cef},
+        lhash={e981cefe10ce8035de354461cb80c15ee4a39409},
         authname={Brent Longborough},
         authemail={brent+ctancontrib@longborough.org},
-        authsdate={2014-09-04},
-        authidate={2014-09-04 19:40:07 +0100},
-        authudate={1409856007},
+        authsdate={2014-10-03},
+        authidate={2014-10-03 22:57:33 +0100},
+        authudate={1412373453},
         commname={Brent Longborough},
         commemail={brent+ctancontrib@longborough.org},
-        commsdate={2014-09-04},
-        commidate={2014-09-04 19:40:07 +0100},
-        commudate={1409856007},
-        refnames={ (HEAD, tag: 2.0.2, release/2.0.2)},
-        firsttagdescribe={2.0.2},
-        reltag={2.0.2-0-g39d3087}
+        commsdate={2014-10-03},
+        commidate={2014-10-03 22:57:33 +0100},
+        commudate={1412373453},
+        refnames={ (HEAD, tag: 2.0.4, origin/CTAN, CTAN)},
+        firsttagdescribe={2.0.4},
+        reltag={2.0.4-0-ge981cef}
     ]{gitexinfo}
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf
index 8211e4c6073..48d14a354f9 100644
--- a/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf
+++ b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf
diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex
index ca8f62d8c8c..ddc488debc7 100644
--- a/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex
+++ b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex
@@ -31,7 +31,7 @@
 % -----------------------------------------------------
 % End of tweak
 % =====================================================
-\usepackage[nodayofweek]{datetime}
+\usepackage[nodayofweek,level]{datetime}
 \longdate{}
 \usepackage[pcount,grumpy,mark,markifdirty]{gitinfo2}
 \usepackage{tgpagella}
@@ -52,6 +52,16 @@
 \setmarginnotes{0.125\foremargin}{0.75\foremargin}{\onelineskip}
 \setheaderspaces{*}{*}{0.618}
 \checkandfixthelayout[fixed]
+\makepagenote
+\continuousnotenums
+\notepageref
+\foottopagenote
+\renewcommand*{\printpageinnotes}[1]{%
+  (p.\pageref{#1})\space}
+\renewcommand\printpageinnoteshyperref[1]{%
+  (p.\pageref*{#1})\space}
+\renewcommand*{\pagenotesubhead}[3]{%
+  \subsubsection*{#1: #3}}
 \tightlists
 \chapterstyle{bringhurst}
 \pagestyle{empty}
@@ -60,6 +70,7 @@
 \setsecnumdepth{none}
 \newcommand{\bpara}[1]{\par\vspace{\beforeparaskip}\noindent\textbf{#1}\,}
 \newcommand{\rpara}[1]{\par\noindent\textbf{#1}\,}
+\newcommand{\dark}[1]{\texttt\textbf{{#1}}}
 \newcommand{\sfit}[1]{\textit{#1}}
 \newcommand{\git}{\sfit{git}}
 \newcommand*{\emailat}{@}
@@ -153,32 +164,32 @@ read `\titleref{ch:setup}' later.
 \clearpage
 \section{Why a new package?}
 
-The improvements to \opname\ version~2 mean that 
-existing repositories would not work; 
-so if I just dumped a new version of \opname\  
-on to CTAN, anyone who updated \opname\ 
+The improvements to \opname\ version~2 mean that
+existing repositories would not work;
+so if I just dumped a new version of \opname\
+on to CTAN, anyone who updated \opname\
 would need to migrate all their active repositories
 before they could resume work.
 
-So in order to avoid the rebukes that would follow, 
-I have changed the package name to \tpname, 
+So in order to avoid the rebukes that would follow,
+I have changed the package name to \tpname,
 and the inner package name from \sfit{gitsetinfo}
 to \sfit{gitexinfo}.
 
-\opname\ is now informally deprecated, 
+\opname\ is now informally deprecated,
 and the first reply to any bug reports or feature requests
 will be `try \tpname'.
-Of course, I will support \tpname\ itself 
-to the best of my somewhat limited ability. 
+Of course, I will support \tpname\ itself
+to the best of my somewhat limited ability.
 
-For obvious reasons, \emph{do not try} 
+For obvious reasons, \emph{do not try}
 to use both packages in the same repository;
 for a new repository, use \tpname,
 and for an old one, either leave it alone with \opname,
 or migrate it to \tpname.
 
-To the administrators of CTAN, 
-I'm sorry I caused you this clutter 
+To the administrators of CTAN,
+I'm sorry I caused you this clutter
 by not getting it right the first time.
 
 % -----------------------------------------------------
@@ -306,7 +317,7 @@ since whatever tag is found is used as-is.
 \label{ch:using}
 Once you've set up your \git hooks, and done your first commit,
 merge, or checkout to drive them,
-you can start incorporating the metadata into your document, 
+you can start incorporating the metadata into your document,
 by loading the \tpname\ package in the usual way:\\[0.5\baselineskip]
 \texttt{\textbackslash usepackage[$<options>$]\{gitinfo2\}}
 
@@ -328,8 +339,8 @@ this warning becomes an error, and processing stops.
 
 \item[\texttt{missing=\textit{text}, notags=\textit{text}, dirty=\textit{text}}]
 These three options allow you to tailor the default text used by \tpname\ when
-metadata is missing `(None)', 
-the branch head has no tags `(None)', 
+metadata is missing `(None)',
+the branch head has no tags `(None)',
 and the working copy has uncommitted changes `(*)'.
 For example:
 
@@ -354,25 +365,25 @@ deeper in your repository tree, you can extend this limit with, say,
 \clearpage
 \subsection{Options for watermarking}
 
-These options allow you to place a watermark of \git\ metadata, 
+These options allow you to place a watermark of \git\ metadata,
 at the bottom of the paper, conditionally or unconditionally
 
 \begin{description}
 
 \item[mark]
-This option causes \tpname\ to generate a watermark, 
+This option causes \tpname\ to generate a watermark,
 centred at the bottom of each sheet,
-containing `useful' \git\ metadata. 
+containing `useful' \git\ metadata.
 The watermark is always added.
 
 \item[markifdraft]
 This option is like {\ttfamily\bfseries mark,}
 but only activates the watermark if the document is being processed
-with the {\ttfamily\bfseries draft} option. 
+with the {\ttfamily\bfseries draft} option.
 
 \item[markifdirty]
 This option is like {\ttfamily\bfseries mark,}
-but only activates the watermark if the last commit or checkout left 
+but only activates the watermark if the last commit or checkout left
 uncommitted changes in the repository.
 
 \item[marknotags]
@@ -383,10 +394,11 @@ add this option to the package options.
 
 \item[raisemark=\textit{vertical space}]
 By default, \tpname\ sets the bottom line of the watermark
-at 1.5 baseline 
-skips\footnote{\texttt{1.5\textbackslash{}baselineskip}, an admittedly arbitrary value, chosen for my Canon printer.} 
+at 1.5 baseline
+skips\footnote{\texttt{1.5\textbackslash{}baselineskip},
+an admittedly arbitrary value, chosen for my Canon printer.}
 above the bottom of the paper.
-If you prefer something different, 
+If you prefer something different,
 you can specify it here.
 For example:
 
@@ -398,14 +410,14 @@ For example:
 
 
 \item[draft]
-This option \emph{should not be used;} it only exists to `capture' the 
+This option \emph{should not be used;} it only exists to `capture' the
 {\ttfamily\bfseries draft} option from the document class definition.
 
 \end{description}
 
 \subsection{Options for \sfit{memoir} users}
 
-For more about these options, 
+For more about these options,
 please read
 %The use of these options is described in more detail in
 `\titleref{sect:memuser}'
@@ -454,7 +466,7 @@ Here they are:
 
 \item[gitDirty]
     If the last commit or checkout left uncommitted changes in the working tree,
-    the default or specified value of the \texttt{dirty} package option; 
+    the default or specified value of the \texttt{dirty} package option;
     otherwise empty.
 
 \item[gitAbbrevHash]
@@ -592,7 +604,7 @@ Here are the new commands in Version~2:
 
 \item[gitDescribe]
     The raw output from the git-describe command for the last release tag
-    reachable from the current \textsc{head}, including tag name, commit offset, 
+    reachable from the current \textsc{head}, including tag name, commit offset,
     short hash, and a dirty flag.
     Please see git-describe for more information.
     Example: \textit{\gitDescribe}
@@ -609,22 +621,22 @@ by redefining one or more of the following commands.
 \begin{description}
 
 \item[gitMark]
-    Contains the text of the watermark. 
+    Contains the text of the watermark.
     Output from the default definition can be seen
     below the footer
     at the bottom of this page.
-    The definition 
-    (here split onto four lines to fit) 
+    The definition
+    (here split onto four lines to fit)
     is:
 
 \begin{verbatim}
-Branch: \gitBranch\,@\,\gitAbbrevHash{} 
-\textbullet{} 
+Branch: \gitBranch\,@\,\gitAbbrevHash{}
+\textbullet{}
 Release:\gitReln{} (\gitAuthorDate)\\
 Head tags: \gitTags
 \end{verbatim}
-You can tailor this by redefining \verb!\gitMark!. 
-For example: 
+You can tailor this by redefining \verb!\gitMark!.
+For example:
 
 \begin{verbatim}
 \renewcommand{\gitMark}{\gitHash\hfill\gitRel}
@@ -637,17 +649,17 @@ For example:
 \begin{verbatim}
 \color{gray}\small\sffamily
 \end{verbatim}
-You can tailor this by redefining \verb!\gitMarkFormat!. For example: 
+You can tailor this by redefining \verb!\gitMarkFormat!. For example:
 
 \begin{verbatim}
 \renewcommand{\gitMarkFormat}{\color(red)\ttfamily}
 \end{verbatim}
 
 \item[gitMarkPref]
-    Contains the text of the watermark prefix, 
+    Contains the text of the watermark prefix,
     which depends on the reason the document is being watermarked.
     The default values are \sfit{[Dirty]}, \sfit{[Draft]}, or \sfit{[git]}.
-    You can tailor this by redefining \verb!\gitMarkPref!. For example: 
+    You can tailor this by redefining \verb!\gitMarkPref!. For example:
 
 \begin{verbatim}
 \renewcommand{\gitMarkPref}{[Pending review]}
@@ -657,11 +669,35 @@ You can tailor this by redefining \verb!\gitMarkFormat!. For example:
 
 % - - - - - - - - - - - - - - - - - - - - - - - - - - -
 \clearpage
+\section{Handling \TeX-hostile e-mail addresses}
+\label{sect:emailuser}
+Occasionally, a repository will contain `\TeX-hostile'
+e-mail addresses such as \verb!my_name@somewhere.net!.
+As a result, using the \dark{gitAuthorEmail}
+or \dark{gitCommitterEmail} commands can cause errors.
+
+\tpname\ provides an e-mail wrapping command,
+\verb!\gitWrapEmail!, to allow you to tailor your use
+of email addresses. Its default definition does nothing:
+\begin{verbatim}
+\newcommand{\gitWrapEmail}[1]{#1}
+\end{verbatim}
+You can tailor this by redefining \verb!\gitWrapEmail!.
+For example, a number of packages
+(\sfit{hyperref} is one) provide a \verb!\url! command
+which provides the necessary protection.
+Using such a package (independently of \tpname),
+you can redefine the \tpname\ wrapper in this way:
+\begin{verbatim}
+\renewcommand{\gitWrapEmail}[1]{\url{#1}}
+\end{verbatim}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
 \section{For \sfit{memoir} users}
 \label{sect:memuser}
 If you use \sfit{memoir}, \tpname\ provides you with
 three new pagestyles, based on
-\sfit{plain},\sfit{ruled}, and \sfit{headings}.
+\sfit{plain}, \sfit{ruled}, and \sfit{headings}.
 The new pagestyles are called
 \sfit{giplain}, \sfit{giruled}, and \sfit{giheadings}.
 
@@ -689,37 +725,113 @@ Note that, in contrast to version 1 of \tpname,
 version 2 no longer modifies the existing page styles.
 If you wish to use this facility,
 you must now select
-the appropriate \sfit{gi\textellipsis} page style 
+the appropriate \sfit{gi\textellipsis} page style
 explicitly.
 
-You can see an example in the footer of this page, 
+You can see an example in the footer of this page,
 above the \tpname\ watermark.
+
 % - - - - - - - - - - - - - - - - - - - - - - - - - - -
 \section{For \sfit{datetime} users}
 \label{sect:dtuser}
-If you use Nicola Talbot's excellent \sfit{datetime} package, 
-\tpname\ creates a new date object named \sfit{gitdate}, 
+If you use Nicola Talbot's excellent \sfit{datetime} package,
+\tpname\ copies the value of the tag {\ttfamily\bfseries gitAuthorDate}
+as a new date object named \sfit{gitdate},
 which you can then refer to with other \sfit{datetime}
-functions. 
+functions.
 
 Please refer to the \sfit{datetime} manual for
-further details, 
-especially in the section entitled `Saving Dates'. 
+further details,
+especially in the section entitled `Saving Dates'.
+
+If you use it, you must load \sfit{datetime}
+before you load \tpname.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Notes on the sequence of events}
+\label{sect:seqeve}
+Users of \tpname\ (including me) are frequently surprised
+by what appear to be incorrect results in their output,%
+\footnote{Most frequent are `wrong tag' and `falsely flagged as dirty'}
+but are determined in fact by the precise sequence of operations
+on a working copy.
+
+As it's impossible to foresee every possible workflow,
+what follows is a sequence of steps of a simple workflow
+which will serve as an example to help users
+to understand what is happening, and to avoid it.
+
+The example repository manages two main files:
+\sfit{abc.tex} and its output file, \sfit{abc.pdf}.%
+\footnote{Although derived files are often excluded from version control,
+the .pdf file in this case might need to be archived ---
+think of versions of a proposal, for example.}
+Intuitively, the overall sequence of one update \& release cycle
+might be like this:
+
+\begin{enumerate}
+\item Edit \sfit{abc.tex}, (perhaps) commit intermediate changes,
+format the output into \sfit{abc.pdf}, and
+check and repeat until ready for release;
+\item \label{wf:tex} Commit the release version of \sfit{abc.tex};
+\item \label{wf:tag} Tag the release;
+\item \label{wf:git} (Missing step);
+\item \label{wf:pdf} Format the release version of \sfit{abc.pdf}; and
+\item Commit the release version of \sfit{abc.pdf}.
+\end{enumerate}
 
-If you use it, you must load \sfit{datetime} 
-before you load \tpname. 
+\noindent For reasons that I hope will become obvious,
+that doesn't work.
+The \git\ metadata is extracted and stored at step (\ref{wf:tex}).
+At that point, the release tag doesn't yet exist,
+and the working copy is dirty,
+since \sfit{abc.pdf} has been regenerated, and has changed
+since the last recorded version.
+
+It's simple to fix; all we have to do is
+ensure the working copy is clean and regenerate
+the saved metadata (now with correct tag information).
+Here's the missing step, kept, perhaps, somewhere in a \sfit{makefile:}
+
+\begin{enumerate}
+\item[\ref{wf:git}.] \texttt{git checkout abc.pdf}
+\end{enumerate}
+
+\noindent This will revert the .pdf file to its repository version,
+and then regenerate the stored metadata,
+including the release tag.
+Step (\ref{wf:pdf}) will now produce output showing the release tag
+and a clean working copy.
 % -----------------------------------------------------
 \chapter{Etc}
 \section{Release notes}
 
-\rpara{R2.0.2: 2014-09-04 -- Mostly cosmetic} 
+\rpara{R2.0.4: 2014-10-03 -- Fixes and documentation improvements}
+\begin{itemize}
+\item More robust \git\ hooks,
+for improved detection of dirty working copies
+\item A new section, \textit{\titleref{sect:seqeve}},
+to help with doing things in the right order
+\item Other minor improvements to the manual
+\end{itemize}
+
+\rpara{R2.0.3: 2014-09-05 -- Handle hostile e-mail addresses}
+\begin{itemize}
+\item Provide an e-mail address wrapper command,
+to allow users to tailor protection
+against `\_' and other characters in email addresses.
+\item This release was not shipped to \textsc{Ctan}
+\end{itemize}
+
+\rpara{R2.0.2: 2014-09-04 -- Mostly cosmetic}
 \begin{itemize}
 \item Fix packaging problems for \textsc{Ctan} and \TeX{}~Live
 \item Improve appearance of watermark
 \item Improve documentation: correct file references. remove gibberish, extend acknowledgments
 \end{itemize}
 
-\section{Acknowledgements \& dependencies}
+\clearpage
+\section{Acknowledgements}
 
 The \href{http://tex.stackexchange.com}{\TeX.SE community}
 has been a constant source of help, inspiration, and amazement.
@@ -728,8 +840,8 @@ In particular, I'd like to thank
 who rescued me from the jaws of the TeX parser by explaining
 \textbackslash expandafter.
 
-I's also like to register my thanks to the owners of the packages on which
-\tpname\ depends: eso-pic, etoolbox, kvoptions, and xstring.
+I'd also like to register my thanks to the owners of the packages on which
+\tpname\ depends: datetime, eso-pic, etoolbox, kvoptions, and xstring.
 
 Many people have written to me kindly
 to point out some of the defects in \opname, and to offer code.
@@ -740,19 +852,20 @@ In some cases, I have not taken up suggestions other than as food for thought,
 in others used the code or suggestions directly, and,
 in yet others, adapted.
 I thank you all, especially for stimulating my thought processes,
-and thus, hopefully, 
+and thus, hopefully,
 helping to make \tpname\ a whole lot better than \opname.
 
 I think I owe a special mention, both for ideas and code,
 to Clea Rees, Jörg Weber, and Kai Mindermann
 for improving the handling of \git\ references;
 to Jörg Weber for watermarking;
-and to Michael Rans and Ross Vandegrift for 
+and to Michael Rans and Ross Vandegrift for
 the deduplication of \metaname.
 
 My sincere thanks, too, to
 Adrian Burd,
 Felix Wenger,
+ivokabadshow (on GitHub),
 Johannes Hoetzer,
 Martin W Leidig,
 Mikko Korpela,
@@ -767,17 +880,19 @@ reduce my incompetence with \texttt{ctanify}.
 And, of course, for \TeX{} Live and everything else.
 
 Finally, but by no means least,
-my thanks to the \textsc{Ctan} elves, and their dæmons, 
-particularly, in my case, 
+my thanks to the \textsc{Ctan} elves, and their dæmons,
+particularly, in my case,
 Robin Fairbairns, Manfred Lotz, and Petra Rübe-Pugliese,
-for their infinite patience and unstinting 
+for their infinite patience and unstinting
 dedication to the \TeX\ community.
 
 The failings, of course, I claim for my self.
-Among these, a major one appears to be my incapacity 
-decently to package this stuff for 
+Among these, a major one appears to be my incapacity
+decently to package this stuff for
 \textsc{Ctan} and \TeX{}~Live.
-Now that I have finally built a Makefile, \emph{either} this will improve \emph{or} I now have two problems. 
+Now that I have finally built a Makefile,
+\emph{either} this will improve \emph{or}
+I now have \emph{two} problems.
 % - - - - - - - - - - - - - - - - - - - - - - - - - - -
 \clearpage
 \section{Copyright \& licence}
@@ -792,7 +907,7 @@ of this license, or (at your option) any later version.
 The latest version of this license can be found
 at the \LaTeX\ Project website,%
 \footnote{(\url{http://www.latex-project.org/lppl.txt})}
-and version 1.3 or later is part of all recent distributions of 
+and version 1.3 or later is part of all recent distributions of
 \LaTeX.
 
 This work has the LPPL maintenance status `maintained';
@@ -800,7 +915,8 @@ the Current Maintainer of this work is Brent Longborough.
 
 This work consists of the files
 gitinfo2.sty, gitexinfo.sty, gitinfo2.tex, gitinfo2.pdf,
-post-xxx-sample.txt, and gitPseudoHeadInfo.gin.
+gitinfotest.tex, post-xxx-sample.txt,
+and gitPseudoHeadInfo.gin.
 
 % - - - - - - - - - - - - - - - - - - - - - - - - - - -
 \section{From the author}
@@ -813,4 +929,7 @@ Brent Longborough\\[\baselineskip]
 \textsf{brent+ctancontrib (bei) longborough (punkt) org}\\
 and at \href{http://tex.stackexchange.com/users/344/brent-longborough}{\TeX.SE}
 % -----------------------------------------------------
+\clearpage
+\raggedright
+\printpagenotes
 \end{document}
diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex b/Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex
index 4cc0bcbac3f..a01310fc2e3 100644
--- a/Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex
+++ b/Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex
@@ -13,6 +13,8 @@
 % End of tweak
 % =====================================================
 \usepackage[missing={(Oh my!)},dirty={Oh no!},markifdirty,marknotags]{gitinfo2}
+\usepackage{hyperref}
+\renewcommand{\gitWrapEmail}[1]{\url{#1}}
 \frenchspacing
 \begin{document}
 
@@ -45,4 +47,6 @@
 
 !\gitRoff ! Roff
 
+!\gitCommitterEmail! C.Email
+
 \end{document}
diff --git a/Master/texmf-dist/doc/latex/gitinfo2/post-xxx-sample.txt b/Master/texmf-dist/doc/latex/gitinfo2/post-xxx-sample.txt
index 76e6a263454..df0730af47b 100644
--- a/Master/texmf-dist/doc/latex/gitinfo2/post-xxx-sample.txt
+++ b/Master/texmf-dist/doc/latex/gitinfo2/post-xxx-sample.txt
@@ -6,11 +6,11 @@
 # Post-{commit,checkout,merge} hook for the gitinfo2 package
 #
 # Get the first tag found in the history from the current HEAD
-FIRSTTAG=$(git describe --tags --dirty='-*' 2>/dev/null)
+FIRSTTAG=$(git describe --tags --always --dirty='-*' 2>/dev/null)
 # Get the first tag in history that looks like a Release
-RELTAG=$(git describe --tags --long --dirty='-*' --match '[0-9]*.*' 2>/dev/null)
+RELTAG=$(git describe --tags --long --always --dirty='-*' --match '[0-9]*.*' 2>/dev/null)
 # Hoover up the metadata
-git --no-pager log -1 --date=short \
+git --no-pager log -1 --date=short --decorate=short \
     --pretty=format:"\usepackage[%
         shash={%h},
         lhash={%H},