README file for COMPASS Proposal 2010
=====================================

v1.0     03.12.2009             Bernhard Ketzer
v2.0     23.12.2009             Bernhard Ketzer
v3.0     28.01.2010             Wolf-Dieter Nowak
v3.1     13.02.2010             Wolf-Dieter Nowak
         - mod's on "add files"
         - mod's on "compass_prop.bib" file
v3.2     23.02.2010             Wolf-Dieter Nowak
         - mod's on "svn update"
         - update on Compilation
         - new: Sect.9 Resolving conflicts


===========================
1. Access to the repository
===========================
The repository is hosted by the CERN SVN service. There are many ways to 
access the repository. See http://svn.web.cern.ch/svn/howto.php#accessing
for details on web interfaces, access under Windows, etc. Here we restrict 
ourselves to access on Linux machines, either at CERN (lxplus) or remotely.

All (suggested) authors have read and write access to the
repository. If new authors should be added, please contact B. Ketzer
(Bernhard.Ketzer@cern.ch) who is the administrator of this document.

a) ACCESS via ssh and Kerberos (lxplus and remote Unix machines)
---------------------------------------------------------------
Access is provided via the ssh protocol and Kerberos authentification. 
You need ssh and the svn client installed on your system. If you can
do ssh lxplus.cern.ch, then also this method works.

First choose a directory of yours, IN WHICH you want SVN to create your 
'working copy' (i.e. the full tree of directories) that contains all 
material needed to generate the paper with pdflatex.

In order to 'check out' the latest version of the paper, type

$ svn co svn+ssh://svn.cern.ch/reps/compass-pub/proposal2010

or if you use a differnet username for lxplus:

$ svn co svn+ssh://<username>@svn.cern.ch/reps/compass-pub/proposal2010

===> SVN will create your working copy as directory tree proposal2010


