Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2016 by Philippe Faist <[email protected]>
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3 or later is part of all distributions of LaTeX
14 % version 2005/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{phfsvnwatermark.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
23 %<package>\ProvidesPackage{phfsvnwatermark}
24 %<*package>
25 [2016/08/15 v1.0 phfsvnwatermark package]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{xcolor}
31 \usepackage[id=svn-multi,watermark=false]{phfsvnwatermark}
32 \svnid{$Id$}
33 \usepackage[preset=xpkgdoc]{phfnote}
34 \EnableCrossrefs
35 \CodelineIndex
36 \RecordChanges
37 \begin{document}
38 \DocInput{phfsvnwatermark.dtx}
39 \end{document}
40 %</driver>
41 % \fi
42 %
43 % \CheckSum{0}
44 %
45 % \CharacterTable
46 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
47 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
48 % Digits \0\1\2\3\4\5\6\7\8\9
49 % Exclamation \! Double quote \" Hash (number) \#
50 % Dollar \$ Percent \% Ampersand \&
51 % Acute accent \' Left paren \( Right paren \)
52 % Asterisk \* Plus \+ Comma \,
53 % Minus \- Point \. Solidus \/
54 % Colon \: Semicolon \; Less than \<
55 % Equals \= Greater than \> Question mark \?
56 % Commercial at \@ Left bracket \[ Backslash \\
57 % Right bracket \] Circumflex \^ Underscore \_
58 % Grave accent \` Left brace \{ Vertical bar \|
59 % Right brace \} Tilde \~}
60 %
61 %
62 % \changes{v1.0}{2016/05/03}{Initial version}
63 %
64 % \GetFileInfo{phfsvnwatermark.dtx}
65 %
66 % \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef,\xdef,\if,\else,\fi,\ifx}
67 %
68 % \title{\phfqitltxPkgTitle{phfsvnwatermark}}
69 % \author{Philippe Faist\quad\email{[email protected]}}
70 % \date{\pkgfmtdate\filedate}
71 % \maketitle
72 %
73 % \begin{abstract}
74 % \pkgname{phfsvnwatermark}---Add a watermark on each page with version control
75 % information from SVN.
76 % \end{abstract}
77 %
78 % \inlinetoc
79 %
80 % \section{Introduction}
81 %
82 % This package allows you to add version control information as a gray watermark on each
83 % page of your document.
84 %
85 % The watermark may be placed automatically on each page, or its placement may be
86 % controlled manually by the user.
87 %
88 % It is based on reading SVN keywords from your source file (e.g.\@ |$Id$|, which SVN
89 % expands upon the following commit to |$Id: file.tex ... $|). The tags are read with
90 % either the \pkgname{svn} or \pkgname{svn-multi} packages (at your option).
91 %
92 % There is also decent support for multiple files, with \pkgname{svn-multi} and
93 % \pkgname{currfile}. This allows to both display overall document version information as
94 % well as information for the current file.
95 %
96 %
97 % \section{SVN Identification Methods}
98 %
99 % The SVN version of the input file(s) is read with the help of SVN keyword |$Id$|. (The
100 % \pkgname{svn} package may also read |$Date$| and |$Author$|, I'm not sure any more [TODO: CHECK].)
101 %
102 % Don't forget to enable source keyword expansion for your \LaTeX{} source(s). This is
103 % done with the help of the command:
104 % \begin{verbatim}
105 % svn propset svn:keywords "Id Date Author" my-file.tex
106 % \end{verbatim}
107 %
108 % You must specify an identification method with the package option |id=|\meta{method}.
109 %
110 % \begin{pkgoptions}
111 % \item[id=svn] Read the keywords with the \pkgname{svn} package. Keywords are set in the
112 % file with the command |\SVN $Id$|. (The |$Id$| keyword contains all the relevant
113 % information and only this one needs to be set.) See below.
114 % \item[id=gitnotsvn] Read the keywords with the \pkgname{svn} pacakge. However, a script
115 % is used to fake these tags from what are in fact GIT meta-information. This causes
116 % |$Id$| not to contain all the information, and the |$Date$| and |$Author$| tags must
117 % be read and included in the watermark, as well. See below.
118 % \item[id=svn-multi] Read the keywords with the \pkgname{svn-multi} package. The ID
119 % information is set with the command |\svnid{$Id$}|. (The |$Id$| keyword contains all
120 % the relevant information.) See below.
121 % \item[id=svn-multi-currfile] Read the keywords with the \pkgname{svn-multi} package, with
122 % \pkgname{currfile} support. Ideal for a document with multiple source files which are
123 % |\input| into each other. The ID information is set in each file with the command
124 % |\svnid{$Id$}|. (The |$Id$| keyword contains all the relevant information.) See
125 % below.
126 % \end{pkgoptions}
127 %
128 % In each case, the relevant SVN package is automatically loaded \pkgname{svn},
129 % \pkgname{svn-multi} and/or \pkgname{currfile}.
130 %
131 %
132 % \subsection{SVN Keywords read with the \pkgname{svn} package}
133 %
134 %
135 % Probably the most straightforward solution. Just introduce in your \LaTeX{} source
136 % file, somewhere near the top, the line:
137 % \begin{verbatim}
138 % \SVN $Id$
139 % \end{verbatim}
140 %
141 % Don't forget to enable source keyword expansion for this \LaTeX{} file, and next time
142 % you commit your file to SVN, the |$Id$| tag will be replaced by something like:
143 % \begin{verbatim}
144 % \SVN $Id: thesis.tex 1488 2016-05-03 16:19:34Z pfaist $
145 % \end{verbatim}
146 % which identifies the file version.
147 %
148 %
149 %
150 % \subsection{GIT information faked as SVN keywords and read with the \pkgname{svn} package}
151 %
152 % \begin{pkgwarning}
153 % This method is buggy, and keywords won't always get updated. I'm currently seeking a
154 % better method. Unfortunately all methods for obtaining GIT meta-data require running
155 % GIT hooks or auxiliary scripts.
156 %
157 % To force update the GIT keywords, make sure you file has no local modifications,
158 % delete the file and run |git checkout |\meta{file}.
159 % \end{pkgwarning}
160 %
161 % The idea is to use the same keyword parsing engine, with the \pkgname{svn} package, but
162 % to plug in the GIT meta-information instead inside faked svn keyword tags.
163 %
164 % In your source file, add the lines
165 % \begin{verbatim}
166 % \SVN $Id$
167 % \SVN $Date$
168 % \SVN $Author$
169 % \end{verbatim}
170 %
171 % And then, with the additional GIT configuration described below, these keywords will be
172 % expanded to the hash of the file contents (and not the commit, this may be misleading!),
173 % the date of the commit and the author.
174 %
175 % In order to set up GIT for this, add to the |.gitattribtes| file (create it in the
176 % repository directory if necessary):
177 % \begin{verbatim}
178 % *.tex ident filter=rcs-keyword
179 % \end{verbatim}
180 %
181 % Then copy the following code, and paste it at the end of your |REPO/.git/config| or
182 % |HOME/.gitconfig|:
183 % \begin{samepage}
184 % \begin{verbatim}
185 % [filter "rcs-keyword"]
186 % clean = perl -pwe \"s/\\\\\\$(Date|Author)[^\\\\\\$]*\\\\\\$/\\\\\\$\\$1\\\\\\$/\"
187 % smudge = "echo >&2 'Applying RCS filter rules on '%f'.' && perl -we \
188 % \"\\$f=%f; use Date::Parse; use POSIX;\
189 % chomp(\\$author=\\`git log -1 --format=format:%ae -- \\$f\\`);\
190 % chomp(\\$gitdate=\\`git log -1 --format=format:%aD -- \\$f\\`);\
191 % \\$date=POSIX::strftime('%Y-%m-%d %H:%M:%S %z (%a, %e %b %Y)',\
192 % localtime(str2time(\\$gitdate)));\
193 % print STDERR \\\"formatted date: \\$date\\\\n\\\";\
194 % while (<>) {\
195 % s/\\\\\\$Date[^\\\\\\$]*\\\\\\$/'\\$Date: '.\\$date.' \\$'/e;\
196 % s/\\\\\\$Author[^\\\\\\$]*\\\\\\$/'\\$Author: '.\\$author.' \\$'/e;\
197 % print \\$_; }\""
198 % \end{verbatim}
199 % \end{samepage}
200 %
201 % \subsection{SVN Keywords read with the \pkgname{svn-multi} package}
202 %
203 % The \pkgname{svn-multi} package is an alternative, more powerful, package for parsing SVN
204 % keywords.
205 %
206 % Add near the top of your files the command
207 % \begin{verbatim}
208 % \svnid{$Id$}
209 % \end{verbatim}
210 % and make sure keyword expansion is enabled in your source files.
211 %
212 %
213 % \subsection{SVN Keywords read with the \pkgname{svn-multi} package, with \pkgname{currfile} support}
214 %
215 % This method is the same as for the |id=svn-multi| method with the \pkgname{svn-multi}
216 % package, but with added support for multiple files.
217 %
218 % Now, the watermark displays \emph{two} lines, with the overall document version
219 % information, and the version information of the current file.
220 %
221 %
222 %
223 % \section{Placement of the Watermark}
224 %
225 % First, there is a master switch for enabling or disabling the watermark. In either
226 % case, the relevant SVN-related package is loaded anyway, to allow files to provide their
227 % meta-information regardless of whether the watermark is displayed or not.
228 % \begin{pkgoptions}
229 % \item[watermark=true] Show the watermark with the ID information.
230 % \item[watermark=false] Do not show the watermark with the ID information. (Note that
231 % manually placed watermarks are not affected by this option.)
232 % \end{pkgoptions}
233 %
234 %
235 % \begin{pkgoptions}
236 % \item[placement=shipout] Place the watermark at the bottom of each page;
237 % \item[placement=manual] Don't place the watermark anywhere automatically; the user is
238 % responsible for placing it with a call to |\phfsvnVersionIdTag| wherever they want.
239 % \end{pkgoptions}
240 %
241 % \subsection{Watermark on each page}
242 %
243 % With the |placement=shipout| option, the watermark is automatically added on each page.
244 %
245 % \DescribeMacro{\phfsvnShipoutWatermarkXposRight}
246 % \DescribeMacro{\phfsvnShipoutWatermarkYposBaseline} \null\par\vspace*{\baselineskip} The
247 % macros |\phfsvnShipoutWatermarkXposRight| and |\phfsvnShipoutWatermarkYposBaseline|
248 % determine the position of the watermark. They are macros which expand to a length, not
249 % lengths themselves. You may redefine them to adjust the placement of the watermark.
250 %
251 % \subsection{Manual placement}
252 %
253 % You may also opt to place the watermark manually on the page with the |placement=manual|
254 % option. Do this if you want the information to appear for example in a header or
255 % footer.
256 %
257 % \DescribeMacro{\phfsvnVersionIdTag}\DescribeMacro{\phfsvnVersionIdTag*} Places the ID
258 % tag immediately, at the given location. The starred version produces a box of zero
259 % width.
260 %
261 %
262 %
263 % \StopEventually{\PrintChangesAndIndex}
264 %
265 % \section{Implementation}
266 %
267 % Include useful packages.
268 % \begin{macrocode}
269 \RequirePackage{kvoptions}
270 \RequirePackage{calc}
271 % \end{macrocode}
272 %
273 %
274 % make sure the 'color' or 'xcolor' package is loaded
275 % \begin{macrocode}
276 \@ifpackageloaded{xcolor}{}{%
277 \@ifpackageloaded{color}{}{%
278 \RequirePackage{xcolor}%
279 }
280 }
281 % \end{macrocode}
282 %
283 %
284 % \subsection{Common Formatting of ID tag}
285 %
286 % common exterior formatting for Version ID tag.
287 %
288 % \begin{macrocode}
289 \definecolor{phfsvnversionidcolor}{rgb}{0.6,0.6,0.6}
290 \def\phfsvnVersionIdTagOuterFont{\normalfont\scriptsize}
291 \def\phfsvnVersionIdTagInnerFont{\ttfamily}
292 \def\phfsvn@versionidtag{%
293 \begingroup%
294 \color{phfsvnversionidcolor}\phfsvnVersionIdTagOuterFont%
295 [\,\begingroup\phfsvnVersionIdTagInnerFont%
296 {\phfsvn@versionidtag@contents}\endgroup\,]%
297 \endgroup%
298 }
299 % \end{macrocode}
300 %
301 %
302 % \begin{macro}{\phfsvnVersionIdTag}
303 % For manual placement. Starred version does not smash the thing.
304 % \begin{macrocode}
305 \newcommand\phfsvnVersionIdTag{%
306 \@ifstar\phfsvn@smashedsvnversionidtag\phfsvn@versionidtag
307 }
308 \def\phfsvn@smashedsvnversionidtag{%
309 \hspace*{0pt}\smash{\phfsvn@clap{\phfsvn@versionidtag}}
310 }
311 % \end{macrocode}
312 % \end{macro}
313 %
314 % Helper macro\footnote{see \url{https://www.tug.org/TUGboat/tb22-4/tb72perlS.pdf}}:
315 % \begin{macrocode}
316 \def\phfsvn@clap#1{\hbox to 0pt{\hss#1\hss}}
317 % \end{macrocode}
318 %
319 %
320 %
321 % \subsection{Definitions for the different SVN info engines}
322 %
323 % \begin{macro}{\phfsvn@versionidtag@contents@svn}
324 % \begin{macro}{\phfsvn@doincludesvn@svn}
325 % Definitions for method \phfverb{id=svn}:
326 % \begin{macrocode}
327 \def\phfsvn@versionidtag@contents@svn{%
328 \SVNId%
329 }
330 \def\phfsvn@doincludesvn@svn{
331 \RequirePackage{svn}
332 }
333 % \end{macrocode}
334 % \end{macro}
335 % \end{macro}
336 %
337 %
338 % \begin{macro}{\phfsvn@versionidtag@contents@gitnotsvn}
339 % \begin{macro}{\phfsvn@versionidtag@contents@gitnotsvn}
340 % Definitions for method \phfverb{id=gitnotsvn}. Use the \pkgname{svn}
341 % package because the files have fake SVN tags with in fact the GIT
342 % meta-info
343 % \begin{macrocode}
344 \def\phfsvn@versionidtag@contents@gitnotsvn{%
345 \SVNId\hspace*{1.5em}\SVNDate~\SVNTime\hspace*{1.5em}\SVNAuthor%
346 }
347 \def\phfsvn@doincludesvn@gitnotsvn{
348 \RequirePackage{svn}%
349 }
350 % \end{macrocode}
351 % \end{macro}
352 % \end{macro}
353 %
354 %
355 %
356 % \begin{macro}{\phfsvn@versionidtag@contents@svnmulti}
357 % \begin{macro}{\phfsvn@doinludesvn@svnmulti}
358 % Definitions for method \phfverb{id=svn-multi}:
359 % \begin{macrocode}
360 \def\phfsvn@versionidtag@contents@svnmulti{%
361 SVN Document Version:\hspace*{1ex}%
362 \svnmainfilename~r\svnrev~\svndate~\svnauthor%
363 }
364 \def\phfsvn@doincludesvn@svnmulti{
365 \PassOptionsToPackage{filehooks}{svn-multi}
366 \RequirePackage{svn-multi}
367 }
368 % \end{macrocode}
369 % \end{macro}
370 % \end{macro}
371 %
372 %
373 % \begin{macro}{\phfsvn@versionidtag@for@svnmulticurrfile}
374 % \begin{macro}{\phfsvn@doincludesvn@svnmulticurrfile}
375 % Definitions for method \phfverb{id=svn-multi-currfile}:
376 % \begin{macrocode}
377 \def\phfsvn@svnmulticurrfile@maxwidth{0.8\paperwidth}
378 \newsavebox\phfsvn@box@upperline
379 \newsavebox\phfsvn@box@lowerline
380 \def\phfsvn@svnmulticurrfile@upperline{%
381 SVN Document Version:\hspace{1.5ex}r\svnrev~\svndate~\svnauthor}%
382 \def\phfsvn@svnmulticurrfile@lowerline{%
383 \svnkw{Filename}:\hspace{1.5ex}r\svnfilerev~\svnfiledate~\svnfileauthor}%
384 \def\phfsvn@versionidtag@for@svnmulticurrfile{%
385 \begingroup%
386 \color{phfsvnversionidcolor}%
387 \phfsvnVersionIdTagOuterFont\phfsvnVersionIdTagInnerFont%
388 \sbox\phfsvn@box@upperline{\phfsvn@svnmulticurrfile@upperline}%
389 \sbox\phfsvn@box@lowerline{\phfsvn@svnmulticurrfile@lowerline}%
390 \begin{minipage}[t]{\minof{\phfsvn@svnmulticurrfile@maxwidth}%
391 {\maxof{\wd\phfsvn@box@upperline}{\wd\phfsvn@box@lowerline}}}%
392 \parindent=0pt\relax\parskip=0pt\relax%
393 \raggedleft%
394 % \end{macrocode}
395 % Don't just |\usebox| the saved boxes, because if the filenames are long we want to
396 % re-layout and allow line breaks:
397 % \begin{macrocode}
398 \par\phfsvn@svnmulticurrfile@upperline%
399 \par\phfsvn@svnmulticurrfile@lowerline%
400 \end{minipage}%
401 \endgroup%
402 }%
403 \def\phfsvn@doincludesvn@svnmulticurrfile{%
404 \RequirePackage{currfile}%
405 \RequirePackage[filehooks]{svn-multi}%
406 }%
407 % \end{macrocode}
408 % \end{macro}
409 % \end{macro}
410 %
411 %
412 % \subsection{Placement Methods}
413 %
414 % \begin{macro}{\phfsvn@doplace@shipout}
415 % The |shipout| placement method.
416 % \begin{macrocode}
417 \def\phfsvn@doplace@shipout{%
418 \RequirePackage{eso-pic}
419 \AddToShipoutPicture{%
420 \setlength{\@tempdimb}{\phfsvnShipoutWatermarkXposRight}%
421 \setlength{\@tempdimc}{\phfsvnShipoutWatermarkYposBaseline}%
422 \setlength{\unitlength}{1pt}%
423 \put(2,\strip@pt\@tempdimc){%
424 \makebox(\strip@pt\@tempdimb,0)[r]%
425 {\hfill\phfsvn@versionidtag}}%
426 }%
427 }
428 % \end{macrocode}
429 % \end{macro}
430 %
431 % \begin{macro}{\phfsvnShipoutWatermarkXposRight}
432 % \begin{macro}{\phfsvnShipoutWatermarkYposBaseline}
433 % Control the position of the watermark. These are proper macros which expand to a
434 % length; they are not declared as lengths directly. (This allows to calculate the
435 % lengths on the spot.)
436 % \begin{macrocode}
437 \def\phfsvnShipoutWatermarkXposRight{0.9\paperwidth}
438 \def\phfsvnShipoutWatermarkYposBaseline{0.05\paperheight}
439 % \end{macrocode}
440 % \end{macro}
441 % \end{macro}
442 %
443 % \begin{macro}{\phfsvn@doplace@manual}
444 % There is nothing to do for the |manual| placement, since the info is placed manually
445 % anyway. This macro is called by the package option treatment.
446 % \begin{macrocode}
447 \def\phfsvn@doplace@manual{}
448 % \end{macrocode}
449 % \end{macro}
450 %
451 %
452 %
453 % \subsection{Package Options \& Setup}
454 %
455 % \begin{macrocode}
456 \SetupKeyvalOptions{
457 family=phfsvn,
458 prefix=phfsvn@
459 }
460 % \end{macrocode}
461 %
462 % Setup code for a given ID method:
463 % \begin{macrocode}
464 \def\phfsvn@SetupForId#1{%
465 \ifcsname phfsvn@SetupForId@#1\endcsname%
466 \csname phfsvn@SetupForId@#1\endcsname%
467 \else%
468 \PackageError{phfsvn}{Unknown SvnId method: '#1'}%
469 \fi
470 }
471 \def\phfsvn@doincludesvn{}
472 \def\phfsvn@SetupForId@svn{
473 \message{phfsvn: Using SvnId method = svn}
474 \let\phfsvn@doincludesvn\phfsvn@doincludesvn@svn
475 \let\phfsvn@versionidtag@contents\phfsvn@versionidtag@contents@svn
476 }
477 \def\phfsvn@SetupForId@gitnotsvn{
478 \message{phfsvn: Using SvnId method = gitnotsvn}
479 \let\phfsvn@doincludesvn\phfsvn@doincludesvn@gitnotsvn
480 \let\phfsvn@versionidtag@contents\phfsvn@versionidtag@contents@gitnotsvn
481 }
482 \expandafter\def\csname phfsvn@SetupForId@svn-multi\endcsname{
483 \message{phfsvn: Using SvnId method = svn-multi}
484 \let\phfsvn@doincludesvn\phfsvn@doincludesvn@svnmulti
485 \let\phfsvn@versionidtag@contents\phfsvn@versionidtag@contents@svnmulti
486 }
487 \expandafter\def\csname phfsvn@SetupForId@svn-multi-currfile\endcsname{
488 \message{phfsvn: Using SvnId method = svn-multi-currfile}
489 \let\phfsvn@doincludesvn\phfsvn@doincludesvn@svnmulticurrfile
490 % redefine whole versionidtag, not only contents:
491 \let\phfsvn@versionidtag\phfsvn@versionidtag@for@svnmulticurrfile
492 }
493 \def\phfsvn@SetupForId@{% no ID method
494 \PackageWarning{phfsvn}{*** No SvnId method provided, no watermark will be displayed.}
495 \phfsvn@watermarkfalse
496 }
497 % \end{macrocode}
498 %
499 %
500 %
501 % Setup code for the placement:
502 % \begin{macrocode}
503 \def\phfsvn@SetupPlacement#1{%
504 \ifcsname phfsvn@doplace@#1\endcsname%
505 \csname phfsvn@doplace@#1\endcsname%
506 \else%
507 \PackageError{phfsvn}{Unknown placement method: '#1'}%
508 \fi
509 }
510 % \end{macrocode}
511 %
512 % Declare the |keyval| options:
513 %
514 % \begin{macrocode}
515 \DeclareStringOption[]{id}[svn]
516 \DeclareBoolOption[true]{watermark}
517 \DeclareStringOption[shipout]{placement}
518 \DeclareDefaultOption{%
519 % We provide the standard LaTeX error.
520 \@unknownoptionerror
521 }
522 % \end{macrocode}
523 %
524 %
525 % Process \& execute options:
526 % \begin{macrocode}
527 \ProcessKeyvalOptions*
528 % \end{macrocode}
529 %
530 %
531 % Now, take action according to the given options.
532 %
533 % Set up the correct ID method:
534 % \begin{macrocode}
535 \phfsvn@SetupForId{\phfsvn@id}
536 % \end{macrocode}
537 %
538 % Always include the relevant SVN package, so all files can have their meta-info tags
539 % regardless of whether the watermark is displayed or not:
540 % \begin{macrocode}
541 \phfsvn@doincludesvn
542 % \end{macrocode}
543 %
544 %
545 % Finish setting up, set up the watermark if we want it on.
546 % \begin{macrocode}
547 \ifphfsvn@watermark
548 \phfsvn@SetupPlacement{\phfsvn@placement}
549 \fi
550 % \end{macrocode}
551 %
552 %\Finale
553 \endinput