Merge pull request #290 from robander/cleanup

More spec cleanup

Author: robander

specification/archSpec/technicalContent/dita-generic-task-topic.dita

@@ -2,14 +2,10 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA 2.x Concept//EN" "concept.dtd">
 <concept id="dita_generic_task_topic" xml:lang="en-US">
 	<title>General task</title>
-  <shortdesc>A general task topic answers the "How do I?" question by
-    providing instructions and other necessary information that enables
-    users to complete the task successfully. It has a content model that is
-    more relaxed than that of the strict
-    task.<!-- The general-task document type serves as the base for the strict-task document type. It also can be used to create new document types or specializations.--></shortdesc>
+  <shortdesc>A general task topic answers the "How do I?" question by providing instructions and
+    other necessary information that enables users to complete the task successfully. It has a
+    content model that is more relaxed than that of the strict task.</shortdesc>
 	<conbody>
-    <!--<section id="purpose"><title>Purpose</title><p>The purpose of the general task topic is to provide the user with comprehensive instructions for performing a task. In addition, its content model can facilitate the migration of procedural information that does not follow the content model of the strict task topic.</p></section>-->
-    <!--<section id="section_4B12CAE12AF84259B9DED26BC5F9FEDE"><title>The purpose of the general task information type</title><p>Like the DITA strict task document type, the general task document and information types contain the essential building blocks to provide procedural information. Both task information types answer the "How do I?" question by providing step-by-step instructions that detail the requirements that must be fulfilled, the actions that must be performed, and the order in which the actions must be performed. Both task topics include sections for describing the context, prerequisites, expected results, and other aspects of a task.</p><p id="p_14C11461E6164EEDB93CDECE17D657C5">The general task information type is specifically designed to accommodate task specializations that differ from the DITA task information type. It might also be used for the conversion of loosely structured tasks from other sources into DITA before they are restructured to follow the more restrictive DITA task model.</p></section>-->
     <section id="content-model">
       <title>Content model</title>
       <p>The general task topic is divided into three parts:</p>
@@ -110,7 +106,5 @@
   &lt;/taskbody>
 &lt;/task></codeblock>
     </section>
-    <!--<section id="section_0C8A068CDF1D498F9FF534D3CE88CF2F"><title>The structure of the general task topic</title><p id="p_366CB29A7238470BA9070488F953FBDD">The <xmlelement>task</xmlelement> element is the top-level element for the general task topic. The general task topic contains a <xmlelement>title</xmlelement>, a short description or <xmlelement>abstract</xmlelement>, a <xmlelement>prolog</xmlelement>, <xmlelement>taskbody</xmlelement> for the main task content, and <xmlelement>related-links</xmlelement>.</p><p id="p_7262A46437C34654BD4E46DC49BC6FD4">The following elements are described here because they are introduced as part of the general task model. All other elements are described in the strict task topic.<draft-comment author="robander" audience="spec-editors" time="25 may 2021">this paragraph also makes me think we're adding to confusion by defining some elements here, and some in "strict task"</draft-comment></p><dl><dlentry><dt><xmlelement>section</xmlelement> </dt><dd>Represents an organizational division in a task topic. Sections organize subsets of information within the larger topic. Sections cannot be nested. A section can have an optional <xmlelement>title</xmlelement>. </dd></dlentry><dlentry><dt><xmlelement>steps-informal</xmlelement> </dt><dd>Describes procedural task information that would not normally be ordered as <xmlelement>steps</xmlelement>, such as a group of general procedures that might all be applied in a particular situation. Instead of <xmlelement>step</xmlelement>, the <xmlelement>steps-informal</xmlelement> element uses <xmlelement>ol</xmlelement> and <xmlelement>ul</xmlelement> elements, which are less strictly defined than the <xmlelement>step</xmlelement> element. When converting legacy content, it might be simpler to convert numbered lists to <xmlelement>ol</xmlelement> elements than to <xmlelement>step</xmlelement> elements. </dd></dlentry></dl></section>-->
-    <!--<section id="section_9CD7027683F049709DD7BCD431B421D8"><title>Comparison of general and strict task</title><p id="p_5533CE00385F44929D16A29C78727AF9">The following table compares the structures of general and strict task:</p><table id="table_D297CDD1D8B24415A28A74A37372B423"><tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry valign="top">General <xmlelement>taskbody</xmlelement> </entry><entry valign="top">Strict <xmlelement>taskbody</xmlelement> constraint </entry></row></thead><tbody><row><entry>prerequisite (optional, in any order, any number) </entry><entry>prerequisite (optional, one only, must precede context) </entry></row><row><entry>context (optional, in any order, any number) </entry><entry>context (optional, one only, must follow prerequisite) </entry></row><row><entry>section (optional, in any order, any number) </entry><entry>(not defined for strict <xmlelement>taskbody</xmlelement>) </entry></row><row><entry>steps </entry><entry>steps </entry></row><row><entry>steps-unordered </entry><entry>steps-unordered </entry></row><row><entry>steps-informal </entry><entry>(not allowed in strict <xmlelement>taskbody</xmlelement>) </entry></row><row><entry>result (optional, one only, precedes example) </entry><entry>result (optional, one only, precedes example) </entry></row><row><entry>tasktroubleshooting (optional, one only)</entry><entry>tasktroubleshooting (optional, one only)</entry></row><row><entry>example (optional, any number, precedes post-req) </entry><entry>example (optional, one only, precedes post-req) </entry></row><row><entry>post-requisite (optional, any number) </entry><entry>post-requisite (optional, one only) </entry></row></tbody></tgroup></table></section>-->
 	</conbody>
 </concept>

