summaryrefslogtreecommitdiff
path: root/support/vc/vc-manual.tex
blob: dd203fe7e605daec73027204ee754faa58e62866 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
\documentclass[11pt]{article}
\usepackage[ansinew]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{textcomp}
\usepackage{tabularx}
\usepackage{booktabs}
\usepackage{multicol}

\immediate\write18{sh ./vc}
\input{vc}
\usepackage[rgb,x11names]{xcolor}
\usepackage{prelim2e}
\renewcommand*{\PrelimWords}{\textnormal{\small The \pkg\ bundle}}
\renewcommand*{\PrelimText}{\textnormal{\small\textcolor{black!40}{\PrelimWords,
      \VCAuthor\ -- \VCDateISO\ -- commit \texttt{\VCRevision}}}}

\usepackage{listings}
\lstloadlanguages{[LaTeX]TeX, sh}
\colorlet{lstcolTeX}{green!50!black}
\colorlet{lstcoltext}{black}
\colorlet{lstcolshell}{blue!50!black}
\lstset{basicstyle=\small\ttfamily, keywordstyle={}, commentstyle={},
  columns=flexible, showspaces=false, showstringspaces=false,
  aboveskip=12pt, belowskip=12pt, frame=tb,
  framesep=8pt, framerule=2pt, xleftmargin=10pt,
  xrightmargin=10pt, framexleftmargin=10pt, framexrightmargin=10pt
}
\lstdefinestyle{shell}{language=sh, rulecolor=\color{lstcolshell!25}}
\lstdefinestyle{TeX}{language=TeX, rulecolor=\color{lstcolTeX!25}}
\lstdefinestyle{text}{language=TeX, rulecolor=\color{lstcoltext!25}}
\lstnewenvironment{listing}[1][]
{\lstset{#1}}
{}
\newlength{\sbslistingwd}
\setlength{\sbslistingwd}{.48\linewidth}

\usepackage{hyperref}
\hypersetup{
  pdftitle={The vc bundle},
  pdfauthor={Roland Hieber, Stephan Hennig}
}
\hypersetup{
  pdfstartview={XYZ null null null},% Zoom factor is determined by viewer.
  colorlinks,
  linkcolor=RoyalBlue3,
  urlcolor=Chocolate4,
  citecolor=SpringGreen3
}

\newcommand*{\pkg}{\texttt{vc}}
\newcommand*{\pkgversion}{v0.6}
\newcommand*{\descr}[1]{$\langle$#1$\rangle$}
\newcommand*{\full}{\makebox[0pt][r]{${}^{\mbox{\footnotesize\textasteriskcentered}}$}}
\begin{document}
\author{Roland Hieber\thanks{rohieb+ctan@rohieb.name} \and
    Stephan Hennig\thanks{stephanhennig@arcor.de}}
\title{The \pkg\ bundle\thanks{This document describes the \pkg\ bundle
    \pkgversion}}
\maketitle
\begin{abstract}
  This is a script based approach to version control for \TeX\
  documents.  It works more reliably than keyword substitution based
  approaches, since it tracks \emph{all} files in a working copy, not
  only \texttt{.tex} files.  The \pkg\ bundle works with \LaTeX\ and
  plain \TeX.  Currently, Bazaar, Git, Mercurial and Subversion are supported.
\end{abstract}
\begin{multicols}{2}
\tableofcontents
\end{multicols}



\section{Introduction}
There is an inherent problem with \LaTeX\ and version control software
as soon as you're dealing with files generated by an external tool,
\emph{e.g.}, graphics.  Packages such as \texttt{svn-multi} can't track
neither binary files, nor source files of graphics compiled by,
\emph{e.g.}, MetaPost.  For that reason, if you check-in a new revision
that only touches a graphic file, your VCS package would never know a
check-in has happened and tell you the old revision number (or date or
other meta data) in your documents.

At least, the problem is only of temporary nature and as soon as you
check-in a file that is tracked by the VCS package, \emph{i.e.}, a
\texttt{.tex} file, you'll get the correct revision number again.  But
traditional VCS packages, that build on the keyword substitution feature
provided by some VCS can't track revision information \emph{reliably},
as they look at \texttt{.tex} files only.

To enable reliable tracking of revision information one has to look at
\emph{all} files in a working copy.  Since for non-source files the
keyword substitution feature doesn't work, another approach has been
taken here.  This bundle consists of some scripts that directly talk
with the VCS backend to get the desired information and write them to a
file \texttt{vc.tex}.  This file can then be included into your document
sources.

The \pkg\ bundle works with \LaTeX\ as well as plain \TeX.  Currently,
Bazaar, Git, Mercurial and Subversion are supported.  Additional contributions are
welcome!



\section{Usage}
\label{sec:usage}
Doing version control with the \pkg\ bundle is very easy.  While for
other \LaTeX\ VCS packages you need to activate keyword substitution and
modify all \texttt{.tex} source files, these steps aren't necessary for
the \pkg\ bundle.  You just have to copy two files to your project's
working copy and add one line to your \TeX\ preamble.


\subsection{Installation}
\label{sec:installation}
Ok, lets set-up the project repository.  As a prerequisite, the scripts
of the \pkg\ bundle need \texttt{GNU awk}.  Please install this first.%
\footnote{For Windows you can find \texttt{gawk} in the
  \texttt{GNUWin32} utilities.  Alternative ports can be found in
  \texttt{Msys} or \texttt{Cygwin}.} %

The \pkg\ bundle consists of three files: a shell script, an AWK script,
and an automatically generated \TeX\ file.  For Unix and Windows the set
of files might be\newline
\begin{minipage}{\textwidth}
  \begin{minipage}[t]{\sbslistingwd}
    \begin{listing}[style=text, title=Unix\strut]
vc
vc-bzr.awk
vc.tex
    \end{listing}
  \end{minipage}\hfill
  \begin{minipage}[t]{\sbslistingwd}
    \begin{listing}[style=text, title=Windows\strut]
vc.bat
vc-bzr.awk
vc.tex
    \end{listing}
  \end{minipage}
\end{minipage}
Note, depending on your VCS the AWK script might be any of
\texttt{vc-bzr.awk}, \texttt{vc-git.awk}, \texttt{vc-hg.awk} or \texttt{vc-svn.awk}.
Additionally, while the AWK scripts have the same names on Unix and
Windows, the \pkg\ bundle provides them with different line endings.
So, watch out to take the right one for your VCS and~OS.

Installation is a one-step procedure (with two additional optional
steps).
\begin{enumerate}
\item Copy the two script files\newline
  \begin{tabular}{l@{\hspace{5em}}l}
    \textbullet~\texttt{vc} & (or \texttt{vc.bat} for Windows)\\
    \textbullet~\texttt{vc-bzr.awk} & (or \texttt{vc-git.awk} or \texttt{vc-hg.awk} or \texttt{vc-svn.awk})\\
  \end{tabular}\newline
  into the top-level directory of your project's working copy.

\item \emph{(Optionally)} You can instruct your VCS software to ignore
  all three \texttt{vc} related files.  Please consult the manual of
  your VCS software about this.  Question~\ref{vcIgnoreFiles} in
  Section~\ref{sec:qa} contains some brief instructions for Bazaar, Git, Mercurial
  and Subversion, too.

\item \emph{(Optionally)} Personally, the author is used to check-in
  both scripts into each project repository to have them available when
  they are needed and ignore file \texttt{vc.tex} only.
\end{enumerate}


\subsection{Preparing documents}
\label{sec:preparing}
What remains to be done is adding this line 
\begin{listing}[style=TeX]
\input{vc}
\end{listing}
to your main \LaTeX\ or plain \TeX\ document.  That's it.

\emph{Congratulations!}  You have now access to several macros
containing VCS information in your \TeX\ document.  The general macros
available are shown in table~\ref{tab:vcmacros}.

\begin{table}
  \centering\small
  \begin{tabularx}{\textwidth}{l>{\raggedright\arraybackslash}X}
    macro & meaning\\\addlinespace \toprule\addlinespace
    \verb+\VCRevision+    & current (maximum) working copy revision number\\
    \verb+\VCAuthor+      & author of the last check-in operation\\
    \verb+\VCDateRAW+     & date of last check-in in native format of the VCS software\\
    \verb+\VCDateISO+     & date of last check-in in ISO format YYYY-MM-DD\\
    \verb+\VCDateTEX+     & date of last check-in in \TeX\ format YYYY/MM/DD\\
    \verb+\VCTime+        & time of last check-in\\
    \verb+\VCRevisionMod+ & as \verb+\VCRevision+, but with an additional note if the working copy contains modified files\\
    \verb+\VCModifiedText+& contains the note shown in macro \verb+\VCRevisionMod+ if there were modified files.  This macro can be redefined by the user.\\
    \verb+\VCModified+    & \verb+0+ if there are no modified files in the working copy directory; \verb+1+ or \verb+2+ if there are modified files.  In general you don't need this macro.\\
  \end{tabularx}
  \caption{General version control macros.}
  \label{tab:vcmacros}
\end{table}

The most prominent information is probably the revision number, that can
be found in macro \verb+\VCRevision+.  For Bazaar and Subversion this is
a plain number, for Git it is a 7-hexdigit hash (the truncated
40-hexdigit SHA1 commit hash), for Mercurial it is a 12-hexdigit hash (truncated from 40 symbols).  Another macro that might be of interest
is \verb+\VCRevisionMod+.  This macro is discussed in detail in
appendix~\ref{sec:localmod}.

The remaining macros found in table~\ref{tab:vcmacros} contain author,
date (in different formats) and time of the last commit and should be
straightforward to use.

The above mentioned macros are available for all supported systems and
in general should be sufficient.  However, depending on the VCS software
you are using, there might be additional meta data available.%
\footnote{Such as the complete 40-hexdigit SHA1 commit hash for Git or Mercurial.}
Those data are stored in other macros that are discussed in
appendix~\ref{sec:notes}.


\subsection{Compiling documents}
\label{sec:compiling}
Before file \texttt{vc.tex} can be loaded in the document preamble, it
needs to be generated.  Doing that is as easy as running the shell
script \texttt{vc} -- or \texttt{vc.bat} for Windows -- before (La)\TeX.
There are three ways to do this:
\begin{enumerate}
\item from a \texttt{Makefile} -- this is the preferred method,
\item via \verb+\write18+ -- another automatic solution,
\item manually -- not recommended (inconvenient and error-prone).
\end{enumerate}

Here's how the script can be called from within a \LaTeX\ run via the
\verb+\write18+ feature.  Add the two lines\newline
\begin{minipage}{\textwidth}
  \begin{minipage}[t]{\sbslistingwd}
    \begin{listing}[style=TeX, title=Unix\strut]
\immediate\write18{sh ./vc}
\input{vc}
    \end{listing}
  \end{minipage}\hfill
  \begin{minipage}[t]{\sbslistingwd}
    \begin{listing}[style=TeX, title=Windows\strut]
\immediate\write18{vc.bat}
\input{vc}
    \end{listing}
  \end{minipage}
\end{minipage}
to your document.  If \LaTeX\ sees the first line, it immediately
executes the argument of \verb+\write18+ on the command-line.  That is,
the script \texttt{vc} -- or \texttt{vc.bat} -- is executed and file
\texttt{vc.tex} is updated.  On the second line \LaTeX\ reads-in the
newly generated file \texttt{vc.tex}.

To make this work the \verb+\write18+ feature has to be enabled.  By
default, it is disabled for security reasons.  For MiK\TeX\
\verb+\write18+ can be enabled by calling \LaTeX\ via
\begin{listing}[style=shell, escapechar=\#]
> latex -enable-write18 #\descr{document}#
\end{listing}
For other \LaTeX\ distributions, please consult the documentation.

The \verb+\write18+ feature is not relevant if \texttt{vc} is called by
a \texttt{Makefile}.

\nobreak
\bigskip
\nobreak
\begingroup
\raggedright
\itshape
Happy \TeX ing!\par
Stephan Hennig
\endgroup


\appendix
\section{Notes on supported VCS}
\label{sec:notes}

\emph{To be completed.}  VCS specific macros are prefixed \verb+\BZR+,
\verb+\GIT+, \verb+\HG+ or \verb+\SVN+.  Tables~\ref{tab:vcBZRmacros}
to~\ref{tab:vcSVNmacros} show the additional macros available, depending
on your VCS.

The macros marked by an asterisk might contains sensitive information
such as the path to a repository, file names, \emph{etc.}  These macros
are only written to file \texttt{vc.tex} in \emph{full mode}.  By
default, full mode is disabled.  That is, distributing file
\texttt{vc.tex} along with your \TeX\ source files should be fairly
save, by default.

To activate full mode script \texttt{vc} has to be called with
command-line option~\verb+-f+.  This option should only be used with
care.

\begin{table}[p]
  \centering\small
  \begin{tabularx}{\textwidth}{p{12em}>{\raggedright\arraybackslash}X}
    macro & meaning\\\addlinespace \toprule\addlinespace
    \full\verb+\BZRBranchNick+ & branch nickname\\
    \verb+\BZRRevisionId+ & full revision id\\
    \verb+\BZRDate+ & date of the last revision\\
    \verb+\BZRBuildDate+ & current date\\
    \verb+\BZRRevNo+ & revision number\\
  \end{tabularx}
  \caption{Bazaar specific version control macros.}
  \label{tab:vcBZRmacros}
\end{table}

\begin{table}[p]
  \centering\small
  \begin{tabularx}{\textwidth}{p{12em}>{\raggedright\arraybackslash}X}
    macro & meaning\\\addlinespace \toprule\addlinespace
    \verb+\GITHash+ & 40-hexdigit SHA1 commit hash\\
    \verb+\GITAbrHash+ & abbreviated commit hash\\
    \verb+\GITParentHashes+ & parent hashes\\
    \verb+\GITAbrParentHashes+ & abbreviated parent hashes\\
    \verb+\GITAuthorName+ & author name\\
    \verb+\GITAuthorEmail+ & author e-mail\\
    \verb+\GITAuthorDate+ & author date\\
    \verb+\GITCommitterName+ & committer name\\
    \verb+\GITCommitterEmail+ & committer e-mail\\
    \verb+\GITCommitterDate+ & committer date\\
  \end{tabularx}
  \caption{Git specific version control macros.}
  \label{tab:vcGITmacros}
\end{table}

\begin{table}[p]
  \centering\small
  \begin{tabularx}{\textwidth}{p{12em}>{\raggedright\arraybackslash}X}
    macro & meaning\\\addlinespace \toprule\addlinespace
    \verb+\HGHash+ & 40-hexdigit SHA1 commit hash\\
    \verb+\HGAbrHash+ & abbreviated commit hash\\
    \verb+\HGBranch+ & commit branch\\
    \verb+\HGFirstParentHash+ & first parent hash\\
    \verb+\HGSecondParentHash+ & second parent hash (\textit{All zeroes means one-parent revision}) \\
    \verb+\HGAbrFirstParentHash+ & abbreviated first parent hash\\
    \verb+\HGAbrSecondParentHash+ & abbreviated second parent hash \\
    \verb+\HGAuthorName+ & author name\\
    \verb+\HGAuthorEmail+ & author e-mail\\
    \verb+\HGAuthorDate+ & author date\\
  \end{tabularx}
  \caption{Mercurial specific version control macros.}
  \label{tab:vcHGmacros}
\end{table}

\begin{table}[p]
  \centering\small
  \begin{tabularx}{\textwidth}{p{12em}>{\raggedright\arraybackslash}X}
    macro & meaning\\\addlinespace \toprule\addlinespace
    \full\verb+\SVNPath+ & path to an arbitrary file or directory, that
    is part of the last commit\\
    \full\verb+\SVNName+ & \verb+\SVNPath+'s name without path\\
    \full\verb+\SVNUrl+ & path of \verb+\SVNPath+ in the repository\\
    \full\verb+\SVNNodeKind+ & node kind of \verb+\SVNPath+ (file,
    directory, \emph{etc.})\\
    \full\verb+\SVNRepositoryRoot+ & repository root URL\\
    \verb+\SVNRevision+ & revision number of \verb+\SVNPath+\\
    \verb+\SVNLastChangedRev+ & revision number of \verb+\SVNPath+\\
    \verb+\SVNLastChangedAuthor+ & author of the last commit\\
    \verb+\SVNLastChangedDate+ & date of the last commit\\
    \verb+\SVNRepositoryUuid+ & repository UUID\\
  \end{tabularx}
  \caption{Subversion specific version control macros.}
  \label{tab:vcSVNmacros}
\end{table}

\clearpage


\section{Checking for local modifications}
\label{sec:localmod}
Some people prefer to be notified, if a document is compiled from a
dirty working copy, \emph{i.e.}, from a state not corresponding to a
committed revision.  This feature has been implemented in the \pkg\
bundle, but is disabled by default (see below).

Macro \verb+\VCRevisionMod+ is similar to \verb+\VCRevision+, but it has
an additional message appended to the revision number, if there are any
modified files in the working copy.

The actual message is defined in macro \verb+\VCModifiedText+ and can be
redefined by the user.  The default definition is
\begin{listing}[style=TeX]
\gdef\VCModifiedText{\textcolor{red}{with local modifications!}}
\end{listing}
That is, package \texttt{color} has to be loaded in the document
preamble if macro \verb+\VCRevisionMod+ is used or macro
\verb+\VCModifiedText+ has to be redefined accordingly.

By default, searching for local modifications is disabled to prevent
slowing down execution of the scripts.  To check a working copy for
modified files script \texttt{vc} has to be called with the switch
\texttt{--m}.  The \verb+\write18+ example from
section~\ref{sec:compiling} now reads:\newline
\begin{minipage}{\textwidth}
  \begin{minipage}[t]{\sbslistingwd}
    \begin{listing}[style=TeX, title=Unix\strut]
\immediate\write18{sh ./vc -m}
\input{vc}
    \end{listing}
  \end{minipage}\hfill
  \begin{minipage}[t]{\sbslistingwd}
    \begin{listing}[style=TeX, title=Windows\strut]
\immediate\write18{vc.bat -m}
\input{vc}
    \end{listing}
  \end{minipage}
\end{minipage}

Note, since distributing documents not corresponding to a committed
revision is bad style, it is wise make sure by other means (a release
procedure), that distributed documents never contain uncommitted
changes.  Therefore, a note, say, next to the revision number, doesn't
really provide any additional information.  If you think you need such a
note, something might be wrong with your release procedure.



\section{Questions and answers}
\label{sec:qa}

\newcommand*{\qfont}{\sffamily\bfseries}
\newcommand*{\question}[2]{%
  \expandafter\gdef\csname #1\endcsname{#2}%
\item\label{#1}\csname #1\endcsname%
}
\newcommand{\answer}[1]{%
  \medskip\par
  {\noindent\qfont\ref{#1}.~\csname #1\endcsname\par}
  \nobreak\noindent\ignorespaces%
}

\begin{enumerate}
  \qfont%
  \setlength{\itemsep}{4pt}%
  \setlength{\parskip}{0pt}%

\question{vcHowOften}{How often do I need to run the script \texttt{vc}?
  Every time before \TeX\ is run?}

\question{vcWhyNoData}{Why are VCS data not updated in my document?}

\question{vcHowToInsert}{How can I print VCS data at arbitrary places in
  my document?}

\question{vcDraftMode}{I want to have VCS data in the document only in
  draft mode!}

\question{vcDateFormat}{How can I change the date format?}

\question{vcVcsSpecifics}{How can I access software specific VCS
  information, \emph{e.g.}, Git's 40-hexdigit commit hash?}

\question{vcWhyGdef}{Why are macros defined with \texttt{\textbackslash
    gdef} instead of \texttt{\textbackslash newcommand} in file
  \texttt{vc.tex}?}

\question{vcVCRevisionMod-m}{Macro \texttt{\textbackslash VCRevisionMod}
  only shows the revision number, even if there are modified files in my
  working copy.}

\question{vcVCRevisionMod-unskip}{In macro \texttt{\textbackslash
    VCRevisionMod}, how can I get rid of the horizontal skip between
  revision number and the message?}

\question{vcIgnoreFiles}{How do I ignore files with my VCS?}

\question{vcPerFile}{Is it possible to get per-file revision data with
  the \pkg\ bundle?  This were quite handy when working with a
  multi-file document (say, each file is a chapter).  After changing one
  file, the information could be used to check if an old print-out of
  another chapter is current.}

\question{vcLicense}{Can I put files of the \pkg\ bundle into a private,
  public or commercial repository?}
\end{enumerate}

\answer{vcHowOften} First, it is not recommended to run the script
manually, but automatically, either from a \texttt{Makefile} or directly
from \LaTeX\ via \verb+\write18+.  For that reason, it shouldn't matter
how often the script is called.

To answer the question: If you run the script \texttt{vc} manually, it
is sufficient to do that once after each check-in or update operation.
The only advantage of running the script before \emph{every} \TeX\ run
is that it keeps macro \verb+\VCRevisionMod+ up-to-date w.r.t.\@ local
modifications (when called with the \texttt{--m} switch).

Therefore, a fourth way to run script \texttt{vc} were to put it into a
VCS hook that is called after check-in or update operations.  There are
no examples for this solution, since it heavily depends on the
underlying VCS.  Additionally, some VCS might not provide enough hooks
to cover all operations that modify a working copy.

\answer{vcWhyNoData} Make sure script \texttt{vc} is run between
check-in operations and the \TeX\ run.  In case the script is called
from \TeX\ via \verb+\write18+ (see section~\ref{sec:compiling}), you've
probably just forgotten to enable that feature.  Please, refer to the
manual of your \TeX\ distribution to learn how to enable
\verb+\write18+.

\answer{vcHowToInsert} This question is covered in the UK-TeX-FAQ.
Depending on where you want to put VCS information---header, footer,
page background---you might be interested in the following links:
\begin{itemize}
\item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=fancyhdr}
\item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=watermark}
\item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=abspos}
\end{itemize}
Here is some code to put the revision number together with check-in date
and time into the foot line with packages \texttt{fancyhdr} and
\texttt{scrpage2}:
\begin{listing}[style=TeX]
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyfoot[LE,LO]{Rev: \VCRevision}
\fancyfoot[RE,RO]{Time: \VCDateISO \VCTime}
\end{listing}
\begin{listing}[style=TeX]
\usepackage{scrpage2}
\pagestyle{scrheadings}
\lefoot{Rev: \VCRevision}
\lofoot{Rev: \VCRevision}
\refoot{Time: \VCDateISO \VCTime}
\rofoot{Time: \VCDateISO \VCTime}
\end{listing}

Another source of information might be the \TeX\ catalogue:
\begin{itemize}
\item \url{http://texcatalogue.sarovar.org/bytopic.html#revision}
\end{itemize}
In this manual, the \texttt{prelim2e.sty} package has been used to
present VCS information.  See file \texttt{vc-manual.tex} to learn how
the foot line has been set up in this document.

\answer{vcDraftMode} Have a look at the \texttt{ifdraft} package from
the \texttt{oberdiek} bundle.

\answer{vcDateFormat} Package \texttt{isodate} provides means to convert
between various (localized) date formats.

\answer{vcVcsSpecifics} The general VCS information provided in macros
prefixed \verb+\VC+ are available for all supported version control
systems.  However, there are additional information available for some
VCS that are not for others.  These information are stored in macros
that have a VCS specific prefix (\emph{cf.} appendix~\ref{sec:notes} and
file \texttt{vc.tex}).  As an example, Git's 40-hexdigit commit hash is
provided in a macro \verb+\GITHash+.  You can either use this macro
directly or redefine \verb+\VCRevision+ to show the long hash as
follows:
\begin{listing}[style=TeX]
\renewcommand*{\VCRevision}{\GITHash}
\end{listing}
But keep in mind, that persons, unfamiliar with version control software
or Git in particular, might be irritated by cryptic information on every
document page.

\answer{vcWhyGdef} This is plain \TeX\ syntax and this works with
\LaTeX, too.  If you're using \LaTeX\ you can of course use
\verb+\renewcommand+ to redefine macros, \emph{e.g.}, \verb+\VCRevision+
as shown in the answer to the preceeding question.

\answer{vcVCRevisionMod-m} Call script \texttt{vc} with the \texttt{--m}
switch, see appendix~\ref{sec:localmod}.

\answer{vcVCRevisionMod-unskip} By default, the definition of macro
\verb+\VCRevisionMod+ is
\begin{listing}[style=TeX]
\gdef\VCRevisionMod{\VCRevision~\VCModifiedText}
\end{listing}
To remove the horizontal space before macro \verb+\VCModifiedText+ just
start its definition with \verb+\unskip+, \emph{e.g.},
\begin{listing}[style=TeX]
\gdef\VCModifiedText{\unskip, modified}
\end{listing}

\answer{vcIgnoreFiles} \emph{If you don't know how to configure your
  VCS, please read its documentation carefully before doing any of the
  steps shown below!}

Here are some short instructions for ignoring file \texttt{vc.tex} in
Bazaar, Git, Mercurial and Subversion:
\begin{description}
\item[Bazaar] In the directory containing the script files issue the
  following commands on the command line:
\begin{listing}[style=shell]
> bzr ignore vc.tex
> bzr commit .bzrignore
\end{listing}
This creates a file \texttt{.bzrignore} that contains ignore patterns
and puts that file under version control.

\item[Git] In the directory containing the script files create a file
  \texttt{.gitignore} containing the line
\begin{listing}[style=text]
vc.tex
\end{listing}
and put \texttt{.gitignore} under version control:
\begin{listing}[style=shell]
> git add .gitignore
> git commit .gitignore
\end{listing}

\item[Mercurial] In the directory containing the script files create a file
  \texttt{.hgignore} containing the line
\begin{listing}[style=text]
vc.tex
\end{listing}
and put \texttt{.hgignore} under version control:
\begin{listing}[style=shell]
> hg add .hgignore
> hg commit .hgignore
\end{listing}

\item[Subversion] In the directory containing the script files issue the
  following commands on the command line:
\begin{listing}[style=shell]
> svn propedit svn:ignore .
> svn commit
\end{listing}
The first command will open an editor.  Add the line
\begin{listing}[style=text]
vc.tex
\end{listing}
save the file, close the editor and commit the changes.
\end{description}

\answer{vcPerFile} This sounds like you're interested in tracking
changes instead of just revision data.  Note, that tracking changes and
documenting revision data for later reference are fundamentally
different requirements.  The \pkg\ bundle has only been written with the
latter use-case in mind.  In fact, the scripts of the \pkg\ bundle try
hard to be ignorant of individual file revision data.

There are three possible solutions (that do without \pkg):
\begin{enumerate}
\item To check whether files have changed between revisions one can use:
\begin{listing}[style=shell, escapechar=\#]
> svn diff -r #\descr{r1}#:#\descr{r2}# #\descr{file}#
\end{listing}
Of course, this is an on-line only solution, while you can check printed
numbers off-line and anywhere.  That's not to say it's better or worse,
but it requires a slightly different work-flow.  (For example, to pass
\emph{anybody} the new document version, therefore avoiding the question
if and where two print-outs differ.)

\item If you want to track changes instead of revision numbers, have a
  look at this item in UK-TeX-FAQ:
  \begin{itemize}
  \item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=changebars}
  \end{itemize}

\item Packages \texttt{svninfo} or \texttt{svn-multi} and \pkg\ can
  perfectly be used together to get reliable total revision data as well
  as per-file revision data.  Although, this may sound like overkill it
  could fit some use-cases.  For alternative version control packages
  see
  \begin{itemize}
  \item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=RCS}
  \item \url{http://texcatalogue.sarovar.org/bytopic.html#revision}
  \end{itemize}
\end{enumerate}

\answer{vcLicense} This is perfectly possible.  The \pkg\ bundle has
been put into the Public Domain to remove any usage restrictions.



\section{Comparision with alternative VCS packages}
\label{sec:comparision}
The \pkg\ bundle
\begin{itemize}
\item looks at all files in a working copy to get reliable revision
  information,
\item doesn't provide per-file revision data,
\item doesn't use keyword substitution,
\item works with \LaTeX\ and plain \TeX,
\item supports Bazaar, Git, Mercurial and Subversion,
\item needs an AWK interpreter.
\item Running the scripts might become noticeable on projects with many
  files.
\end{itemize}



\section{To do}
\label{sec:todo}
\begin{itemize}
\item Base Git scripts on plumbing commands.
\item Rewrite (and merge) scripts in Perl.
\item Add support for other VCS software.  Contributions are welcome!
\end{itemize}



\end{document}

%%% Local Variables: 
%%% mode: latex
%%% TeX-PDF-mode: t
%%% TeX-master: t
%%% End: