PDF manual

Added PDF manual. I had to reorganize a bit the documentation to make
it more linear. In particular, I assigned each of the previously
"dangling" pages as subpage of another one (e.g. DEBUG keyword).
Additionally, I changed a bit the way MD-specific instructions are linked
and added some comment about the PDF manual in the introduction.

The most important change is that I am not using the Layout anymore since
it was difficult to keep it in sync. Now, in the html version, only
the left-side tree is visible, and the tabs disappeared. I don't think
this is a big issue but we might try to solve it.

PDF manual is still a bit buggy: some links are not properly resolved
and images are not shown. I think we can solve these issues later.

Addresses #101

user-doc/.gitignore

@@ -7,4 +7,5 @@
 /modifier_file
 /*aux
 /*doc*
+/manual.pdf
 

user-doc/Colvar.txt

@@ -25,6 +25,12 @@ implement all these collective variables without implementing having an unmanigi
 \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.
 
+\subpage Group
+\subpage Colvar
+\subpage dists
+\subpage Function
+\subpage mcolv
+
 \page Colvar CV Documentation
 
 The following list contains descriptions of a number of the colvars that are currently implemented in PLUMED 2.

user-doc/Doxyfile

@@ -651,7 +651,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.
 
-LAYOUT_FILE            = PlumedLayout.xml
+# LAYOUT_FILE            = PlumedLayout.xml
 
 # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 # the reference definitions. This must be a list of .bib files. The .bib
@@ -733,10 +733,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../CHANGES \
-                         tutorials \
-                         automatic
-
+INPUT                  = 
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1533,7 +1530,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = NO
+GENERATE_LATEX         = YES
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1576,7 +1573,7 @@ COMPACT_LATEX          = NO
 # The default value is: a4.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-PAPER_TYPE             = a4wide
+PAPER_TYPE             = a4
 
 # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
 # that should be included in the LaTeX output. To get the times font for

user-doc/Installation.txt

@@ -336,7 +336,9 @@ do not want to set up modules, but we believe that using modules as described ab
 
 At the present times PLUMED can be added to the following list of codes:
 
-@CODES@
+@CODESL@
+
+In the section \subpage CodeSpecificNotes you can find information specific for each MD code.
 
 To patch your MD code, you should have already installed PLUMED properly.
 This is necessary as you need to have the command "plumed" in your execution
@@ -380,7 +382,6 @@ If your MD code is not supported, you may want to implement an interface for
 it. Refer to the <a href="../../developer-doc/html/index.html"> developer
 manual </a>.
 
-
 \section installingalmost Installing PLUMED with ALMOST
 
 In order to used some of the NMR based collective variables (\ref CS2BACKBONE and \ref CH3SHIFTS) PLUMED needs to be linked with ALMOST.
@@ -403,6 +404,12 @@ Once ALMOST is installeed, PLUMED 2 can then be configured with ALMOST enabled:
 ./configure --enable-almost CPPFLAGS="-I/ALMOST_INSTALL_PATH/include -I/ALMOST_INSTALL_PATH/include/almost" LDFLAGS="-L/ALMOST_INSTALL_PATH/lib"
 \endverbatim
 with ALMOST_INSTALL_PATH set to the full path to the ALMOST installation folder.
+
+\page CodeSpecificNotes Code specific notes
+
+Here you can find instructions that are specific for patching each of the supported MD codes.
+
+@CODES@
  
 */
 

user-doc/Intro.txt

@@ -9,16 +9,33 @@ extensive rewrite of the original in a way that makes it more modular and thus e
 new methods, more straightforward to add it to MD codes and hopefully simpler to use.  
 This is the user manual -  if you want to modify PLUMED or to understand how it works internally, have a look at the 
 <a href="../../developer-doc/html/index.html"> developer manual </a>.
+\htmlonly
+An experimental PDF copy of this manual can be found
+<a href="../manual.pdf"> here </a>.
+\endhtmlonly
 
 To understand the difference between PLUMED 1 and PLUMED 2, and to
-follow the development of PLUMED 2, you can look at the detailed changelog:
-- Changes for \ref CHANGES-2-0
-- Changes for \ref CHANGES-2-1
+follow the development of PLUMED 2, you can look at the detailed \ref Changelog.
 
 A short tutorial explaining how to move from PLUMED 1 to PLUMED 2 is also available (see \ref moving)
 
 To install PLUMED 2, see this page: \ref Installation
 
+\section AboutManual About this manual
+
+Since version 2.1 we provide an experimental PDF manual.
+The PDF version is still not complete and has some known issue (e.g. some
+links are not working properly and images are not correctly included),
+and the html documentation should be considered as the official one.
+The goal of the PDF manual is to allow people to download a full copy on the documentation for offline
+access and to perform easily full-text searches.
+Notice that the manual is updated very frequently (sometime more than once per week),
+so keep your local version of the PDF manual up to date. 
+Since the PDF manual is 200+ pages and is continuously updated,
+<b>
+please do not print it!
+</b>
+
 \section qintro A quick introduction
 
 To run PLUMED 2 you need to provide one input file.  In this file you specify what it
