From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- support/vc/vc-manual.tex | 702 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 702 insertions(+) create mode 100644 support/vc/vc-manual.tex (limited to 'support/vc/vc-manual.tex') 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: -- cgit v1.2.3