Merge branch 'feature/cli-options' into hotfix/3.1.1

* feature/cli-options:
  Link to output formats for CLI examples
  Add command line examples to output format topics
  Clarify Markdown format as example
  Wrap options in square brackets per EBNF convention

resources/conref-task.dita

@@ -64,7 +64,7 @@
             <li id="novice-variables-last" audience="novice">
               <p id="common-format-info">
                 <varname>format</varname> is the output format (transformation type).
-                This argument corresponds to the common parameter 
+                This argument corresponds to the common parameter
                 <parmname>transtype</parmname>.
                 Use the same values as for the <parmname>transtype</parmname> build
                 parameter, for example <option>html5</option> or <option>pdf</option>.
@@ -87,9 +87,11 @@
                   <li><option>troff</option></li>
                   <li><option>xhtml</option></li>
                 </ul>
+                <note type="tip">See <xref keyref="output-formats"/> for sample command line syntax and more information
+                  on each transformation.</note>
               </p>
             </li>
-            <li id="options"><varname>options</varname> include the following optional build parameters:
+            <li id="options"><varname>[options]</varname> include the following optional build parameters:
               <parml conref="../parameters/dita-command-arguments.dita#dita-command-properties/dita_build_options">
                 <plentry>
                   <pt/>

topics/dita2eclipsehelp.dita

@@ -38,5 +38,11 @@
     <p>To run the Eclipse help transformation, set the <parmname>transtype</parmname> parameter to
         <option>eclipsehelp</option>, or pass the <parmname>--format</parmname>=<option>eclipsehelp</option> option to
       the <cmdname>dita</cmdname> command line.</p>
+    <codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<option>eclipsehelp</option></codeblock>
+    <p>where:</p>
+    <ul>
+      <li conref="../resources/conref-task.dita#ID/novice-variables-1"
+        conrefend="../resources/conref-task.dita#ID/novice-variables-2"/>
+    </ul>
   </conbody>
 </concept>

topics/dita2html5.dita

@@ -14,5 +14,11 @@
     <p>To run the HTML5 transformation, set the <parmname>transtype</parmname> parameter to <option>html5</option>, or
       pass the <parmname>--format</parmname>=<option>html5</option> option to the <cmdname>dita</cmdname> command
       line.</p>
+    <codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<option>html5</option></codeblock>
+    <p>where:</p>
+    <ul>
+      <li conref="../resources/conref-task.dita#ID/novice-variables-1"
+        conrefend="../resources/conref-task.dita#ID/novice-variables-2"/>
+    </ul>
   </conbody>
 </concept>

topics/dita2htmlhelp.dita

@@ -37,5 +37,11 @@
     <p>To run the HTML Help transformation, set the <parmname>transtype</parmname> parameter to
         <option>htmlhelp</option>, or pass the <parmname>--format</parmname>=<option>htmlhelp</option> option to the
         <cmdname>dita</cmdname> command line.</p>
+    <codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<option>htmlhelp</option></codeblock>
+    <p>where:</p>
+    <ul>
+      <li conref="../resources/conref-task.dita#ID/novice-variables-1"
+        conrefend="../resources/conref-task.dita#ID/novice-variables-2"/>
+    </ul>
   </conbody>
 </concept>

topics/dita2markdown.dita

@@ -27,7 +27,8 @@
               <option>markdown_gitbook</option> transtype.</p></li>
       </ul>
       <p>Run the <cmdname>dita</cmdname> command and set the value of the output <parmname>--format</parmname> option to
-        the desired format:</p><codeblock xml:space="preserve"><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<option>markdown</option></codeblock>
+        the desired format, for example:</p>
+      <codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<option>markdown</option></codeblock>
       <p>where:</p>
       <ul>
         <li conref="../resources/conref-task.dita#ID/novice-variables-1"

topics/dita2pdf.dita

@@ -11,5 +11,11 @@
       PDF2. The plug-in was bundled into the default toolkit distribution with release 1.4.3.</p>
     <p>To run the PDF transformation, set the <parmname>transtype</parmname> parameter to <option>pdf</option>, or pass
       the <parmname>--format</parmname>=<option>pdf</option> option to the <cmdname>dita</cmdname> command line.</p>
+    <codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<option>pdf</option></codeblock>
+    <p>where:</p>
+    <ul>
+      <li conref="../resources/conref-task.dita#ID/novice-variables-1"
+        conrefend="../resources/conref-task.dita#ID/novice-variables-2"/>
+    </ul>
   </conbody>
 </concept>

topics/dita2tocjs.dita

@@ -13,5 +13,11 @@
     <p>To run the TocJS transformation, set the <parmname>transtype</parmname> parameter to <option>tocjs</option>, or
       pass the <parmname>--format</parmname>=<option>tocjs</option> option to the <cmdname>dita</cmdname> command
       line.</p>
+    <codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<option>tocjs</option></codeblock>
+    <p>where:</p>
+    <ul>
+      <li conref="../resources/conref-task.dita#ID/novice-variables-1"
+        conrefend="../resources/conref-task.dita#ID/novice-variables-2"/>
+    </ul>
   </conbody>
 </concept>

topics/dita2troff.dita

@@ -14,5 +14,11 @@
     <p>To run the troff transformation, set the <parmname>transtype</parmname> parameter to <option>troff</option>, or
       pass the <parmname>--format</parmname>=<option>troff</option> option to the <cmdname>dita</cmdname> command
       line.</p>
+    <codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<option>troff</option></codeblock>
+    <p>where:</p>
+    <ul>
+      <li conref="../resources/conref-task.dita#ID/novice-variables-1"
+        conrefend="../resources/conref-task.dita#ID/novice-variables-2"/>
+    </ul>
   </conbody>
 </concept>

topics/dita2xhtml.dita

@@ -14,5 +14,11 @@
     <p>To run the XHTML transformation, set the <parmname>transtype</parmname> parameter to <option>xhtml</option>, or
       pass the <parmname>--format</parmname>=<option>xhtml</option> option to the <cmdname>dita</cmdname> command
       line.</p>
+    <codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<option>xhtml</option></codeblock>
+    <p>where:</p>
+    <ul>
+      <li conref="../resources/conref-task.dita#ID/novice-variables-1"
+        conrefend="../resources/conref-task.dita#ID/novice-variables-2"/>
+    </ul>
   </conbody>
 </concept>

topics/using-dita-command.dita

@@ -22,7 +22,7 @@
       </step>
       <step>
         <cmd>At the command-line prompt, enter the following command:</cmd>
-        <info><codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<varname>format</varname> <varname audience="expert">options</varname></codeblock>
+        <info><codeblock><filepath conref="../resources/conref-task.dita#ID/dita-cmd"/> <parmname>--input</parmname>=<varname>input-file</varname> <parmname>--format</parmname>=<varname>format</varname> <varname audience="expert">[options]</varname></codeblock>
           <p>where:</p>
           <ul>
             <li conref="../resources/conref-task.dita#ID/novice-variables-1"