Merge branch 'peppe/common_test/html_improvements_docs' into maint

* peppe/common_test/html_improvements_docs:
  Document the new HTML improvements

2 files changed, 81 insertions, 43 deletions

diff --git a/lib/common_test/doc/src/ct.xml b/lib/common_test/doc/src/ct.xml
index ed3d76061a..c96ae06c7d 100644
--- a/lib/common_test/doc/src/ct.xml
+++ b/lib/common_test/doc/src/ct.xml
@@ -661,52 +661,70 @@
 
     <func>
       <name>log(Format) -&gt; ok</name>
-      <fsummary>Equivalent to log(default, 50, Format, []).</fsummary>
+      <fsummary>Equivalent to log(default, 50, Format, [], []).</fsummary>
       <desc><marker id="log-1"/>
         <p>Equivalent to
-          <seealso marker="#log-4"><c>ct:log(default, 50, Format, [])</c></seealso>.</p>
+          <seealso marker="#log-5"><c>ct:log(default, 50, Format, [], [])</c></seealso>.</p>
       </desc>
     </func>
 
     <func>
       <name>log(X1, X2) -&gt; ok</name>
       <fsummary>Equivalent to log(Category, Importance, Format,
-        Args).</fsummary>
+        FormatArgs, []).</fsummary>
       <type>
         <v>X1 = Category | Importance | Format</v>
-        <v>X2 = Format | Args</v>
+        <v>X2 = Format | FormatArgs</v>
       </type>
       <desc><marker id="log-2"/>
-        <p>Equivalent to <seealso marker="#log-4"><c>ct:log(Category,
-          Importance, Format, Args)</c></seealso>.</p>
+        <p>Equivalent to <seealso marker="#log-5"><c>ct:log(Category,
+          Importance, Format, FormatArgs, [])</c></seealso>.</p>
       </desc>
     </func>
 
     <func>
       <name>log(X1, X2, X3) -&gt; ok</name>
       <fsummary>Equivalent to log(Category, Importance, Format,
-        Args).</fsummary>
+        FormatArgs, Opts).</fsummary>
       <type>
         <v>X1 = Category | Importance</v>
         <v>X2 = Importance | Format</v>
-        <v>X3 = Format | Args</v>
+        <v>X3 = Format | FormatArgs | Opts</v>
       </type>
       <desc><marker id="log-3"/>
-        <p>Equivalent to <seealso marker="#log-4"><c>ct:log(Category,
-          Importance, Format, Args)</c></seealso>.</p>
+        <p>Equivalent to <seealso marker="#log-5"><c>ct:log(Category,
+          Importance, Format, FormatArgs, Opts)</c></seealso>.</p>
       </desc>
     </func>
 
     <func>
-      <name>log(Category, Importance, Format, Args) -&gt; ok</name>
+      <name>log(X1, X2, X3, X4) -&gt; ok</name>
+      <fsummary>Equivalent to log(Category, Importance, Format,
+        FormatArgs, Opts).</fsummary>
+      <type>
+        <v>X1 = Category | Importance</v>
+        <v>X2 = Importance | Format</v>
+        <v>X3 = Format | FormatArgs</v>
+	<v>X4 = FormatArgs | Opts</v>
+      </type>
+      <desc><marker id="log-4"/>
+        <p>Equivalent to <seealso marker="#log-5"><c>ct:log(Category,
+          Importance, Format, FormatArgs, Opts)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>log(Category, Importance, Format, FormatArgs, Opts) -&gt; ok</name>
       <fsummary>Prints from a test case to the log file.</fsummary>
       <type>
         <v>Category = atom()</v>
         <v>Importance = integer()</v>
         <v>Format = string()</v>
-        <v>Args = list()</v>
+        <v>FormatArgs = list()</v>
+        <v>Opts = [Opt]</v>
+	<v>Opt = no_css | esc_chars</v>
       </type>
-      <desc><marker id="log-4"/>
+      <desc><marker id="log-5"/>
         <p>Prints from a test case to the log file.</p>
 
         <p>This function is meant for printing a string directly from a
@@ -714,11 +732,15 @@
 
         <p>Default <c>Category</c> is <c>default</c>,
           default <c>Importance</c> is <c>?STD_IMPORTANCE</c>,
-          and default value for <c>Args</c> is <c>[]</c>.</p>
+          and default value for <c>FormatArgs</c> is <c>[]</c>.</p>
 
