Changed manual after discussions about issue #97

I split up the section on the input syntax and rewrote the introductions
to plumed and to collective variables in general

user-doc/Colvar.txt

 /**
 
-\page Colvar Collective Variables
+\page colvarintro Collective variables
 
 Chemical systems contain an enormous number atoms, which, in most cases makes it simply impossible for
 us to understand anything by monitoring the atom postions directly.  Consquentially,
-we introduce Collective variables (CVs) that describe the chemical processes we are 
-interested in and monitor these simpler quantities instead.  These CVs are used in many of the methods 
+we introduce Collective variables (CVs) that describe the chemical processes we are
+interested in and monitor these simpler quantities instead.  These CVs are used in many of the methods
 implemented in PLUMED - there values can be monitored using \ref PRINT, \ref Function of them can be calculated
-or they can be analyzed or biased using the \ref Analysis and \ref Bias "Biasing" methods implemented in PLUMED.  
-Before doing any of these things however we first have to tell PLUMED how to calculate them.    
-
-On this page we list the simplest collective variables that are implemented in PLUMED 2. These colvars all take in a 
-set of atomic positions and output one or multiple scalar CV values.  Many other collective variables are available in PLUMED.  
+or they can be analyzed or biased using the \ref Analysis and \ref Bias "Biasing" methods implemented in PLUMED.
+Before doing any of these things however we first have to tell PLUMED how to calculate them.
+
+The simplest collective variables that are implemented in PLUMED 2 take in a
+set of atomic positions and output one or multiple scalar CV values.  Information on these variables is given here while 
+information as to how sets of atoms can be selected
+can be found in the pages on \ref Group.  Please be aware that PLUMED contains implementations of many other collective variables 
+are available in PLUMED but that the input for these variables may be less transparent when it is first encourntered.
 In particular, the page on \dists describes the various ways that you can calculate the distance from a particular reference
-configuration.  Meanwhile, the page on \ref Function describes the various functions of collective variables that can be used in the
-code.  Lastly the page on \mcolv describes MultiColvars.  MultiColvars allow you to use many different colvars and allow us to 
+configuration.  So you will find instructions on how to calculate the RMSD distance from the folded state of a protein here.
+Meanwhile, the page on \ref Function describes the various functions of collective variables that can be used in the
+code.  This is a very powerful feature of PLUMED as you can use the \ref Function commands to calculate any function or 
+combination of the simple collective variables listed on the page \ref Colvar.  Lastly the page on \mcolv describes MultiColvars.  
+MultiColvars allow you to use many different colvars and allow us to
 implement all these collective variables without implementing having an unmanigiably large ammount of code.  For some things (e.g.
-\ref DISTANCES GROUPA=1 GROUPB=2-100 LESS_THAN={RATIONAL R_0=3}) there are more computationally efficient options available in plumed 
-(e.g. \ref COORDIATION).  However, MultiColvars are worth investigating as they provide a flexible syntax for many quite-complex CVs.
+\ref DISTANCES GROUPA=1 GROUPB=2-100 LESS_THAN={RATIONAL R_0=3}) there are more computationally efficient options available in plumed
+(e.g. \ref COORDINATION).  However, MultiColvars are worth investigating as they provide a flexible syntax for many quite-complex CVs.
 
-\section cvavail CV Documentation
+\section Colvar CV Documentation
 
 The following list contains descriptions of a number of the colvars that are currently implemented in PLUMED 2.
 

user-doc/Glossary.txt

@@ -6,8 +6,7 @@ The following page contains an alphabetically ordered list of all the Actions an
 that are available in PLUMED 2. For lists of Actions classified in accordance with the 
 particular tasks that are being performed see:
 
-- \ref Colvar tells you about the functions of the positions atoms that PLUMED can calculate.
-- \ref Function tells you about the functions of collective variables that PLUMED can calculate.
+- \ref colvarintro tells you about the ways that you can calculate functions of the positions of the atoms.
 - \ref Analysis tells you about the various forms of analysis you can run on trajectories using PLUMED.
 - \ref Bias tells you about the methods that you can use to bias molecular dynamics simulations with PLUMED.
 

user-doc/Intro.txt

@@ -33,14 +33,17 @@ is provided in this <a href="http://www.youtube.com/watch?v=PxJP16qNCYs"> 10-min
 More information on the input syntax as well as details on the the various trajectory
 analsyis tools that come with PLUMED are given in: 
 
-- \ref Colvar tells you about the functions of the positions atoms that PLUMED can calculate.
-- \ref Function tells you about the functions of collective variables that PLUMED can calculate.
+- \ref colvarintro tells you about the ways that you can calculate functions of the positions of the atoms.
 - \ref Analysis tells you about the various forms of analysis you can run on trajectories using PLUMED.
 - \ref Bias tells you about the methods that you can use to bias molecular dynamics simulations with PLUMED.
 
-PLUMED can be used in one of two ways.  It can be incorporated into any one of the MD codes listed on the
-\ref Installation page and used to analyse or bias a molecular dynamics run on the fly.  Alternatively, one
-can use it as a standalone tool for postprocessing the results from molecular dynamics or enhanced sampling calculations.
+PLUMED can be used in one of two ways.  It can be incorporated into any one of the MD codes listed below:
+
+@CODES@
+
+and used to analyse or bias a molecular dynamics run on the fly.  Alternatively, one
+can use it as a standalone tool for postprocessing the results from molecular dynamics 
+or enhanced sampling calculations.
 
 
 */

