summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gitinfo/gitinfo.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/gitinfo/gitinfo.tex')
-rw-r--r--macros/latex/contrib/gitinfo/gitinfo.tex408
1 files changed, 408 insertions, 0 deletions
diff --git a/macros/latex/contrib/gitinfo/gitinfo.tex b/macros/latex/contrib/gitinfo/gitinfo.tex
new file mode 100644
index 0000000000..af6f90764c
--- /dev/null
+++ b/macros/latex/contrib/gitinfo/gitinfo.tex
@@ -0,0 +1,408 @@
+% gitinfo.tex
+% Copyright 2011 Brent Longborough
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+% The Current Maintainer of this work is Brent Longborough.
+%
+% This work consists of these files:
+% gitinfo.sty, gitsetinfo.sty, gitinfo.tex, gitinfo.pdf,
+% post-git-sample.txt, and gitHeadInfo.gin
+% -----------------------------------------------------
+\documentclass[a4paper,12pt,twoside,openany]{memoir}
+\usepackage[pcount,footinfo,grumpy]{gitinfo}
+\usepackage{tgpagella}
+\usepackage{tgadventor}
+\usepackage{fontspec}
+\defaultfontfeatures{Ligatures=TeX}
+\setmainfont[Numbers={Proportional,OldStyle}]{TeX Gyre Pagella}
+\setsansfont[Numbers={Proportional,OldStyle}]{TeX Gyre Adventor}
+\setmonofont{Consolas}
+\setulmarginsandblock{0.11111\paperwidth}{0.22222\paperwidth}{*}
+\setlrmarginsandblock{0.11111\paperwidth}{0.22222\paperwidth}{*}
+\setheadfoot{1.2\baselineskip}{0.0849\paperwidth}
+\setmarginnotes{0.125\foremargin}{0.75\foremargin}{\onelineskip}
+\setheaderspaces{*}{*}{0.618}
+\checkandfixthelayout[fixed]
+\tightlists
+\chapterstyle{bringhurst}
+\pagestyle{ruled}
+\settocdepth{section}
+\setsecnumdepth{none}
+\newcommand{\sfit}[1]{\textit{#1}}
+\newcommand{\git}{\sfit{git}}
+\newcommand{\tpname}{\sfit{gitinfo}}
+\newcommand{\tpfname}{\textsf{gitinfo.sty}}
+\newcommand{\ginname}{gitHeadInfo.gin}
+\newcommand{\metaname}{\texttt{\ginname}}
+% -----------------------------------------------------
+\usepackage[%
+ bookmarksnumbered,
+ bookmarksopen,
+ linktocpage,
+ ]{hyperref}
+\hypersetup{
+ pdfauthor={Brent Longborough},
+ pdftitle={The gitinfo package: git metadata for LaTeX},
+ pdfkeywords={git;metadata;dvcs},
+}
+\begin{document}
+% -----------------------------------------------------
+\title{%
+ \Huge \tpfname\\[2ex]%
+ \Large A package for accessing metadata\\from the \git\ \textsc{dvcs}
+ }
+\author{Brent Longborough}
+\date{29th August, 2011}
+\maketitle
+
+{\centering
+Version:\gitVtagn\\
+}
+%\vspace*{2\baselineskip}
+% -----------------------------------------------------
+\begingroup
+\aliaspagestyle{chapter}{empty}
+\setlength{\afterchapskip}{20pt}
+\let\clearpage\relax
+\let\chaptitlefont\Large\bfseries
+\vspace*{5\baselineskip}
+\tableofcontents*
+\clearpage
+\endgroup
+% -----------------------------------------------------
+\chapter{Introduction}
+More and more, writers are using version control systems
+to manage the progress of their works.
+One popular distributed version control system commonly used today
+is \git.
+
+Among other blessings, \git provides
+some useful metadata concerning the history of the developers'
+work, and, in particular, about the current state of that work.
+
+\tpname\ allows writers to incorporate some of this metadata
+into their documents, to show from which point in their development
+a given formatted copy was produced.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{How \tpname\ works}
+\begin{enumerate}
+\item Whenever you commit work or check out a branch in \git,
+\git\ executes a \textit{post-commit} or \textit{post-checkout hook}.
+\item The \tpname\ package includes a sample hook
+(placed in your \git\ hooks directory),
+which extracts metadata from \git\ and writes it to a \TeX\ file,
+named \metaname\ (`gin' for \textbf{g}it \textbf{in}fo).
+\item When you format your document, \tpname\ reads
+\metaname\ and stores the metadada
+in a series of \LaTeX\ commands.
+\item You may use these commands to insert
+the metadata you need at any point in the document.
+\end{enumerate}
+
+It is important to note that \tpname\ reads the metadata
+with the equivalent of \texttt{\textbackslash input\{./\ginname\}}.
+This is necessary to avoid possible future confusion in a
+\TeX distribution where more than one package includes its
+metadata in this way; but it requires that for every document which
+uses \tpname, a \metaname\ must be generated in the same directory.
+
+If you actually want to use \tpname, then please read on.
+But you may just be reading this to see whether it will be useful;
+in this case,
+please skip the next chapter and go on to (Using the package)
+on page \pageref{ch:using}.
+If you like what you see, you can come back to
+read (Setup) later.
+% -----------------------------------------------------
+\chapter{Setup}
+\tpname\ will be installed by your favourite package or distribution manager,
+but before you can start to use it,
+you need to configure each of your \git\ working copies
+by setting up hooks to capture the metadata.
+Every document in your working copy that uses \tpname\
+will need a copy of \metaname\ in the same directory.
+
+These copies can be generated by the \git\ post-hooks,
+which need to be configured once, at the start.
+
+If you're familiar with tweaking \git, you can probably work it out for yourself.
+If not, I suggest you follow these steps:
+
+\begin{enumerate}
+
+\item First, you need a \git\ repository and working tree.
+For this example, let's suppose that the root of the working tree is in
+\texttt{\textasciitilde/compsci}
+
+\item Copy the file \texttt{post-xxx-sample.txt} as \texttt{post-checkout}
+into the \git\ hooks directory in your working copy.
+In our example case, you should end up with a file called
+\texttt{\textasciitilde/compsci/.git/hooks/post-checkout}
+
+\item With your favourite editor, edit the file you have just created.
+Very near the start of the file, you will see two lines:
+\vspace{0.5\baselineskip}
+
+\noindent\texttt{prefixes=". test docs"\\
+prefixes="."}
+\vspace{0.5\baselineskip}
+
+The first line is an example of how you might configure for multiple
+copies of \metaname; the second is the default,
+and means ``the working copy root''.
+
+If all of your documents will be kept in the root of the working copy,
+you may leave this file alone.
+If not, you should delete the line \verb!prefixes="."!, and edit
+the other line to include the paths, relative to the working copy root,
+where the documents that need access to \tpname\ are kept.
+
+Suppose, for example, that you have a project called `compsci'.
+Your working copy is \texttt{\textasciitilde/compsci}
+with two paths containing documents,
+\texttt{\textasciitilde/compsci/docs/essays} and
+\texttt{\textasciitilde/compsci/docs/reference}.
+Then you might set up the prefixes like this:
+\vspace{0.5\baselineskip}
+
+\noindent\texttt{prefixes="docs/essays docs/reference"}
+\vspace{0.5\baselineskip}
+
+which will cause copies of the metadata to be saved in
+just those two directories.
+In this example, it will not be accessible to documents
+kept in the working copy's root
+(designated by ``.'', omitted in this case),
+
+\item Test your setup with ``git checkout master''
+(or another suitable branch name).
+This should generate copies of \metaname\ in the directories
+you intended.
+
+\item Now make two more copies of this file in the same directory (\texttt{hooks}), calling them
+\texttt{post-commit} and \texttt{post-merge}, and you're done.
+\end{enumerate}
+% -----------------------------------------------------
+\chapter{Using the package}
+\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.
+
+The \tpname\ package is loaded in the usual way:\\[0.5\baselineskip]
+\texttt{\textbackslash usepackage[$<options>$]\{gitinfo\}}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Package options}
+
+The following options are available:\\[0.5\baselineskip]
+
+\noindent
+\begin{tabularx}{\textwidth}{@{}>{\ttfamily\bfseries}lX@{}}
+grumpy&
+By default, If \tpname\ can't find \metaname\ (the metadata file),
+it will set all the metadata to a common value, ``(None)'',
+issue a package warning, and carry on.
+If the \texttt{grumpy} option is used,
+this warning becomes an error, and processing stops.
+\\
+\texttt{missing=\textit{text}}&
+If \tpname\ can't find \metaname (the metadata file),
+it will normally set all the metadata to a default common value, ``(None)''.
+If you wish, you can change this value to something else with, say
+\texttt{missing=Help!} or \texttt{missing=\{What a mess\}}.
+
+If you have complex needs, as in the second example,
+don't forget to enclose your text in \{\}s.
+\\
+footinfo&
+For \sfit{memoir} users, \tpname\ will set certain items of metadata into
+some memoir page footer categories,
+provided that (a) the memoir package is loaded,
+and (b) this option is given.
+
+No warning is given, and no action taken,
+if this parameter is used with another document class.
+More detail is given below (For \textit{memoir} users).
+\\
+pcount&
+For \sfit{memoir} users, this option, when used together with \texttt{footinfo},
+will, in the affected footers, replace the folio with one of the form \textit{x/y},
+where \textit{x} is the folio and \textit{y} is the page count.
+
+No warning is given, and no action taken,
+if this parameter is used with another document class,
+or if the \texttt{footinfo} option is omitted.
+More detail is given below (For \textit{memoir} users).
+\end{tabularx}
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\clearpage
+\section{The metadata}
+The \git\ metadata, for the current HEAD commit,
+is made available in the document
+as a series of parameter-less \LaTeX commands.
+Here they are:
+\vspace{0.5\baselineskip}
+
+\noindent
+\begin{tabularx}{\textwidth}{@{}>{\ttfamily\bfseries\textbackslash}lX@{}}
+gitAbbrevHash&
+ The seven-hex-char abbreviated commit hash
+\\
+gitHash&
+ The full 40-hex-character commit hash
+\\
+gitAuthorName&
+ The name of the author of this commit
+\\
+gitAuthorEmail&
+ The email address of the author of this commit
+\\
+gitAuthorDate&
+ The date this change was committed by the author,
+ in the format \textit{yyyy-mm-dd}
+\\
+gitAuthorIsoDate&
+ The date and time this change was committed by the author,
+ in ISO format, e.g. \textit{2011-08-29 13:05:54 +0100}
+\\
+gitAuthorUnixDate&
+ The date and time this change was committed by the author,
+ as a Unix timestamp, e.g \textit{1314619554}
+\\
+gitCommitterName&
+ The name of the committer of this commit
+\\
+gitCommitterEmail&
+ The email address of the committer of this commit
+\\
+gitCommitterDate&
+ The date this change was committed by the committer,
+ in the format \textit{yyyy-mm-dd}
+\\
+gitCommitterIsoDate&
+ The date and time this change was committed by the committer,
+ in ISO format, e.g. \textit{2011-08-29 13:05:54 +0100}
+\\
+gitCommitterUnixDate&
+ The date and time this change was committed by the committer,
+ as a Unix timestamp, e.g \textit{1314619554}
+\\
+gitReferences&
+ A list of any \git\ references (tags, branches) associated
+ with this commit, e.g. \textit{ (HEAD, master)}
+\\
+\end{tabularx}
+
+\vspace{0.5\baselineskip}
+Three more commands are available, but their use should be considered
+experimental. \tpname\ searches the \git\ references metadata for
+anything (probably a \git\ tag) that looks like a number with a decimal point.
+The first such number it finds is taken as a ``Version Number''
+and made available in three different formats, explained here:
+\vspace{0.5\baselineskip}
+
+\noindent
+\begin{tabularx}{\textwidth}{@{}>{\ttfamily\bfseries\textbackslash}lX@{}}
+gitVtag&
+ The version number, without any decorations. If no version number is found,
+ empty (i.e. zero width).
+\\
+gitVtags&
+ The version number, with a leading space. If no version number is found,
+ empty.
+\\
+gitVtagn&
+ The version number, with a leading space.
+ If no version number is found, a space,
+ followed by the default or specified value of
+ the \texttt{missing} package option.
+\\
+\end{tabularx}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{For \sfit{memoir} users}
+If you use \sfit{memoir}, \tpname provides some preset page
+headers and footers for you,
+if you specify the \texttt{footinfo} option as described above.
+
+With the \texttt{footinfo} option, \tpname\ redefines
+the \sfit{plain},\sfit{ruled}, and \sfit{headings} pagestyles.
+
+For the \sfit{plain} and \sfit{ruled} pagestyles,
+the folio is moved from the centre to the outer margin of the footer,
+and a revision stamp is placed in the inner margin.
+
+For the \sfit{headings} pagestyle,
+the folio is moved from the outer margin of the header
+to the outer margin of the footer,
+and a revision stamp is placed in the inner margin of the footer.
+
+If, as well, you use the \texttt{pcount} option, a solidus, and the page count,
+are appended to the folio.
+
+The revision stamp id generated by this fragment:
+\vspace{0.5\baselineskip}
+
+\noindent
+\verb!Revision\gitVtags: \gitAbbrevHash{} (\gitAuthorDate)!
+\vspace{0.5\baselineskip}
+
+\noindent
+which is set at tiny in the sans-serif font.
+You can see an example in the footer of this page.
+% -----------------------------------------------------
+\chapter{Etc}
+\section{Acknowledgements \& dependencies}
+
+The \href{http://tex.stackexchange.com}{\TeX.SE community}
+has been a constant source of help, inspiration, and amazement.
+In particular, I'd like to thank
+\href{http://tex.stackexchange.com/users/73/joseph-wright}{Joseph Wright},
+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: etoobox, kvoptions, and xstring.
+
+The failings, of course, are all mine.
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Copyright \& licence}
+Copyright \copyright\ 2011, Brent Longborough.
+
+This work --- \tpname\ --- may be distributed and/or modified under the
+conditions of the LaTeX Project Public License: either version 1.3
+of this license, or (at your option) any later version.
+
+The latest version of this license is at
+\url{http://www.latex-project.org/lppl.txt},
+and version 1.3 or later is part of all distributions of \LaTeX
+version 2005/12/01 or later.
+
+This work has the LPPL maintenance status `maintained';
+the Current Maintainer of this work is Brent Longborough.
+
+This work consists of the files
+gitinfo.sty, gitsetinfo.sty, gitinfo.tex, gitinfo.pdf,
+post-git-sample.txt, and \ginname.
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{From the author}
+Although my limitations as a \TeX nician
+mean that I've implemented \tpname\ in a rather simplistic way
+that needs some setup that is more complicated than I wanted,
+I hope you find the package useful.
+I'll be very happy to receive your comments by email.\\[\baselineskip]
+Brent Longborough\\[\baselineskip]
+\textsf{brent+gitinfo (at) longborough (dot) org}\\
+and at \href{http://tex.stackexchange.com/users/344/brent-longborough}{\TeX.SE}
+% -----------------------------------------------------
+\end{document}