-        <p>For details on <c>Category</c> and <c>Importance</c>, see section
-          <seealso marker="write_test_chapter#logging">Logging - Categories
-          and Verbosity Levels</seealso> in the User's Guide.</p>
+        <p>For details on <c>Category</c>, <c>Importance</c> and the <c>no_css</c>
+	option, see section <seealso marker="write_test_chapter#logging">
+	Logging - Categories and Verbosity Levels</seealso> in the User's Guide.</p>
+
+	<p>Common Test will not escape special HTML characters (&lt;, &gt; and &amp;)
+	   in the text printed with this function, unless the <c>esc_chars</c>
+	   option is used.</p>
       </desc>
     </func>
 
@@ -769,40 +791,40 @@
     <func>
       <name>pal(X1, X2) -&gt; ok</name>
       <fsummary>Equivalent to pal(Category, Importance, Format,
-        Args).</fsummary>
+        FormatArgs).</fsummary>
       <type>
         <v>X1 = Category | Importance | Format</v>
-        <v>X2 = Format | Args</v>
+        <v>X2 = Format | FormatArgs</v>
       </type>
       <desc><marker id="pal-2"/>
         <p>Equivalent to <seealso marker="#pal-4"><c>ct:pal(Category,
-          Importance, Format, Args)</c></seealso>.</p>
+          Importance, Format, FormatArgs)</c></seealso>.</p>
       </desc>
     </func>
 
     <func>
       <name>pal(X1, X2, X3) -&gt; ok</name>
       <fsummary>Equivalent to pal(Category, Importance, Format,
-        Args).</fsummary>
+        FormatArgs).</fsummary>
       <type>
         <v>X1 = Category | Importance</v>
         <v>X2 = Importance | Format</v>
-        <v>X3 = Format | Args</v>
+        <v>X3 = Format | FormatArgs</v>
       </type>
       <desc><marker id="pal-3"/>
         <p>Equivalent to <seealso marker="#pal-4"><c>ct:pal(Category,
-          Importance, Format, Args)</c></seealso>.</p>
+          Importance, Format, FormatArgs)</c></seealso>.</p>
       </desc>
     </func>
 
     <func>
-      <name>pal(Category, Importance, Format, Args) -&gt; ok</name>
+      <name>pal(Category, Importance, Format, FormatArgs) -&gt; ok</name>
       <fsummary>Prints and logs from a test case.</fsummary>
       <type>
         <v>Category = atom()</v>
         <v>Importance = integer()</v>
         <v>Format = string()</v>
-        <v>Args = list()</v>
+        <v>FormatArgs = list()</v>
       </type>
       <desc><marker id="pal-4"/>
         <p>Prints and logs from a test case.</p>
@@ -812,11 +834,15 @@
 
         <p>Default <c>Category</c> is <c>default</c>,
           default <c>Importance</c> is <c>?STD_IMPORTANCE</c>,
-          and default value for <c>Args</c> is <c>[]</c>.</p>
+          and default value for <c>FormatArgs</c> is <c>[]</c>.</p>
 
         <p>For details on <c>Category</c> and <c>Importance</c>, see section
           <seealso marker="write_test_chapter#logging">Logging - Categories
           and Verbosity Levels</seealso> in the User's Guide.</p>
+
+	<p>Note that special characters in the text (&lt;, &gt; and &amp;) will
+	   be escaped by Common Test before the text is printed to the log
+	   file.</p>
       </desc>
     </func>
 
@@ -854,40 +880,40 @@
     <func>
       <name>print(X1, X2) -&gt; ok</name>
       <fsummary>Equivalent to print(Category, Importance, Format,
-        Args).</fsummary>
+        FormatArgs).</fsummary>
       <type>
         <v>X1 = Category | Importance | Format</v>
-        <v>X2 = Format | Args</v>
+        <v>X2 = Format | FormatArgs</v>
       </type>
       <desc><marker id="print-2"/>
         <p>Equivalent to <seealso marker="#print-4"><c>ct:print(Category,
-          Importance, Format, Args)</c></seealso>.</p>
+          Importance, Format, FormatArgs)</c></seealso>.</p>
       </desc>
     </func>
 
     <func>
       <name>print(X1, X2, X3) -&gt; ok</name>
       <fsummary>Equivalent to print(Category, Importance, Format,
-        Args).</fsummary>
+        FormatArgs).</fsummary>
       <type>
         <v>X1 = Category | Importance</v>
         <v>X2 = Importance | Format</v>
