dita-ot-docs/topics/lwdita-input.dita at develop · DeltaXML/dita-ot-docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
<topic id="lwdita-input">
  <title>Preview support for Lightweight DITA</title>
  <titlealts>
    <navtitle>Lightweight DITA</navtitle>
  </titlealts>
  <shortdesc>DITA-OT provides preview support for the authoring formats proposed for
    <xref keyref="lwdita"/>, or “<term>LwDITA</term>”. The <term>XDITA</term>, <term>MDITA</term> and <term>HDITA</term>
    formats are alternative representations of DITA content in XML, Markdown and HTML5.</shortdesc>
  <prolog>
    <metadata>
      <keywords>
        <indexterm><xmlelement>topicref</xmlelement></indexterm>
        <indexterm><xmlatt>format</xmlatt></indexterm>
        <indexterm>authoring formats
          <indexterm>Lightweight DITA</indexterm></indexterm>
        <indexterm>metadata
          <indexterm>Lightweight DITA</indexterm></indexterm>
        <indexterm>DITA 1.3
          <indexterm>Lightweight DITA</indexterm></indexterm>
        <indexterm>converting lightweight formats to DITA</indexterm>
      </keywords>
    </metadata>
  </prolog>

  <body>
    <note type="attention">Since
      <xref keyref="lwdita"/> has not yet been released as a formal specification, the implementation for
        <term>XDITA</term>, <term>MDITA</term> and <term>HDITA</term> authoring formats is subject to change. Future
      versions of DITA Open Toolkit will be updated as LwDITA evolves.</note>
    <section>
      <title>XDITA</title>
      <p><term>XDITA</term> is the LwDITA authoring format that uses XML to structure information. XDITA is a subset of
        DITA, with new multimedia element types added to support interoperability with HTML5. XDITA is designed for
        users who want to write DITA content but who do not want (or need) the full power of DITA.</p>
      <p>The XDITA parser included in the <codeph>org.lwdita</codeph> plug-in provides preliminary support for XDITA
        maps and XDITA topics.</p>
      <p>To apply XDITA-specific processing to topics in an XDITA map or a full DITA 1.3 map, set the
          <xmlatt>format</xmlatt> attribute on a <xmlelement>topicref</xmlelement> to <codeph>xdita</codeph>:</p>
      <p>
        <codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;map>
  &lt;topicref href="xdita-topic.xml" <b>format="xdita"</b>/>
&lt;/map></codeblock>
      </p>
      <note type="tip">For examples of cross-format content sharing between topics in <term>XDITA</term>,
          <term>HDITA</term>, extended-profile <term>MDITA</term>, and DITA 1.3, see the LwDITA sample files in the
        DITA-OT installation directory under <filepath>plugins/org.oasis-open.xdita.v0_2_2/samples</filepath>.</note>
    </section>
    <section>
      <title>MDITA</title>
      <p><term>MDITA</term> is the LwDITA authoring format based on Markdown. It is designed for users who want to write
        structured content with the minimum of overhead, but who also want to take advantage of the reuse mechanisms
        associated with the DITA standard and the multi-channel publishing afforded by standard DITA tooling.</p>
      <p>Recent proposals for LwDITA include two profiles for authoring MDITA topics:</p>
      <ul>
        <li>The “<term>Core profile</term>” is based on
          <xref keyref="gfm-spec"/> and includes elements that are common to many other Markdown implementations.</li>
        <li>The “<term>Extended profile</term>” borrows additional features from other flavors of Markdown to represent
          a broader range of DITA content with existing plain-text syntax conventions.</li>
      </ul>
      <p>The MDITA parser included in the <codeph>org.lwdita</codeph> plug-in provides preliminary support for these
        profiles and additional Markdown constructs as described in the
        <xref keyref="mdita-syntax"/>.</p>
      <p>To apply the stricter LwDITA-specific processing to Markdown topics, set the <xmlatt>format</xmlatt> attribute
        to <codeph>mdita</codeph>:</p>
      <p>
        <codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;map>
  &lt;topicref href="mdita-topic.md" <b>format="mdita"</b>/>
&lt;/map></codeblock>
      </p>
      <p>In this case, the first paragraph in the topic will be treated as a short description, for example, and
        additional metadata can be specified for the topic via a YAML front matter block.</p>
      <note conkeyref="reusable-components/md-formats"/>
    </section>

    <section>
      <title>HDITA</title>
      <p><term>HDITA</term> is the LwDITA authoring format based on HTML5, which is intended to support structured
        content authoring with tools designed for HTML authoring. HDITA also uses custom data attributes to provide
        interoperability with DITA.</p>
      <p>The HDITA parser included in the <codeph>org.lwdita</codeph> plug-in provides preliminary support for these
        constructs.</p>
      <p>To apply LwDITA-specific processing to HTML topics, set the <xmlatt>format</xmlatt> attribute to
          <codeph>hdita</codeph>:</p>
      <p>
        <codeblock outputclass="language-xml normalize-space show-line-numbers show-whitespace">&lt;map>
  &lt;topicref href="hdita-topic.html" <b>format="hdita"</b>/>
&lt;/map></codeblock>
      </p>
      <note type="attention">The HDITA map format is not yet supported. To include HDITA content, use an XDITA map or a
        DITA 1.3 map.</note>
    </section>
    <section id="conditional-processing">
      <title>Using conditional processing in MDITA and HDITA</title>
      <p>When you set up conditional processing in MDITA and HDITA, use the <xmlatt>data-props</xmlatt> attribute in the
        element that will have the conditional processing applied. In the <filepath>.ditaval</filepath> file, however,
        use the <xmlatt>props</xmlatt> attribute.</p>
    </section>
    <section>
      <title>Converting lightweight formats to DITA XML</title>
      <p>When you add LwDITA topics to a DITA publication, the content is temporarily converted to DITA in the
        background when generating other output formats like HTML or PDF, but the source files remain unchanged.</p>
      <p>If you prefer to maintain this content in DITA in the future, you can generate DITA output by passing the
          <parmname>--format</parmname>=<option>dita</option> option on the command line.</p>
      <p>This converts all input files (both LwDITA formats and DITA XML) to
        <xref keyref="dita2dita">Normalized DITA</xref>. You can then copy the generated DITA files from the output
        folder to your project and replace references to the lightweight topics with their DITA equivalents.</p>
    </section>
  </body>
</topic>