Refactor ToC/parts (#586)

Refactor map hierarchies to simplify top-level navigation for #585.

index.dita

@@ -21,53 +21,37 @@
 
     <section>
       <title>DITA-OT documentation</title>
-      <p>The DITA Open Toolkit documentation provides information about installing, running, configuring and extending
+      <p>The DITA Open Toolkit documentation provides information about installing, running, configuring, and extending
         the toolkit.</p>
       <ul outputclass="list-group mb-5">
-        <li outputclass="list-group-item list-group-item-action">See the
-          <xref keyref="release-notes" outputclass="stretched-link"/> for information on the changes in the current
-          release.</li>
-        <li outputclass="list-group-item list-group-item-action">
-          <xref keyref="installing-client" outputclass="stretched-link"/> shows how to install the toolkit and run a
+        <li outputclass="list-group-item list-group-item-action">This first part includes
+          <xref keyref="release-notes">Release Notes</xref> with information on the changes in the current release, and
+          the
+          <xref keyref="input-formats">Authoring formats</xref> and
+          <xref keyref="output-formats">Output formats</xref> that are provided in the default installation of DITA-OT
+            <keyword keyref="release"/>.</li>
+        <li outputclass="list-group-item list-group-item-action">
+          <xref keyref="installing" outputclass="stretched-link"/> shows how to install the toolkit and run a
           build to verify the installation.</li>
         <li outputclass="list-group-item list-group-item-action">
-          <xref keyref="building-output" outputclass="stretched-link"/> explains the methods that can be used to
-          transform DITA content to other formats, including the <cmdname>dita</cmdname> command, Ant, and the Java API,
-          along with information on publishing DITA content from a containerized environment.</li>
-        <li outputclass="list-group-item list-group-item-action">
-          <xref keyref="input-formats" outputclass="stretched-link"/> provides information on supported input formats,
-          including standard DITA XML, Markdown and the Lightweight DITA formats (<term>XDITA</term>, <term>MDITA</term>
-          and <term>HDITA</term>).</li>
-        <li outputclass="list-group-item list-group-item-action">
-          <xref keyref="output-formats" outputclass="stretched-link">Output formats</xref> describes the core
-          transformations that convert DITA to other formats.</li>
-        <li outputclass="list-group-item list-group-item-action">
-          <xref keyref="parameters" outputclass="stretched-link"/> explains how to adjust the behavior of DITA Open
-          Toolkit via <cmdname>dita</cmdname> command arguments and options, DITA-OT parameter settings, and
-          configuration properties.</li>
+          <xref keyref="publishing" outputclass="stretched-link"/> explains the methods that can be used to publish DITA
+          content to other formats, including the <cmdname>dita</cmdname> command, Ant, and the Java API, along with
+          information on building output from a containerized environment such as Docker or GitHub Actions.</li>
         <li outputclass="list-group-item list-group-item-action">
-          <xref keyref="html-customization" outputclass="stretched-link"/> shows how to <ph
-            conkeyref="html-customization/shortdesc-ph"
+          <xref keyref="parameters" outputclass="stretched-link"/> explains how to <ph
+            conkeyref="parameters/ph_docs-pr-desc"
           />.</li>
         <li outputclass="list-group-item list-group-item-action">
-          <xref keyref="pdf-customization" outputclass="stretched-link"/> explains how to <ph
-            conkeyref="pdf-customization/shortdesc-ph"
-          />.</li>
-        <li outputclass="list-group-item list-group-item-action">
-          <xref keyref="adding-plugins" outputclass="stretched-link"/> explains how to install, remove, and discover new
-          plug-ins.</li>
-        <li outputclass="list-group-item list-group-item-action">
-          <xref keyref="custom-plugins" outputclass="stretched-link"/> provides information on extending DITA-OT with
-          plug-ins of your own.</li>
+          <xref keyref="extending" outputclass="stretched-link"/> explains how to install, remove, and discover
+          plug-ins, and create custom plug-ins to change the default transformations or add new output formats.</li>
         <li outputclass="list-group-item list-group-item-action">
           <xref keyref="troubleshooting-overview" outputclass="stretched-link"/> contains information about resolving
           problems that you might encounter.</li>
         <li outputclass="list-group-item list-group-item-action">
-          <xref keyref="reference" outputclass="stretched-link"/> topics provide additional information about the
-          <xref keyref="architecture"/>,
-          <xref keyref="dita-spec-support"/>, a
-          <xref keyref="glossary"/> and other
-          <xref keyref="dita-and-dita-ot-resources"/>.</li>
+          <xref keyref="reference">Reference</xref> topics provide additional information about the
+          <xref keyref="architecture">DITA Open Toolkit Architecture</xref>,
+          <xref keyref="dita-spec-support">DITA specification support</xref>, and other
+          <xref keyref="dita-and-dita-ot-resources">DITA and DITA-OT resources</xref>.</li>
       </ul>
     </section>
   </body>

parameters/index.dita

@@ -2,12 +2,12 @@
 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
 <!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
 <reference id="ID">
-  <title>DITA Open Toolkit parameters</title>
+  <title>Configuring DITA-OT</title>
   <titlealts>
-    <navtitle>Parameters</navtitle>
+    <navtitle>Configuring</navtitle>
   </titlealts>
   <shortdesc>
-    <ph id="ph_docs-pr-desc">You can adjust DITA Open Toolkit behavior via <cmdname>dita</cmdname> command arguments and
-      options, DITA-OT parameter settings, and configuration properties.</ph>
+    You can <ph id="ph_docs-pr-desc">adjust DITA Open Toolkit behavior via <cmdname>dita</cmdname> command arguments and
+      options, parameter settings, and configuration properties</ph>.
   </shortdesc>
 </reference>

parameters/parameters.ditamap

@@ -2,7 +2,7 @@
 <!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>Parameter Reference</title>
+  <title>Configuration</title>
   <topicref keyref="dita-command-arguments"/>
   <topicref keyref="parameters_intro" keys="dita-ot-params">
     <topicref keyref="parameters-base"/>
@@ -26,4 +26,10 @@
     <topicref keyref="configuration-properties-file"/>
     <topicref keyref="internal-ant-properties"/>
   </topicref>
+  <topicref keyref="html-customization" collection-type="family">
+    <mapref href="../topics/html-customization.ditamap"/>
+  </topicref>
+  <topicref keyref="pdf-customization">
+    <mapref href="../topics/pdf-customization.ditamap"/>
+  </topicref>
 </map>

reference/markdown-formats.ditamap

@@ -18,12 +18,8 @@
   <reltable>
     <title>Source and target</title>
     <relheader>
-      <relcolspec linking="sourceonly">
-        <title>Sourceonly: links to →</title>
-      </relcolspec>
-      <relcolspec linking="targetonly">
-        <title>Targetonly</title>
-      </relcolspec>
+      <relcolspec linking="sourceonly"/>
+      <relcolspec linking="targetonly"/>
     </relheader>
     <relrow>
       <relcell>

reference/reference.ditamap

@@ -54,7 +54,16 @@
   <mapref href="markdown-formats.ditamap"/>
 
   <mapref href="license.ditamap"/>
-  <mapref href="glossary.ditamap"/>
+
+  <topicref keyref="dita-and-dita-ot-resources">
+    <topicgroup deliveryTarget="html">
+      <mapref href="../topics/dita-resources.ditamap" toc="no"/>
+      <mapref href="../topics/dita-ot-day-videos.ditamap"/>
+    </topicgroup>
+    <topicref keyref="web-based-resources" deliveryTarget="pdf" print="yes"/>
+    <topicref keyref="books" toc="yes"/>
+    <mapref href="glossary.ditamap"/>
+  </topicref>
 
   <reltable>
     <relrow>

resources/common-toc.ditamap

@@ -4,48 +4,27 @@
 <map xml:lang="en-US">
   <title>DITA Open Toolkit <keyword keyref="release"/></title>
 
-  <topicref keyref="landing-page"/>
-  <topicref keyref="release-notes">
-    <topicref keyref="release-history"/>
+  <topicref keyref="intro" linking="targetonly">
+    <mapref href="../topics/intro.ditamap"/>
   </topicref>
-  <topicref keyref="installing-client">
+  <topicref keyref="installing">
     <mapref href="../topics/installing.ditamap"/>
   </topicref>
-  <topicref keyref="building-output">
+  <topicref keyref="publishing">
     <mapref href="../topics/publishing.ditamap"/>
   </topicref>
-  <topicref keyref="input-formats" collection-type="family">
-    <mapref href="../topics/input-formats.ditamap"/>
-  </topicref>
-  <topicref keyref="output-formats">
-    <mapref href="../topics/transformations.ditamap"/>
-  </topicref>
   <topicref keyref="parameters">
     <mapref href="../parameters/parameters.ditamap"/>
   </topicref>
-  <topicref keyref="html-customization" collection-type="family">
-    <mapref href="../topics/html-customization.ditamap"/>
-  </topicref>
-  <topicref keyref="pdf-customization">
-    <mapref href="../topics/pdf-customization.ditamap"/>
-  </topicref>
-  <topicref keyref="adding-plugins">
+  <topicref keyref="extending">
     <mapref href="../topics/using-plugins.ditamap"/>
   </topicref>
-  <topicref keyref="custom-plugins">
-    <mapref href="../topics/creating-plugins.ditamap"/>
-  </topicref>
   <topicref keyref="troubleshooting-overview">
     <mapref href="../topics/troubleshooting.ditamap"/>
   </topicref>
   <topicref keyref="reference">
     <mapref href="../reference/reference.ditamap"/>
   </topicref>
-  <topicref keyref="dita-and-dita-ot-resources">
-    <mapref href="../topics/dita-resources.ditamap" toc="no"/>
-    <mapref href="../topics/dita-ot-day-videos.ditamap"/>
-    <topicref keyref="books" toc="yes"/>
-  </topicref>
 
   <topicgroup processing-role="resource-only">
     <mapref href="common-resources.ditamap"/>

resources/reltable.ditamap

@@ -351,7 +351,7 @@
       </relcell>
       <relcell>
         <topicref keyref="release-notes"/>
-        <topicref keyref="installing-client"/>
+        <topicref keyref="installing"/>
       </relcell>
     </relrow>
   </reltable>

resources/source-files.ditamap

@@ -8,12 +8,10 @@
   </topicmeta>
   <keydef keys="adding-new-languages" href="../topics/adding-new-languages.dita"/>
   <keydef keys="adding-new-strings" href="../topics/adding-new-strings.dita"/>
-  <keydef keys="adding-plugins" href="../topics/adding-plugins.dita"/>
   <keydef keys="ant" href="../topics/ant.dita"/>
   <keydef keys="ant-parameters-details" href="../parameters/ant-parameters-details.dita"/>
   <keydef keys="architecture" href="../reference/architecture.dita"/>
   <keydef keys="books" href="../reference/books.dita"/>
-  <keydef keys="building-output" href="../topics/building-output.dita"/>
   <keydef keys="building-with-ant" href="../topics/building-with-ant.dita"/>
   <keydef keys="common-html-processing" href="../reference/common-html-processing.dita"/>
   <keydef keys="configuration-properties" href="../parameters/configuration-properties.dita"/>
@@ -56,6 +54,7 @@
   <keydef keys="error-messages messages" href="../topics/error-messages.xml"/>
   <keydef keys="error-messages-details messages-push" href="../topics/error-messages-details.xml"/>
   <keydef keys="extended-functionality" href="../reference/extended-functionality.dita"/>
+  <keydef keys="extending" href="../topics/extending.dita"/>
   <keydef keys="extension-points-by-plugin" href="../extension-points/extension-points-by-plugin.dita"/>
   <keydef keys="extension-points-details" href="../extension-points/extension-points-details.dita"/>
   <keydef keys="flagging-migration" href="../reference/flagging-migration.dita"/>
@@ -80,11 +79,11 @@
   <keydef keys="implementation-dependent-features" href="../reference/implementation-dependent-features.dita"/>
   <keydef keys="increasing-the-jvm" href="../topics/increasing-the-jvm.dita"/>
   <keydef keys="input-formats" href="../topics/input-formats.dita"/>
-  <keydef keys="installing-client" href="../topics/installing-client.dita"/>
+  <keydef keys="installing" href="../topics/installing.dita"/>
   <keydef keys="installing-via-homebrew" href="../topics/installing-via-homebrew.dita"/>
   <keydef keys="internal-ant-properties" href="../parameters/internal-ant-properties.dita"/>
+  <keydef keys="intro" href="../index.dita"/>
   <keydef keys="java-api" href="../reference/java-api.dita"/>
-  <keydef keys="landing-page" href="../index.dita"/>
   <keydef keys="license" href="../reference/license.dita"/>
   <keydef keys="local-properties-file" href="../parameters/local-properties-file.dita"/>
   <keydef keys="logging" href="../topics/logging.dita"/>
@@ -194,6 +193,7 @@
   <keydef keys="project-files-json" href="../topics/project-files-json.dita"/>
   <keydef keys="project-files-xml" href="../topics/project-files-xml.dita"/>
   <keydef keys="project-files-yaml" href="../topics/project-files-yaml.dita"/>
+  <keydef keys="publishing" href="../topics/publishing.dita"/>
   <keydef keys="publishing-with-ant" href="../topics/publishing-with-ant.dita"/>
   <keydef keys="rebuilding-docs" href="../topics/rebuilding-docs.dita"/>
   <keydef keys="reducing-processing-time" href="../topics/reducing-processing-time.dita"/>

topics/dita-ot-day-2014.ditamap

@@ -119,7 +119,7 @@
     </relrow>
     <relrow>
       <relcell>
-        <topicref keyref="landing-page"/>
+        <topicref keyref="intro"/>
       </relcell>
       <relcell>
         <topicref keyref="overviewoftheditaopentoo-2014"/>

topics/dita-ot-day-2015.ditamap

@@ -107,7 +107,7 @@
     </relrow>
     <relrow>
       <relcell>
-        <topicref keyref="building-output"/>
+        <topicref keyref="publishing"/>
       </relcell>
       <relcell>
         <topicref keyref="howtorundita-ot-2015"/>

topics/adding-plugins.dita → topics/extending.dita

@@ -2,19 +2,20 @@
 <!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>Adding and removing plug-ins</title>
+  <title>Extending DITA-OT with plug-ins</title>
   <titlealts>
-    <navtitle>Adding plug-ins</navtitle>
+    <navtitle>Extending</navtitle>
   </titlealts>
-  <shortdesc>You can extend DITA-OT with additional plug-ins to change the default output types in various ways, add
-    entirely new kinds of output formats, or implement DITA specializations. A variety of open source plug-ins are
-    available from the plug-in registry at
+  <shortdesc>You can extend DITA Open Toolkit with plug-ins that change the default transformations, add new output
+    formats, or implement DITA specializations. A variety of open source plug-ins are available from the plug-in
+    registry at
     <xref keyref="site-plugin-registry"/>.</shortdesc>
   <prolog>
     <metadata>
       <keywords>
         <indexterm>DITA
           <indexterm>specializations</indexterm></indexterm>
+        <indexterm>extending</indexterm>
         <indexterm>plug-ins</indexterm>
         <indexterm>plug-ins
           <indexterm>working with</indexterm></indexterm>

topics/installing-client.dita → topics/installing.dita

@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
 <!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
-<task id="installing-client">
+<task id="installing">
   <title>Installing DITA Open Toolkit</title>
   <titlealts>
-    <navtitle>Installing DITA-OT</navtitle>
+    <navtitle>Installing</navtitle>
   </titlealts>
-  <shortdesc id="what-is-client">The DITA-OT distribution package can be installed on Linux, macOS, and Windows. It
-    contains everything that you need to run the toolkit except for Java.</shortdesc>
+  <shortdesc>The DITA-OT distribution package can be installed on Linux, macOS, and Windows. It contains everything that
+    you need to run the toolkit except for Java.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

topics/intro.ditamap

@@ -0,0 +1,17 @@
+<?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>Intro topics</title>
+
+  <topicref keyref="release-notes">
+    <topicref keyref="release-history" deliveryTarget="html"/>
+  </topicref>
+  <topicref keyref="input-formats" collection-type="family" linking="normal">
+    <mapref href="input-formats.ditamap"/>
+  </topicref>
+  <topicref keyref="output-formats" linking="normal">
+    <mapref href="transformations.ditamap"/>
+  </topicref>
+
+</map>

topics/output-formats.dita

@@ -2,10 +2,7 @@
 <!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="availabletransforms">
-  <title>DITA-OT transformations (output formats)</title>
-  <titlealts>
-    <navtitle>Output formats</navtitle>
-  </titlealts>
+  <title>Output formats</title>
   <shortdesc>DITA Open Toolkit ships with several core transformations that convert DITA content to different output
     formats. Additional formats are available from the plug-in registry at
     <xref keyref="site-plugin-registry"/>.</shortdesc>
@@ -22,6 +19,6 @@
   </prolog>
   <conbody>
     <note type="tip">For information on how to install other formats, see
-      <xref keyref="adding-plugins"/>.</note>
+      <xref keyref="extending"/>.</note>
   </conbody>
 </concept>

topics/pdf-customization.dita

@@ -7,7 +7,8 @@
     <navtitle>Customizing PDF</navtitle>
   </titlealts>
   <shortdesc>You can <ph id="shortdesc-ph">adjust various aspects of PDF output by changing parameter settings or using
-      a theme file</ph>. For more complex customizations, you can create custom DITA-OT plug-ins.</shortdesc>
+      a theme file</ph>. For more complex customizations, you can create or install 
+    <xref keyref="extending">custom plug-ins</xref>.</shortdesc>
   <prolog>
     <metadata>
       <keywords>

topics/plugins-registry.dita

@@ -6,8 +6,9 @@
   <titlealts>
     <navtitle>Plug-in registry</navtitle>
   </titlealts>
-  <shortdesc><ph id="registry-summary">DITA-OT 3.2 supports a new plug-in registry that makes it easier to discover and
-      install new plug-ins. The registry provides a searchable list of plug-ins at
+  <shortdesc>
+    <ph id="registry-summary">DITA-OT supports a plug-in registry that makes it easier to discover and install new
+      plug-ins. The registry provides a searchable list of plug-ins at
       <xref keyref="site-plugin-registry"/>.</ph></shortdesc>
   <prolog>
     <metadata>

topics/publishing.dita

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
+<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
+<task id="transforming-dita-content">
+  <title>Publishing DITA content</title>
+  <titlealts>
+    <navtitle>Publishing</navtitle>
+  </titlealts>
+  <shortdesc>You can use the <cmdname>dita</cmdname> command, Ant, or the Java API to publish DITA content to other
+    formats, or build output from a containerized environment such as Docker or GitHub Actions.</shortdesc>
+</task>