-
Notifications
You must be signed in to change notification settings - Fork 96
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add topic on DITA features used in docs (Fixes #50)
Signed-off-by: Roger Sheen <roger@infotexture.net>
- Loading branch information
1 parent
70182c8
commit 0babcff
Showing
3 changed files
with
126 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> | ||
| <!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. --> | ||
|
|
||
| <concept id="ID"> | ||
| <title>DITA features in the documentation</title> | ||
| <titlealts> | ||
| <navtitle>DITA features in docs</navtitle> | ||
| </titlealts> | ||
| <shortdesc>The DITA Open Toolkit uses various recent DITA features in the project documentation.</shortdesc> | ||
|
|
||
| <conbody> | ||
| <p>The | ||
| <xref href="https://github.com/dita-ot/docs" format="html" scope="external">source files</xref> for the DITA-OT | ||
| documentation include examples of the following DITA features (among others):</p> | ||
| <ul> | ||
| <li>subjectScheme classification for controlling available attributes</li> | ||
| <li>profiling and branch filtering (novice/expert content)</li> | ||
| <li>extending topics with conref push</li> | ||
| <li>keys and key references</li> | ||
| <li>XML mention domain</li> | ||
| </ul> | ||
| <section> | ||
| <title>Subject schemes </title> | ||
| <p>Various topics, sections and elements in the docs are profiled by audience:</p> | ||
| <codeblock><li id="novice-variables-last" audience="novice"> | ||
| <p id="common-format-info"> | ||
| <varname>format</varname> is the output format (transformation type). | ||
| Use the same values available for the <parmname>transtype</parmname> | ||
| build parameter, for example, <codeph>html5</codeph> or <codeph>pdf</codeph>. | ||
| </p> | ||
| </li></codeblock> | ||
| <p>An “audience” subject scheme controls the values that are available for the <xmlatt>audience</xmlatt> | ||
| attribute:</p> | ||
| <codeblock><subjectdef keys="audience"> | ||
| <subjectdef keys="novice"/> | ||
| <subjectdef keys="expert"/> | ||
| <subjectdef keys="xslt-customizer"/> | ||
| </subjectdef></codeblock> | ||
| </section> | ||
| <section> | ||
| <title>Branch filtering: re-using profiled content</title> | ||
| </section> | ||
| <section> | ||
| <p>The <cite>Getting Started</cite> section pulls a subset of the build description from the <cite>User | ||
| Guide</cite>, filtered to display only content deemed suitable for novice users under | ||
| <xref keyref="first-build-using-dita-command"/>:</p> | ||
| <codeblock><topicref href="../user-guide/using-dita-command.dita" | ||
| copy-to="using-dita-command.dita" keys="first-build-using-dita-command"> | ||
| <topicmeta> | ||
| <navtitle>Building output</navtitle> | ||
| </topicmeta> | ||
|
|
||
| <ditavalref href="../resources/novice.ditaval"> | ||
| <ditavalmeta> | ||
| <dvrResourcePrefix>first-build-</dvrResourcePrefix> | ||
| </ditavalmeta> | ||
| </ditavalref> | ||
| </topicref></codeblock> | ||
| <p>The same content appears later in the <cite>User Guide</cite> with additional information on arguments, options | ||
| and examples (see | ||
| <xref keyref="build-using-dita-command"/>).</p> | ||
| </section> | ||
| <section> | ||
| <title>Conref push</title> | ||
| </section> | ||
| <section> | ||
| <p>The docs build uses the conref push mechanism (specifically | ||
| <xmlatt>conaction</xmlatt>=<codeph>"pushafter"</codeph>) to extend the parameter descriptions embedded in the | ||
| default plug-ins:</p> | ||
| <codeblock><plentry id="args.csspath"> | ||
| <pt> | ||
| <parmname>args.csspath</parmname> | ||
| </pt> | ||
| <pd conaction="mark" | ||
| conref="parameters-base-html.dita#base-html/args.csspath.desc"/> | ||
| <pd conaction="pushafter" audience="xslt-customizer"> | ||
| Corresponds to the XSLT parameter <parmname>CSSPATH</parmname>. | ||
| DITA-OT will copy the file to this location.</pd> | ||
| </plentry></codeblock> | ||
| <p>The pushed content appears in the output after the default description. (See | ||
| <xref keyref="parameters-base-html"/>.)</p> | ||
| <note type="tip">You could also use the same mechanism to extend the documentation with custom information that | ||
| applies only to your company's toolkit distribution.</note> | ||
| </section> | ||
| <section> | ||
| <title>Keys and key references</title> | ||
| </section> | ||
| <section> | ||
| <p>The <codeph>key-definitions.ditamap</codeph> defines keys for version references, re-usable links, etc.</p> | ||
| <p>This key definition defines the maintenance release version:</p> | ||
| <codeblock><keydef keys="maintenance-version"> | ||
| <topicmeta> | ||
| <keywords> | ||
| <keyword>2.3.3</keyword> | ||
| </keywords> | ||
| </topicmeta> | ||
| </keydef></codeblock> | ||
| <p>In topics, the keyword is used in place of hard-coded version references:</p> | ||
| <codeblock><title>DITA Open Toolkit <keyword keyref="maintenance-version"/> Release Notes</title></codeblock> | ||
| </section> | ||
| <section> | ||
| <title>XML mention domain</title> | ||
| </section> | ||
| <section> | ||
| <p>The docs use the | ||
| <xref format="html" | ||
| href="http://docs.oasis-open.org/dita/dita/v1.3/os/part3-all-inclusive/langRef/containers/xml-mention-domain.html#xml-mention-domain" | ||
| scope="external">XML mention domain</xref> to mark up XML elements and attributes:</p> | ||
| <codeblock><li id="1777"> | ||
| DITA 1.3: Initial support has been added for the <xmlatt>orient</xmlatt> | ||
| attribute on <xmlelement>table</xmlelement> elements. These changes allow | ||
| Antenna House Formatter to render tables in landscape mode when the | ||
| <xmlatt>orient</xmlatt> attribute is set to <option>land</option>. […] | ||
| </li></codeblock> | ||
| <p>When the toolkit generates output for the sample above:</p> | ||
| <ul> | ||
| <li>the XML element name is wrapped in angle brackets as <xmlelement>table</xmlelement> | ||
| </li> | ||
| <li>the attribute name is prefixed with an “at” sign as <xmlatt>orient</xmlatt></li> | ||
| </ul> | ||
| </section> | ||
| </conbody> | ||
| </concept> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters