Merge branch 'feature/new-toc' into release/3.0

* feature/new-toc: (36 commits) Disable default MiniToC layout for PDF output Provide @href value as fallback to work around NPE Insert common ToC submap into main target maps Retain Getting Started map to work around filtering Remove obsolete Release Notes keys Move common ToC submap to resources/ Remove empty lines in common ToC submap Move topic stubs to subfolders Move navtitles to topics Add/update submaps with keys Port additional keyrefs to submaps Restore HTML-only reltable to 'userguide.ditamap' Revise landing page to reflect new ToC structure Revise reference hierarchy Add new topics to revised ToC structure & reltables Use keyrefs for reltable links Remove redundant topics Add navtitle to JVM topic Remove redundant 'Log files' reference Combine plug-in concept files & revise hierarchy ...
dita-ot · Oct 28, 2017 · 6f8d77c · 6f8d77c
2 parents 10ec61c + 08d81dd
commit 6f8d77c
Show file tree

Hide file tree

Showing 49 changed files with 919 additions and 367 deletions.
diff --git a/dev_ref/DITA-OTArchitecture.dita b/dev_ref/DITA-OTArchitecture.dita
@@ -5,7 +5,7 @@
 <concept id="ditaotarch" xml:lang="en-US">
   <title>Architecture of the DITA Open Toolkit</title>
   <titlealts>
