summaryrefslogtreecommitdiff
path: root/support/vc/vc-manual.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 /support/vc/vc-manual.tex
Initial commit
Diffstat (limited to 'support/vc/vc-manual.tex')
-rw-r--r--support/vc/vc-manual.tex702
1 files changed, 702 insertions, 0 deletions
diff --git a/support/vc/vc-manual.tex b/support/vc/vc-manual.tex
new file mode 100644
index 0000000000..dd203fe7e6
--- /dev/null
+++ b/support/vc/vc-manual.tex
@@ -0,0 +1,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: