From 5e3775e74d3445586dfb14b025aa3b758c9fe50d Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 1 Sep 2014 22:26:27 +0000 Subject: gitinfo2 (1sep14) git-svn-id: svn://tug.org/texlive/trunk@35083 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/gitinfo2/README | 23 + .../doc/latex/gitinfo2/gitPseudoHeadInfo.gin | 17 + Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf | Bin 0 -> 110855 bytes Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex | 801 +++++++++++++++++++++ .../texmf-dist/doc/latex/gitinfo2/gitinfotest.tex | 48 ++ 5 files changed, 889 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/gitinfo2/README create mode 100644 Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin create mode 100644 Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf create mode 100644 Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex create mode 100644 Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex (limited to 'Master/texmf-dist/doc') diff --git a/Master/texmf-dist/doc/latex/gitinfo2/README b/Master/texmf-dist/doc/latex/gitinfo2/README new file mode 100644 index 00000000000..ee18c3b25d9 --- /dev/null +++ b/Master/texmf-dist/doc/latex/gitinfo2/README @@ -0,0 +1,23 @@ + The `gitinfo2' package allows version control metadata to be +incorporated into LaTeX documents; the metadata is obtained from the +git distributed version control system. + For `memoir' users, the package provides additional page styles +(headers and footers) with selected metadata. + + gitinfo2 is licenced under the LPPL. For more details, +please see the accompanying manual: gitinfo2.pdf. + +Change History +~~~~~~~~~~~~~~ + +Warning: existing repositories using gitinfo will need to be migrated +in order to take advantage of the new features in gitinfo2. + +2014-05-12 2.0 Changed package name for backward compatibility + Improved documentation + New tags for improved Release annotation + A relocated 'gitHeadInfo.gin' file + Re-engineered page styles for Memoir users + Watermarking facility + +2011-08-29 1.0 Initial release diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin b/Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin new file mode 100644 index 00000000000..d1a7f3c5339 --- /dev/null +++ b/Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin @@ -0,0 +1,17 @@ +\usepackage[% + shash={3dfeae6}, + lhash={3dfeae68bb3109a335704f4420958d4394329f15}, + authname={Brent Longborough}, + authemail={brent+ctancontrib@longborough.org}, + authsdate={2014-05-17}, + authidate={2014-05-17 17:08:57 +0100}, + authudate={1400342937}, + commname={Brent Longborough}, + commemail={brent+ctancontrib@longborough.org}, + commsdate={2014-05-17}, + commidate={2014-05-17 17:08:57 +0100}, + commudate={1400342937}, + refnames={ (HEAD, develop)}, + firsttagdescribe={2.0-13-g3dfeae6}, + reltag={2.0-13-g3dfeae6} + ]{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 new file mode 100644 index 00000000000..30b7c3f396d Binary files /dev/null and b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf differ diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex new file mode 100644 index 00000000000..673e746d815 --- /dev/null +++ b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex @@ -0,0 +1,801 @@ +% gitinfo2.tex +% Copyright 2014 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: +% gitinfo2.sty, gitexinfo.sty, gitinfo2.tex, gitinfo2.pdf, +% gitinfotest.tex, post-git-sample.txt, +% and gitPseudoHeadInfo.gin +% ----------------------------------------------------- +\documentclass[a4paper,12pt,twoside,openany]{memoir} +% ===================================================== +% This is a tweak to allow this document to be formatted +% even when it doesn't live in an adequately configured +% git repository. Please do not try this at home. +% You have been warned. +% ----------------------------------------------------- +\makeatletter +\newcommand{\GI@repo@prefix}{} +\newcommand{\GI@githeadinfo@file}{\GI@repo@prefix./gitPseudoHeadInfo.gin} +\makeatother +% ----------------------------------------------------- +% End of tweak +% ===================================================== +\usepackage[nodayofweek]{datetime} +\longdate{} +\usepackage[pcount,grumpy,mark,markifdirty]{gitinfo2} +\usepackage{tgpagella} +\usepackage{tgadventor} +\usepackage{fontspec} +\setmainfont[Numbers={Proportional,OldStyle},Ligatures=TeX]{TeX Gyre Pagella} +\setsansfont[Numbers={Proportional,OldStyle},Ligatures=TeX]{TeX Gyre Adventor} +\setmonofont{Consolas} +\usepackage{enumitem} +\setlist[description]{% + format=\ttfamily\bfseries, + style=nextline, + leftmargin=5em, + itemsep=0.5\onelineskip} +\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{empty} +\aliaspagestyle{chapter}{empty} +\settocdepth{section} +\setsecnumdepth{none} +\newcommand{\bpara}[1]{\par\vspace{\beforeparaskip}\noindent\textbf{#1}\,} +\newcommand{\sfit}[1]{\textit{#1}} +\newcommand{\git}{\sfit{git}} +\newcommand*{\emailat}{@} +\newcommand{\opname}{\sfit{gitinfo}} +\newcommand{\tpname}{\sfit{gitinfo2}} +\newcommand{\tpfname}{\textsf{gitinfo2.sty}} +\newcommand{\ginname}{gitHeadInfo.gin} +\newcommand{\metaname}{\texttt{\ginname}} +\newcommand{\metapath}{\texttt{.git/\ginname}} +% ----------------------------------------------------- +\usepackage[% + bookmarksnumbered, + bookmarksopen, + linktocpage, + frenchlinks, + ]{hyperref} +\hypersetup{ + pdfauthor={Brent Longborough}, + pdftitle={The gitinfo2 package: git metadata for LaTeX}, + pdfkeywords={git;metadata;dvcs}, +} +\begin{document} +\frontmatter +% ----------------------------------------------------- +\title{% + \Huge \tpfname\\[2ex]% + \Large A package for accessing metadata\\from the \git\ \textsc{dvcs} + } +\author{Brent Longborough} +\date{\displaydate{gitdate}} +\maketitle + +{\centering +Release:\gitReln\ (\gitAbbrevHash)\\ +} +%\vspace*{2\baselineskip} +% ----------------------------------------------------- +\begingroup +\thispagestyle{empty} +\aliaspagestyle{chapter}{empty} +\setlength{\afterchapskip}{20pt} +\let\clearpage\relax +\let\chaptitlefont\Large\bfseries +\vspace*{5\baselineskip} +\tableofcontents* +\endgroup +% ----------------------------------------------------- +\mainmatter +\pagestyle{giruled} +\aliaspagestyle{chapter}{giplain} +\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\{.git/\ginname\}} +in the repository (module or submodule) root. + +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 `\titleref{ch:using}' +on page \pageref*{ch:using}. +Then, if you like what you see, come back to +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\ +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, +and the inner package name from \sfit{gitsetinfo} +to \sfit{gitexinfo}. + +\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. + +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 +by not getting it right the first time. + +% ----------------------------------------------------- +\chapter{Setup and tailoring} +\label{ch: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. + +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 If you're using a unix-like system, +don't forget to make the file executable. +Just how you do this is outside the scope of this manual, +but one possible way is with commands such as this: + +\begin{verbatim} +chmod g+x post-checkout. +\end{verbatim} + +\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. +As before, users of unix-like systems should ensure these files are marked as executable. +\end{enumerate} + +If you don't want to install \tpname\ using a package manager, +you can instead just copy the two *.sty files into your document directory. +However, it may be simpler, for more complex project trees, +to install the package as part of your \TeX\ distribution. + +% - - - - - - - - - - - - - - - - - - - - - - - - - - - +\section{Migrating from version 1} + +Version~2 of \tpname\ simplifies setup and brings additional convenience. +But this comes at a cost: +existing repositories need to be upgraded to be compatible. +This decision wasn't taken lightly; I really do think the incompatible changes +will give us a much firmer base for the future. +The changes needed, which should be applied to every repository, follow. + +\bpara{Update \git\ hooks.} +Replace the hooks (\texttt{post-checkout}, \texttt{post-commit}, +and \texttt{post-merge}) with the contents of the file \texttt{post-xxx-sample.txt}. +Since \tpname\ now uses only a single \metaname\ file for the whole repository, +you do \emph{not} need to tailor these hooks to map your document folders. + +If you are fortunate enough to be using a unix-like system, +don't forget to ensure the hooks are executable. + +\bpara{Recreate the new \metaname\ file.} +After you've replaced the hooks, the simplest way is to re-check-out the current branch, +using a command such as \verb!git checkout!. + +\bpara{Delete the old \metaname\ files,} +when you're ready. + +\bpara{If you're a \sfit{memoir} user,} +and you use the \texttt{footinfo} package option, +you will need to adjust your page styles. + +From \tpname\ version~2, we no longer override the standard \sfit{memoir} +page styles. +Instead, \tpname\ provides three new page styles: +\sfit{giplain}, \sfit{giruled}, and \sfit{giheadings}, +which you should now use to provide \tpname-tailored pages. + +% - - - - - - - - - - - - - - - - - - - - - - - - - - - +\section{Tailoring release tags} + +As shipped, the \git\ hook code uses a certain convention +for identifying `release' tags: +the tag must begin with a numeric digit, and contain at least one decimal +point.\footnote{I.e. full stop or period, depending on which variant of English you use.} + +Here is the line in the hook where this convention is established: + +\begin{quotation} +{\ttfamily +RELTAG=\$(git describe \textellipsis\ --match '[0-9]*.*' \textellipsis) +} +\end{quotation} + +By changing the \texttt{--match} parameter, you can decide exactly which tags +qualify as `release' tags for your needs. Thus + +\begin{quotation} +{\ttfamily +RELTAG=\$(git describe \textellipsis\ --match 'R.*' \textellipsis) +} +\end{quotation} +would allow you to find tags like `R.2.0.1' and `R.L.Stevenson', +or + +\begin{quotation} +{\ttfamily +RELTAG=\$(git describe \textellipsis\ --match '*' \textellipsis) +} +\end{quotation} +would allow you to find any tag whatsoever. + +You can change the hooks without needing to alter \tpname, +since whatever tag is found is used as-is. + +% ----------------------------------------------------- +\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, +by loading the \tpname\ package in the usual way:\\[0.5\baselineskip] +\texttt{\textbackslash usepackage[$$]\{gitinfo2\}} + +% - - - - - - - - - - - - - - - - - - - - - - - - - - - +\section{Package options} + +The following options are available: + +\subsection{General options} + +\begin{description} + +\item[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. + +\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)', +and the working copy has uncommitted changes `(*)'. +For example: + +\begin{quote} +{\ttfamily +[missing=Help!,notags=\{No tags?\},dirty=Yuck] +} +\end{quote} +If you have complex needs, as in the second example, +don't forget to enclose your text in \{\}s. + +\item[\texttt{maxdepth=\textit{n}}] +In order to locate \metapath\ in the repository root, +\tpname\ starts in the directory containing the master document, +and searches up the directory tree until it finds it. +This search is limited to {\ttfamily\itshape n} levels --- 4 by default. +If have to deal with documents +deeper in your repository tree, you can extend this limit with, say, +{\ttfamily maxdepth=8}. + +\end{description} +\clearpage +\subsection{Options for watermarking} + +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, +centred at the bottom of each sheet, +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. + +\item[markifdirty] +This option is like {\ttfamily\bfseries mark,} +but only activates the watermark if the last commit or checkout left +uncommitted changes in the repository. + +\item[marknotags] +If \tpname\ can't find any tags in the \git\ references, +it suppresses the second line of the watermark. +If, however, you would like the second line always to appear, +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.} +above the bottom of the paper. +If you prefer something different, +you can specify it here. +For example: + +\begin{quote} +{\ttfamily +[raisemark=0.95\textbackslash{}paperheight] +} +\end{quote} + + +\item[draft] +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, +please read +%The use of these options is described in more detail in +`\titleref{sect:memuser}' +on page~\pageref*{sect:memuser}. + +\begin{description} + +\item[footinfo] +This option is no longer used, and if present is silently ignored. +For \sfit{memoir} users, \tpname\ now creates, automatically, +three new page styles. + +\item[pcount] +For \sfit{memoir} users, this option will replace the folio +in the new page styles 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. + +\end{description} +% - - - - - - - - - - - - - - - - - - - - - - - - - - - +\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: + +\begin{description} + +\item[gitReferences] + A list of any \git\ references (tags, branches) associated + with this commit. + This string is not for the faint-hearted; + its format and order may vary between versions of \git.\\ + Example:\\\textit{\small\gitReferences} + +\item[gitBranch] + The name of the current branch. + Depending on how you use \git,\footnote{For example, checking out unnamed branches} + this information may not be available, + and will then be shown as the default or specified value of + the \texttt{missing} package option.\\ + Example: \textit{\gitBranch} + +\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; + otherwise empty. + +\item[gitAbbrevHash] + The seven-hex-char abbreviated commit hash\\ + Example: \textit{\gitAbbrevHash} + +\item[gitHash] + The full 40-hex-character commit hash\\ + Example: \textit{\gitHash} + +\item[gitAuthorName] + The name of the author of this commit\\ + Example: \textit{\gitAuthorName} + +\item[gitAuthorEmail] + The email address of the author of this commit\\ + Example: \textit{myemail\emailat evilspam.net} + +\item[gitAuthorDate] + The date this change was committed by the author, + in the format \textit{yyyy-mm-dd}\\ + Example: \textit{\gitAuthorDate} + +\item[gitAuthorIsoDate] + The date and time this change was committed by the author, + in ISO format\\ + Example: \textit{\gitAuthorIsoDate} +\clearpage +\item[gitAuthorUnixDate] + The date and time this change was committed by the author, + as a Unix timestamp\\ + Example: \textit{\gitAuthorUnixDate} + +\item[gitCommitterName] + The name of the committer of this commit\\ + Example: \textit{\gitCommitterName} + +\item[gitCommitterEmail] + The email address of the committer of this commit\\ + Example: \textit{watcher\emailat gchq.gov.uk} + +\item[gitCommitterDate] + The date this change was committed by the committer, + in the format \textit{yyyy-mm-dd}\\ + Example: \textit{\gitCommitterDate} + +\item[gitCommitterIsoDate] + The date and time this change was committed by the committer, + in ISO format\\ + Example: \textit{\gitCommitterIsoDate} + +\item[gitCommitterUnixDate] + The date and time this change was committed by the committer, + as a Unix timestamp\\ + Example: \textit{\gitCommitterUnixDate} + +\end{description} + + +\subsection{Additional metadata (Version 1)} + +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: + +\begin{description} +\item[gitVtag] + The version number, without decorations. If no version number is found, + empty (i.e. zero width). +\item[gitVtags] + The version number, with a leading space. If no version number is found, + empty. +\item[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.\\ + Example: \textit{\gitVtagn} +\end{description} + +These versioning tags have been superseded by release tags in Version 2, +although they should continue to work as before. + +\subsection{Additional metadata (Version 2)} + +From Version 2 onwards, additional \git\ metadata is available, +in general improving or extending the facilities available in Version 1. +The Version 1 metadata is retained for backward compatibility. + +Included is a new set of \texttt{gitRel} commands, +designed to replace \texttt{gitVtag} and its cousins. +\tpname\ searches the \git\ metadata for tags +on the current \textsc{head} commit or its ancestors, +and makes the first tag found available. +It also looks for the latest such tag +whose name begins with a digit, and which contains a full stop (period), +and makes the tag, and the number of commits following it, +available as a `release number'.% +\footnote{\tpname\ doesn't check for numerics, so you can use a tag like `1.5-beta' if you wish.} +Here are the new commands in Version~2: + +\begin{description} + +\item[gitFirstTagDescribe] + The last tag reachable from the current \textsc{head}. + Please see git-describe for more information. + If the working copy is \textit{dirty} (has uncommitted changes), + the string has '-*' appended.\\ + Example: \textit{\gitFirstTagDescribe} + +\item[gitRel] + The release number, without any decorations. + If no release number is found, empty (i.e. zero width). + +\item[gitRels] + The release number, with a leading space. + If no release number is found, empty. + +\item[gitReln] + The release number, with a leading space. + If no release number is found, a space, + followed by the default or specified value of + the \texttt{missing} package option. + +\item[gitRoff] + The number of commits between the current \textsc{head} + and the tag holding the release number. + If the tag refers to the current \textsc{head}, zero. + +\item[gitTags] + A comma-separated list of tags associated with the current \textsc{head}.\\ + Example: \textit{\gitTags} + +\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, + short hash, and a dirty flag. + Please see git-describe for more information. + Example: \textit{\gitDescribe} + +\end{description} + +\clearpage +\subsection{Watermark tailoring commands} + +If you use the Version 2 options to place a watermark, +you can tailor the format of the watermark to suit your needs, +by redefining one or more of the following commands. + +\begin{description} + +\item[gitMark] + 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 three lines to fit) + is: + +\begin{verbatim} +Branch: \gitBranch\,@\,\gitAbbrevHash{} / +Release:\gitReln{} (\gitAuthorDate)\\ +Head tags: \gitTags +\end{verbatim} +You can tailor this by redefining \verb!\gitMark!. +For example: + +\begin{verbatim} +\renewcommand{\gitMark}{\gitHash\hfill\gitRel} +\end{verbatim} + +\item[gitMarkFormat] + Defines typesetting parameters for the whole watermark. + The default definition is: + +\begin{verbatim} +\color{gray}\small\sffamily +\end{verbatim} +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, + which depends on the reason the document is being watermarked. + is being printed. + The default values are \sfit{[Dirty]}, \sfit{[Draft]}, or \sfit{[git]}. + You can tailor this by redefining \verb!\gitMarkPref!. For example: + +\begin{verbatim} +\renewcommand{\gitMarkPref}{[Pending review]} +\end{verbatim} + +\end{description} + +% - - - - - - - - - - - - - - - - - - - - - - - - - - - +\clearpage +\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}. +The new pagestyles are called +\sfit{giplain}, \sfit{giruled}, and \sfit{giheadings}. + +For the \sfit{giplain} and \sfit{giruled} 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{giheadings} 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 you use the \texttt{pcount} option, a solidus, and the page count, +are appended to the folio. + +The revision stamp is generated by this fragment: + +\begin{verbatim} + Release\gitRels: \gitAbbrevHash{} (\gitAuthorDate) +\end{verbatim} +\noindent +which is set at tiny in the sans-serif font. + +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 +explicitly. + +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}, +which you can then refer to with other \sfit{datetime} +functions. + +Please refer to the \sfit{datetime} manual for +further details, +especially in the section entitled `Saving Dates'. + +If you use it, you must load \sfit{datetime} +before you load \tpname. +% ----------------------------------------------------- +\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: 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. +I owe you all an apology for the amount of time that elapsed +from your suggestions to the making of \tpname. + +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, +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 +the deduplication of \metaname. + +My sincere thanks, too, to +Adrian Burd, +Felix Wenger, +Johannes Hoetzer, +Martin W Leidig, +Nik (of gwdg nokta de), +Omid (of gmail nokta com), +Robbie Morrison, +Ryan Matlock, and +Sasaki~Suguru. + +Finally, but by no means least, +my thanks to the \textsc{Ctan} elves, and their dæmons, +particularly, in my case, +Robin Fairbairns and Petra Rübe-Pugliese, +for their infinite patience and unstinting +dedication to the \TeX\ community. + +The failings, of course, I claim for my self. +% - - - - - - - - - - - - - - - - - - - - - - - - - - - +\section{Copyright \& licence} +Copyright \copyright\ 2014, 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 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 +\LaTeX. + +This work has the LPPL maintenance status `maintained'; +the Current Maintainer of this work is Brent Longborough. + +This work consists of the files +gitinfo2.sty, gitexinfo.sty, gitinfo2.tex, gitinfo2.pdf, +post-git-sample.txt, and gitPseudoHeadInfo.gin. + +% - - - - - - - - - - - - - - - - - - - - - - - - - - - +\clearpage +\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+ctancontrib (bei) longborough (punkt) org}\\ +and at \href{http://tex.stackexchange.com/users/344/brent-longborough}{\TeX.SE} +% ----------------------------------------------------- +\end{document} diff --git a/Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex b/Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex new file mode 100644 index 00000000000..4cc0bcbac3f --- /dev/null +++ b/Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex @@ -0,0 +1,48 @@ +\documentclass[10pt,a4paper,article,showtrims]{memoir} +% ===================================================== +% This is a tweak to allow this document to be formatted +% even when it doesn't live in an adequately configured +% git repository. Please do not try this at home. +% You have been warned. +% ----------------------------------------------------- +\makeatletter +\newcommand{\GI@repo@prefix}{} +\newcommand{\GI@githeadinfo@file}{\GI@repo@prefix./gitPseudoHeadInfo.gin} +\makeatother +% ----------------------------------------------------- +% End of tweak +% ===================================================== +\usepackage[missing={(Oh my!)},dirty={Oh no!},markifdirty,marknotags]{gitinfo2} +\frenchspacing +\begin{document} + +\ttfamily +!\gitMark! Mark + +!\gitReferences ! References + +!\gitVtag ! Vtag + +!\gitVtags ! Vtags + +!\gitVtagn ! Vtagn + +!\gitRel ! Rel + +!\gitRels ! Rels + +!\gitReln ! Reln + +!\gitFirstTagDescribe ! F.T.Describe + +!\gitDescribe ! Describe + +!\gitTags ! Tags + +!\gitDirty ! Dirty + +!\gitBranch ! Branch + +!\gitRoff ! Roff + +\end{document} -- cgit v1.2.3