New manual version

new-manual/.gitignore

@@ -0,0 +1,2 @@
+docs
+site

new-manual/Files.md

@@ -0,0 +1,68 @@
+# Files
+
+We tried to design PLUMED in such a manner that input/output is done consistently
+irrespective of the file type. Most of the files written or read by PLUMED thus follow
+the conventions discussed below. 
+
+## Restart
+
+Whenever the [RESTART](RESTART.md) option is used, all the files written by PLUMED are appended.
+This makes it easy to analyze results of simulations performed as a chain of several sub-runs.
+Notice that most of the PLUMED textual files have a header. The header is repeated at every
+restart. Additionally, several files have time in the first column. PLUMED just takes the value
+of the physical time from the MD engine. As such, you could have that time starts again from zero
+upon restart or not.
+
+An exception from this behavior is given by files which are not growing as the simulation proceeds.
+For example, grids written with [METAD](METAD.md) with `GRID_WFILE` are overwritten by default during the simulation.
+As such, when restarting, there is no point in appending the file. Internally, PLUMED opens the file in append
+mode but then rewinds it every time a new grid is dumped.
+
+## Backup
+
+Whenever the [RESTART](RESTART.md) option is not used, PLUMED tries to write new files. If an old file
+is found in the way, PLUMED takes a backup named "bck.X.filename" where X is a progressive number.
+Notice that by default PLUMED only allows a maximum of 100 backup copies for a file.
+This behavior can be changed by setting the environment variable `PLUMED_MAXBACKUP` to the desired number
+of copies. E.g. export `PLUMED_MAXBACKUP=10` will fail after 10 copies. `PLUMED_MAXBACKUP=-1` will never fail - be careful
+since your disk might fill up quickly with this setting.
+
+# Replica-Suffix Replica suffix
+
+When running with multiple replicas (e.g., with GROMACS, -multi option) PLUMED adds the replica index as a suffix to
+all the files. The following command
+will thus print files named COLVAR.0, COLVAR.1, etc for the different replicas.
+
+```plumed
+#SETTINGS NREPLICAS=2
+d: DISTANCE ATOMS=1,2
+PRINT ARG=d FILE=COLVAR
+```
+
+When reading a file, PLUMED will try to add the suffix. If the file is not found, it will fall back to
+the name without suffix. The most important case is the reading of the plumed input file.
+If you provide a file for each replica (e.g. plumed.0.dat, plumed.1.dat, etc) you will be able to
+setup plumed differently on each replica. 
+On the other hand, using a single plumed.dat will make all the replicas read the same file.
+
+>[!CAUTION]
+>This rule is true for almost all the files read by PLUMED. As of
+>PLUMED version 2.4, the only exception is PDB files, where the replica suffix is not added.
+
+Notice that when PLUMED adds the replica suffix, it recognizes the file extension and add the suffix _before_ the
+extension. Before PLUMED 2.2, the only recognized suffix was ".gz". Since 2.2, any suffix with length
+less or equal to five letters is recognized.
+
+This means that if you use the following input in a multi-replica context 
+
+```plumed
+#SETTINGS NREPLICAS=2
+d: DISTANCE ATOMS=1,2
+PRINT ARG=d FILE=COLVAR.gz
+METAD ARG=d FILE=test.HILLS SIGMA=0.1 HEIGHT=0.1 PACE=100
+```
+
+PLUMED will write files named COLVAR.0.gz, COLVAR.1.gz, test.0.HILLS, test.1.HILLS, etc
+etc. This is useful since the preserved extension makes it easy
+to process the files later.
+

new-manual/Makefile

@@ -0,0 +1,27 @@
+# include the machine dependent configuration
+ifneq ($(MAKECMDGOALS),clean)
+  -include ../Makefile.conf
+endif
+
+.PHONY: all clean 
+
+plumed_compiled := $(wildcard ../src/lib/plumed)
+
+ifeq ($(strip $(plumed_compiled)),)
+
+all:
+	@echo You must compile plumed before building the user manual
+
+else
+
+all:
+ifeq ($(make_doc),yes)
+	rm -rf docs site
+	python build_manual.py
+	mkdocs build
+endif
+endif
+
+clean:
+	rm -rf docs site
+

new-manual/README.md

@@ -0,0 +1,22 @@
+# Installing
+
+You need to install the following:
+
+````
+pip install mkdocs
+pip install python-markdown-math 
+````
+
+# Building 
+
+You then build the website locally by doing
+
+```
+make
+```
+
+To see the website you do
+
+````
+mkdocs serve
+````

