\documentclass[letterpaper]{article}

%% Set the \pdfpagewidth and \pdfpagelength, ONLY if we're using pdflatex.
\usepackage{ifthen}
\ifx\pdfoutput\undefined
\else
\setlength\pdfpagewidth{8.5in}
\setlength\pdfpageheight{11in}
\fi

%% Set up some margins that waste less paper :-)
\topmargin          =  0in
\oddsidemargin      =  0in
\textwidth          =  06.50in
\textheight         =  08.00in

\newcommand{\code}[1]{\vspace{3pt}\\\makebox[\textwidth]{\tt #1}\vspace{3pt}}

\begin{document}

\title{CVS Guidelines}
\author{Tony Novak (afn@cs.cornell.edu)}

\maketitle

%% 9pt spacing between paragraphs
\setlength\parskip{9pt}

%% but we don't want the spacing for section, subsection, etc.
\let\oldsection\section
\renewcommand\section[1]{\vspace{-\parskip}\oldsection{#1}\vspace{-\parskip}}
\let\oldsubsection\subsection
\renewcommand\subsection[1]{\vspace{-\parskip}\oldsubsection{#1}\vspace{-\parskip}}
\let\oldsubsubsection\subsubsection
\renewcommand\subsubsection[1]{\vspace{-\parskip}\oldsubsubsection{#1}\vspace{-\parskip}}

\section{Getting started with CVS}

The first thing you should do is follow the directions at {\tt http://adm/CVS/cvs-howto.html} to get your CVS account set up, and make sure you can successfully check out the {\tt quark} repository.  Then, read the rest of this document to ensure that you understand some of the subtleties of CVS that affect the Quark project.

\section{Keyword Substitution}

More often than not, the issues that crop up in CVS and cause files to get corrupted have to do with keyword substition.  Keyword substitution serves two distinct purposes:
\vspace{-1.5\parskip}

\begin{itemize}
\item Replace keywords such as {\tt \$Id\$} in the file with a certain value (in this case, version information about the file)
\item Replace UNIX line-endings ({\tt LF}) with Windows line-endings ({\tt CRLF}) when checking out files on Windows, and the reverse substitution when checking files back in on Windows.
\end{itemize}

This is obviously a useful file when editing text files, such as C++ source files.  However, it is extremely important that this substitution \emph{not} happen on binary files, such as PDF, JPEG, etc., as they would get corrupted.  For this reason, there is a parameter that can be passed to {\tt cvs add} which specifies that keyword substitution should not be performed on a particular file:
\code{cvs add -kb doc/XQGM.pdf}

\section{CVS and Windows}

As mentioned above, CVS converts line endings on non-binary files when checking files in and out on Windows.  Depending on what editor you use, this may or may not be crucial---some editors automatically detect the line endings in files, and save files with the same line endings as the original; others automatically convert files to Windows line endings when saving them.  The latter can be particularly problematic; consider the following case: you check out {\tt Foo.cpp} on your Windows machine, and it now has {\tt LF}s at the end of each line.  You make a change in your favorite text editor and save it; now the line has {\tt CRLF}s at the end of each line.  Finally, you commit the file to CVS.  What this has done is a problem for several reasons:

\begin{itemize}
\item CVS now thinks that {\em every} line in the file has changed (because each line now has an extra {\tt CR} at the end!).  This is indeed a major problem, because one of the most useful features of CVS is being able to track what changed between each revision of the file.
\item Each line in the file now has an extra {\tt CR} at the end.  Suppose the next person editing the file edits it with {\tt vi} on Solaris (which doesn't automatically detect that the file has Windows line endings, but rather, just sees an explicit {\tt CR} at the end of each line).  If the user adds an extra line, and commits the file, then the file now has {\em mixed} line endings: some of the lines end with {\tt CRLF}, and others end with {\tt LF}.  While earlier, editors may have been able to detect what type of line endings the file had, the situation is now completely hopeless because the file is neither a valid Unix file nor a valid Windows file as far as line endings are concerned.
\end{itemize}

So the question is, what can be done?  Well, fortunately, the Win32 version of the CVS executable does a special form of keyword expansion that the Unix version does not.  It adds an extra {\tt CR} at the end of each line (in non-binary files) when checking out; and similarly, strips a {\tt CR} from the end of each line when committing.  The result is that your local versions of files have Windows line endings, but the repository has Unix line endings.

While this may seem straightforward and obvious, it is very important to make sure that you always use the Windows version of CVS when editing files on Windows, and the Unix version when editing files on Unix.  Frequently, people use Visual Studio to edit and/or create files which are physically stored in their Unix home directories, and use CVS on Linux.  This has the same serious problems as the scenario discussed earlier, before we introduced the idea of newline keyword expansion.  Thus, I will say it again: {\bf It is imperative that you edit your files with a Windows text editor if and only if you work on files checked out with the Windows version of CVS}.

So now you're probably thinking, ``OK, so I'll just use Cygwin's {\tt cvs}.  Right?''  {\bf Wrong.}  At least in its default installation, Cygwin uses Unix line endings, and therefore its version of CVS will {\em not} do the required newline conversion.  Instead, you'll need to use the actual Win32 version of CVS, as described below.

\subsection{What You'll Need}

You'll need the latest version of CVS, a few tools from PuTTY ({\tt plink}, {\tt pageant}, and {\tt puttygen}), and a couple of batch files to work around Windows's deficiencies :-)  Everything you need is in the {\tt windows-cvs.zip} file in the {\tt quark-extlib} repository (hint: check it out on Linux, and copy it to your Windows machine.)  Extract its contents to {\tt c:\verb$\$bin} (or, if you choose a different path, edit {\tt cvs.bat} to reflect this).

\subsection{Setting up PuTTY}

The next you'll need to do is create a public/private key that {\tt pageant}, the PuTTY key manager, can use.  Assuming you've already set this up in Unix (if you haven't, visit the URL in the first paragraph), you can just import your existing private key:
\vspace{-1.5\parskip}

\begin{enumerate}
\setlength{\itemsep}{0pt}
\item Start {\tt c:\verb$\$bin\verb$\$puttygen.exe}.
\item Go to {\em Converstions} $\rightarrow$ {\em Import Key}.
\item Select the private key file from your {\tt \verb$~$/.ssh} directory\footnote{Hint: look in {\tt $\backslash\backslash$sundial$\backslash${\em your\_username}}}: if you are using SSH1, it is called {\tt identity}; for SSH2 it is {\tt id\_dsa}.  Click {\em Open}.
\item Click {\em Save private key} (it may warn you if you're not using a passphrase), and choose a location.  The {\tt cvs.bat} script tries using {\tt c:\verb$\$bin\verb$\$cvs.ppk} by default; if you save your key in a different location, then you will have to change {\tt cvs.bat}.
\item Close {\tt puttygen}.
\end{enumerate}

Now, edit {\tt c:\verb$\$bin\verb$\$cvs.bat} with your favorite
text editor.  Change the line that says \code{set USER=changeme}
to match your information.  In addition, if you are using SSH2 you
will need to change the port number: \code{set SSH\_PARAMS=-P
3000} to {\tt 22}.  Finally, if you've put {\tt cvs.bat} somewhere
other than in {\tt c:\verb$\$bin}, or if you've placed your PuTTY
key file in a location other than the default, you'll need to make
the appropriate changes in this file.

Now, you need to tell {\tt plink} to learn the CVS server's key
fingerprint---at a command prompt, type:
\code{C:$\backslash$bin$\backslash$plink -v -P 22
gforge.cis.cornell.edu}  It will give you a bunch of warnings,
then ask ``{\em Store key in cache? (y/n)}''.  Type {\tt y} and
hit {\tt Enter}.  It'll then prompt you for your password but you
can just hit {\tt Ctrl-C}; the fingerprint is now saved in your
registry.

Finally, you may want cvs to be in your path: right-click on {\em My Computer}, and under {\em Advanced}, click {\em Environment Variables}.  If you don't have {\tt PATH} set as a user variable, click {\em New}, and set {\tt PATH} to
\code{c:$\backslash$bin;\%PATH\%}
or if you already have a user variable for {\tt PATH}, just put {\tt c:\verb$\$bin} at the beginning.

That's it---you should now be able to go to a command prompt and type something like:
\code{cvs co quark}

\end{document}
