diff options
| -rw-r--r-- | Master/texmf-dist/doc/latex/gitinfo2/README | 23 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/gitinfo2/gitPseudoHeadInfo.gin | 17 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf | bin | 0 -> 110855 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.tex | 801 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/gitinfo2/gitinfotest.tex | 48 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/gitinfo2/gitexinfo.sty | 126 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/gitinfo2/gitinfo2.sty | 198 | ||||
| -rwxr-xr-x | Master/tlpkg/bin/tlpkginfo | 2 | ||||
| -rw-r--r-- | Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc | 1 | ||||
| -rw-r--r-- | Master/tlpkg/tlpsrc/gitinfo2.tlpsrc | 0 |
10 files changed, 1215 insertions, 1 deletions
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 Binary files differnew file mode 100644 index 00000000000..30b7c3f396d --- /dev/null +++ b/Master/texmf-dist/doc/latex/gitinfo2/gitinfo2.pdf 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[$<options>$]\{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} diff --git a/Master/texmf-dist/tex/latex/gitinfo2/gitexinfo.sty b/Master/texmf-dist/tex/latex/gitinfo2/gitexinfo.sty new file mode 100644 index 00000000000..7767684eb8e --- /dev/null +++ b/Master/texmf-dist/tex/latex/gitinfo2/gitexinfo.sty @@ -0,0 +1,126 @@ +% gitexinfo.sty +% 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, +% gitinfo2test.tex, post-git-sample.txt, +% and gitPseudoHeadInfo.gin +% ----------------------------------------------------- +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{gitexinfo}[2014/05/12 v2.00 Auxiliary package for gitinfo2] +\RequirePackage{kvoptions} +\RequirePackage{xstring} +\RequirePackage{etoolbox} +\SetupKeyvalOptions{family=gitinfo,prefix=gitInf@} +\DeclareStringOption{shash} +\DeclareStringOption{lhash} +\DeclareStringOption{authname} +\DeclareStringOption{authemail} +\DeclareStringOption{authsdate} +\DeclareStringOption{authidate} +\DeclareStringOption{authudate} +\DeclareStringOption{commname} +\DeclareStringOption{commemail} +\DeclareStringOption{commsdate} +\DeclareStringOption{commidate} +\DeclareStringOption{commudate} +\DeclareStringOption{refnames} +\DeclareStringOption{firsttagdescribe} +\DeclareStringOption{reltag} +\ProcessKeyvalOptions* +\renewcommand{\gitAbbrevHash}{\gitInf@shash} +\renewcommand{\gitHash}{\gitInf@lhash} +\renewcommand{\gitAuthorName}{\gitInf@authname} +\renewcommand{\gitAuthorEmail}{\gitInf@authemail} +\renewcommand{\gitAuthorDate}{\gitInf@authsdate} +\renewcommand{\gitAuthorIsoDate}{\gitInf@authidate} +\renewcommand{\gitAuthorUnixDate}{\gitInf@authudate} +\renewcommand{\gitCommitterName}{\gitInf@commname} +\renewcommand{\gitCommitterEmail}{\gitInf@commemail} +\renewcommand{\gitCommitterDate}{\gitInf@commsdate} +\renewcommand{\gitCommitterIsoDate}{\gitInf@commidate} +\renewcommand{\gitCommitterUnixDate}{\gitInf@commudate} +\renewcommand{\gitFirstTagDescribe}{\gitInf@firsttagdescribe} +\renewcommand{\gitReferences}{\gitInf@refnames} +\newcommand{\git@vtag}[1]{% + \def\do##1{% + \StrCut{##1}{tag: }\lcut\rcut% + \IfEq{\rcut}{}{% + \IfDecimal{\lcut}{% case where we have decimal e.g. 1.0 + \renewcommand{\gitVtag}{\lcut} + \renewcommand{\gitVtags}{\space\lcut} + \renewcommand{\gitVtagn}{\space\lcut} + \listbreak + }{}% + }{% + \IfDecimal\rcut{% case where we have string: decimal e.g. tag: 1.0 + \renewcommand{\gitVtag}{\rcut} + \renewcommand{\gitVtags}{\space\rcut} + \renewcommand{\gitVtagn}{\space\rcut} + \listbreak + }{}% + }% + }% + \expandafter\docsvlist\expandafter{#1}% + \StrDel{#1}{)}[\bcut]% + \StrDel{\bcut}{(HEAD}[\bcut]% + \StrCount{\bcut}{, }[\xcut]% + \StrCut[\xcut]{\bcut}{, }{\bcut}{\xcut}% + \IfEq{\xcut}{}{}{% + \renewcommand{\gitBranch}{\xcut}% + }% +}% +\newcommand{\git@taglist}[1]{% + \def\do##1{% + \StrCut{##1}{tag: }\llcut\rrcut% + \IfEq{\rrcut}{}{% + \IfDecimal{\llcut}{% case where we have decimal e.g. 1.0 + \StrGobbleLeft{\gitTags,\space\llcut}{0}[\gitTags] + }{}% + }{% + \StrGobbleLeft{\gitTags,\space\rrcut}{0}[\gitTags] + }% + }% + \expandafter\docsvlist\expandafter{#1}% + \StrGobbleLeft{\gitTags}{2}[\gitTags] +}% +\newcommand{\git@rtag}[1]{% + \IfEq{#1}{}{}{% + \StrRight{#1}{2}[\gitInf@dirtflag] + \StrDel{#1}{-*}[\gitInf@describe] + \IfEq{\gitInf@dirtflag}{-*}{\renewcommand{\gitDirty}{\gitInf@dirty}}{} + \StrGobbleRight{\gitInf@describe}{9}[\gitInf@describe]% Remove -g<hash> + \StrCount{\gitInf@describe}{-}[\gitInf@mcount]% Find last - + \StrCut[\gitInf@mcount]{\gitInf@describe}{-}{\gitInf@rel}{\gitInf@off} + \renewcommand{\gitRel}{\gitInf@rel} + \renewcommand{\gitRels}{\space\gitInf@rel} + \renewcommand{\gitReln}{\space\gitInf@rel} + \renewcommand{\gitRoff}{\gitInf@off} + \renewcommand{\gitDescribe}{#1} + }% +}% +\git@vtag{\gitInf@refnames} +\git@taglist{\gitInf@refnames} +\git@rtag{\gitInf@reltag} +\newcommand{\git@tagmark}{} +\IfEq{\gitTags}{}{% + \renewcommand{\gitTags}{\gitInf@notags} + \ifbool{gitInf@marknotags}{% + \renewcommand{\git@tagmark}{\\Head tags: \gitTags} + }{% + } +}{% + \renewcommand{\git@tagmark}{\\Head tags: \gitTags} +} +\renewcommand{\gitMark}{Branch: \gitBranch\,@\,\gitAbbrevHash{} / Release:\gitReln{} (\gitAuthorDate)\git@tagmark} diff --git a/Master/texmf-dist/tex/latex/gitinfo2/gitinfo2.sty b/Master/texmf-dist/tex/latex/gitinfo2/gitinfo2.sty new file mode 100644 index 00000000000..e6dabe42ce9 --- /dev/null +++ b/Master/texmf-dist/tex/latex/gitinfo2/gitinfo2.sty @@ -0,0 +1,198 @@ +% gitinfo2.sty +% 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, +% gitinfo2test.tex, post-git-sample.txt, +% and gitPseudoHeadInfo.gin +% ----------------------------------------------------- +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{gitinfo2}[2014/05/12 v2.00 git revision information] +\RequirePackage{etoolbox} +\RequirePackage{kvoptions} +\RequirePackage{eso-pic} +\SetupKeyvalOptions{family=gitinfo,prefix=gitInf@} +\DeclareBoolOption{draft} +\DeclareBoolOption{grumpy} +\DeclareBoolOption{pcount} +\DeclareBoolOption{footinfo} +\DeclareBoolOption{mark} +\DeclareBoolOption{markifdraft} +\DeclareBoolOption{markifdirty} +\DeclareBoolOption{marknotags} +\DeclareStringOption[(None)]{missing} +\DeclareStringOption[(None)]{notags} +\DeclareStringOption[(*)]{dirty} +\DeclareStringOption[4]{maxdepth} +\DeclareStringOption[1.5\baselineskip]{raisemark} +\ProcessKeyvalOptions* +\newcommand{\gitAbbrevHash}{\gitInf@missing} +\newcommand{\gitHash}{\gitInf@missing} +\newcommand{\gitAuthorName}{\gitInf@missing} +\newcommand{\gitAuthorEmail}{\gitInf@missing} +\newcommand{\gitAuthorDate}{\gitInf@missing} +\newcommand{\gitAuthorIsoDate}{\gitInf@missing} +\newcommand{\gitAuthorUnixDate}{\gitInf@missing} +\newcommand{\gitCommitterName}{\gitInf@missing} +\newcommand{\gitCommitterEmail}{\gitInf@missing} +\newcommand{\gitCommitterDate}{\gitInf@missing} +\newcommand{\gitCommitterIsoDate}{\gitInf@missing} +\newcommand{\gitCommitterUnixDate}{\gitInf@missing} +\newcommand{\gitTags}{} +\newcommand{\gitFirstTagDescribe}{\gitInf@missing} +\newcommand{\gitReferences}{\gitInf@missing} +\newcommand{\gitBranch}{\gitInf@missing} +\newcommand{\gitVtag}{} +\newcommand{\gitVtags}{} +\newcommand{\gitVtagn}{\space\gitInf@missing} +\newcommand{\gitRel}{} +\newcommand{\gitRels}{} +\newcommand{\gitReln}{\space\gitInf@missing} +\newcommand{\gitDirty}{} +\newcommand{\gitRoff}{} +\newcommand{\gitDescribe}{(None)} +\newcommand{\gitMarkPref}{[git]} +\newcommand{\gitMarkFormat}{\color{gray}\small\sffamily} +\newcommand{\gitMark}{} + +% private values +\newif\ifGI@is@a@repo@ + +% private constants +\providecommand{\GI@repo@prefix}{} +\providecommand{\GI@githeadinfo@file}{\GI@repo@prefix.git/gitHeadInfo.gin} +\newcommand{\gitInf@dirtflag}{} +\newcommand{\gitInf@describe}{} +\newcommand{\gitInf@mcount}{} +\newcommand{\gitInf@rel}{} +\newcommand{\gitInf@off}{} + +% \TeX{}nical tools + +\newcommand\GI@export@macro[1]{% + \edef\@tempa{\endgroup + \def\noexpand#1{#1}}% + \@tempa} + +% finding the .git directory + +\newcommand\GI@check@repo@prefix{% + \GI@is@a@repo@true + \IfFileExists{./\GI@githeadinfo@file}{% + \edef\GI@repo@prefix{./}% + }{% + \GI@set@repo@prefix}} + +\newcommand\GI@set@repo@prefix{% + \begingroup \count@\gitInf@maxdepth\relax + \GI@set@repo@prefix@} + +\newcommand\GI@set@repo@prefix@{% + \advance\count@\m@ne + \ifnum\count@<\z@ + % \expandafter\GI@not@a@git@repo + \endgroup\relax + \else + \edef\GI@repo@prefix{../\GI@repo@prefix}% + \IfFileExists{\GI@githeadinfo@file}{% + \PackageWarningNoLine{gitinfo2}{% + gitinfo2 found : \GI@githeadinfo@file \MessageBreak + }% + \GI@export@macro\GI@githeadinfo@file + }{% + \expandafter\GI@set@repo@prefix@}% + \fi} + +\GI@check@repo@prefix +\InputIfFileExists{\GI@githeadinfo@file}{}{% + \ifbool{gitInf@grumpy}{% + \PackageError{gitinfo2}{I can't find the file '\GI@githeadinfo@file'\MessageBreak + Please check the manual (gitinfo2.pdf) \MessageBreak + if you need more details}{} + }{% + \PackageWarningNoLine{gitinfo2}{I can't find the file '\GI@githeadinfo@file'.\MessageBreak + All git metadata has been set to '\gitInf@missing'} + } +} +% --------------------------------------------------------------------- +% Memoir support +% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +\@ifclassloaded{memoir}{% + \ifbool{gitInf@pcount}{ + \newcommand{\@gitPage}{\thepage/\thelastpage} + \addtodef{\frontmatter}{\renewcommand{\@gitPage}{\thepage}}{} + \addtodef{\mainmatter}{}{\renewcommand{\@gitPage}{\thepage/\thelastpage}} + }{% + \newcommand{\@gitPage}{\thepage} + } + \newcommand{\@gitFootRev}{Release\gitRels: \gitAbbrevHash{} (\gitAuthorDate)} + \newcommand{\@gitrFootRev}{% + \tiny\textsf{\raggedleft \@gitFootRev}% + }% + \newcommand{\@gitlFootRev}{% + \tiny\textsf{\@gitFootRev}% + }% + \copypagestyle{giplain}{plain} + \copypagestyle{giruled}{ruled} + \copypagestyle{giheadings}{headings} + \makeevenfoot{giplain}{\@gitPage}{}{\@gitrFootRev} + \makeoddfoot{giplain}{\@gitlFootRev}{}{\@gitPage} + \makeevenfoot{giruled}{\@gitPage}{}{\@gitrFootRev} + \makeoddfoot{giruled}{\@gitlFootRev}{}{\@gitPage} + \makeevenfoot{giheadings}{\@gitPage}{}{\@gitrFootRev} + \makeoddfoot{giheadings}{\@gitlFootRev}{}{\@gitPage} + \makeevenhead{giheadings}{}{}{\slshape\leftmark} + \makeoddhead{giheadings}{\slshape\rightmark}{}{} +}{}% +% --------------------------------------------------------------------- +% Watermarking +% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +\ifbool{gitInf@markifdirty}{% + \IfEq{\gitDirty}{}{}{% + \booltrue{gitInf@mark} + \renewcommand{\gitMarkPref}{[Dirty]} + }% +}{}% +\ifbool{gitInf@markifdraft}{% + \ifbool{gitInf@draft}{% + \booltrue{gitInf@mark} + \renewcommand{\gitMarkPref}{[Draft]} + }{}% +}{}% +\ifbool{gitInf@mark}{% + \AddToShipoutPictureBG{% + \AtPageLowerLeft{% + \raisebox{\gitInf@raisemark}{% + \makebox[\paperwidth]{% + \begin{minipage}[b]{\paperwidth}% + \renewcommand{\baselinestretch}{1}% + \centering{\gitMarkFormat\gitMarkPref{} \gitMark}% + \end{minipage}% + }% + }% + }% + }% +}{}% +% --------------------------------------------------------------------- +% Datetime integration +% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +\@ifpackageloaded{datetime}{% + \IfEq{\gitAuthorDate}{\gitInf@missing}{% + \newdate{gitdate}{\THEDAY}{\THEMONTH}{\THEYEAR} + }{% + \StrCut{\gitAuthorDate}{-}{\gitInf@year}{\gitInf@md} + \StrCut{\gitInf@md}{-}{\gitInf@month}{\gitInf@day} + \newdate{gitdate}{\gitInf@day}{\gitInf@month}{\gitInf@year} + } +}{}% diff --git a/Master/tlpkg/bin/tlpkginfo b/Master/tlpkg/bin/tlpkginfo index 80ca069ff64..157ddd1e026 100755 --- a/Master/tlpkg/bin/tlpkginfo +++ b/Master/tlpkg/bin/tlpkginfo @@ -263,7 +263,7 @@ sub catalogue_find_ctan_path { # Subcase of (2): package name is babel-hungarian, but CTAN path is # babel-contrib/hungarian. Sigh. # -warn "ctan path $ctan_path, pkg $pkgname\n"; +#warn "ctan path $ctan_path, pkg $pkgname\n"; if ($ctan_path =~ /file='true'/) { (my $ctan_babel_path = $ctan_path) =~ s,babel-contrib/,babel-,; if ($ctan_path =~ m,/$pkgname/, diff --git a/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc b/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc index b18a5a90fd9..2b6e9a9fedf 100644 --- a/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc +++ b/Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc @@ -356,6 +356,7 @@ depend genmpage depend getfiledate depend ginpenc depend gitinfo +depend gitinfo2 depend gloss depend glossaries depend gmdoc diff --git a/Master/tlpkg/tlpsrc/gitinfo2.tlpsrc b/Master/tlpkg/tlpsrc/gitinfo2.tlpsrc new file mode 100644 index 00000000000..e69de29bb2d --- /dev/null +++ b/Master/tlpkg/tlpsrc/gitinfo2.tlpsrc |