Skip to content

Commit

Permalink
Merge pull request #720 from keberlein/proposal-15
Browse files Browse the repository at this point in the history 
Updates for proposal 15
  • Loading branch information
@keberlein
keberlein authored Jul 14, 2022
2 parents f025236 + e48a7f1 commit 83249fe
Show file tree
Hide file tree
Showing 14 changed files with 221 additions and 182 deletions.
10 changes: 0 additions & 10 deletions specification/archSpec/base/constraints-processing-interoperability.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,15 +31,5 @@
a <xmlelement>shortdesc</xmlelement> element. However, if the task document type also has been
constrained to require the <xmlelement>shortdesc</xmlelement> element, it is compatible with the
constrained topic 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; accordingly I
removed the following paragraph:</p>
<p>"A constrained document type allows only a subset of the possible instances of the
unconstrained 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>
<p>Does this topic make sense without that paragraph? How do we need to rework it? Does it need
to cover anything about</p>
</draft-comment>
</conbody>
</concept>
4 changes: 2 additions & 2 deletions specification/archSpec/base/ditaspecialization.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,8 @@
<dl>
<dlentry>
<dt>Constraint</dt>
<dd>Constraint modules enables the restriction of content models and attribute lists
for individual elements.</dd>
<dd>Constraint modules enable the restriction of content
models and attribute lists for individual elements.</dd>
</dlentry>
<dlentry>
<dt>Expansion</dt>
Expand Down
35 changes: 21 additions & 14 deletions specification/archSpec/base/example-constrain-a-domain-using-rng.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,15 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="example_constrain_a_domain_using_rng">
<title>Example: Constrain a domain module using RNG</title>
<shortdesc>In this scenario, an information architect wants to use only a subset of the elements
defined in the highlighting domain. She wants to use <xmlelement>b</xmlelement> and
<xmlelement>i</xmlelement> but not <xmlelement>line-through</xmlelement>,
<xmlelement>overline</xmlelement>, <xmlelement>sup</xmlelement>,
<xmlelement>sup</xmlelement>, <xmlelement>tt</xmlelement>, or
<xmlelement>u</xmlelement>. Her implementation uses RNG for its grammar files.</shortdesc>
<shortdesc>In this scenario, <ph rev="2.0">a DITA architect</ph> wants
to use only a subset of the elements defined in the highlighting
domain. <ph rev="2.0">They want</ph> to use <xmlelement>b</xmlelement>
and <xmlelement>i</xmlelement> but not
<xmlelement>line-through</xmlelement>,
<xmlelement>overline</xmlelement>, <xmlelement>sup</xmlelement>,
<xmlelement>sup</xmlelement>, <xmlelement>tt</xmlelement>, or
<xmlelement>u</xmlelement>. <ph rev="2.0">Their</ph> implementation
uses RNG for its grammar files.</shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -22,9 +25,10 @@
<p>When using RNG, domains can be constrained directly in the document-type shells.</p>
<ol>
<li>
<p>She opens the document-type shell for topic in an XML editor, and then modifies the
"MODULE INCLUSIONS" division to exclude the elements that she does not want the
implementation to use:</p>
<p><ph rev="2.0">They open</ph> the document-type shell for topic
in an XML editor, and then <ph rev="2.0">they modify</ph> the
"MODULE INCLUSIONS" division to exclude the elements that <ph
rev="2.0">they do</ph> not want the implementation to use:</p>
<codeblock>&lt;div>
&lt;a:documentation>MODULE INCLUSIONS&lt;/a:documentation>
...
Expand All @@ -50,12 +54,15 @@
&lt;/include>
..
&lt;/div></codeblock>
<note>The information architect made a choice as to where in the document-type shell she
would implement the constraint. It can be placed either in the "Element-type configuration
integration" or the "Module inclusions" section.</note>
<note>The <ph rev="2.0">DITA</ph> architect made a choice as to
where in the document-type shell <ph rev="2.0">they</ph> would
implement the constraint. It can be placed either in the
"Element-type configuration integration" or the "Module
inclusions" section.</note>
</li>
<li>She makes similar changes to all the other document-type shells in which she wants
to constrain the highlighting domain.</li>
<li><ph rev="2.0">They make</ph> similar changes to all the
other document-type shells in which <ph rev="2.0">they want</ph> to
constrain the highlighting domain.</li>
</ol>
</conbody>
</concept>
56 changes: 33 additions & 23 deletions specification/archSpec/base/example-contraints-redefine-content-model-attributes.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,10 @@
<concept xml:lang="en-us" id="reference_cfb_ck4_5p">
<title>Example: Constrain attributes for the <xmlelement>section</xmlelement> element using
DTD</title>
<shortdesc>In this scenario, an information architect wants to redefine the attributes for the
<xmlelement>section</xmlelement> element. He wants to make the <xmlatt>id</xmlatt> attribute
required.</shortdesc>
<shortdesc>In this scenario, a <ph rev="2.0">DITA architect</ph> wants to
redefine the attributes for the <xmlelement>section</xmlelement>
element. <ph rev="2.0">They want</ph> to make the <xmlatt>id</xmlatt>
attribute required.</shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -19,10 +20,10 @@
<conbody>
<example id="example">
<ol>
<li>He creates a <filepath>.mod</filepath> file named
<filepath>idRequiredSectionContraint.mod</filepath>, where "idRequired" is a string that
characterizes the constraint.</li>
<li>He adds the following content to
<li><ph rev="2.0">They create</ph> a <filepath>.mod</filepath> file
named <filepath>idRequiredSectionContraint.mod</filepath>, where
"idRequired" is a string that characterizes the constraint.</li>
<li><ph rev="2.0">They add</ph> the following content to
<filepath>idRequiredSectionContraint.mod</filepath>:<codeblock>&lt;!-- Declares the entities referenced in the constrained content -->
&lt;!-- model. -->

