summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/gitinfo2
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-10-04 22:51:58 +0000
committerKarl Berry <karl@freefriends.org>2014-10-04 22:51:58 +0000
commit0f9f9b8b3bac411ca6aaaea921af2538e5664ecf (patch)
tree6711cf09dfe0be6c8bf1e27ad6b0141b57193d7b /Master/texmf-dist/doc/latex/gitinfo2
parent47f07d898776ffc6befb1355e16e81e00f906daa (diff)
gitinfo2 (4oct14)
git-svn-id: svn://tug.org/texlive/trunk@35310 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/gitinfo2')
-rw-r--r--Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin22
-rw-r--r--Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdfbin115923 -> 123452 bytes
-rw-r--r--Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex243
-rw-r--r--Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex4
-rw-r--r--Master/texmf-dist/doc/latex/gitinfo2/post-xxx-sample.txt6
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
Binary files differ
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},