Debian Codegraph @

texmf-dist/source/latex/gitstatus/gitstatus.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2022 by Maximilian Gruber
4 %
5 % This file may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either
7 % version 1.3 of this license or (at your option) any later
8 % version. The latest version of this license is in:
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % and version 1.3 or later is part of all distributions of
13 % LaTeX version 2005/12/01 or later.
14 %
15 % \fi
16 %
17 %
18 % \iffalse
19 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
20 %<package>\ProvidesPackage{gitstatus}
21 %<package> [2022/10/06 v1.1 Watermark Git Information Package]
22 %
23 %<*driver>
24 \documentclass{ltxdoc}
25 \usepackage[watermark]{gitstatus}
26 \usepackage[utf8]{inputenc}
27 \usepackage[T1]{fontenc}
28 \EnableCrossrefs
29 \CodelineIndex
30 \RecordChanges
31 %\OnlyDescription
32 \begin{document}
33 \DocInput{gitstatus.dtx}
34 \end{document}
35 %</driver>
36 % \fi
37 %
38 % \CheckSum{0}
39 %
40 %
41 % \changes{v1.1}{2022/10/06}{Initial version}
42 %
43 % \DoNotIndex{\CatchFileDef, \DeclareBoolOption, \DeclareComplementaryOption, \DeclareStringOption}
44 % \DoNotIndex{\\, \def, \else, \fi, \IfFileExists, \iffalse, }
45 % \DoNotIndex{\newwatermark, \texttt}
46 % \DoNotIndex{\RequirePackage, \PackageWarning, \ProcessKeyvalOptions, \StrBehind, \StrGobbleRight}
47 %
48 % \GetFileInfo{gitstatus.sty}
49 % \title{The \textsf{gitstatus} package\thanks{This document
50 % corresponds to \textsf{gitstatus}~\fileversion,
51 % dated~\filedate.}}
52 % \author{Maximilian Gruber \\ \texttt{[email protected]}}
53 %
54 % \maketitle
55 %
56 % \begin{abstract}
57 % This package allows to include information about a git-repository into a document.
58 % This information can be included like the watermark in this document or by the use of variables.
59 % \end{abstract}
60 %
61 % \section{Introduction}
62 % 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.
63 %
64 % \section{Options}
65 % \DescribeMacro{gitdir}
66 % custom git dir (can be relative), (default is ".git/", meaning your LaTeX document is in the top level of your repo)
67 %
68 % \DescribeMacro{watermark}
69 % watermark with branch + hash on top of page (default: don't use watermark)
70 %
71 % \DescribeMacro{nowatermark}
72 % same as watermark=false
73 %
74 % \DescribeMacro{novariables}
75 % disable creation of variables (default: false, hence variables are created)
76 %
77 %
78 % \section{Variables}
79 % 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.
80 % These variables are:
81 % \DescribeMacro{\gitdir}
82 % The directory of the git repository.
83 %
84 % \DescribeMacro{\gitcommit}
85 % The hash of the most recent commit of the current branch.
86 %
87 % \DescribeMacro{\gitbranch}
88 % The name of the current branch.
89 %
90 %
91 % \StopEventually{\PrintChanges}
92 %
93 % \section{Implementation}
94 %
95 % \subsection{Required Packages}
96 % The package relies on five other packages. Three are listed here, the other two are only required if a watermark is created.
97 % \begin{macrocode}
98 \RequirePackage{kvoptions}
99 \RequirePackage{catchfile}
100 \RequirePackage{xstring}
101 % \end{macrocode}
102 %
103 % \subsection{Options}
104 % The options are defined.
105 % \begin{macrocode}
106 \DeclareStringOption[.git/]{gitdir} % custom git dir (can be relative)
107 \DeclareBoolOption[false]{watermark} % watermark with branch + hash on top of page
108 \DeclareComplementaryOption{nowatermark}{watermark}
109 \DeclareBoolOption[false]{novariables} % disable creation of variables
110 \ProcessKeyvalOptions*
111 % \end{macrocode}
112 %
113 %
114 % \subsection{Getting Git Information}
115 % Git information is read directly from the files within the specified git-directory.
116 %
117 % \subsubsection{Branch Name}
118 % Branch is read from HEAD.
119 % \begin{macrocode}
120 \def\gitstatus@headpath{\gitstatus@gitdir HEAD}
121 \IfFileExists{\gitstatus@headpath}{
122 \CatchFileDef{\gitstatus@headfull}{\gitstatus@headpath}{}
123 \StrGobbleRight{\gitstatus@headfull}{1}[\gitstatus@head]
124 \StrBehind[2]{\gitstatus@head}{/}[\gitstatus@branch]
125 }{
126 \def\gitstatus@branch{NOT AVAILABLE}
127 \PackageWarning{gitstatus}{Can't find HEAD (maybe check specified gitdir).}
128 }
129 % \end{macrocode}
130 %
131 % \subsubsection{Commit Hash}
132 % Commit-Hash is read from refs/heads/<branch-name>.
133 % \begin{macrocode}
134 \def\gitstatus@branchpath{\gitstatus@gitdir refs/heads/\gitstatus@branch}
135 \IfFileExists{\gitstatus@branchpath}{
136 \CatchFileDef{\gitstatus@commit}{\gitstatus@branchpath}{}
137 }{
138 \def\gitstatus@commit{NOT AVAILABLE}
139 \PackageWarning{gitstatus}{Can't read commit hash (maybe check specified gitdir).}
140 }
141 % \end{macrocode}
142 %
143 % \subsection{Defining Local Variables}
144 % Make directory, branch and hash available outside of package
145 % \begin{macrocode}
146 \ifgitstatus@novariables
147 \else
148 \def\gitdir{\gitstatus@gitdir}
149 \def\gitbranch{\gitstatus@branch}
150 \def\gitcommit{\gitstatus@commit}
151 \fi
152 % \end{macrocode}
153 %
154 % \subsection{Creating Watermark}
155 % Include git information as watermark.
156 % \begin{macrocode}
157 \ifgitstatus@watermark
158 \RequirePackage{xcolor}
159 \RequirePackage[printwatermark]{xwatermark}
160 \newwatermark
161 [allpages,color=black!20,angle=0,scale=0.5,align=left,xpos=-2cm,ypos=13cm]
162 {On branch: \texttt{\gitstatus@branch}\\ Commit: \texttt{\gitstatus@commit}}
163 \fi
164 % \end{macrocode}
165 %
166 % \PrintIndex
167 %
168 % \Finale
169 \endinput