Expand Down Expand Up @@ -109,22 +110,31 @@
outputclass
CDATA
#IMPLIED"
></codeblock><note>The information architect had to declare all the parameter entities
that are referenced in the redefined attributes for <xmlelement>section</xmlelement>. If
he did not do so, none of the attributes that are declared in the parameter entities
would be available on the <xmlelement>section</xmlelement> element. Furthermore, since
the <parameterentity>select-atts</parameterentity> parameter entity references the
<parameterentity>filter-atts</parameterentity> parameter entity, the
<parameterentity>filter-atts</parameterentity> must be declared and it must precede
the declaration for the <parameterentity>select-atts</parameterentity> parameter entity.
The <parameterentity>props-attribute-extensions</parameterentity> and
<parameterentity>base-attribute-extensions</parameterentity> parameter entities do not
need to be declared in the constraint module, because they are declared in the
document-type shells before the inclusion of the constraint module.</note></li>
<li>He adds the constraint module to the <filepath>catalog.xml</filepath> file.</li>
<li>He then integrates the constraint module into the applicable document-type shells.</li>
<li>After checking test topics to ensure that the content model is modified as expected, his
work is done.</li>
></codeblock><note>The DITA architect had to declare all the
parameter entities that are referenced in the redefined
attributes for <xmlelement>section</xmlelement>. If <ph
rev="2.0">they</ph> did not do so, none of the attributes
that are declared in the parameter entities would be available
on the <xmlelement>section</xmlelement> element. Furthermore,
since the <parameterentity>select-atts</parameterentity>
parameter entity references the
<parameterentity>filter-atts</parameterentity> parameter
entity, the <parameterentity>filter-atts</parameterentity> must
be declared and it must precede the declaration for the
<parameterentity>select-atts</parameterentity> parameter
entity. The
<parameterentity>props-attribute-extensions</parameterentity>
and
<parameterentity>base-attribute-extensions</parameterentity>
parameter entities do not need to be declared in the constraint
module, because they are declared in the document-type shells
before the inclusion of the constraint module.</note></li>
<li><ph rev="2.0">They add</ph> the constraint module to the
<filepath>catalog.xml</filepath> file.</li>
<li><ph rev="2.0">They then integrate</ph> the constraint module
into the applicable document-type shells.</li>
<li>After checking the test topics to ensure that the content model
is modified as expected, the work is done.</li>
</ol>
</example>
</conbody>
Expand Down
40 changes: 24 additions & 16 deletions specification/archSpec/base/example-contraints-redefine-content-model.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,14 @@
<concept xml:lang="en-us" id="reference_cfb_ck4_5p">
<title>Example: Redefine the content model for the <xmlelement>topic</xmlelement> element using
DTD</title>
<shortdesc>In this scenario, an information architect for Acme, Incorporated wants to redefine the
content model for the topic document type. She wants to omit the
<xmlelement>abstract</xmlelement> element and make the <xmlelement>shortdesc</xmlelement>
element required; she also wants to omit the <xmlelement>related-links</xmlelement> element and
disallow topic nesting.</shortdesc>
<shortdesc>In this scenario, <ph rev="2.0">the DITA architect</ph> for
Acme, Incorporated wants to redefine the content model for the topic
document type. <ph rev="2.0">The architect</ph> wants to omit the
<xmlelement>abstract</xmlelement> element and make the
<xmlelement>shortdesc</xmlelement> element required; <ph rev="2.0"
>the architect also wants</ph> to omit the
<xmlelement>related-links</xmlelement> element and disallow topic
nesting.</shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -21,13 +24,16 @@
<conbody>
<example id="example">
<ol>
<li>She creates a <filepath>.mod</filepath> file using the following naming conventions:
<li><ph rev="2.0">The architect creates</ph> a
<filepath>.mod</filepath> file using the following naming
conventions:
<filepath><varname>qualifer</varname><varname>Tagname</varname>Constraint.mod</filepath>,
where <varname>qualifer</varname> is a string the describes the constraint, and
<varname>Tagname</varname> is the element type name with an initial capital. Her
constraint module is named <filepath>acme-TopicConstraint.mod</filepath>.</li>
<li>She adds the following content to
<filepath>acme-TopicConstraint.mod</filepath>:<codeblock>
where <varname>qualifer</varname> is a string the describes the
constraint, and <varname>Tagname</varname> is the element type
name with an initial capital. The constraint module is named
<filepath>acme-TopicConstraint.mod</filepath>.</li>
<li><ph rev="2.0">The architect adds</ph> the following content to
<filepath>acme-TopicConstraint.mod</filepath>:<codeblock>
&lt;!-- ============================================================= -->
&lt;!-- CONSTRAINED TOPIC ENTITIES -->
&lt;!-- ============================================================= -->
Expand All @@ -48,9 +54,11 @@
(%prolog;)?,
(%body;)?)"
></codeblock></li>
<li>She adds the constraint module to the <filepath>catalog.xml</filepath> file.</li>
<li>She then integrates the constraint module into her document-type shell for topic by
adding the following section above the "TOPIC ELEMENT INTEGRATION"
<li><ph rev="2.0">The architect adds</ph> the constraint module to
the <filepath>catalog.xml</filepath> file.</li>
<li><ph rev="2.0">The architect then integrates</ph> the constraint
module into the document-type shell for topic by adding the
following section above the "TOPIC ELEMENT INTEGRATION"
comment:<codeblock>&lt;!-- ============================================================= -->
&lt;!-- ELEMENT-TYPE CONFIGURATION INTEGRATION -->
&lt;!-- ============================================================= -->
Expand All @@ -59,8 +67,8 @@
PUBLIC "-//ACME//ELEMENTS DITA Topic Constraint//EN"
"acme-TopicConstraint.mod">
%topic-constraints-c-def;</codeblock></li>
<li>After checking her test topic to ensure that the content model is modified as expected,
her work is done.</li>
<li>After checking the test topic to ensure that the content model
is modified as expected, the work is done.</li>
</ol>
</example>
</conbody>
Expand Down
22 changes: 13 additions & 9 deletions specification/archSpec/base/example-contraints-replace-base-element-w-domain-extensions.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en-us" id="reference_cfb_ck4_5p">
<title>Example: Replace a base element with the domain extensions using DTD</title>
<shortdesc>In this scenario, an information architect wants to remove the
<xmlelement>ph</xmlelement> element but allow the extensions of <xmlelement>ph</xmlelement>
that exist in the highlighting, programming, software, and user interface domains.</shortdesc>
<shortdesc>In this scenario, <ph rev="2.0">a DITA</ph> architect wants to
remove the <xmlelement>ph</xmlelement> element but allow the extensions
of <xmlelement>ph</xmlelement> that exist in the highlighting,
programming, software, and user interface domains.</shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -18,18 +19,21 @@
<conbody>
<example id="example">
<ol>
<li>In the "DOMAIN EXTENSIONS" section, the information architect removes the reference to
the <xmlelement>ph</xmlelement>
<li>In the "DOMAIN EXTENSIONS" section, <ph rev="2.0">the DITA
architect</ph> removes the reference to the
<xmlelement>ph</xmlelement>
element:<codeblock>&lt;!-- Removed "ph | " so as to make &lt;ph> not available, only the domain extensions. -->
&lt;!ENTITY % ph "%pr-d-ph; |
%sw-d-ph; |
%ui-d-ph;
"></codeblock></li>
</ol>
<note>Because no other entities are modified or declared outside of the usual "DOMAIN
EXTENSIONS" section, this completes the information architect's task. Because no new grammar
file or entity is created that would highlight this change, adding a comment to highlight
the constraint becomes particularly important (as shown in the example above).</note>
<note>Because no other entities are modified or declared outside of
the usual "DOMAIN EXTENSIONS" section, this completes the
architect's task. Because no new grammar file or entity is created
that would highlight this change, adding a comment to highlight the
constraint becomes particularly important (as shown in the example
above).</note>
</example>
</conbody>