specification/archSpec/technicalContent/dita-reference-topic.dita

@@ -29,7 +29,6 @@
         <li>Syntax diagrams and explanations</li>
       </ul>
     </section>
-    <!--<section id="purpose"><title>The purpose of the reference topic</title><p>Reference topics provide data that supports users as they perform a task. Reference topics might provide lists and tables that include product specifications, parts lists, and other data that is often <q>looked up</q> rather than memorized. A reference topic also can describe commands in a programming language or required tools for a series of maintenance tasks.</p><p>Reference topics provide quick access to fact-based information. In technical information, reference topics are used to list product specifications and parameters, provide essential data, and provide detailed information on subjects such as the commands in a programming language. Reference topics can contain any subject matter that has regular content, such as ingredients for food in recipes, bibliographic lists, catalog items, and so on.</p></section>-->
     <section id="content-model">
       <title>Content model</title>
       <p>The body of a reference topic can contain the following document
@@ -41,46 +40,19 @@
           </li>
         <li>Sections: <xmlelement>section</xmlelement></li>
         <li>Syntax sections: <xref keyref="elements-refsyn"><xmlelement>refsyn</xmlelement></xref></li>
-        <li>Tables: <xmlelement>simpletable</xmlelement> and
-            <xmlelement>table</xmlelement></li>
+        <li>Tables: <xmlelement>simpletable</xmlelement> and <xmlelement>table</xmlelement></li>
       </ul>
       <p>These structures can appear in any order or combination. However,
         basic document structure such as paragraphs, lists, and figures
         cannot be placed directly in the body of the reference topic. They
         must be contained within one of the structures listed above.</p>
     </section>
-    <!--<section id="structure"><title>The structure of the reference topic</title><p>The top-level element for a reference topic is the <xmlelement>reference</xmlelement> element.</p><p>The <xmlelement>refbody</xmlelement> element contains the main body-level elements of the reference topic. Reference topics limit the body to tables (both simple and complex), property lists, syntax sections, generic sections, and examples.</p><p>All of the elements of <xmlelement>refbody</xmlelement> are optional; they can appear in any sequence and number.</p></section>-->
-    <!--<section id="limitations"><title>Limitations on the reference body</title><p>The <xmlelement>refbody</xmlelement> provides for an unlimited number of subdivisions in the form of sections, examples, syntax sections, property lists, and tables. Simple tables, complex tables, and property lists also can appear within syntax sections. Sections, examples, syntax sections, table subdivisions, and property lists cannot nest; only one level of subdivision is permitted in the reference topic.</p></section>-->
-    <!--<section id="elements"><title>The elements in the reference body</title><draft-comment author="robander" audience="spec-editors" time="25 may 2021">Like in concept, this is almost but not quite a redefinition of section, example, etc</draft-comment><dl><dlentry><dt><xmlelement>section</xmlelement> </dt><dd>Represents an organizational division in a reference topic. Sections organize subsets of information within a larger topic. You can only include a simple list of peer sections in a topic; sections cannot be nested. A section can have an optional title. </dd></dlentry><dlentry><dt><xmlelement>refsyn</xmlelement> </dt><dd>Contains syntax or signature content (for example, a command-line utility's calling syntax or an API's signature). The <xmlelement>refsyn</xmlelement> contains a brief, possibly diagrammatic description of the subject's interface or high-level structure. </dd></dlentry><dlentry><dt><xmlelement>example</xmlelement> </dt><dd>Provides examples that illustrate or support the current topic. The <xmlelement>example</xmlelement> element has the same content model as <xmlelement>section</xmlelement>. </dd></dlentry><dlentry><dt><xmlelement>table</xmlelement> </dt><dd>Organizes information according into a rows and columns. Table markup also allows for more complex structures, including spanning rows and columns, as well as table captions. </dd></dlentry><dlentry><dt><xmlelement>simpletable</xmlelement> </dt><dd>Holds information in regular rows and columns and does not allow a caption. </dd></dlentry><dlentry><dt><xmlelement>properties</xmlelement> </dt><dd>Lists properties of a subject and their types, values, and descriptions. </dd></dlentry></dl></section>-->
-    <!--<example id="example" otherprops="examples"><title>Example</title><draft-comment author="robander" audience="spec-editors" time="25 may 2021">Should not start with "Following is …"</draft-comment><p>The following code examples contains a simple reference topic, including the <xmlelement>refsyn</xmlelement> element. </p><codeblock>&lt;reference id="boldproperty"&gt;
-&lt;title&gt;Bold property&lt;/title&gt;
-&lt;shortdesc&gt;(Read-write) Whether to use a bold font for the specified text string.&lt;/shortdesc&gt;
-&lt;refbody&gt;
-  &lt;refsyn&gt;
-    &lt;synph&gt;
-      &lt;var&gt;object&lt;/var&gt;&lt;delim&gt;.&lt;/delim&gt;&lt;kwd&gt;Font&lt;/kwd&gt;&lt;delim&gt;.&lt;/delim&gt;
-      &lt;kwd&gt;Bold&lt;/kwd&gt;&lt;delim&gt; = &lt;/delim&gt;&lt;var&gt;trueorfalse&lt;/var&gt;
-    &lt;/synph&gt;
-  &lt;/refsyn&gt;
-  &lt;properties&gt;
-    &lt;property&gt;
-      &lt;proptype&gt;Data type&lt;/proptype&gt;
-      &lt;propvalue&gt;Boolean&lt;/propvalue&gt;
-    &lt;/property&gt;
-    &lt;property&gt;
-      &lt;proptype&gt;Legal values&lt;/proptype&gt;
-      &lt;propvalue&gt;True (1) or False (0)&lt;/propvalue&gt;
-    &lt;/property&gt;
-  &lt;/properties&gt;
-&lt;/refbody&gt;
-&lt;/reference&gt;</codeblock></example>-->
     <example id="example" otherprops="examples">
       <title>Example</title>
       <p>The following code sample contains a simple reference topic:</p>
       <draft-comment author="Kristen J Eberlein" time="26 October 2022">