-        <v>X3 = Format | Args</v>
+        <v>X3 = Format | FormatArgs</v>
       </type>
       <desc><marker id="print-3"/>
         <p>Equivalent to <seealso marker="#print-4"><c>ct:print(Category,
-          Importance, Format, Args)</c></seealso>.</p>
+          Importance, Format, FormatArgs)</c></seealso>.</p>
       </desc>
     </func>
 
     <func>
-      <name>print(Category, Importance, Format, Args) -&gt; ok</name>
+      <name>print(Category, Importance, Format, FormatArgs) -&gt; ok</name>
       <fsummary>Prints from a test case to the console.</fsummary>
       <type>
         <v>Category = atom()</v>
         <v>Importance = integer()</v>
         <v>Format = string()</v>
-        <v>Args = list()</v>
+        <v>FormatArgs = list()</v>
       </type>
       <desc><marker id="print-4"/>
         <p>Prints from a test case to the console.</p>
@@ -897,7 +923,7 @@
 
         <p>Default <c>Category</c> is <c>default</c>,
           default <c>Importance</c> is <c>?STD_IMPORTANCE</c>,
-          and default value for <c>Args</c> is <c>[]</c>.</p>
+          and default value for <c>FormatArgs</c> is <c>[]</c>.</p>
 
         <p>For details on <c>Category</c> and <c>Importance</c>, see section
           <seealso marker="write_test_chapter#logging">Logging - Categories
diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml
index 3e30974c9f..96137a632d 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -953,11 +953,11 @@
     <p><c>Common Test</c> provides the following three main functions for 
     printing strings:</p>
     <list type="bulleted">
-      <item><c>ct:log(Category, Importance, Format, Args)</c></item>
-      <item><c>ct:print(Category, Importance, Format, Args)</c></item>
-      <item><c>ct:pal(Category, Importance, Format, Args)</c></item>
+      <item><c>ct:log(Category, Importance, Format, FormatArgs, Opts)</c></item>
+      <item><c>ct:print(Category, Importance, Format, FormatArgs)</c></item>
+      <item><c>ct:pal(Category, Importance, Format, FormatArgs)</c></item>
     </list>
-    <p>The <seealso marker="ct#log-1"><c>log/1,2,3,4</c></seealso> function 
+    <p>The <seealso marker="ct#log-1"><c>log/1,2,3,4,5</c></seealso> function 
     prints a string to the test case log file. 
     The <seealso marker="ct#print-1"><c>print/1,2,3,4</c></seealso> function 
     prints the string to screen.
@@ -1031,14 +1031,26 @@
  4. Categorized info, importance = 25
  6. Categorized error, importance = 99</pre>
 
+    <p>The arguments <c>Format</c> and <c>FormatArgs</c> in <c>ct:log/print/pal</c> are
+    always passed on to the <c>stdlib</c> function <c>io:format/3</c> (For details,
+    see the <seealso marker="stdlib:io"><c>stdlib:io</c></seealso> manual page).</p>
+
+    <p><c>ct:pal/4</c> and <c>ct:log/5</c> add headers to strings being printed to the
+    log file. The strings are also wrapped in div tags with a CSS class
+    attribute, so that stylesheet formatting can be applied. To disable this feature for
+    a printout (i.e. to get a result similar to using <c>io:format/2</c>),
+    call <c>ct:log/5</c> with the <c>no_css</c> option.</p>
+
     <p>How categories can be mapped to CSS tags is documented in section
     <seealso marker="run_test_chapter#html_stylesheet">HTML Style Sheets</seealso>
     in section Running Tests and Analyzing Results.</p>
-
-    <p>The arguments <c>Format</c> and <c>Args</c> in <c>ct:log/print/pal</c> are
-    always passed on to function <c>stdlib:io:format/3</c> (For details, see the 
-    <seealso marker="stdlib:io"><c>stdlib:io</c></seealso> manual page).</p>
     
+    <p>Common Test will escape special HTML characters (&lt;, &gt; and &amp;) in printouts
+    to the log file made with <c>ct:pal/4</c> and <c>io:format/2</c>. In order to print
+    strings with HTML tags to the log, use the <c>ct:log/5</c> function. The character escaping
+    feature is per default disabled for <c>ct:log/5</c>, but can be enabled with the
+    <c>esc_chars</c> option.</p>
+
     <p>For more information about log files, see section
     <seealso marker="run_test_chapter#log_files">Log Files</seealso> 
     in section Running Tests and Analyzing Results.</p>