Expand Down
42 changes: 25 additions & 17 deletions specification/archSpec/base/example-contraints-subset-domain.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,15 @@
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en-us" id="reference_cfb_ck4_5p">
<title>Example: Constrain a domain module using DTD</title>
<shortdesc>In this scenario, an information architect wants to use only a subset of the elements
defined in the highlighting domain. She wants to use <xmlelement>b</xmlelement> and
<xmlelement>i,</xmlelement> but not <xmlelement>line-through</xmlelement>,
<xmlelement>overline</xmlelement>, <xmlelement>sup</xmlelement>, <xmlelement>sup</xmlelement>,
<xmlelement>tt</xmlelement>, or <xmlelement>u</xmlelement>. She wants to integrate this
constraint into the document-type shell for task.</shortdesc>
<shortdesc>In this scenario, <ph rev="2.0">a DITA architect</ph> wants to
use only a subset of the elements defined in the highlighting domain.
<ph rev="2.0">They want</ph> to use <xmlelement>b</xmlelement> and
<xmlelement>i,</xmlelement> but not
<xmlelement>line-through</xmlelement>,
<xmlelement>overline</xmlelement>, <xmlelement>sup</xmlelement>,
<xmlelement>sup</xmlelement>, <xmlelement>tt</xmlelement>, or
<xmlelement>u</xmlelement>. <ph rev="2.0">They want</ph> to integrate
this constraint into the document-type shell for task.</shortdesc>
<prolog>
<metadata>
<keywords>
Expand All @@ -21,18 +24,22 @@
<conbody>
<example id="example">
<ol>
<li>She creates <filepath>reducedHighlightingDomainConstraint.mod</filepath>, where
"reduced" is a string that characterizes the constraint.</li>
<li>She adds the following content to
<li><ph rev="2.0">They create</ph>
<filepath>reducedHighlightingDomainConstraint.mod</filepath>,
where "reduced" is a string that characterizes the
constraint.</li>
<li><ph rev="2.0">They add</ph> the following content to
<filepath>reducedHighlightingDomainConstraint.mod</filepath>:<codeblock>&lt;!-- ============================================================= -->
&lt;!-- CONSTRAINED HIGHLIGHT DOMAIN ENTITIES -->
&lt;!-- ============================================================= -->

