summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gitstatus/gitstatus.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/gitstatus/gitstatus.dtx')
-rw-r--r--macros/latex/contrib/gitstatus/gitstatus.dtx169
1 files changed, 169 insertions, 0 deletions
diff --git a/macros/latex/contrib/gitstatus/gitstatus.dtx b/macros/latex/contrib/gitstatus/gitstatus.dtx
new file mode 100644
index 0000000000..1d8fc04374
--- /dev/null
+++ b/macros/latex/contrib/gitstatus/gitstatus.dtx
@@ -0,0 +1,169 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2022 by Maximilian Gruber
+%
+% This file 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.
+%
+% \fi
+%
+%
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
+%<package>\ProvidesPackage{gitstatus}
+%<package> [2022/10/06 v1.1 Watermark Git Information Package]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[watermark]{gitstatus}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+%\OnlyDescription
+\begin{document}
+ \DocInput{gitstatus.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{0}
+%
+%
+% \changes{v1.1}{2022/10/06}{Initial version}
+%
+% \DoNotIndex{\CatchFileDef, \DeclareBoolOption, \DeclareComplementaryOption, \DeclareStringOption}
+% \DoNotIndex{\\, \def, \else, \fi, \IfFileExists, \iffalse, }
+% \DoNotIndex{\newwatermark, \texttt}
+% \DoNotIndex{\RequirePackage, \PackageWarning, \ProcessKeyvalOptions, \StrBehind, \StrGobbleRight}
+%
+% \GetFileInfo{gitstatus.sty}
+% \title{The \textsf{gitstatus} package\thanks{This document
+% corresponds to \textsf{gitstatus}~\fileversion,
+% dated~\filedate.}}
+% \author{Maximilian Gruber \\ \texttt{m.gruber@mailbox.org}}
+%
+% \maketitle
+%
+% \begin{abstract}
+% This package allows to include information about a git-repository into a document.
+% This information can be included like the watermark in this document or by the use of variables.
+% \end{abstract}
+%
+% \section{Introduction}
+% If your LaTeX-document is version-controlled with git, you might encounter situations, where you want to include some information of your git-repository into your LaTeX-document - e.g. to keep track on who gave you feedback on which version of your document.
+%
+% \section{Options}
+% \DescribeMacro{gitdir}
+% custom git dir (can be relative), (default is ".git/", meaning your LaTeX document is in the top level of your repo)
+%
+% \DescribeMacro{watermark}
+% watermark with branch + hash on top of page (default: don't use watermark)
+%
+% \DescribeMacro{nowatermark}
+% same as watermark=false
+%
+% \DescribeMacro{novariables}
+% disable creation of variables (default: false, hence variables are created)
+%
+%
+% \section{Variables}
+% Apart from the option to add a watermark at the top of the page that mentions the current commit hash and branch-name, the package also provides variables with the same information for individual use.
+% These variables are:
+% \DescribeMacro{\gitdir}
+% The directory of the git repository.
+%
+% \DescribeMacro{\gitcommit}
+% The hash of the most recent commit of the current branch.
+%
+% \DescribeMacro{\gitbranch}
+% The name of the current branch.
+%
+%
+% \StopEventually{\PrintChanges}
+%
+% \section{Implementation}
+%
+% \subsection{Required Packages}
+% The package relies on five other packages. Three are listed here, the other two are only required if a watermark is created.
+% \begin{macrocode}
+\RequirePackage{kvoptions}
+\RequirePackage{catchfile}
+\RequirePackage{xstring}
+% \end{macrocode}
+%
+% \subsection{Options}
+% The options are defined.
+% \begin{macrocode}
+\DeclareStringOption[.git/]{gitdir} % custom git dir (can be relative)
+\DeclareBoolOption[false]{watermark} % watermark with branch + hash on top of page
+\DeclareComplementaryOption{nowatermark}{watermark}
+\DeclareBoolOption[false]{novariables} % disable creation of variables
+\ProcessKeyvalOptions*
+% \end{macrocode}
+%
+%
+% \subsection{Getting Git Information}
+% Git information is read directly from the files within the specified git-directory.
+%
+% \subsubsection{Branch Name}
+% Branch is read from HEAD.
+% \begin{macrocode}
+\def\gitstatus@headpath{\gitstatus@gitdir HEAD}
+\IfFileExists{\gitstatus@headpath}{
+ \CatchFileDef{\gitstatus@headfull}{\gitstatus@headpath}{}
+ \StrGobbleRight{\gitstatus@headfull}{1}[\gitstatus@head]
+ \StrBehind[2]{\gitstatus@head}{/}[\gitstatus@branch]
+}{
+ \def\gitstatus@branch{NOT AVAILABLE}
+ \PackageWarning{gitstatus}{Can't find HEAD (maybe check specified gitdir).}
+}
+% \end{macrocode}
+%
+% \subsubsection{Commit Hash}
+% Commit-Hash is read from refs/heads/<branch-name>.
+% \begin{macrocode}
+\def\gitstatus@branchpath{\gitstatus@gitdir refs/heads/\gitstatus@branch}
+\IfFileExists{\gitstatus@branchpath}{
+ \CatchFileDef{\gitstatus@commit}{\gitstatus@branchpath}{}
+}{
+ \def\gitstatus@commit{NOT AVAILABLE}
+ \PackageWarning{gitstatus}{Can't read commit hash (maybe check specified gitdir).}
+}
+% \end{macrocode}
+%
+% \subsection{Defining Local Variables}
+% Make directory, branch and hash available outside of package
+% \begin{macrocode}
+\ifgitstatus@novariables
+\else
+ \def\gitdir{\gitstatus@gitdir}
+ \def\gitbranch{\gitstatus@branch}
+ \def\gitcommit{\gitstatus@commit}
+\fi
+% \end{macrocode}
+%
+% \subsection{Creating Watermark}
+% Include git information as watermark.
+% \begin{macrocode}
+\ifgitstatus@watermark
+ \RequirePackage{xcolor}
+ \RequirePackage[printwatermark]{xwatermark}
+ \newwatermark
+ [allpages,color=black!20,angle=0,scale=0.5,align=left,xpos=-2cm,ypos=13cm]
+ {On branch: \texttt{\gitstatus@branch}\\ Commit: \texttt{\gitstatus@commit}}
+\fi
+% \end{macrocode}
+%
+% \PrintIndex
+%
+% \Finale
+\endinput