b) ACCESS via ssh and public ssh keys (remote Unix machines)
------------------------------------------------------------
[this hasn't been tested yet]

If you do not want to type your password every time you access the 
repository, follow these instructions:

Execute 

$linux> ssh-keygen -t dsa 

on your Linux/Unix machine in order to generate the ssh keys.

Copy the public key (~/.ssh/id_dsa.pub) to your AFS home directory at CERN

$linux> scp ~/.ssh/id_dsa.pub USERNAME@lxplus.cern.ch:~

Add the PUBLIC key you copied in the 3rd step in your 
~/.ssh/authorized_keys file on lxplus with the following command:

$lxplus> cat ~/id_dsa.pub >> ~/.ssh/authorized_keys

Since the AFS home directory is on AFS, ssh needs AFS tokens to read 
~/.ssh/authorized_keys, to fix this, execute the following script on lxplus:

$ /afs/cern.ch/project/svn/dist/bin/set_ssh 

Voila you are done:

ssh USERNAME@svn.cern.ch

and accept the server key. You shouldn't be prompted for a password, and you 
should see the message:

*******************************************************************************
*                                                                             *
* http://cern.ch/ComputingRules : Govern the use of CERN computing facilities *
*                                                                             *
*******************************************************************************
SVN server - wrong number of arguments, interactive login disabled
Connection to svn closed.

Now you can connect to the SVN server without having to type your password. 
Unfortunately, your normal logins to lxplus will now also use
this mechanism, which fails to give you AFS tokens. In order to fix this, you 
have to create the file ~/.ssh/config on your local Linux machine and add the  
following lines to it

Host lxplus.cern.ch lxplus
Protocol 2
PubkeyAuthentication no
PasswordAuthentication yes

Host svn.cern.ch svn
GSSAPIAuthentication yes
GSSAPIDelegateCredentials yes
Protocol 2
ForwardX11 no

Now, ssh lxplus.cern.ch should prompt you for your password while 
ssh svn.cern.ch should not.

See the CERN svn documentation for more details.


================================
2. Editing the proposal with SVN
================================

You can find more information on SVN at 
http://svn.web.cern.ch
http://svnbook.red-bean.com             <== this is wdn's prefered one...


For editing the proposal, your top level directory is 'sources'. HERE you 
have to run 'make' (or 'pdflatex compass_prop.tex') in order to generate 
your document version 'compass_prop.pdf' (to be viewed with e.g. acroread).

As a general rule, update your own working copy before you start working,
in order to always start from the most actual version, by typing :

$ svn update

Beware: this command acts on your actual directory, NOT on the repository
        as a whole! Hence make sure that you issue this command in the top
        directory ("proposal2010").

The present structure of the directory tree makes sure that changes made
on the level of subsections (of the sections 'Physics' and 'Upgrades') are
entirely independent. IF it may happen that a remote colleague of yours 
wants to work on the same subsection as you, you better 'lock' your file(s)
while working on it(them). We may try to avoid that by having only 1-2 
persons working on a certain subsection of the proposal.

'Organizational comments' that explain how to take advantage of this
specially designed structure, can be found in 'steering .tex files', made
for every section and subsection, which have the same name as the directory
in which they reside:

.../sources/physics/physics.tex
-------------------------------
.../sources/physics/gpd/gpd.tex
.../sources/physics/dy/dy.tex
.../sources/physics/cpt/cpt.tex
.../sources/physics/unpol/unpol.tex

.../sources/upgrades/upgrades.tex
---------------------------------
.../sources/upgrades/trigger/trigger.tex
.../sources/upgrades/LH2_RPD/LH2_RPD.tex 
.../sources/upgrades/absorber/absorber.tex
.../sources/upgrades/trackers/trackers.tex
.../sources/upgrades/ECALs/ECALs.tex 

The above also explains the present structure of the two main sections of
the proposal, 'Physics' and 'Upgrades'.

A few recommendations:
- commit your work often to minimize the chance of conflicts
- make sure that your working copy of the document compiles 
  successfully, before you commit your changes to the repository
- make sure that any changes you commit to the repository are
  compatible with the latest version in the repository


Whenever you have simply modified existing .tex files, commit them by:

$ svn ci . 

New files that you have created locally, ALSO figures files that you've
copied into your local ./figures directory from somewhere else, MUST be 
added to the repository by

$ svn add file_XY.tex [fig_XY.png] ...

They can be committed by

$ svn ci file_XY.tex [fig_XY.png]    (while $ svn ci . includes this as well)

A new directory is added in a single step:

$ mkdir subdir

and commited by

$ svn add subdir

BEWARE: whenever you have committed something, your default editor opens
      and you should type some short text (in the top part!) that explains
      what you have done. Once you've closed the editor, your changes will
      (only now!) be sent to the repository and the new version number is 
      assigned and given to you.


==============
3. Compilation
==============
In order to allow the use of jpg and pdf files, pdflatex will be used.
There is a Makefile ("./proposal2010/sources/make") which cares about 
compilation. Typing "make" will do all the required passes of
pdflatex and bibtex, and will produce a file compass_prop.pdf. At the
moment, the "draft" option is used, so the output is
single-column. 

BEWARE: Should "make" claim that nothing is to do, you can still 
        i) compile `by hand' by "pdflatex compass_prop" and
        ii) update your bbl file by "bibtex compass_prop"


===============
4. Bibliography
===============
In order not to duplicate work and to ensure a common citation style,
all references will be stored in a bibtex database called
compass_prop.bib. This file already includes quite a number of
references, so please check before you add new references there. 

Each item in the database has to be given a unique name, which should
correspond to the name one gets when downloading the bibtex entry from
spires or ArXiV. Only if there is no such entry, the convention 
{LastNameOfFirstAuthor:Year} should be used. If, in this system, there 
is more than one publication by the same person in the same 
year, the letters a,b,c,etc. should be added to the Year, e.g. 
{Alexakhin:05a}. In the text, references are cited by 
\cite{Alexakhin:05a}.

The proposal_2010 references should be introduced into the 
compass_prop.bib file according to the structure of the document (see
section 2 of the README). A corresponding structure is prepared in the
.bib file, please try to stick to it.

 
===================
5. Cross references
===================
Every (sub)section should carry the corresponding label, e.g. 
\label{sec:physics.gpd.intro}, where the dots separate subsections. 
For each new sub(sub)section a similar naming scheme should be
obeyed. Cross referencing in the text is then done via e.g. "in 
Section~\ref{sec:physics.gpd.intro}". 

==========
6. Figures
==========
All figures should be stored in a separate subdirectory called
./figures/.The labelling scheme for figures is the same as for
sections,e.g. \label{fig:physics.gpd.theory.handbag_diagram}.
 
pdflatex only allows the use of pdf or jpg files. All other graphics
formats should be converted to one of these two formats using
e.g. "convert foo.gif foo.jpg" or "epstopdf foo.eps". Do not give
explicit file extensions like .pdf or .jpg in the \includegraphics
command. The files are automatically searched for .pdf and .jpg 
extensions in this order. If only a .eps version is found, the file 
will be converted to .pdf on the fly using epstopdf, so that next 
time the pdf version is found.   

An example for including graphics is in compass_spec_lay.tex:
\begin{figure}[tbp]
  \begin{center}
    \includegraphics[width=\columnwidth]{./figures/rate}
  \end{center}
  \caption{\small Rate of muons for two orthogonal cross sections
    through the beam center at a longitudinal position of $\sim
    10\,\m$ downstream of the target.}
  \label{fig:intro.rate}
\end{figure}

Please note the use of [width=\columnwidth] for a single-column
figure. Avoid explicit numbers here!  

Two-column figures can be included using the *-ed version of figure, e.g. in
compass_spec_int.tex: 
\begin{figure*}[tbp]
  \begin{center}
    \includegraphics[width=\textwidth]{./figures/COMPASS_setup2002-bw}
  \end{center}
  \caption{\small The COMPASS spectrometer at CERN's SPS accelerator.}
  \label{fig:intro.setup}
\end{figure*}

========
7. Units
========
In order to use a consistent style for units, a special style is
introduced, which defines all commonly used units. The notation is
e.g. $190\,\GeV$. Note the math-environment ($...$), a small space (\,)
and the unit itself (\GeV). Have a look at myunits.sty to see which
prefixes and which units are defined. 

=================
8. Spell Checking
=================
Always carefully spell-check your files before committing them to the
repository. It was agreed to use the British English spelling of
words. You can use e.g. ispell to spell-check LaTeX 
documents. There is a command-line version which allows you to
interactively correct typos and misspelled words:

ispell -d british foo.tex 

If you use emacs to edit your files, you can also invoke the spell
checker from emacs (on most Linux distributions) by clicking on
"Tools->Spell Checking->Select British Dict" and then "Tools->Spell
Checking->Spell-Check Buffer". The options are the same as for the
command-line version. 

==========================
9. Resolving SVN conflicts
==========================
Should it happen that commitments by different people at (almost) the
same time have created a conflict, SVN will inform the person who actually 
created the conflict. In this case, BOTH versions of the tex-file containing 
the conflict, will be stored by SVN in your directory, with the 
corresponding version number embedded in the file name.

There are two solutions for you:
i) you agree on what the other person made earlier, i.e. you want to forget
   your own changes. In this case erase your local version of the file that 
   contains the conflict and do "svn update"
ii)you don't agree with the other person. In this case you'll find the
   place(s) of conflict marked by SVN inside the actual version of the file.
   You have to solve the conflict 'by hand' and commit a new version,
   hopefully informing the other person ;-)