&lt;!ENTITY % HighlightingDomain-c-ph "b | i" > </codeblock></li>
<li>She adds the constraint module to the <filepath>catalog.xml</filepath> file.</li>
<li>She then integrates the constraint module into her company-specific, document-type shell
for the task topic by adding the following section directly before the "DOMAIN ENTITY
DECLARATIONS"
<li><ph rev="2.0">They add</ph> the constraint module to the
<filepath>catalog.xml</filepath> file.</li>
<li><ph rev="2.0">They then integrate</ph> the constraint module
into the company-specific, document-type shell for the task topic
by adding the following section directly before the "DOMAIN
ENTITY DECLARATIONS"
comment:<codeblock>&lt;!-- ============================================================= -->
&lt;!-- DOMAIN CONSTRAINT INTEGRATION -->
&lt;!-- ============================================================= -->
Expand All @@ -41,15 +48,16 @@
PUBLIC "-//ACME//ENTITIES DITA Highlighting Domain Constraint//EN"
"acme-HighlightDomainConstraint.mod"
>%HighlightDomain-c-dec;</codeblock></li>
<li>In the "DOMAIN EXTENSIONS" section, she replaces the parameter entity for the
highlighting domain with the parameter entity for the constrained highlighting
<li>In the "DOMAIN EXTENSIONS" section, <ph rev="2.0">they
replace</ph> the parameter entity for the highlighting domain
with the parameter entity for the constrained highlighting
domain:<codeblock>&lt;!ENTITY % ph "ph |
<b>%HighlightDomain-c-ph;</b> |
%sw-d-ph; |
%ui-d-ph;
"></codeblock></li>
<li>After checking her test topic to ensure that the content model is modified as expected,
her work is done.</li>
<li>After checking the test topic to ensure that the content model
is modified as expected, the work is done.</li>
</ol>
</example>
</conbody>
Expand Down
Loading

0 comments on commit 83249fe

Please sign in to comment.