Support rst tables in tool help texts

Make it possible to use reStructuredTables in the help texts for tools,
and replace some [BR] tags in gmx energy help with a proper table.  The
formatting in the HTML help is greatly improved.

Change-Id: Ib25f7366d3196ba10fbc6cbcd09a0edd8dd3daf5

diff --git a/src/gromacs/gmxana/gmx_energy.c b/src/gromacs/gmxana/gmx_energy.c
index 89db7f316e087c8d76bd94d86c55b77cd36485d5..9851f10bc80aa6605894fbe425e7440f29557cbc 100644 (file)
--- a/src/gromacs/gmxana/gmx_energy.c
+++ b/src/gromacs/gmxana/gmx_energy.c
@@ -1874,15 +1874,18 @@ int gmx_energy(int argc, char *argv[])
         "Some fluctuation-dependent properties can be calculated provided",
         "the correct energy terms are selected, and that the command line option",
         "[TT]-fluct_props[tt] is given. The following properties",
-        "will be computed:[BR]",
-        "Property                        Energy terms needed[BR]",
-        "---------------------------------------------------[BR]",
-        "Heat capacity C[SUB]p[sub] (NPT sims):    Enthalpy, Temp     [BR]",
-        "Heat capacity C[SUB]v[sub] (NVT sims):    Etot, Temp         [BR]",
-        "Thermal expansion coeff. (NPT): Enthalpy, Vol, Temp[BR]",
-        "Isothermal compressibility:     Vol, Temp          [BR]",
-        "Adiabatic bulk modulus:         Vol, Temp          [BR]",
-        "---------------------------------------------------[BR]",
+        "will be computed:",
+        "",
+        "===============================  ===================",
+        "Property                         Energy terms needed",
+        "===============================  ===================",
+        "Heat capacity C[SUB]p[sub] (NPT sims):    Enthalpy, Temp",
+        "Heat capacity C[SUB]v[sub] (NVT sims):    Etot, Temp",
+        "Thermal expansion coeff. (NPT):  Enthalpy, Vol, Temp",
+        "Isothermal compressibility:      Vol, Temp",
+        "Adiabatic bulk modulus:          Vol, Temp",
+        "===============================  ===================",
+        "",
         "You always need to set the number of molecules [TT]-nmol[tt].",
         "The C[SUB]p[sub]/C[SUB]v[sub] computations do [BB]not[bb] include any corrections",
         "for quantum effects. Use the [gmx-dos] program if you need that (and you do).[PAR]"

diff --git a/src/gromacs/onlinehelp/helpwritercontext.cpp b/src/gromacs/onlinehelp/helpwritercontext.cpp
index 415f2602f7f9d57d4cae5d5233d6a3fc058b38f0..4b6ad5ab2613adc447b6cb8df68f99ed855f7231 100644 (file)
--- a/src/gromacs/onlinehelp/helpwritercontext.cpp
+++ b/src/gromacs/onlinehelp/helpwritercontext.cpp
@@ -371,6 +371,45 @@ bool startsListItem(const std::string &text, size_t index)
     return false;
 }
 
+/*! \brief
+ * Returns `true` if a table starts in \p text at \p index.
+ *
+ * The function only inspects the first line for something that looks like a
+ * reStructuredText table, and accepts also some malformed tables.
+ * Any issues should be apparent when Sphinx parses the reStructuredText
+ * export, so full validation is not done here.
+ *
+ * Does not throw.
+ */
+bool startsTable(const std::string &text, size_t index)
+{
+    if (text[index] == '=')
+    {
+        while (index < text.length() && text[index] != '\n')
+        {
+            if (text[index] != '=' && !std::isspace(text[index]))
+            {
+                return false;
+            }
+            ++index;
+        }
+        return true;
+    }
+    else if (text[index] == '+')
+    {
+        while (index < text.length() && text[index] != '\n')
+        {
+            if (text[index] != '-' && text[index] != '+')
+            {
+                return false;
+            }
+            ++index;
+        }
+        return true;
+    }
+    return false;
+}
+
 //! \}
 
 }   // namespace