@@ -37,12 +54,17 @@ analsyis tools that come with PLUMED are given in:
 
 PLUMED can be used in one of two ways.  It can be incorporated into any one of the MD codes listed below:
 
-@CODES@
+@CODESL@
 
 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.
 
+\page Changelog Change Log
+
+- Changes for \subpage CHANGES-2-0
+- Changes for \subpage CHANGES-2-1
+- \subpage CHANGES-UNRELEASED
 
 */
 

user-doc/Makefile

@@ -21,4 +21,4 @@ all:
 endif
 
 clean:
-	rm -fr html latex automatic *~ *PP.txt errors 
+	rm -fr html latex automatic *~ *PP.txt errors manual.pdf

user-doc/Misc.txt

 /**
 
+\page Miscelaneous Miscelaneous
+
+- \subpage comments
+- \subpage ContinuationLines
+- \subpage includes
+- \subpage load
+- \subpage degub
+- \subpage exchange-patterns
+- \subpage mymodules
+- \subpage misc
+
+\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 
+comments can be added using a # sign.  On any given line everything after the # sign is ignored so 
+erm... yes add lines of comments or trailing comments to your hearts content as shown below (using Shakespeare is optional):
+
+\verbatim
+# This is the distance between two atoms:
+DISTANCE ATOM=1,2 LABEL=d1
+UPPER_WALLS ARG=d1 AT=3.0 KAPPA=3.0 LABEL=Snout # In this same interlude it doth befall. That I, one Snout by name, present a wall.
+\endverbatim
+(see \ref DISTANCE and \ref UPPER_WALLS)
+
+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.
+
+\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 
+easier - aren't we kind?  Well no not really, we have to use this code too.  Anyway, you can do continuations by using the "..." syntax
+as this makes this: 
+
+\verbatim
+DISTANCES ATOMS1=1,300 ATOMS2=1,400 ATOMS3=1,500
+\endverbatim
+(see \ref DISTANCES)
+
+equivalent to this:
+
+\verbatim
+DISTANCES ...
+# we can also insert comments here
+  ATOMS1=1,300
+# multiple kewords per line are allowed
+  ATOMS2=1,400 ATOMS3=1,500
+#empty lines are also allowed
+
+... DISTANCES
+\endverbatim
+
+\page includes Including other files 
+
+If, for some reason, you want to spread your PLUMED input over a number of files you can use \subpage INCLUDE as shown below:
+
+\verbatim
+INCLUDE FILE=filename
+\endverbatim
+
+So, for example, a single "plumed.dat" file:
+
+\verbatim
+DISTANCE ATOMS=0,1 LABEL=dist
+RESTRAINT ARG=dist
+\endverbatim
+(see \ref DISTANCE and \ref RESTRAINT)
+
+could be split up into two files as shown below:
+ 
+\verbatim
+DISTANCE ATOMS=0,1 LABEL=dist
+INCLUDE FILE=toBeIncluded.dat
+\endverbatim
+plus a "toBeIncluded.dat" file
+\verbatim
+RESTRAINT ARG=dist
+\endverbatim
+
+However, when you do this it is important to recognise that \ref INCLUDE is a real directive that is only resolved
+after all the \ref comments have been stripped and the \ref ContinuationLines have been unrolled.  This means it
+is not possible to do things like:
+
+\verbatim
+# this is wrong:
+DISTANCE INCLUDE FILE=options.dat
+RESTRAINT ARG=dist
+\endverbatim
+
+\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
+so you can release it independely - we won't be offended), then you can create your own dynamic library.  To use this 
+in conjuction with PLUMED you can then load it at runtime by using the \subpage LOAD keyword as shown below:
+
+\verbatim
+LOAD FILE=library.so
+\endverbatim
+ 
+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.
+
+\page degub Debugging the code
+
+The \subpage 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.
+
+\page exchange-patterns Changing exchange patterns in replica exchange
+
+Using the \subpage RANDOM_EXCHANGES keyword it is possible to make exchanges betweem randomly
+chosen replicas. This is useful e.g. for bias exchange metadynamics \cite{piana}.
+
 \page misc Frequently used tools
 
 @DICTIONARY@
 <TABLE ALIGN="center" FRAME="void" WIDTH="95%%" CELLPADDING="5%%">
 <TR>
 <TD WIDTH="5%"> 
-\ref Regex </TD><TD> </TD><TD> POSIX regular expressions can be used to select multiple actions when using ARG (i.e. \ref PRINT).
+\subpage Regex </TD><TD> </TD><TD> POSIX regular expressions can be used to select multiple actions when using ARG (i.e. \ref PRINT).
 </TD>
 </TR>
 </TABLE>

user-doc/Syntax.txt

@@ -65,105 +65,7 @@ By default the PLUMED inputs and outputs quantities in the following units:
 - Time - picoseconds
 
 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. 
-
-\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 
-comments can be added using a # sign.  On any given line everything after the # sign is ignored so 
-erm... yes add lines of comments or trailing comments to your hearts content as shown below (using Shakespeare is optional):
-
-\verbatim
-# This is the distance between two atoms:
-DISTANCE ATOM=1,2 LABEL=d1
-UPPER_WALLS ARG=d1 AT=3.0 KAPPA=3.0 LABEL=Snout # In this same interlude it doth befall. That I, one Snout by name, present a wall.
-\endverbatim
-(see \ref DISTANCE and \ref UPPER_WALLS)
-
-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.
-
-\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 
-easier - aren't we kind?  Well no not really, we have to use this code too.  Anyway, you can do continuations by using the "..." syntax
-as this makes this: 
-
-\verbatim
-DISTANCES ATOMS1=1,300 ATOMS2=1,400 ATOMS3=1,500
-\endverbatim
-(see \ref DISTANCES)
-
-equivalent to this:
-
-\verbatim
-DISTANCES ...
-# we can also insert comments here
-  ATOMS1=1,300
-# multiple kewords per line are allowed
-  ATOMS2=1,400 ATOMS3=1,500
-#empty lines are also allowed
-
-... DISTANCES
-\endverbatim
-
-\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:
-
-\verbatim
-INCLUDE FILE=filename
-\endverbatim
-
-So, for example, a single "plumed.dat" file:
-
-\verbatim
-DISTANCE ATOMS=0,1 LABEL=dist
-RESTRAINT ARG=dist
-\endverbatim
-(see \ref DISTANCE and \ref RESTRAINT)
-
-could be split up into two files as shown below:
- 
-\verbatim
-DISTANCE ATOMS=0,1 LABEL=dist
-INCLUDE FILE=toBeIncluded.dat
-\endverbatim
-plus a "toBeIncluded.dat" file
-\verbatim
-RESTRAINT ARG=dist
-\endverbatim
-
-However, when you do this it is important to recognise that \ref INCLUDE is a real directive that is only resolved
-after all the \ref comments have been stripped and the \ref ContinuationLines have been unrolled.  This means it
-is not possible to do things like:
-
-\verbatim
-# this is wrong:
-DISTANCE INCLUDE FILE=options.dat
-RESTRAINT ARG=dist
-\endverbatim
-
-\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
-so you can release it independely - we won't be offended), then you can create your own dynamic library.  To use this 
-in conjuction with PLUMED you can then load it at runtime by using the \ref LOAD keyword as shown below:
-
-\verbatim
-LOAD FILE=library.so
-\endverbatim
- 
-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.
-
-\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.
+\subpage UNITS keyword. 
 
 */
 

