From 2898d79db8fd35f3151ead38d075c66507556f8e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 3 Sep 2011 23:05:48 +0000 Subject: new latex package gitinfo (30aug11) git-svn-id: svn://tug.org/texlive/trunk@23779 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/gitinfo/README | 13 + .../texmf-dist/doc/latex/gitinfo/gitHeadInfo.gin | 15 + Master/texmf-dist/doc/latex/gitinfo/gitinfo.pdf | Bin 0 -> 79308 bytes Master/texmf-dist/doc/latex/gitinfo/gitinfo.tex | 408 +++++++++++++++++++++ .../doc/latex/gitinfo/post-xxx-sample.txt | 27 ++ 5 files changed, 463 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/gitinfo/README create mode 100644 Master/texmf-dist/doc/latex/gitinfo/gitHeadInfo.gin create mode 100644 Master/texmf-dist/doc/latex/gitinfo/gitinfo.pdf create mode 100644 Master/texmf-dist/doc/latex/gitinfo/gitinfo.tex create mode 100644 Master/texmf-dist/doc/latex/gitinfo/post-xxx-sample.txt (limited to 'Master/texmf-dist/doc/latex/gitinfo') diff --git a/Master/texmf-dist/doc/latex/gitinfo/README b/Master/texmf-dist/doc/latex/gitinfo/README new file mode 100644 index 00000000000..9eab676f86e --- /dev/null +++ b/Master/texmf-dist/doc/latex/gitinfo/README @@ -0,0 +1,13 @@ + The `gitinfo' package provides to allow version control metadata +to be incorporated into documents. The metadata is obtained from +the git distributed version control system. + For `memoir' users, the package can, optionally, tailor some +page headers and footers with certain metadata. + + gitinfo is licenced under the LPPL. For more details, +please see the accompanying manual: gitinfo.pdf. + +Change History +~~~~~~~~~~~~~~ + +2011-08-29 1.0 Initial release diff --git a/Master/texmf-dist/doc/latex/gitinfo/gitHeadInfo.gin b/Master/texmf-dist/doc/latex/gitinfo/gitHeadInfo.gin new file mode 100644 index 00000000000..6edee9c3b1c --- /dev/null +++ b/Master/texmf-dist/doc/latex/gitinfo/gitHeadInfo.gin @@ -0,0 +1,15 @@ +\usepackage[% + shash={11721ae}, + lhash={11721ae40233b940a8a8409d758409456c0a10ed}, + authname={Brent Longborough}, + authemail={brent@longborough.org}, + authsdate={2011-08-29}, + authidate={2011-08-29 23:23:28 +0100}, + authudate={1314656608}, + commname={Brent Longborough}, + commemail={brent@longborough.org}, + commsdate={2011-08-29}, + commidate={2011-08-29 23:23:28 +0100}, + commudate={1314656608}, + refnames={ (HEAD, 1.0, master, CTAN)} + ]{gitsetinfo} \ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/gitinfo/gitinfo.pdf b/Master/texmf-dist/doc/latex/gitinfo/gitinfo.pdf new file mode 100644 index 00000000000..8807bf49cc7 Binary files /dev/null and b/Master/texmf-dist/doc/latex/gitinfo/gitinfo.pdf differ diff --git a/Master/texmf-dist/doc/latex/gitinfo/gitinfo.tex b/Master/texmf-dist/doc/latex/gitinfo/gitinfo.tex new file mode 100644 index 00000000000..af6f90764c7 --- /dev/null +++ b/Master/texmf-dist/doc/latex/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[$$]\{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} diff --git a/Master/texmf-dist/doc/latex/gitinfo/post-xxx-sample.txt b/Master/texmf-dist/doc/latex/gitinfo/post-xxx-sample.txt new file mode 100644 index 00000000000..7bc91ceabd5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/gitinfo/post-xxx-sample.txt @@ -0,0 +1,27 @@ +#!/bin/sh +# Copyright 2011 Brent Longborough +# Please read gitinfo.pdf for licencing and other details +# ----------------------------------------------------- +# Post-{commit,checkout,merge} hook for the gitinfo package +# +prefixes=". test docs" # Example for multiple gitHeadInfo.tex files +prefixes="." # Default --- in the working copy root +for pref in $prefixes + do + git log -1 --date=short \ + --pretty=format:"\usepackage[% + shash={%h}, + lhash={%H}, + authname={%an}, + authemail={%ae}, + authsdate={%ad}, + authidate={%ai}, + authudate={%at}, + commname={%an}, + commemail={%ae}, + commsdate={%ad}, + commidate={%ai}, + commudate={%at}, + refnames={%d} + ]{gitsetinfo}" HEAD > $pref/gitHeadInfo.gin + done -- cgit v1.2.3