From 7b93c5a7d9bf9700b5636944add3927601298507 Mon Sep 17 00:00:00 2001
From: Giovanni Bussi <giovanni.bussi@gmail.com>
Date: Tue, 13 Jun 2017 18:29:27 +0200
Subject: [PATCH] Reorganization of manual source files
I renamed all files from .txt to .md so that they can be
visualized on github.
In addition, I renamed all files to have a name consistent with the content.
This makes manual portions easier to find.
Notice that I left the original labels (e.g. "Syntax" instead of "Getting Started")
not to break direct links to manual, though I think we should rationalize these names
as well.
[makedoc]
---
user-doc/.gitignore | 1 +
user-doc/{Analysis.txt => Analysis.md} | 4 --
user-doc/{Bias.txt => Bias.md} | 4 --
user-doc/ChangeLog.md | 33 ++++++++++++++++
.../{Colvar.txt => CollectiveVariables.md} | 6 +--
user-doc/{Tools.txt => CommandLineTools.md} | 3 --
user-doc/{Files.txt => Files.md} | 4 --
user-doc/{Functions.txt => Functions.md} | 3 --
user-doc/{Syntax.txt => GettingStarted.md} | 5 +--
user-doc/{Glossary.txt => Glossary.md} | 5 +--
user-doc/{Group.txt => Group.md} | 5 ---
.../{Installation.txt => Installation.md} | 7 ----
user-doc/{Intro.txt => Introduction.md} | 38 +------------------
user-doc/Makefile | 2 +-
user-doc/{Misc.txt => Miscelaneous.md} | 5 ---
user-doc/{Modules.txt => Modules.md} | 5 +--
.../{Performances.txt => Performances.md} | 4 --
user-doc/{Regex.txt => Regex.md} | 4 --
user-doc/{Tutorials.txt => Tutorials.md} | 5 +--
user-doc/extract | 14 ++++---
user-doc/go-doxygen | 25 ++++++++++--
21 files changed, 71 insertions(+), 111 deletions(-)
rename user-doc/{Analysis.txt => Analysis.md} (99%)
rename user-doc/{Bias.txt => Bias.md} (97%)
create mode 100644 user-doc/ChangeLog.md
rename user-doc/{Colvar.txt => CollectiveVariables.md} (99%)
rename user-doc/{Tools.txt => CommandLineTools.md} (98%)
rename user-doc/{Files.txt => Files.md} (99%)
rename user-doc/{Functions.txt => Functions.md} (99%)
rename user-doc/{Syntax.txt => GettingStarted.md} (99%)
rename user-doc/{Glossary.txt => Glossary.md} (93%)
rename user-doc/{Group.txt => Group.md} (99%)
rename user-doc/{Installation.txt => Installation.md} (99%)
rename user-doc/{Intro.txt => Introduction.md} (64%)
rename user-doc/{Misc.txt => Miscelaneous.md} (99%)
rename user-doc/{Modules.txt => Modules.md} (98%)
rename user-doc/{Performances.txt => Performances.md} (99%)
rename user-doc/{Regex.txt => Regex.md} (99%)
rename user-doc/{Tutorials.txt => Tutorials.md} (83%)
diff --git a/user-doc/.gitignore b/user-doc/.gitignore
index ff1be481a..a187357cd 100644
--- a/user-doc/.gitignore
+++ b/user-doc/.gitignore
@@ -3,6 +3,7 @@
/*.tmp
/automatic
/*PP.txt
+/*PP.md
/errors
/modifier_file
/*aux
diff --git a/user-doc/Analysis.txt b/user-doc/Analysis.md
similarity index 99%
rename from user-doc/Analysis.txt
rename to user-doc/Analysis.md
index ef3a00589..4f1246667 100644
--- a/user-doc/Analysis.txt
+++ b/user-doc/Analysis.md
@@ -1,5 +1,3 @@
-/**
-
\page Analysis Analysis
PLUMED can be used to analyse trajectories either on the fly during an MD run or via
@@ -90,5 +88,3 @@ the trajectory. The RUN keyword then tells PLUMED how frequently to do the dime
described above if RUN is not present and you are analysing trajectories using \ref driver all the data in
the traejctory (with the expection of the first frame) will be analysed.
-*/
-
diff --git a/user-doc/Bias.txt b/user-doc/Bias.md
similarity index 97%
rename from user-doc/Bias.txt
rename to user-doc/Bias.md
index 94eb105e3..7d835927b 100644
--- a/user-doc/Bias.txt
+++ b/user-doc/Bias.md
@@ -1,5 +1,3 @@
-/**
-
\page Bias Bias
PLUMED allows you to run a number of enhanced sampling algorithms.
@@ -10,5 +8,3 @@ The list of enhanced sampling algorithms contained in PLUMED is as follows:
Methods, such as \ref METAD or \ref PBMETAD, that work by introducing a history dependent bias can be restarted
using the \subpage RESTART keyword
-*/
-
diff --git a/user-doc/ChangeLog.md b/user-doc/ChangeLog.md
new file mode 100644
index 000000000..684318ac7
--- /dev/null
+++ b/user-doc/ChangeLog.md
@@ -0,0 +1,33 @@
+\page ChangeLog Change Log
+
+Here you can find a history of changes across different PLUMED versions.
+The future releases are expected to follow more or less the pace
+of the old release. This means:
+- Approximately once per year, after summer, a new release (2.X). These releases
+ typically group together all the features that were contributed during the
+ year.
+- Approximately every three month, we announce a patch (e.g. 2.2.X).
+ This typically contains bug fixes, and could occasionally contain a new feature.
+
+A few months before each new release we provide a beta release.
+We typically maintain release branches until the fifth patch release (2.X.5),
+which should come out approximately 15 month after the original release (2.X).
+After that, branches are not supported anymore.
+
+Notice that occasionally we publish patches on the mailing list.
+These patches are always included in the following release, but we encourage
+users that want to be up to date to follow the mailing list.
+
+Below you can find change logs for all the published releases.
+We mostly add new features without breaking existing ones.
+However, some of the changes lead to incompatible behavior.
+In the Change Log we try to give as much visibility as possible to these changes
+to avoid surprises.
+
+We also log changes that are relevant if you are developing the code. These
+change lists are however not complete, and if you want to put your hands in the code
+and maintain your own collective variables we suggest you to follow the development
+on github.
+
+@CHANGES@
+
diff --git a/user-doc/Colvar.txt b/user-doc/CollectiveVariables.md
similarity index 99%
rename from user-doc/Colvar.txt
rename to user-doc/CollectiveVariables.md
index 840fe41c8..4a090d4de 100644
--- a/user-doc/Colvar.txt
+++ b/user-doc/CollectiveVariables.md
@@ -1,6 +1,4 @@
-/**
-
-\page colvarintro 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,
@@ -203,5 +201,3 @@ with a set of connected components are listed below:
@CONCOMP@
-*/
-
diff --git a/user-doc/Tools.txt b/user-doc/CommandLineTools.md
similarity index 98%
rename from user-doc/Tools.txt
rename to user-doc/CommandLineTools.md
index efe59c206..10f8c9979 100644
--- a/user-doc/Tools.txt
+++ b/user-doc/CommandLineTools.md
@@ -1,5 +1,3 @@
-/**
-
\page tools Command Line Tools
PLUMED contains a number of simple command line tools. To use one of these tools
@@ -15,4 +13,3 @@ The following is a list of the various standalone tools that PLUMED contains.
For all these tools and to use PLUMED as a plugin in an MD calculation you will need an input file.
-*/
diff --git a/user-doc/Files.txt b/user-doc/Files.md
similarity index 99%
rename from user-doc/Files.txt
rename to user-doc/Files.md
index 3c1c4c8af..f7411c338 100644
--- a/user-doc/Files.txt
+++ b/user-doc/Files.md
@@ -1,5 +1,3 @@
-/**
-
\page Files Files
We tried to design PLUMED in such a manner that input/output is done consistently
@@ -62,5 +60,3 @@ PLUMED will write files named COLVAR.0.gz, COLVAR.1.gz, test.0.HILLS, test.1.HIL
etc. This is useful since the preserved extension makes it easy
to process the files later.
-
-*/
diff --git a/user-doc/Functions.txt b/user-doc/Functions.md
similarity index 99%
rename from user-doc/Functions.txt
rename to user-doc/Functions.md
index 53de40f36..444ff57f2 100644
--- a/user-doc/Functions.txt
+++ b/user-doc/Functions.md
@@ -1,4 +1,3 @@
-/**
\page Function Functions
When performing biased dynamics or analysing a trajectory you may wish to analyse/bias the value of
@@ -43,5 +42,3 @@ dz: COMBINE ARG=d.z PERIODIC=-10,10
@FUNCTION@
-*/
-
diff --git a/user-doc/Syntax.txt b/user-doc/GettingStarted.md
similarity index 99%
rename from user-doc/Syntax.txt
rename to user-doc/GettingStarted.md
index 277d339e9..496c7a146 100644
--- a/user-doc/Syntax.txt
+++ b/user-doc/GettingStarted.md
@@ -1,5 +1,4 @@
-/**
-\page Syntax Getting started
+\page Syntax Getting Started
To run PLUMED 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
@@ -74,5 +73,3 @@ 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
\subpage UNITS keyword.
-*/
-
diff --git a/user-doc/Glossary.txt b/user-doc/Glossary.md
similarity index 93%
rename from user-doc/Glossary.txt
rename to user-doc/Glossary.md
index 5ca385d32..f618c7f28 100644
--- a/user-doc/Glossary.txt
+++ b/user-doc/Glossary.md
@@ -1,6 +1,4 @@
-/**
-
-@page glossary Index of Actions
+\page glossary Index of Actions
The following page contains an alphabetically ordered list of all the Actions and command line tools
that are available in PLUMED 2. For lists of Actions classified in accordance with the
@@ -14,4 +12,3 @@ particular tasks that are being performed see:
@GLOSSARY@
-*/
diff --git a/user-doc/Group.txt b/user-doc/Group.md
similarity index 99%
rename from user-doc/Group.txt
rename to user-doc/Group.md
index 6edc0225b..3aa4d63d6 100644
--- a/user-doc/Group.txt
+++ b/user-doc/Group.md
@@ -1,5 +1,3 @@
-/**
-
\page Group Groups and Virtual Atoms
\section atomSpecs Specifying Atoms
@@ -124,6 +122,3 @@ DISTANCE ATOMS=11,com1
If you don't want to calculate CVs from the virtual atom. That is to say you just want to monitor the position of a virtual atom
(or any set of atoms) over the course of your trajectory you can do this using \ref DUMPATOMS.
-
-*/
-
diff --git a/user-doc/Installation.txt b/user-doc/Installation.md
similarity index 99%
rename from user-doc/Installation.txt
rename to user-doc/Installation.md
index 1179cac28..9013f5fe7 100644
--- a/user-doc/Installation.txt
+++ b/user-doc/Installation.md
@@ -1,5 +1,3 @@
-/**
-
\page Installation Installation
In this page you can learn how to
@@ -601,8 +599,3 @@ Notice that MD codes with native PLUMED support are not listed here.
@CODES@
-
-
-
-*/
-
diff --git a/user-doc/Intro.txt b/user-doc/Introduction.md
similarity index 64%
rename from user-doc/Intro.txt
rename to user-doc/Introduction.md
index fdf050b08..4f69ec3a3 100644
--- a/user-doc/Intro.txt
+++ b/user-doc/Introduction.md
@@ -1,4 +1,3 @@
-/**
\mainpage Introduction
PLUMED is a plugin that works with a large number of molecular dynamics codes (\ref codes).
@@ -7,7 +6,7 @@ PLUMED can also work as a \ref tools to perform analysis on trajectories saved i
existing formats. If PLUMED is useful for your work please read and cite \cite plumed2, if you are interested in
the PLUMED 1 original publication please read and cite \cite plumed1 .
-To follow the development of PLUMED 2, you can look at the detailed \ref Changelog .
+To follow the development of PLUMED 2, you can look at the detailed \ref ChangeLog .
To install PLUMED, see this page: \ref Installation , while in \ref Syntax you can find a brief introduction on how to write your first PLUMED input file.
@@ -52,38 +51,3 @@ also from the following packages:
- [PLUMED-GUI](http://github.com/tonigi/vmd_plumed) is a [VMD](http://www.ks.uiuc.edu/Research/vmd/) plugin that computes PLUMED collective variables.
- [HTMD](http://www.htmd.org/) can use PLUMED collective variables for analysis.
-\page Changelog Change Log
-
-Here you can find a history of changes across different PLUMED versions.
-The future releases are expected to follow more or less the pace
-of the old release. This means:
-- Approximately once per year, after summer, a new release (2.X). These releases
- typically group together all the features that were contributed during the
- year.
-- Approximately every three month, we announce a patch (e.g. 2.2.X).
- This typically contains bug fixes, and could occasionally contain a new feature.
-
-A few months before each new release we provide a beta release.
-We typically maintain release branches until the fifth patch release (2.X.5),
-which should come out approximately 15 month after the original release (2.X).
-After that, branches are not supported anymore.
-
-Notice that occasionally we publish patches on the mailing list.
-These patches are always included in the following release, but we encourage
-users that want to be up to date to follow the mailing list.
-
-Below you can find change logs for all the published releases.
-We mostly add new features without breaking existing ones.
-However, some of the changes lead to incompatible behavior.
-In the Change Log we try to give as much visibility as possible to these changes
-to avoid surprises.
-
-We also log changes that are relevant if you are developing the code. These
-change lists are however not complete, and if you want to put your hands in the code
-and maintain your own collective variables we suggest you to follow the development
-on github.
-
-@CHANGES@
-
-*/
-
diff --git a/user-doc/Makefile b/user-doc/Makefile
index dfb3524d4..3ac15dd61 100644
--- a/user-doc/Makefile
+++ b/user-doc/Makefile
@@ -24,4 +24,4 @@ endif
endif
clean:
- rm -fr html latex automatic *~ *PP.txt errors manual.pdf regtests
+ rm -fr html latex automatic *~ *PP.txt *PP.md errors manual.pdf regtests
diff --git a/user-doc/Misc.txt b/user-doc/Miscelaneous.md
similarity index 99%
rename from user-doc/Misc.txt
rename to user-doc/Miscelaneous.md
index 4fceb133d..dc706f0fa 100644
--- a/user-doc/Misc.txt
+++ b/user-doc/Miscelaneous.md
@@ -1,5 +1,3 @@
-/**
-
\page Miscelaneous Miscelaneous
- \subpage comments
@@ -437,6 +435,3 @@ chosen replicas. This is useful e.g. for bias exchange metadynamics \cite piana.
</TR>
</TABLE>
-
-
-*/
diff --git a/user-doc/Modules.txt b/user-doc/Modules.md
similarity index 98%
rename from user-doc/Modules.txt
rename to user-doc/Modules.md
index 70df94bce..83f7d4751 100644
--- a/user-doc/Modules.txt
+++ b/user-doc/Modules.md
@@ -1,6 +1,4 @@
-/**
-
-@page mymodules List of modules
+\page mymodules List of modules
The functionality in PLUMED 2 is divided into a small number of modules. Some
users may only wish to use a subset of the functionality available within the
@@ -54,4 +52,3 @@ Until PLUMED 2.2, it was also possible to switch on or off modules by adding fil
in the plumed2/src directory. Since PLUMED 2.3 this is discouraged, since any choice made
in this manner will be overwritten next time `./configure` is used.
-*/
diff --git a/user-doc/Performances.txt b/user-doc/Performances.md
similarity index 99%
rename from user-doc/Performances.txt
rename to user-doc/Performances.md
index 00fc973ac..b6830637c 100644
--- a/user-doc/Performances.txt
+++ b/user-doc/Performances.md
@@ -1,5 +1,3 @@
-/**
-
\page Performances Performances
In this page we collect hints on how to use the features available in PLUMED to speed
@@ -218,5 +216,3 @@ or just use somenthing else)
To have an accurate timing of your input you can use the \ref DEBUG DETAILED_TIMERS.
-
-*/
diff --git a/user-doc/Regex.txt b/user-doc/Regex.md
similarity index 99%
rename from user-doc/Regex.txt
rename to user-doc/Regex.md
index 11999b582..29c610abb 100644
--- a/user-doc/Regex.txt
+++ b/user-doc/Regex.md
@@ -1,5 +1,3 @@
-/**
-
\page Regex Regular Expressions
When you use need to pass many arguments to a PLUMED action, being them
@@ -82,5 +80,3 @@ You can check the log to see whether or not your regular expression is picking t
For more information on regular expressions visit http://www.regular-expressions.info/reference.html.
-*/
-
diff --git a/user-doc/Tutorials.txt b/user-doc/Tutorials.md
similarity index 83%
rename from user-doc/Tutorials.txt
rename to user-doc/Tutorials.md
index edeb14db6..283a6eb78 100644
--- a/user-doc/Tutorials.txt
+++ b/user-doc/Tutorials.md
@@ -1,6 +1,4 @@
-/**
-
-@page tutorials Tutorials
+\page tutorials Tutorials
The following pages describe how to perform a variety of tasks using PLUMED
@@ -10,4 +8,3 @@ In addition, the following websites contain resources that might be helpful
@WEBSITES@
-*/
diff --git a/user-doc/extract b/user-doc/extract
index 0462705d7..7982325a0 100755
--- a/user-doc/extract
+++ b/user-doc/extract
@@ -262,16 +262,20 @@ done
sed -ie 's/<b> --/<b> \\c \\-\\-/g' automatic/*.txt
rm automatic/*.txte
-rm -f *PP.txt
-for f in *.txt
+rm -f *PP.txt *PP.md
+for f in *.txt *.md
do
-file=${f%.txt}
+test -f $f || continue
+
+extension=${f##*.}
+
+file=${f%.$extension}
# first replace with the content of the files
# then grep out the special strings
-cat $file.txt |
+cat $f |
sed "
/^ *@COLVAR@ *$/r automatic/COLVAR.list
/^ *@MCOLVAR@ *$/r automatic/MCOLVAR.list
@@ -304,5 +308,5 @@ cat $file.txt |
/^ *@VERSION@ *$/r automatic/version.tmp
/^ *@CHANGES@ *$/r automatic/changes.tmp
/^ *@PDFMANUAL@ *$/r automatic/pdfmanual.tmp
-" | grep -Ev '^ *@[A-Z]*@ *$' > ${file}PP.txt
+" | grep -Ev '^ *@[A-Z]*@ *$' > ${file}PP.$extension
done
diff --git a/user-doc/go-doxygen b/user-doc/go-doxygen
index a3d87e201..fff47ed0c 100755
--- a/user-doc/go-doxygen
+++ b/user-doc/go-doxygen
@@ -3,8 +3,25 @@
source ../sourceme.sh
LIST="
- IntroPP.txt ../CHANGES InstallationPP.txt SyntaxPP.txt ColvarPP.txt GroupPP.txt FunctionsPP.txt AnalysisPP.txt
- BiasPP.txt ToolsPP.txt MiscPP.txt PerformancesPP.txt RegexPP.txt FilesPP.txt ModulesPP.txt TutorialsPP.txt GlossaryPP.txt automatic tutorials"
+ IntroductionPP.md
+ ChangeLogPP.md
+ ../CHANGES
+ InstallationPP.md
+ GettingStartedPP.md
+ CollectiveVariablesPP.md
+ GroupPP.md
+ FunctionsPP.md
+ AnalysisPP.md
+ BiasPP.md
+ CommandLineToolsPP.md
+ MiscelaneousPP.md
+ RegexPP.md
+ FilesPP.md
+ ModulesPP.md
+ TutorialsPP.md
+ PerformancesPP.md
+ GlossaryPP.md
+ automatic tutorials"
{
cat Doxyfile
@@ -32,7 +49,7 @@ awk -v version="$version" '{
sub("Page","("version")",$0);
print
} else if(match($0,"<span>Related Pages</span>")){
- print " <li><a href=\"_syntax.html\"><span>Getting started</span></a></li>"
+ print " <li><a href=\"_syntax.html\"><span>Getting Started</span></a></li>"
print " <li><a href=\"tutorials.html\"><span>Tutorials</span></a></li>"
print " <li><a href=\"glossary.html\"><span>Index of Actions</span></a></li>"
} else print
@@ -46,7 +63,7 @@ done
cat > html/menudata.js << EOF
var menudata={children:[
{text:'Home ($version)',url:'index.html'},
-{text:'Getting started',url:'_syntax.html'},
+{text:'Getting Started',url:'_syntax.html'},
{text:'Tutorials',url:'tutorials.html'},
{text:'Index of Actions',url:'glossary.html'}]}
EOF
--
GitLab