summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gitver/gitver.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/gitver/gitver.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/gitver/gitver.tex')
-rw-r--r--macros/latex/contrib/gitver/gitver.tex105
1 files changed, 105 insertions, 0 deletions
diff --git a/macros/latex/contrib/gitver/gitver.tex b/macros/latex/contrib/gitver/gitver.tex
new file mode 100644
index 0000000000..dd60069040
--- /dev/null
+++ b/macros/latex/contrib/gitver/gitver.tex
@@ -0,0 +1,105 @@
+%!TEX options = --shell-escape
+%
+% This command causes LatexTools for SublimeText to compile in shell escape mode.
+%
+% If you're not using LatexTools to compile, you will need to enable shell
+% escape on your editor some other way
+
+\documentclass[a4paper]{ltxdoc}
+
+\usepackage{fancyhdr}
+\pagestyle{fancy}
+
+\usepackage{gitver}
+
+
+\begin{document}
+
+\title{\textsf{gitver} -- Git version tags \\
+for \LaTeX{} projects}
+\author{Charles Baynham}
+\date{2019/02/06 (v\,1.0)}
+\MaintainedBy{%
+ This file is maintained by Charles Baynham.\\%
+ Bug reports can be opened at\\%
+ \url{https://github.com/charlesbaynham/gitver}.
+}
+
+\maketitle
+
+\section{Introduction}
+
+The \textsf{gitver} package gets a description of the current git version of this
+document and store it in a command |\gitVer|. If memoir or fancyhdr are in use, it
+will also add this to the document footers unless the option "noheader" is
+passed.
+
+It also defines a command |\versionBox| which outputs a box containing the
+version and date of compilation.
+
+For this to work, you must have git installed and available on the command
+line, this document must be part of a git repository, and latex must be
+running in "shell escape" mode. This can be enabled by passing \textsf{--shell-escape}
+on the command line when compiling your docuemnt, or will be available in the
+options of whatever GUI you're using (try Googling).
+
+Note that it's a good idea to tell git to ignore all the latex auxilary files,
+otherwise your version will always be ``dirty''. Try the \textsf{.gitignore} file from
+\url{https://www.gitignore.io/api/latex} if you don't already have
+one.
+
+The package is released ``as is'' with no warranty under the LaTeX Project Public
+License, version 1.3.
+
+\section{Usage}
+
+\subsection{Macros} % (fold)
+\label{sub:macros}
+
+% subsection macros (end)
+
+\DescribeMacro{\gitVer}
+%
+The main point of this package, the command |\gitVer| prints a string of text describing the current revision of this git repository. Use like so:
+\begin{quote}
+ The current version of this repository is ``|\gitVer{}|''.
+\end{quote}
+which compiles to
+\begin{quote}
+ The current version of this repository is ``\gitVer{}''.
+\end{quote}
+
+\DescribeMacro{\versionBox}
+Alternatively, you can use a |\versionBox|, most commonly in the footer:
+\begin{quote}
+ |\versionBox{}|
+\end{quote}
+%
+gives the output:
+\vspace{3mm}
+
+\versionBox{}
+
+\subsection{Footers} % (fold)
+\label{sub:footers}
+
+By default, \textsf{gitver} will try to place a |\versionBox| into the footer of your document. If you're using the |memoir| class or the |fancyhdr| package, this will happen automatically. This document has these footers enabled: have a look at the bottom of this page for an example.
+
+\DescribeMacro{noheader}
+You can disable the headers by adding the option |noheader| to the package call.
+
+If you include |gitver| without either of |memoir| or |fancyhdr| loaded, it will complain. To suppress this complaint, pass the |noheader| option.
+
+To customise the header / footer behavior, pass |noheader| and then use a combination of |\versionBox| and |\gitVer| to make your own headers/footers.
+
+% subsection footers (end)
+
+\subsection{Metadata} % (fold)
+\label{sub:metadata}
+
+\DescribeMacro{nopdfinfo}
+By default, this package also adds the git tag to to pdf document's metadata under the subject field. To disable this behaviour, pass the option |nopdfinfo|.
+
+% subsection metadata (end)
+
+\end{document}