path: root/Master/texmf-dist/doc/latex/gitinfo/gitinfo.tex

% 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}