@@ -659,6 +698,10 @@ void HelpWriterContext::Impl::processMarkup(const std::string &text,
                             }
                             indent = currentIndent + prefixLength;
                         }
+                        else if (currentLine == 0 && startsTable(result, i))
+                        {
+                            bLiteral = true;
+                        }
                         bLineStart = false;
                     }
                     paragraph.push_back(result[i]);

diff --git a/src/gromacs/onlinehelp/tests/helpwritercontext.cpp b/src/gromacs/onlinehelp/tests/helpwritercontext.cpp
index 9db5f0e3403159f08174d5320e5b40a99ef86637..b1daa1697f4a15b80060bded2bad34d78b0ead3a 100644 (file)
--- a/src/gromacs/onlinehelp/tests/helpwritercontext.cpp
+++ b/src/gromacs/onlinehelp/tests/helpwritercontext.cpp
@@ -207,4 +207,38 @@ TEST_F(HelpWriterContextTest, FormatsEnumeratedList)
     testFormatting(text);
 }
 
+TEST_F(HelpWriterContextTest, FormatsSimpleTable)
+{
+    const char *const text[] = {
+        "Simple table:",
+        "",
+        "============  =============",
+        "First column  Second header",
+        "============  =============",
+        "text          text",
+        "============  =============",
+        "",
+        "Normal paragraph",
+        "again."
+    };
+    testFormatting(text);
+}
+
+TEST_F(HelpWriterContextTest, FormatsGridTable)
+{
+    const char *const text[] = {
+        "Grid table:",
+        "",
+        "+--------------+---------------+",
+        "| First column | Second header |",
+        "+--------------+---------------+",
+        "| text         | text          |",
+        "+--------------+---------------+",
+        "",
+        "Normal paragraph",
+        "again."
+    };
+    testFormatting(text);
+}
+
 } // namespace

diff --git a/src/gromacs/onlinehelp/tests/refdata/HelpWriterContextTest_FormatsGridTable.xml b/src/gromacs/onlinehelp/tests/refdata/HelpWriterContextTest_FormatsGridTable.xml
new file mode 100644 (file)
index 0000000..8b7deab
--- /dev/null
+++ b/src/gromacs/onlinehelp/tests/refdata/HelpWriterContextTest_FormatsGridTable.xml
@@ -0,0 +1,25 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="referencedata.xsl"?>
+<ReferenceData>
+  <String Name="Console"><![CDATA[
+Grid table:
+
++--------------+---------------+
+| First column | Second header |
++--------------+---------------+
+| text         | text          |
++--------------+---------------+
+
+Normal paragraph again.]]></String>
+  <String Name="reStructuredText"><![CDATA[
+Grid table:
+
++--------------+---------------+
+| First column | Second header |
++--------------+---------------+
+| text         | text          |
++--------------+---------------+
+
+Normal paragraph
+again.]]></String>
+</ReferenceData>

diff --git a/src/gromacs/onlinehelp/tests/refdata/HelpWriterContextTest_FormatsSimpleTable.xml b/src/gromacs/onlinehelp/tests/refdata/HelpWriterContextTest_FormatsSimpleTable.xml
new file mode 100644 (file)
index 0000000..c1d0bb3
--- /dev/null
+++ b/src/gromacs/onlinehelp/tests/refdata/HelpWriterContextTest_FormatsSimpleTable.xml
@@ -0,0 +1,25 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="referencedata.xsl"?>
+<ReferenceData>
+  <String Name="Console"><![CDATA[
+Simple table:
+
+============  =============
+First column  Second header
+============  =============
+text          text
+============  =============
+
+Normal paragraph again.]]></String>
+  <String Name="reStructuredText"><![CDATA[
+Simple table:
+
+============  =============
+First column  Second header
+============  =============
+text          text
+============  =============
+
+Normal paragraph
+again.]]></String>
+</ReferenceData>