Add note about atom order in selections

[alexxy/gromacs.git] / src / gromacs / selection / selhelp.cpp

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