-        <p>While the following code sample is a perfectly reasonable
-          example of a properties list, I think we could provide a better
-          example of a reference topic.</p>
+        <p>TODO: While the following code sample is a perfectly reasonable example of a properties
+          list, I think we could provide a better example of a reference topic.</p>
       </draft-comment>
       <codeblock>&lt;reference id="oil-types"&gt;
   &lt;title&gt;Oil types&lt;/title&gt;

specification/archSpec/technicalContent/dita-spec-intro-bookmap.dita

@@ -14,7 +14,6 @@
         for recording information about the book, including authors,
         owners, versions, and production history.</p>
     </section>
-    <!--<section><title>The purpose of the bookmap specialization</title><p>Books and other printed media are popular ways to present DITA content. By specializing the general DITA map structure into the general structure and subject areas used by most book-oriented DTDs, bookmaps enable users to organize their DITA information into front matter, parts, chapters, and so forth. A rich set of metadata allows for recording information about the book, such as its authors and owners, versions, and production history.</p><draft-comment author="robander" audience="spec-editors" time="25 may 2021">Maybe "...used by most book-oriented DTDs" ==> "...used by most technical content books" or even "...used by most books"?</draft-comment></section>-->
     <section>
       <title>Content model</title>
       <p>A book map can contain the following document structures:</p>
@@ -40,7 +39,6 @@
         DITAVAL-reference domain module, and can be used to support branch filtering for the entire
         book.</p>
     </section>
-    <!--<section id="structure"><title>The structure of the bookmap specialization</title><p>The <xmlelement>bookmap</xmlelement> element is the top-level element for a DITA bookmap. Most of the content for a bookmap is optional, allowing for specializations that further restrict the bookmap model.</p><p>A bookmap allows the following parts:</p><ul><li>An initial title or booktitle (booktitle has more semantics)<draft-comment author="robander" audience="spec-editors" time="25 may 2021">I seem to remember a comment on previous specs that "semantics" is invalid like this, should be "semantic elements"?</draft-comment></li><li>Book metadata (publisher, author, copyright holders and dates, etc.)</li><li>A container for resources such as key definitions</li><li>Front matter (placement for Table of Contents and other preliminary information) </li><li>Any number of chapters or parts (parts can group chapters, chapters can group topics)</li><li>An appendices section (similar to a part or a chapter, can group multiple appendices)</li><li>Back matter (similar to front matter, notices, glossary, index, etc.)</li><li>Relationship tables</li></ul><p>In book-oriented XML grammars, authors typically manage content structures as external entities, separate from the body of the book and referenced as embedded elements into the overall structure. Bookmap follows the same organizational approach, using the topicref-based structure of DITA maps as the archetype for the major divisions of a book.</p></section>-->
     <example id="example" otherprops="examples">
       <title>Example</title>
       <p>The following code sample contains <ph rev="review-k">some common</ph> markup for a <ph