From 0babcff4c29ab84fda08c0acbf0241d17f017bf9 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Fri, 11 Nov 2016 15:42:03 +0100 Subject: [PATCH] Add topic on DITA features used in docs (Fixes #50) Signed-off-by: Roger Sheen --- parameters/parameters.ditamap | 2 +- user-guide/DITA-features-in-docs.dita | 124 ++++++++++++++++++++++++++ user-guide/spec-support.ditamap | 1 + 3 files changed, 126 insertions(+), 1 deletion(-) create mode 100644 user-guide/DITA-features-in-docs.dita diff --git a/parameters/parameters.ditamap b/parameters/parameters.ditamap index 4fe1a7c84..ebc470330 100644 --- a/parameters/parameters.ditamap +++ b/parameters/parameters.ditamap @@ -7,7 +7,7 @@ - + diff --git a/user-guide/DITA-features-in-docs.dita b/user-guide/DITA-features-in-docs.dita new file mode 100644 index 000000000..609ce4e35 --- /dev/null +++ b/user-guide/DITA-features-in-docs.dita @@ -0,0 +1,124 @@ + + + + + + DITA features in the documentation + + DITA features in docs + + The DITA Open Toolkit uses various recent DITA features in the project documentation. + + +

The + source files for the DITA-OT + documentation include examples of the following DITA features (among others):

+
    +
  • subjectScheme classification for controlling available attributes
    • +
  • profiling and branch filtering (novice/expert content)
    • +
  • extending topics with conref push
    • +
  • keys and key references
    • +
  • XML mention domain
    • +
+
+ Subject schemes +

Various topics, sections and elements in the docs are profiled by audience:

+ <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> +

An “audience” subject scheme controls the values that are available for the audience + attribute:

+ <subjectdef keys="audience"> + <subjectdef keys="novice"/> + <subjectdef keys="expert"/> + <subjectdef keys="xslt-customizer"/> +</subjectdef> +
+
+ Branch filtering: re-using profiled content +
+
+

The Getting Started section pulls a subset of the build description from the User + Guide, filtered to display only content deemed suitable for novice users under + :

+ <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> +

The same content appears later in the User Guide with additional information on arguments, options + and examples (see + ).

+
+
+ Conref push +
+
+

The docs build uses the conref push mechanism (specifically + conaction="pushafter") to extend the parameter descriptions embedded in the + default plug-ins:

+ <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> +

The pushed content appears in the output after the default description. (See + .)

+ You could also use the same mechanism to extend the documentation with custom information that + applies only to your company's toolkit distribution. +
+
+ Keys and key references +
+
+

The key-definitions.ditamap defines keys for version references, re-usable links, etc.

+

This key definition defines the maintenance release version:

+ <keydef keys="maintenance-version"> + <topicmeta> + <keywords> + <keyword>2.3.3</keyword> + </keywords> + </topicmeta> +</keydef> +

In topics, the keyword is used in place of hard-coded version references:

+ <title>DITA Open Toolkit <keyword keyref="maintenance-version"/> Release Notes</title> +
+
+ XML mention domain +
+
+

The docs use the + XML mention domain to mark up XML elements and attributes:

+ <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> +

When the toolkit generates output for the sample above:

+
    +
  • the XML element name is wrapped in angle brackets as table +
    • +
  • the attribute name is prefixed with an “at” sign as orient
    • +
+
+ + diff --git a/user-guide/spec-support.ditamap b/user-guide/spec-support.ditamap index f19ba8b26..0016f15e1 100644 --- a/user-guide/spec-support.ditamap +++ b/user-guide/spec-support.ditamap @@ -9,5 +9,6 @@ +