user-doc/Misc.txt

 /**
 
-\page misc Miscellaneus
+\page misc Frequently used tools
 
 @DICTIONARY@
 <TABLE ALIGN="center" FRAME="void" WIDTH="95%%" CELLPADDING="5%%">

user-doc/PlumedLayout.xml

@@ -9,12 +9,10 @@
       <tab type="user" visible="yes" url="_configuring_plumed.html" title="Configuration"/>
     </tab>
     --> 
-    <tab type="usergroup" title="Basics">
-      <tab type="user" visible="yes" url="_syntax.html" title="Input File"/>
-    </tab>
-    <tab type="usergroup" title="Collective variables">
+    <tab type="user" visible="yes" url="_syntax.html" title="Quick Introduction"/>
+    <tab type="usergroup" title="Collective variables" >
       <tab type="user" visible="yes" url="_group.html" title="Groups and Atoms"/>
-      <tab type="user" visible="yes" url="_colvar.html" title="Collective Variables"/>
+      <tab type="user" visible="yes" url="colvarintro.html" title="Collective Variables"/>
       <tab type="user" visible="yes" url="dists.html" title="Distances from reference configurations"/>
       <tab type="user" visible="yes" url="_function.html" title="Functions"/>
       <tab type="user" visible="yes" url="mcolv.html" title="MultiColvar documentation"/>
@@ -22,7 +20,14 @@
     <tab type="user" visible="yes" url="_analysis.html" title="Analysis"/>
     <tab type="user" visible="yes" url="_bias.html" title="Bias"/>
     <tab type="user" visible="yes" url="tools.html" title="Tools"/>
-    <tab type="user" visible="yes" url="misc.html" title="Misc"/>
+    <tab type="usergroup" title="Miscelaneous">
+      <tab type="user" visible="yes" url="comments.html" title="Adding comments to the input"/>
+      <tab type="user" visible="yes" url="_continuation_lines.html" title="Splitting commands over multiple lines"/>
+      <tab type="user" visible="yes" url="includes.html" title="Including files"/>
+      <tab type="user" visible="yes" url="load.html" title="Loading shared libraries"/> 
+      <tab type="user" visible="yes" url="degub.html" title="Debugging the code"/>
+      <tab type="user" visible="yes" url="misc.html" title="Frequently used tools"/>
+    </tab> 
     <tab type="user" visible="yes" url="tutorials.html" title="Tutorials"/>
     <tab type="user" visible="yes" url="citelist.html" title="Bibliography"/>
     <tab type="user" visible="yes" url="glossary.html" title="Index"/>

user-doc/Syntax.txt

 /**
-\page Syntax Syntax 
+\page Syntax Quick Introduction
 
 To run PLUMED 2 you need to provide one input file.  In this file you specify what it
 is that PLUMED should do during the course of the run.  Typically this will involve calculating 
@@ -18,7 +18,8 @@ which provide PLUMED with more details as to how the action is to be performed.
 bounadry conditions when calculating a particular colvar) or they can be words followed by an equals sign and a comma separated 
 list - WITH NO SPACES - of numbers or characters (so for example ATOMS=1,2,3,4 tells PLUMED to use atom numbers 1,2,3 and 4 in 
 the calculation of a particular colvar). Space separated lists can be used instead of commma separated list if the entire list
-is enclosed in curly braces (e.g. ATOMS={1 2 3 4}).
+is enclosed in curly braces (e.g. ATOMS={1 2 3 4}).  Please note that you can split commands over multiple lines by using
+\ref ContinuationLines. 
 
 The most important of these keywords is the label keyword as it is only by using these labels that we can pass data 
 from one action to another.  As an example if you do:
@@ -52,9 +53,11 @@ PRINT ARG=d1 FILE=colvar STRIDE=10
 Also notice that all the actions can be labeled, and that many actions besides normal collective variables can define
 one or more value, which can be then referred using the corresponding label.
 
-Actions can be referred also with POSIX regular expressions (see \ref Regex). For this you need to compile PLUMED with the appropriate flag.  
+Actions can be referred also with POSIX regular expressions (see \ref Regex) if PLUMED is compiled with the appropriate flag.  
+You can also add \ref comments to the input or set up your input over multiple files and then create a composite input by
+\ref includes.
 
-\section Units A note on units
+\section units Plumed units
 By default the PLUMED inputs and outputs quantities in the following units:
 
 - Energy - kJ/mol
@@ -64,9 +67,7 @@ By default the PLUMED inputs and outputs quantities in the following units:
 Unlike PLUMED 1 the units used are independent of the MD engine you are using.  If you want to change these units you can do this using the 
 \ref UNITS keyword. 
 
-Those are the essentials but there are a few other tricks that we didn't know where else to put in the manual so we stuck them here.
-
-\section comments Comments
+\page comments Comments
 
 If you are an organised sort of person who likes to remember what the hell you were trying to do when you ran a 
 particular simulation you might find it useful to put comments in your input file.  In PLUMED you can do this as 
@@ -83,7 +84,7 @@ UPPER_WALLS ARG=d1 AT=3.0 KAPPA=3.0 LABEL=Snout # In this same interlude it doth
 An alternative to including comments in this way is to use line starting ENDPLUMED.  Everything in the PLUMED input after this
 keyword will be ignored.
 
-\section ContinuationLines Continuation lines
+\page ContinuationLines Continuation lines
 
 If your input lines get very long then editing them using vi and other such text editors becomes a massive pain in the arse.  
 We at PLUMED are aware of this fact and thus have provided a way of doing line continuations so as to make your life that much 
@@ -108,7 +109,7 @@ DISTANCES ...
 ... DISTANCES
 \endverbatim
 
-\section includes Including other files in the PLUMED input
+\page includes Including other files 
 
 If, for some reason, you want to spread your PLUMED input over a number of files you can use \ref INCLUDE as shown below:
 
@@ -145,7 +146,7 @@ DISTANCE INCLUDE FILE=options.dat
 RESTRAINT ARG=dist
 \endverbatim
 
-\section load Loading shared libraries
+\page load Loading shared libraries
 
 You can introduce new functionality into PLUMED by placing it directly into the src directory and recompiling the 
 PLUMED libraries.  Alternatively, if you want to keep your code independent from the rest of PLUMED (perhaps
@@ -159,7 +160,7 @@ LOAD FILE=library.so
 N.B.  If your system uses a different suffix for dynamic libraries (e.g. macs use .dylib) then PLUMED will try to 
 automatically adjust the suffix accordingly.
 
-\section degub Debugging the code
+\page degub Debugging the code
 
 The \ref DEBUG action provides some functionality for debugging the code that may be useful if you are doing 
 very intensive development of the code of if you are running on a computer with a strange architecture.

user-doc/extract

@@ -37,7 +37,7 @@ for file in ../patches/*.diff
 do
    myengine=`echo "$file" | sed -e 's/.diff//' | sed -e 's/..\/patches\///'`
    mytag=`echo "$myengine" | sed -e 's/\./\_/g'`
-   echo "- \subpage $mytag" >> automatic/codes.list
+   echo "- \ref $mytag" >> automatic/codes.list
    echo "/**" >> automatic/$myengine.txt
    echo "\page $mytag $myengine" >> automatic/$myengine.txt
    plumed patch -e $myengine -i -q >> automatic/$myengine.txt