-    <navtitle>DITA-OT Architecture</navtitle>
+    <navtitle>DITA-OT architecture</navtitle>
   </titlealts>
   <shortdesc>The DITA Open Toolkit is an open-source implementation of the OASIS specification for the Darwin
     Information Typing Architecture. The toolkit uses Ant, XSLT, and Java to transform DITA content (maps and

diff --git a/dev_ref/custom-plugins.dita b/dev_ref/custom-plugins.dita
@@ -0,0 +1,42 @@
+<?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="custom-plugins">
+  <title>Customizing DITA-OT with plug-ins</title>
+  <titlealts>
+    <navtitle>Custom plug-ins</navtitle>
+  </titlealts>
+  <shortdesc id="plugins-creating">You can install or create DITA-OT plug-ins to change the default output types in
+    various ways, to add entirely new kinds of output formats, or to implement support for your DITA topic
+    specializations.</shortdesc>
+
+  <conbody>
+
+    <section id="plugin-benefits">
+      <title>Plug-in benefits</title>
+      <p>Plug-ins allow you to extend the toolkit in a way that is consistent, easy-to-share, and possible to preserve
+        through toolkit upgrades.</p>
+      <p>The DITA-OT plug-in mechanism provides the following benefits:</p>
+      <ul>
+        <li>Plug-ins can easily be shared with other users, teams, or companies. Typically, all users need to do is to
+          unzip and run a single installation command. With many builds, even that installation step is automatic.</li>
+        <li>Plug-ins permit overrides or customizations to grow from simple to complex over time, with no increased
+          complexity to the extension mechanism.</li>
+        <li>Plug-ins can be moved from version to version of the DITA-OT simply by reinstalling or copying the directory
+          from one installation to another. There is no need to re-integrate code based on updates to the core
+          processing of the DITA-OT.</li>
+        <li>Plug-ins can build upon each other. If you like a plug-in, simply install that plug-in, and then create your
+          own plug-in that builds on top of it. The two plug-ins can then be distributed to your team as a unit, or you
+          can share your own extensions with the original provider.</li>
+      </ul>
+    </section>
+
+    <section id="plugins-overview">
+      <title>Plug-in structure</title>
+      <p>A plug-in consists of a directory, typically stored within the <filepath>plugins/</filepath> directory inside
+        of the DITA-OT. Every plug-in is controlled by a file named <filepath>plugin.xml</filepath>, which is located in
+        the root directory of the plug-in.</p>
+    </section>
+  </conbody>
+</concept>
diff --git a/dev_ref/customization.ditamap b/dev_ref/customization.ditamap
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
+<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
+
+<map>
+  <title>Customizing/Extending DITA-OT</title>
+
+  <mapref href="html-customization.ditamap"/>
+  <mapref href="pdf-customization.ditamap"/>
+  <mapref href="../user-guide/globalizing.ditamap"/>
+  <mapref href="plug-ins.ditamap"/>
+  <mapref href="../extension-points/extension-points.ditamap"/>
+  <mapref href="migration.ditamap"/>
+
+</map>
diff --git a/dev_ref/dev_ref.ditamap b/dev_ref/dev_ref.ditamap
@@ -38,16 +38,7 @@
     <topicref href="PdfDefault.dita"/>
     <topicref href="map-first-preprocessing.dita" keys="map-first-preproc"/>
   </topicref>
-  <topicref href="extending-the-ot.dita">
-    <topicref href="plugins-installing.dita"/>
-    <topicref href="plugins-removing.dita"/>
-    <topicref href="rebuilding-the-dita-ot-documentation.dita" keys="rebuild-docs"/>
-  </topicref>
-  <mapref href="plug-ins.ditamap"/>
-  <mapref href="../extension-points/extension-points.ditamap"/>
-  <mapref href="html-customization.ditamap"/>
-  <mapref href="pdf-customization.ditamap"/>
-  <mapref href="migration.ditamap"/>
+
   <topicref href="java-api.dita" keys="java-api"/>
 
   <!-- XXX: is this obsolete? 2 April 2013: Commented out; high priority to write new topic about topic merge-->

diff --git a/dev_ref/extending-the-ot.dita b/dev_ref/extending-the-ot.dita
@@ -3,33 +3,30 @@
 <!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
 
 <reference id="extending-the-ot" xml:lang="en-US">
-  <title>Extending the DITA Open Toolkit</title>
+  <title>Customizing the DITA Open Toolkit</title>
   <titlealts>
-    <navtitle>Extending the DITA-OT</navtitle>
+    <navtitle>Customizing DITA-OT</navtitle>
   </titlealts>
-  <shortdesc>There are several methods that can be used to extend the toolkit; not all of them are recommended or
-    supported. The best way to create most extensions is with a plug-in; extended documentation for creating plug-ins is
-    provided in the next section.</shortdesc>
+  <shortdesc>There are several methods that can be used to customize and extend the toolkit. The best way to create most
+    extensions is with a plug-in; extended documentation for creating plug-ins is provided in the following
+    topics.</shortdesc>
   <refbody>
     <section>
-      <ul>
-        <li>Creating a plug-in can be very simple to very complex, and is generally the best method for changing or
-          extending the toolkit. Plug-ins can be used to accomplish almost any modification that is needed for toolkit
-          processing, from minor style tweaks to extensive, complicated new output formats.</li>
-        <li>The PDF process was initially developed independently of the toolkit, and created its own extension
-          mechanism using customization directories. Many (but not quite all) of the capabilities available through PDF
-          customization directories are now available through plug-ins.</li>
-        <li>Using a single XSL file as an override by passing it in as a parameter. For example, when building XHTML
-          content, the XSL parameter allows users to specify a single local XSL file (inside or outside of the toolkit)
-          that is called in place of the default XHTML code. Typically, this code imports the default processing code,
-          and overrides a couple of processing routines. This approach is best when the override is very minimal, or
-          when the style varies from build to build. However, any extension made with this sort of override is also
-          possible with a plug-in.</li>
-        <li>Editing DITA-OT code directly may work in some cases, but is not advised. Modifying the code directly
-          significantly increases the work and risk involved with future upgrades. It is also likely that such
-          modifications will break plug-ins provided by others, limiting the function available to the toolkit.</li>
-      </ul>
+      <p>Creating a plug-in can be very simple to very complex, and is generally the best method for changing or
+        extending the toolkit. Plug-ins can be used to accomplish almost any modification that is needed for toolkit
+        processing, from minor style tweaks to extensive, complicated new output formats.</p>
+      <p>A single XSL file can be used as an override by passing it in as a parameter. For example, when building XHTML
+        content, the XSL parameter allows users to specify a single local XSL file (inside or outside of the toolkit)
+        that is called in place of the default XHTML code. Typically, this code imports the default processing code, and
+        overrides a couple of processing routines. This approach is best when the override is very minimal, or when the
+        style varies from build to build. However, any extension made with this sort of override is also possible with a
+        plug-in.</p>
+      <p>Editing DITA-OT code directly is strongly discouraged. Modifying the code directly significantly increases the
+        work and risk involved with future upgrades. It is also likely that such modifications will break plug-ins
+        provided by others, limiting the functions available to the toolkit.</p>
+      <note type="warning">Any changes made directly in the code would be overwritten when upgrading to newer versions
+        of DITA-OT, so users that have customized their toolkit installation in this way are often “stuck” on older
+        versions of the toolkit and unable to take advantage of improvements in recent versions of DITA-OT.</note>
     </section>
   </refbody>
 </reference>
-
diff --git a/dev_ref/html-customization.dita b/dev_ref/html-customization.dita
@@ -4,6 +4,7 @@
 
 <task id="customizing-html-output">
   <title>Customizing HTML output</title>
-  <shortdesc>There are several ways to customize the default HTML output. You can easily adjust the look and feel just
-    by setting parameters and adding custom CSS, or create plug-ins for more complex customizations.</shortdesc>
+  <shortdesc>You can adjust the look and feel of your HTML output without
+    creating a DITA-OT plugin by including custom CSS, headers and footers, or
+    table-of-contents navigation in topics.</shortdesc>
 </task>
diff --git a/dev_ref/html-customization.ditamap b/dev_ref/html-customization.ditamap
@@ -4,15 +4,19 @@
 
 <map>
   <title>Customizing HTML output</title>
-  <topicref href="html-customization.dita" keys="html-customization" collection-type="family">
-    <topicref href="html-customization-parameters.dita" keys="html-customization-parameters" collection-type="family">
-      <topicref href="html-customization-navigation.dita" keys="html-customization-navigation"/>
-      <topicref href="html-customization-css.dita" keys="html-customization-css"/>
-      <topicref href="html-customization-header.dita" keys="html-customization-header"/>
+  <topicref keyref="html-customization" locktitle="yes" collection-type="family">
+    <topicmeta>
+      <navtitle>Customizing HTML</navtitle>
+    </topicmeta>
+    <topicref keyref="html-customization-parameters" collection-type="family">
+      <topicref keyref="html-customization-navigation"/>
+      <topicref keyref="html-customization-css"/>
+      <topicref keyref="html-customization-header"/>
+      <topicref keyref="generate-copy-outer"/>
     </topicref>
-    <topicref href="html-customization-properties-file.dita" keys="html-customization-properties-file"/>
-    <topicref href="html-customization-plugins.dita" keys="html-customization-plugins">
-      <topicref href="html-customization-plugin-bundle-css.dita" keys="html-customization-plugin-bundle-css"/>
+    <topicref keyref="html-customization-properties-file"/>
+    <topicref keyref="html-customization-plugins">
+      <topicref keyref="html-customization-plugin-bundle-css"/>
     </topicref>
   </topicref>
 </map>
diff --git a/dev_ref/java-api.dita b/dev_ref/java-api.dita
@@ -4,8 +4,8 @@
 
 <concept id="API">
   <title>Java API</title>
-  <shortdesc>DITA-OT 2.5 includes a new Java Application Programming Interface to allow developers to embed DITA-OT more
-    easily into other Java programs.</shortdesc>
+  <shortdesc>DITA-OT includes a Java Application Programming Interface to allow developers to embed DITA-OT more easily
+    into other Java programs.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

diff --git a/dev_ref/migration.ditamap b/dev_ref/migration.ditamap
@@ -4,19 +4,66 @@
 
 <map>
   <title>Migrating customizations</title>
-  <topicref href="migration.dita" keys="migration" locktitle="yes">
-    <topicref href="migrating-to-3.0.dita" keys="migrating-to-3-0" navtitle="To 3.0"/>
-    <topicref href="migrating-to-2.5.dita" keys="migrating-to-2-5" navtitle="To 2.5"/>
-    <topicref href="migrating-to-2.4.dita" keys="migrating-to-2-4" navtitle="To 2.4"/>
-    <topicref href="migrating-to-2.3.dita" keys="migrating-to-2-3" navtitle="To 2.3"/>
-    <topicref href="migrating-to-2.2.dita" keys="migrating-to-2-2" navtitle="To 2.2"/>
-    <topicref href="migrating-to-2.1.dita" keys="migrating-to-2-1" navtitle="To 2.1"/>
-    <topicref href="migrating-to-2.0.dita" keys="migrating-to-2-0" navtitle="To 2.0"/>
-    <topicref href="migrating-to-1.8.dita" keys="migrating-to-1-8" navtitle="To 1.8"/>
-    <topicref href="migrating-to-1.7.dita" keys="migrating-to-1-7" navtitle="To 1.7">
-      <topicref rev="1.7" href="flagging-migration.dita" keys="flagging-migration" navtitle="Flagging updates"/>
-    </topicref>
-    <topicref href="migrating-to-1.6.dita" keys="migrating-to-1-6" navtitle="To 1.6"/>
-    <topicref href="migrating-to-1.5.4.dita" keys="migrating-to-1-5-4" navtitle="To 1.5.4"/>
+  <topicref keyref="migration" locktitle="yes">
+    <topicref keyref="migrating-to-3.0">
+      <topicmeta>
+        <navtitle>To 3.0</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="migrating-to-2.5">
+      <topicmeta>
+        <navtitle>To 2.5</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="migrating-to-2.4">
+      <topicmeta>
+        <navtitle>To 2.4</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="migrating-to-2.3">
+      <topicmeta>
+        <navtitle>To 2.3</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="migrating-to-2.2">
+      <topicmeta>
+        <navtitle>To 2.2</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="migrating-to-2.1">
+      <topicmeta>
+        <navtitle>To 2.1</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="migrating-to-2.0">
+      <topicmeta>
+        <navtitle>To 2.0</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="migrating-to-1.8">
+      <topicmeta>
+        <navtitle>To 1.8</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="migrating-to-1.7">
+      <topicmeta>
+        <navtitle>To 1.7</navtitle>
+      </topicmeta>
+      <topicref rev="1.7" keyref="flagging-migration">
+        <topicmeta>
+          <navtitle>Flagging updates</navtitle>
+        </topicmeta>
+      </topicref>
+    </topicref>
+    <topicref keyref="migrating-to-1.6">
+      <topicmeta>
+        <navtitle>To 1.6</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="migrating-to-1.5.4">
+      <topicmeta>
+        <navtitle>To 1.5.4</navtitle>
+      </topicmeta>
+    </topicref>
   </topicref>
 </map>
diff --git a/dev_ref/pdf-customization.ditamap b/dev_ref/pdf-customization.ditamap
@@ -4,13 +4,28 @@
 
 <map>
   <title>Customizing PDF output</title>
-  <topicref href="pdf-customization.dita" keys="pdf-customization">
-    <topicref href="pdf-transformation-history.dita"/>
-    <topicref href="pdf-customization-approaches.dita"/>
-    <topicref href="pdf-customization-plugin-types.dita"/>
-    <topicref href="pdf-plugin-structure.dita"/>
-    <topicref href="pdf-customization-example.dita" navtitle="Simple PDF plug-in example" locktitle="yes"/>
-    <topicref href="pdf-customization-best-practices.dita" navtitle="Customization best practices" locktitle="yes"/>
-    <topicref href="pdf-customization-resources.dita" navtitle="Custom PDF plug-in resources" locktitle="yes"/>
+  <topicref keyref="pdf-customization" locktitle="yes">
+    <topicmeta>
+      <navtitle>Customizing PDF</navtitle>
+    </topicmeta>
+    <topicref keyref="pdf-customization-approaches"/>
+    <topicref keyref="pdf-customization-plugin-types"/>
+    <topicref keyref="pdf-plugin-structure"/>
+    <topicref keyref="pdf-customization-best-practices" locktitle="yes">
+      <topicmeta>
+        <navtitle>Customization best practices</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="pdf-customization-example" locktitle="yes">
+      <topicmeta>
+        <navtitle>Simple PDF plug-in example</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="pdf-customization-resources" locktitle="yes">
+      <topicmeta>
+        <navtitle>Custom PDF plug-in resources</navtitle>
+      </topicmeta>
+    </topicref>
+    <topicref keyref="pdf2-creating-change-bars"/>
   </topicref>
 </map>