Skip to content

Commit

Permalink
Edited config and coding req chapters prior to distributing stage 3 o…
Browse files Browse the repository at this point in the history 
…asis-tcs#15
  • Loading branch information
@keberlein
keberlein committed May 14, 2021
1 parent a36de00 commit 6241920
Show file tree
Hide file tree
Showing 35 changed files with 172 additions and 203 deletions.
3 changes: 0 additions & 3 deletions specification/archSpec/base/adding-an-attribute-to-certain-table-elements.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,6 @@
each <codeph>&lt;!ATTLIST</codeph> declaration in its own separate expansion module,
thus allowing DITA architects who construct document-type shells to decide the elements
to which to apply the attribute.</p>
<draft-comment author="Kristen J Eberlein" time="03 May 2021">
<p>Tested and verified that this works as written.</p>
</draft-comment>
<ol>
<li>First, the DITA architect creates the attribute domain module for the
<xmlatt>cell-purpose</xmlatt> attribute:
Expand Down
6 changes: 3 additions & 3 deletions specification/archSpec/base/coding-requirements.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en-us" id="coding-practices">
<title>Coding practices for DITA grammar files</title>
<shortdesc>This section collects all of the rules for creating modular DTD, RELAX NG, or XML Schema
grammar files to represent DITA document types, specializations, and constraints.</shortdesc>
<!--<conbody><draft-comment author="robander" time="16 February 2015">For the "specialization" sections - should make sure the shortdescs for nested topics are consistent. 2 use "implementation (coding) requirements" and one uses "coding requirements". Also, I don't think this ensures backwards compatibility, at least with regards to non-OASIS specializations, or am I missing something?</draft-comment></conbody>-->
<shortdesc>This section collects all of the rules for creating modular DTD or RELAX NG-based
grammar files that represent DITA document types, specializations, constraints, <ph>and expansion
modules</ph>.</shortdesc>
</concept>
6 changes: 3 additions & 3 deletions specification/archSpec/base/configuration-specialization-and-constraints.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
expansion</ph>
</title>
<shortdesc rev="2.0">The extension facilities of DITA allow document-type shells, vocabulary
modules, and element-configuration modules (constraints and expansion) to be combined to create
specific DITA document types. Vocabulary modules also can be specialized to meet requirements
that are not satisfied by existing markup. </shortdesc>
modules, and element-configuration modules (constraint and expansion) to be combined to
create specific DITA document types. Vocabulary modules also can be specialized to meet
requirements that are not satisfied by existing markup. </shortdesc>
</concept>
8 changes: 4 additions & 4 deletions specification/archSpec/base/configuration.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en-us" id="concept_fgy_hbp_wr">
<title rev="2.0">Document-type configuration</title>
<shortdesc>Document-type configuration enables the definition of DITA document types that include
only the vocabulary modules that are required for a given set of documents. There is no need to
modify the vocabulary modules. Configurations are implemented as document-type
shells.</shortdesc>
<shortdesc><ph rev="2.0">Document-type configuration</ph> enables the definition of DITA document
types that include only the vocabulary modules that are required for a given set of
documents. There is no need to modify the vocabulary modules. <ph rev="2.0">Document-type
configurations</ph> are implemented as document-type shells.</shortdesc>
</concept>
8 changes: 4 additions & 4 deletions specification/archSpec/base/constraint-rules.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
<p>The content model and attributes of an element can be constrained by only one constraint
module. If two constraint modules exist that constrain the content model or attributes for a
specific element, those two modules must be replaced with a new constraint module that
reflects the aggregation of the two original constraint modules.</p>
reflects the aggregation of the two original modules.</p>
</dd>
</dlentry>
<dlentry>
Expand All @@ -32,9 +32,9 @@
be omitted from the domain extension group or parameter entity. In such a case, there is no
separate constraint declaration, because the content model is configured directly in the
document-type shell.</p>
<p >A domain module can be constrained by only one constraint module. This
means that all restrictions for the extension elements that are defined in the domain must be
contained within that one constraint module.</p>
<p>A domain module can be constrained by only one constraint module. This means that all
restrictions for the extension elements that are defined in the domain must be contained
within that one constraint module.</p>
</dd>
</dlentry>
<dlentry>
Expand Down
14 changes: 8 additions & 6 deletions specification/archSpec/base/constraints-overview.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en-us" id="concept_sv4_2gm_vp">
<title>Overview of constraints</title>
<shortdesc >Constraint modules enable information architects to restrict the
content models or attributes of OASIS-defined DITA grammars. A constraint is a simplification of
an XML grammar such that any instance that conforms to the constrained grammar also will conform
to the original grammar.<!-- The reverse is not true.--></shortdesc>
<shortdesc>Constraint modules enable information architects to restrict the content models or
attributes of DITA elements. A constraint is a simplification of an XML grammar such that any
instance that conforms to the constrained grammar also will conform to the original
grammar.<!-- The reverse is not true.--></shortdesc>
<prolog>
<metadata>
<keywords>
Expand Down Expand Up @@ -45,11 +45,13 @@
<dt>Restrict the elements that are available in a domain</dt>
<dd>
<p>Constraint modules can restrict the set of extension elements that are provided in a domain.
<ph >They also can restrict the content models for the extension
elements.</ph></p>
They also can restrict the content models for the extension elements.</p>
<p otherprops="examples">For example, a constraint on the programming domain can reduce the
list of included extension elements to <xmlelement>codeph</xmlelement> and
<xmlelement>codeblock</xmlelement>.</p>
<note rev="2.0">For DITA implementations that use RNG-based grammar file, restricting the set of
extension elements that are provided in a domain can be handled simply by document-type
configuration.</note>
</dd>
</dlentry>
<dlentry>
Expand Down
6 changes: 6 additions & 0 deletions specification/archSpec/base/constraints-processing-interoperability.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,12 @@
document type. Thus, for a processor to determine whether a document instance is compatible with
another document type, the document instance <term outputclass="RFC-2119"
>MUST</term> declare any constraints on the document type. </p>
<draft-comment author="Kristen J Eberlein" time="14 May 2021">
<p>For DITA 2.0, we've removed the requirement to add tokens for constraints. So, I think we need
to remove this normative statement. Do we want to replace it with anything? Another statement
about constraints and interoperability? This reminds we that we might want to stress for folks
that we have removed the entire concept of strong and weak constraints ...</p>
</draft-comment>
<p otherprops="examples">For example, an unconstrained task is compatible with an unconstrained
topic, because the <xmlelement>task</xmlelement> element can be generalized to
<xmlelement>topic</xmlelement>. However, if the topic is constrained to require the
Expand Down
30 changes: 15 additions & 15 deletions specification/archSpec/base/ditaspecialization.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,40 +16,40 @@
<dl>
<dlentry>
<dt rev="2.0">Document-type configuration</dt>
<dd>Document-type configuration enables the definition of DITA document types that include
only the vocabulary modules that are required for a given set of documents. There is no
need to modify the vocabulary modules. Configurations are implemented as document-type
shells.</dd>
<dd><ph rev="2.0">Document-type configuration</ph> enables the definition of DITA document
types that include only the vocabulary modules that are required for a given set of
documents. There is no need to modify the vocabulary modules. <ph rev="2.0">Document-type
configurations</ph> are implemented as document-type shells.</dd>
</dlentry>
<dlentry>
<dt>Specialization</dt>
<dd>Specialization enables the creation of new element types in a way that preserves the
ability to interchange those new element types with conforming DITA applications.
Specializations are implemented as vocabulary modules, which are integrated into
document-type shells.<p>Specializations are declare the elements and entities that are
unique to a specialization. The separation of the vocabulary and its declarations into
modules makes it easy to extend existing modules, because new modules can be added
without affecting existing document types. It also makes it easy to assemble elements
from different sources into a single document-type shell and to reuse specific parts of
the specialization hierarchy in more than one document-type shell.</p></dd>
document-type shells.<p>Specializations declare the elements and entities that are unique
to a specialization. The separation of the vocabulary and its declarations into modules
makes it easy to extend existing modules, because new modules can be added without
affecting existing document types. It also makes it easy to assemble elements from
different sources into a single document-type shell and to reuse specific parts of the
specialization hierarchy in more than one document-type shell.</p></dd>
</dlentry>
<dlentry rev="2.0">
<dt>Element-type configuration</dt>
<dd>
<p>Element-type configuration enables DITA architects to modify the content models and
attribute lists for individual elements, without modifying the vocabulary modules in
which the elements are defined.</p>
<p>There are two types of element configuration: Constraints and expansion. Both
constraints and expansions are implemented as modules that are integrated into
document-type shells:</p>
<p>There are two types of element configuration: Constraint and expansion. Both constraint
and expansion are implemented as modules that are integrated into document-type
shells:</p>
<dl>
<dlentry>
<dt>Constraints</dt>
<dt>Constraint</dt>
<dd>Constraint modules enables the restriction of content models and attribute lists
for individual elements.</dd>
</dlentry>
<dlentry>
<dt>Expansions</dt>
<dt>Expansion</dt>
<dd>Expansion modules enable the expansion of content models and attribute lists for
individual elements.</dd>
</dlentry>
Expand Down
10 changes: 5 additions & 5 deletions specification/archSpec/base/document-type-shells-equivalence.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
<conbody>
<p>A DITA document type is defined by the following:</p>
<ul>
<li>The set of vocabulary and <ph rev="2.0">element-configuration modules (constraints and
<li>The set of vocabulary and <ph rev="2.0">element-configuration modules (constraint and
expansion)</ph> that are integrated by the document type shell </li>
<li>The values of the <xmlatt>class</xmlatt> attributes of all the elements in the
document</li>
Expand All @@ -31,9 +31,9 @@
<li>It has a distinct system identifier.</li>
<li>If it has a public identifier, the public identifier is unique.</li>
</ul>
<note>The public or system identifier that is associated with a given document-type shell is
not, by itself, necessarily distinguishing. This is because two different people or groups
might use the same modules and constraints to assemble equivalent document type shells, while
giving them different names or public identifiers. </note>
<note>The public or system identifier that is associated with a given document-type shell is not
necessarily distinguishing. Two different people or groups might use the same modules and
constraints to assemble equivalent document type shells, while giving them different names or
public identifiers. </note>
</conbody>
</concept>
60 changes: 29 additions & 31 deletions specification/archSpec/base/document-type-shells.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,49 +14,47 @@
</metadata>
</prolog>
<conbody>
<p>A DITA document must either have an associated document-type definition
or all required attributes must be made explicit in the document instances.
Most DITA documents have an associated document-type shell. DITA documents that
reference a document-type shell can be validated using standard XML processors.
Such validation enables processors to read the XML grammar files and determine
default values for the <xmlatt>specializations</xmlatt> and <xmlatt>class</xmlatt>
attributes.
</p>
<p>A DITA document either must have an associated document-type definition or all required
attributes must be made explicit in the document instances. Most DITA documents have an
associated document-type shell. DITA documents that reference a document-type shell can
be validated using standard XML processors. Such validation enables processors to read
the XML grammar files and determine default values for the
<xmlatt>specializations</xmlatt> and <xmlatt>class</xmlatt> attributes. </p>
<p>The following figure illustrates the relationship between a DTD-based DITA document, its
document-type shell, the vocabulary modules that it uses, <ph rev="2.0">and the
element-configuration modules (constraints and expansions) that it integrates</ph>.
element-configuration modules (constraint and expansion) that it integrates</ph>.
Similar structure applies to DITA documents that use other XML grammars. </p>
<fig id="fig_A20B8879F2D94F41B6B732A546C8D772">
<title>Document type shell</title>
<image href="../../images/instances-modules-declarations-01.png"
placement="break" id="image_1EB5D8D620784EBA9C6D5F250A8C321B" scale="70"
>
<alt>Diagram showing a typical architecture of a DITA document type shell. At the top left a
DITA document file named <filepath>myTopic.dita</filepath> refers to a document
type of 'myTopic'. An arrow from this file points to a document-type shell file
named <filepath>myTopic.dtd</filepath>. Arrows point to several other modules. A
constraint module is named <filepath>strictMyTopicConstraint.mod</filepath>.
Structural modules are named <filepath>mytopic.ent</filepath>,
<filepath>mytopic.mod</filepath>, <filepath>topic.ent</filepath>, and
<filepath>topic.mod</filepath>. Domain modules are named
<filepath>myPhraseDomain.ent</filepath>,
<fig>
<title>Document type shell</title>
<image href="../../images/instances-modules-declarations-01.png" placement="break"
scale="70">
<alt>Diagram showing a typical architecture of a DITA document type shell. At the
top left a DITA document file named <filepath>myTopic.dita</filepath> refers to
a document type of 'myTopic'. An arrow from this file points to a document-type
shell file named <filepath>myTopic.dtd</filepath>. Arrows point to several other
modules. A constraint module is named
<filepath>strictMyTopicConstraint.mod</filepath>. Structural modules are
named <filepath>mytopic.ent</filepath>, <filepath>mytopic.mod</filepath>,
<filepath>topic.ent</filepath>, and <filepath>topic.mod</filepath>. Domain
modules are named <filepath>myPhraseDomain.ent</filepath>,
<filepath>myPhraseDomain.mod</filepath>,
<filepath>highlightDomain.ent</filepath>,
<filepath>highlightDomain.mod</filepath>,
<filepath>programmingDomain.ent</filepath>, and
<filepath>programmingDomain.mod</filepath>. The structural and domain
modules are grouped together and labeled vocabulary modules. </alt>
</image>
</fig>
modules are grouped together and labeled vocabulary modules. </alt>
</image>
</fig>
<draft-comment author="Kristen J Eberlein" time="28 March 2021">
<p>The illustration needs to be updated to include expansion modules.</p>
</draft-comment>
<p>The DITA specification contains a starter set of document-type shells. These document-type
shells are commented and can be used as templates for creating custom document-type
shells. While the OASIS-provided document-type shells can be used without any
modification, creating custom document-type shells is a best practice. If the
document-type shells need to be modified in the future, for example, to include a
specialization or integrate a constraint, the existing DITA documents will not need to
be modified to reference a new document-type shell. </p>
shells.</p>
<p>While the OASIS-provided document-type shells can be used without any modification,
creating custom document-type shells is a best practice. If the document-type shells
need to be modified in the future, for example, to include a specialization or integrate
a constraint, the existing DITA documents will not need to be modified to reference a
new document-type shell. </p>
</conbody>
</concept>
10 changes: 5 additions & 5 deletions specification/archSpec/base/dtd-coding-overview.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,11 @@
<p>Every element in a DITA DTD defines its content model using an entity. <ph rev="2.0">This
enables element configuration.</ph></p>
<example>For example, rather than directly setting what is allowed in
<xmlelement>ph</xmlelement>, that element sets its content model to
<codeph>%ph.content;</codeph>; that entity defines the actual content model. <ph rev="2.0">A
constraint module can redefine the <codeph>%ph.content;</codeph> model to remove selected
elements, or an expansion module can redefine the <codeph>%ph.content;</codeph> module to add
elements.</ph>.</example>
<xmlelement>ph</xmlelement>, that element sets its content model to
<codeph>%ph.content;</codeph>; that entity defines the actual content model. <ph
rev="2.0">A constraint module can redefine the <codeph>%ph.content;</codeph> model to
remove selected elements, or an expansion module can redefine the
<codeph>%ph.content;</codeph> module to add elements</ph>.</example>
</dd>
</dlentry>
<dlentry>
Expand Down
7 changes: 0 additions & 7 deletions specification/archSpec/base/dtd-coding-requirements-expansion-modules.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,13 +45,6 @@
expansion attribute and should not be included in the
<parameterentity>base-attribute-extensions</parameterentity> entity
in the document-type shell.</p>
<draft-comment author="Kristen J Eberlein" time="08 April 2021">
<p>Should we call this
<codeph><varname>tagname</varname>.attributes</codeph> parameter
entity? Or would
<codeph><varname>Domain</varname>.attributes</codeph> parameter
entity be more appropriate?</p>
</draft-comment>
</dd>
</dlentry>
<dlentry>
Expand Down
Loading

0 comments on commit 6241920

Please sign in to comment.