user-doc/extract

@@ -36,8 +36,9 @@ done
 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 "- \ref $mytag" >> automatic/codes.list
+   mytag=`echo "$myengine" | sed -e 's/\./-/g'`
+   echo "- $mytag" >> automatic/codesl.list # list only, for Intro
+   echo "- \subpage $mytag " >> automatic/codes.list
    echo "/**" >> automatic/$myengine.txt
    echo "\page $mytag $myengine" >> automatic/$myengine.txt
    plumed patch -e $myengine -i -q >> automatic/$myengine.txt
@@ -231,5 +232,6 @@ cat $file.txt |
     /^ *@TOOLS@ *$/r      automatic/TOOLS.list
     /^ *@MODULES@ *$/r    automatic/modules.list
     /^ *@CODES@ *$/r      automatic/codes.list
+    /^ *@CODESL@ *$/r   automatic/codesl.list
 " | grep -Ev '^ *@[A-Z]*@ *$' > ${file}PP.txt
 done

user-doc/go-doxygen

@@ -15,8 +15,19 @@ else
   fi
 fi
 
+LIST="
+ IntroPP.txt ../CHANGES InstallationPP.txt SyntaxPP.txt ColvarPP.txt GroupPP.txt FunctionsPP.txt AnalysisPP.txt
+  BiasPP.txt ToolsPP.txt MiscPP.txt RegexPP.txt ModulesPP.txt TutorialsPP.txt GlossaryPP.txt automatic tutorials"
+
 {
   cat Doxyfile
   echo "PROJECT_NUMBER = \"$(plumed info --version)\""
-  echo "INPUT+=" *PP.txt
+  echo "INPUT+=" $LIST
+  # add this to manually control layout:
+  # echo "LAYOUT_FILE=PlumedLayout.xml"
 } | doxygen -
+
+cd latex
+make
+cp refman.pdf ../manual.pdf
+