Home Explore Help
Sign In
bn
/
se
2
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: a4b429aad5
Branches Tags
se
/
SE
/
schema
/
WPS_Functions
/
dita-ot
/
dita-ot-3.0.4
/
doc
/
topics
/
using-dita-command.html

using-dita-command.html 14 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190 
  1. <!DOCTYPE html
    2. 

  2.   SYSTEM "about:legacy-compat">
    3. 

  3. <html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2018"><meta name="DC.rights.owner" content="(C) Copyright 2018"><meta name="DC.Type" content="task"><meta name="description" content="You can generate output using the DITA Open Toolkit dita command-line tool. Build parameters can be specified on the command line or with .properties files."><meta name="DC.Format" content="HTML5"><meta name="DC.Identifier" content="using-command-line-tool"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Building output using the dita command</title></head><body id="using-command-line-tool"><header role="banner"><div class="header">
    4. 

  4.   <p>DITA Open Toolkit</p>
    5. 

  5.   <hr>
    6. 

  6. </div></header><nav role="toc"><ul></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
    7. 

  7.   <h1 class="title topictitle1" id="ariaid-title1">Building output using the <span class="keyword cmdname">dita</span> command</h1>
    8. 

  8.   
    9. 

  9.   <div class="body taskbody"><p class="shortdesc">You can generate output using the DITA Open Toolkit <span class="keyword cmdname">dita</span> command-line tool. Build
    10. 

  10.     parameters can be specified on the command line or with <span class="ph filepath">.properties</span> files.</p>
    11. 

  11.     <section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>The DITA-OT client is a command-line tool with no graphical user interface. To verify
    12. 

  12.       that your installation works correctly, you can build output using the sample files included in the distribution
    13. 

  13.       package.</section>
    14. 

  14.     <div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
    15. 

  15.         <span class="ph cmd">Open a terminal window by typing the following in the search bar:</span>
    16. 

  16.         <div class="itemgroup info">
    17. 

  17.           <ul class="ul">
    18. 

  18.             <li class="li">On Linux and macOS, type <kbd class="ph userinput">Terminal</kbd>.</li>
    19. 

  19.             <li class="li">On Windows, type <kbd class="ph userinput">Command Prompt</kbd>.</li>
    20. 

  20.           </ul>
    21. 

  21.         </div>
    22. 

  22.       </li><li class="li step stepexpand">
    23. 

  23.         <span class="ph cmd">At the command-line prompt, enter the following command:</span>
    24. 

  24.         <div class="itemgroup info"><pre class="pre codeblock"><code><span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/bin/<span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<var class="keyword varname">format</var> <var class="keyword varname">options</var></code></pre>
    25. 

  25.           <p class="p">where:</p>
    26. 

  26.           <ul class="ul">
    27. 

  27.             <li class="li"><span class="ph filepath"><var class="keyword varname">dita-ot-dir</var></span> is the DITA-OT installation directory.</li><li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
    28. 

  28.               process.</li><li class="li">
    29. 

  29.   <p class="p" id="using-command-line-tool__d36e187">
    30. 

  30.     <var class="keyword varname">format</var> is the output format (transformation type).
    31. 

  31.     This argument corresponds to the common parameter <span class="keyword parmname">transtype</span>. 
    32. 

  32.     Use the same values as for the <span class="keyword parmname">transtype</span> build parameter,
    33. 

  33.     for example, <span class="keyword option">html5</span> or <span class="keyword option">pdf</span>.</p>
    34. 

  34. </li>
    35. 

  35.             <li class="li"><span class="ph filepath"><var class="keyword varname">dita-ot-dir</var></span> is the DITA-OT installation directory.</li><li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
    36. 

  36.               process.</li>
    37. 

  37.             <li class="li">
    38. 

  38.               <p class="p">
    39. 

  39.     <var class="keyword varname">format</var> is the output format (transformation type).
    40. 

  40.     This argument corresponds to the common parameter <span class="keyword parmname">transtype</span>. 
    41. 

  41.     Use the same values as for the <span class="keyword parmname">transtype</span> build parameter,
    42. 

  42.     for example, <span class="keyword option">html5</span> or <span class="keyword option">pdf</span>.</p>
    43. 

  43.               <div class="p" id="using-command-line-tool__d36e226">You can create plug-ins to add new output formats; by default, the following values are
    44. 

  44.                 available:
    45. 

  45.                 <ul class="ul">
    46. 

  46.                   <li class="li"><span class="keyword option">dita</span></li>
    47. 

  47.                   <li class="li"><span class="keyword option">eclipsehelp</span></li>
    48. 

  48.                   <li class="li"><span class="keyword option">html5</span></li>
    49. 

  49.                   <li class="li"><span class="keyword option">htmlhelp</span></li>
    50. 

  50.                   <li class="li"><span class="keyword option">markdown</span>, <span class="keyword option">markdown_gitbook</span>, and
    51. 

  51.                     <span class="keyword option">markdown_github</span></li>
    52. 

  52.                   <li class="li"><span class="keyword option">pdf</span></li>
    53. 

  53.                   <li class="li"><span class="keyword option">tocjs</span></li>
    54. 

  54.                   <li class="li"><span class="keyword option">troff</span></li>
    55. 

  55.                   <li class="li"><span class="keyword option">xhtml</span></li>
    56. 

  56.                 </ul>
    57. 

  57.               </div>
    58. 

  58.             </li>
    59. 

  59.             <li class="li"><var class="keyword varname">options</var> include the following optional build parameters:
    60. 

  60.               <dl class="dl parml">
    61. 

  61.         
    62. 

  62.           <dt class="dt pt dlterm">
    63. 

  63.             <span class="keyword parmname">--output</span>=<var class="keyword varname">dir</var></dt>
    64. 

  64.           <dt class="dt pt dlterm">
    65. 

  65.             <span class="keyword parmname">-o</span>
    66. 

  66.             <var class="keyword varname">dir</var>
    67. 

  67.           </dt>
    68. 

  68.           <dd class="dd pd" id="using-command-line-tool__d36e301">Specifies the path of the output directory; the path can be absolute or relative to
    69. 

  69.             the current directory. This argument corresponds to the common parameter <span class="keyword parmname">output.dir</span>. By
    70. 

  70.             default, the output is written to the <span class="ph filepath">out</span> subdirectory of the current directory.</dd>
    71. 

  71.         
    72. 

  72.         
    73. 

  73.           <dt class="dt pt dlterm">
    74. 

  74.             <span class="keyword parmname">--filter</span>=<var class="keyword varname">file</var>
    75. 

  75.           </dt>
    76. 

  76.           <dd class="dd pd">Specifies filter file(s) used to include, exclude, or flag content. </dd>
    77. 

  77.           <dd class="dd pd ddexpand">This argument corresponds to the common parameter <span class="keyword parmname">args.filter</span>. Relative paths are
    78. 

  78.             resolved against the current directory and internally converted to absolute paths.</dd>
    79. 

  79.         
    80. 

  80.         
    81. 

  81.           <dt class="dt pt dlterm">
    82. 

  82.             <span class="keyword parmname">--temp</span>=<var class="keyword varname">dir</var></dt>
    83. 

  83.           <dt class="dt pt dlterm">
    84. 

  84.             <span class="keyword parmname">-t</span>
    85. 

  85.             <var class="keyword varname">dir</var>
    86. 

  86.           </dt>
    87. 

  87.           <dd class="dd pd">Specifies the location of the temporary directory.</dd>
    88. 

  88.           <dd class="dd pd ddexpand">This argument corresponds to the common parameter <span class="keyword parmname">dita.temp.dir</span>.</dd>
    89. 

  89.         
    90. 

  90.         
    91. 

  91.           <dt class="dt pt dlterm">
    92. 

  92.             <span class="keyword parmname">--verbose</span></dt>
    93. 

  93.           <dt class="dt pt dlterm">
    94. 

  94.             <span class="keyword parmname">-v</span>
    95. 

  95.           </dt>
    96. 

  96.           <dd class="dd pd">Verbose logging.</dd>
    97. 

  97.         
    98. 

  98.         
    99. 

  99.           <dt class="dt pt dlterm">
    100. 

  100.             <span class="keyword parmname">--debug</span></dt>
    101. 

  101.           <dt class="dt pt dlterm">
    102. 

  102.             <span class="keyword parmname">-d</span>
    103. 

  103.           </dt>
    104. 

  104.           <dd class="dd pd">Debug logging.</dd>
    105. 

  105.         
    106. 

  106.         
    107. 

  107.           <dt class="dt pt dlterm">
    108. 

  108.             <span class="keyword parmname">--logfile</span>=<var class="keyword varname">file</var></dt>
    109. 

  109.           <dt class="dt pt dlterm">
    110. 

  110.             <span class="keyword parmname">-l</span>
    111. 

  111.             <var class="keyword varname">file</var>
    112. 

  112.           </dt>
    113. 

  113.           <dd class="dd pd">Write logging messages to a file.</dd>
    114. 

  114.         
    115. 

  115.         
    116. 

  116.           <dt class="dt pt dlterm">
    117. 

  117.             <span class="keyword parmname">--parameter</span>=<var class="keyword varname">value</var></dt>
    118. 

  118.           <dt class="dt pt dlterm">
    119. 

  119.             <span class="keyword parmname">-D</span><var class="keyword varname">parameter</var>=<var class="keyword varname">value</var>
    120. 

  120.           </dt>
    121. 

  121.           <dd class="dd pd">Specify a value for a DITA-OT or Ant build parameter.
    122. 

  122.             <p class="p">The GNU-style <span class="keyword parmname">--parameter</span>=<var class="keyword varname">value</var> form is only available for
    123. 

  123.               parameters that are configured in the plug-in configuration file; the Java-style <span class="keyword parmname">-D</span>
    124. 

  124.               form can also be used to specify additional non-configured parameters or set system properties.</p>
    125. 

  125.             <p class="p">Parameters not implemented by the specified transformation type or referenced in a
    126. 

  126.                 <span class="ph filepath">.properties</span> file are ignored.</p><div class="note tip note_tip"><span class="note__title">Tip:</span> If you are building in different environments where the location of the input
    127. 

  127.         files is not consistent, set <span class="keyword option">args.input.dir</span> with the <span class="keyword cmdname">dita</span> command and
    128. 

  128.         reference its value with <code class="ph codeph">${args.input.dir}</code> in your <span class="ph filepath">.properties</span>
    129. 

  129.         file.</div></dd>
    130. 

  130.         
    131. 

  131.         
    132. 

  132.           <dt class="dt pt dlterm">
    133. 

  133.             <span class="keyword parmname">--propertyfile</span>=<var class="keyword varname">file</var>
    134. 

  134.           </dt>
    135. 

  135.           <dd class="dd pd">Use build parameters defined in the referenced <span class="ph filepath">.properties</span> file.
    136. 

  136.             <p class="p">Build parameters specified on the command line override those set in the <span class="ph filepath">.properties</span>
    137. 

  137.               file.</p></dd>
    138. 

  138.         
    139. 

  139.       </dl></li>
    140. 

  140.           </ul></div>
    141. 

  141.         <div class="itemgroup stepresult">
    142. 

  142.           <p class="p">If processing is successful, nothing is printed in the terminal window. The built output is written to the
    143. 

  143.             specified output directory (by default, in the <span class="ph filepath">out</span> subdirectory of the current
    144. 

  144.             directory).</p>
    145. 

  145.           <div class="note tip note_tip" id="using-command-line-tool__d36e509"><span class="note__title">Tip:</span> Add the absolute path for <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var></span><span class="ph filepath">/bin</span> to the <var class="keyword varname">PATH</var> environment variable to run the
    146. 

  146.               <span class="keyword cmdname">dita</span> command from any location on the file system without typing the path.</div>
    147. 

  147.         </div>
    148. 

  148.       </li></ol>
    149. 

  149.     <div class="example"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Example</h2></div>
    150. 

  150.       <p class="p">Run from <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span>, the following command generates
    151. 

  151.         HTML5 output for the <span class="ph filepath">sequence.ditamap</span> file:</p>
    152. 

  152.       <pre class="pre codeblock"><code><span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/bin/<span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<span class="ph filepath">sequence.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span></code></pre>
    153. 

  153.     </div>
    154. 

  154.     <div class="example"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Example</h2></div>
    155. 

  155.       <p class="p">For example, from <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span>, run:</p>
    156. 

  156.       <pre class="pre codeblock"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">sequence.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span> \
    157. 

  157.      <span class="keyword parmname">--output</span>=<span class="ph filepath">output/sequence</span> \
    158. 

  158.      <span class="keyword parmname">--args.input.dir</span>=<span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span> \
    159. 

  159.      <span class="keyword parmname">--propertyfile</span>=<span class="ph filepath">properties/sequence-html5.properties</span></code></pre>
    160. 

  160.       <p class="p">This builds <span class="ph filepath">sequence.ditamap</span> to HTML5 output in <span class="ph filepath">output/sequence</span> using
    161. 

  161.         the following additional parameters specified in the <span class="ph filepath">properties/sequence-html5.properties</span>
    162. 

  162.         file:</p>
    163. 

  163.       <pre class="pre codeblock"><code># Don't generate headings for sections within task topics:
    164. 

  164. args.gen.task.lbl = NO
    165. 

  165. 

  166. # Directory that contains the custom .css file:
    167. 

  167. args.cssroot = ${args.input.dir}/css/
    168. 

  168. 

  169. # Custom .css file used to style output:
    170. 

  170. args.css = style.css
    171. 

  171. 

  172. # Copy the custom .css file to the output directory:
    173. 

  173. args.copycss = yes
    174. 

  174. 

  175. # Location of the copied .css file relative to the output:
    176. 

  176. args.csspath = branding
    177. 

  177. 

  178. # Generate a full navigation TOC in topic pages:
    179. 

  179. nav-toc = full
    180. 

  180. 

  181. # Base name of the Table of Contents file:
    182. 

  182. args.xhtml.toc = toc</code></pre>
    183. 

  183.     </div>
    184. 

  184.     <section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
    185. 

  185.       <p class="p">Most builds require you to specify more options than are described in this topic.</p>
    186. 

  186.       <p class="p">Usually, you will want to specify a set of reusable build parameters in a
    187. 

  187.           <span class="ph filepath">.properties</span> file.</p>
    188. 

  188.     </section>
    189. 

  189.   </div>
    190. 

  190. </article></main></body></html>
    191.