Add note about atom order in selections

Clarify the behavior of selections in that they always select atoms in
increasing order.  In the same context, mention the mechanisms in place
to work around this.  Use an example that shows the equivalence of
'a to b' and 'b to a' in the selection syntax.

Also clean up the formatting of the selection limitations help topic,
now that bullet lists are properly supported.

Related to #1742

Change-Id: I3daa17521767b3eaadcbc1d8c0c6fc986fa0aee3

diff --git a/src/gromacs/selection/selhelp.cpp b/src/gromacs/selection/selhelp.cpp
index b9662326800f103d59568e34dd4b91e1d5d580ec..2bcb6de49d48e86fcb26b32b103ff543e4e2d837 100644 (file)
--- a/src/gromacs/selection/selhelp.cpp
+++ b/src/gromacs/selection/selhelp.cpp
@@ -284,30 +284,51 @@ const char        LimitationsHelpText::name[]  = "limitations";
 const char        LimitationsHelpText::title[] =
     "Selection limitations";
 const char *const LimitationsHelpText::text[] = {
-    "Some analysis programs may require a special structure for the input",
-    "selections (e.g., [TT]gmx angle[tt] requires the index group to be made",
-    "of groups of three or four atoms).",
-    "For such programs, it is up to the user to provide a proper selection",
-    "expression that always returns such positions.",
-    "[PAR]",
-
-    "Due to technical reasons, having a negative value as the first value in",
-    "expressions like ::",
+    "* Some analysis programs may require a special structure for the input",
+    "  selections (e.g., some options of [TT]gmx gangle[tt] require the index",
+    "  group to be made of groups of three or four atoms).",
+    "  For such programs, it is up to the user to provide a proper selection",
+    "  expression that always returns such positions.",
     "",
-    "  charge -1 to -0.7",
+    "* All selection keywords select atoms in increasing order, i.e., you can",
+    "  consider them as set operations that in the end return the atoms in",
+    "  sorted numerical order.  For example, the following selections select",
+    "  the same atoms in the same order::",
     "",
-    "result in a syntax error. A workaround is to write ::",
+    "    resname RA RB RC",
+    "    resname RB RC RA",
     "",
-    "  charge {-1 to -0.7}",
+    "  ::",
     "",
-    "instead.[PAR]",
-
-    "When [TT]name[tt] selection keyword is used together with PDB input",
-    "files, the behavior may be unintuitive. When Gromacs reads in a PDB",
-    "file, 4 character atom names that start with a digit are transformed",
-    "such that, e.g., 1HG2 becomes HG21, and the latter is what is matched",
-    "by the [TT]name[tt] keyword. Use [TT]pdbname[tt] to match the atom name",
-    "as it appears in the input PDB file.",
+    "    atomnr 10 11 12 13",
+    "    atomnr 12 13 10 11",
+    "    atomnr 10 to 13",
+    "    atomnr 13 to 10",
+    "",
+    "  If you need atoms/positions in a different order, you can:",
+    "",
+    "  * use external index groups (for some static selections),",
+    "  * use the [TT]permute[tt] keyword to change the final order, or",
+    "  * use the [TT]merge[tt] or [TT]plus[tt] keywords to compose the",
+    "    final selection from multiple distinct selections.",
+    "",
+    "* Due to technical reasons, having a negative value as the first value in",
+    "  expressions like ::",
+    "",
+    "    charge -1 to -0.7",
+    "",
+    "  result in a syntax error. A workaround is to write ::",
+    "",
+    "    charge {-1 to -0.7}",
+    "",
+    "  instead.",
+    "",
+    "* When [TT]name[tt] selection keyword is used together with PDB input",
+    "  files, the behavior may be unintuitive. When GROMACS reads in a PDB",
+    "  file, 4 character atom names that start with a digit are transformed",
+    "  such that, e.g., 1HG2 becomes HG21, and the latter is what is matched",
+    "  by the [TT]name[tt] keyword. Use [TT]pdbname[tt] to match the atom name",
+    "  as it appears in the input PDB file.",
 };
 
 struct PositionsHelpText