new-manual/actions.md

@@ -0,0 +1,81 @@
+Actions
+-------
+
+Every command in a PLUMED input file gives the input for an action or a [shortcut](shortcuts.md). The input for an action 
+can all be on a single line as shown below:
+
+```plumed
+d1: DISTANCE ATOMS=1,2 COMPONENTS
+```
+
+Alternatively, you can split the input for an action over multiple lines by using a continuation as shown below:
+
+```plumed
+d1: DISTANCE ...
+   ATOMS=1,2 
+   COMPONENTS
+...
+```
+
+## Adding comments
+
+If you are an organized 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):
+
+```plumed
+# This is the distance between two atoms:
+d1: DISTANCE ATOMS=1,2
+Snout: UPPER_WALLS ARG=d1 AT=3.0 KAPPA=3.0   # In this same interlude it doth befall.
+# That I, one Snout by name, present a wall.
+```
+
+PLUMED ignores any text in comments.  Consequently, if you provide the input for an action in a comment like this:
+
+```plumed
+# d1: DISTANCE ATOMS=1,2 COMPONENTS
+```
+
+a [DISTANCE](DISTANCE.md) command is not created. Similar behaviour is observed when you use the [ENDPLUMED](ENDPLUMED.md) comand.  For example, if your 
+input is as follows:
+
+```plumed
+d1: DISTANCE ATOMS=1,2 COMPONENTS
+ENDPLUMED
+d2: DISTANCE ATOMS=3,4
+```
+
+PLUMED will evaluate the distance between atom 1 and 2 but will not evaluate the distance between atoms 3 and 4.
+
+## Using INCLUDE files
+
+If, for some reason, you want to spread your PLUMED input over a number of files you can use [INCLUDE](INCLUDE.md) as shown below:
+
+````
+INCLUDE FILE=filename
+````
+
+So, for example, instead of having a single "plumed.dat" file:
+
+```plumed
+DISTANCE ATOMS=1,2 LABEL=dist
+RESTRAINT ARG=dist AT=2.0 KAPPA=1.0
+```
+
+you can split the input over a file like the one below and a file called `extras/toBeIncluded.inc` 
+
+```plumed
+DISTANCE ATOMS=1,2 LABEL=dist
+INCLUDE FILE=extras/toBeIncluded.inc
+```
+
+However, when you do this it is important to recognize that INCLUDE is a real directive that is only resolved
+after all the comments have been stripped and the continuation lines have been unrolled.  This means it
+is not possible to do things like:
+
+```plumed
+# this is wrong:
+DISTANCE INCLUDE FILE=options.dat
+RESTRAINT ARG=dist AT=2.0 KAPPA=1.0
+```

new-manual/assets/mermaid.css

@@ -0,0 +1,13 @@
+.mermaidTooltip {
+    position: absolute;
+    text-align: center;
+    max-width: 200px;
+    padding: 2px;
+    font-family: 'trebuchet ms', verdana, arial;
+    font-size: 12px;
+    background: #ffffde;
+    border: 1px solid #aaaa33;
+    border-radius: 2px;
+    pointer-events: none;
+    z-index: 100;
+} 

new-manual/assets/mermaid.js

@@ -0,0 +1,11 @@
+var config = {
+    startOnLoad:true,
+    theme: 'forest',
+    securityLevel: 'loose',
+    flowchart:{
+            useMaxWidth:false,
+            htmlLabels:true
+        }
+};
+mermaid.initialize(config);
+window.mermaid.init(undefined, document.querySelectorAll('.mermaid'));

new-manual/assets/tablecode.js

@@ -0,0 +1,18 @@
+$(document).ready(function() {
+var table = $('table.display').DataTable({
+  "dom": '<"search"f><"top"il>rt<"bottom"Bp><"clear">',
+  language: { search: '', searchPlaceholder: "Search table..." },
+  buttons: [
+        'copy', 'excel', 'pdf'
+  ],
+  "order": [[ 0, "desc" ]]
+  });
+$('#browse-table-searchbar').keyup(function () {
+  table.search( this.value ).draw();
+  });
+  var hu = window.location.search.substring(1);
+  var searchfor = hu.split("=");
+  if( searchfor[0]=="search" ) {
+      table.search( searchfor[1] ).draw();
+  }
+});