Skip to content

Commit

Permalink
Updates for proposal oasis-tcs#15
Browse files Browse the repository at this point in the history
  • Loading branch information
@keberlein
keberlein committed Jul 14, 2022
1 parent 83249fe commit 8162ee9
Show file tree
Hide file tree
Showing 9 changed files with 53 additions and 94 deletions.
40 changes: 11 additions & 29 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 @@ -40,12 +40,6 @@
<ol>
<li><draft-comment author="Kristen J Eberlein" time="07 June 2021">
<p>Comments by Eliot Kimber: </p>
<p>[Re defining the attribute]: I don't really see the value in
having the "-expansion" distinction here--whether to use this
as a global attribute or through extension is really up to the
doc type shell author. The definer of the attribute domain may
intend for it to be used only on specific element types but
that's not really their choice to make."</p>
<p>[Re the entity to be used in the @specializations attribute]:
"Should there be leading and trailing space in the replacement
text?"</p>
Expand All @@ -71,33 +65,21 @@
&lt;!ATTLIST row %cellPurposeAtt-d-attribute-expansion;>
&lt;!ATTLIST colspec %cellPurposeAtt-d-attribute-expansion;>
&lt;!ATTLIST strow %cellPurposeAtt-d-attribute-expansion;>
&lt;!ATTLIST stentry %cellPurposeAtt-d-attribute-expansion;></codeblock><note>The
attribute definition entity ends in <codeph>-expansion</codeph>;
this indicates that this is an expansion attribute and should not
be included in the
<parameterentity>base-attribute-extensions</parameterentity>
entity in the document-type shell.<draft-comment
author="Kristen J Eberlein" time="07 June 2021">
<p>Comment by Eliot Kimber: "See my comment above: I don't
think we should do this."</p>
</draft-comment></note><draft-comment author="Kristen J Eberlein"
time="18 May 2021">
<p>Comment by Robert Anderson: "[The note] should clarify that
this entity is totally optional -- only useful here because
we're adding the same attribute with the same tokens to several
elements. If you're only adding one attribute to one element,
you wouldn't want this entity."</p>
</draft-comment></li>
<li>The DITA architect updates the <filepath>catalog.xml</filepath>
file to include the expansion module.<draft-comment
author="Kristen J Eberlein" time="07 June 2021">
&lt;!ATTLIST stentry %cellPurposeAtt-d-attribute-expansion;></codeblock><note
rev="2.0">The attribute definition entity is optional. It is used
here to enable the DITA architect to add the same attribute with
the same tokens to several elements.</note></li>
<li><ph rev="2.0">They then update</ph> the
<filepath>catalog.xml</filepath> file to include the expansion
module.<draft-comment author="Kristen J Eberlein"
time="07 June 2021">
<p>Comment by Eliot Kimber: "This is something almost everybody
*would* do but it's not actually required since the use of
catalogs is not required by DITA or by the use of DTDs
generally, at least in theory (and in actual fact if you are an
Author/Editor user, which doesn't support catalogs)."</p>
</draft-comment></li>
<li>The DITA architect integrates this module into the applicable
<li><ph rev="2.0">They integrate</ph> this module into the applicable
document-type
shell.<codeblock>&lt;!-- ============================================================= -->
&lt;!-- DOMAIN ATTRIBUTES DECLARATIONS -->
Expand All @@ -109,8 +91,8 @@
PUBLIC "-//ACME//ENTITIES DITA Cell Purpose Attribute Expansion//EN"
"cellPurposeAttExpansion.ent"
>%cellPurposeAttExpansion-d-dec;</b></codeblock></li>
<li>The DITA architect adds the entity for the contribution to the
<xmlatt>specializations</xmlatt>
<li><ph rev="2.0">They add</ph> the entity for the contribution to
the <xmlatt>specializations</xmlatt>
attribute.<codeblock>&lt;!-- ============================================================= -->
&lt;!-- SPECIALIZATIONS ATTRIBUTE OVERRIDE -->
&lt;!-- ============================================================= -->
Expand Down
5 changes: 2 additions & 3 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 @@ -20,9 +20,8 @@
<conbody>
<example id="example">
<ol>
<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 rev="2.0">The DITA architect creates a constraint module:
<filepath>idRequiredSectionContraint.mod</filepath>.</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
26 changes: 10 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 @@ -5,10 +5,10 @@
DTD</title>
<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
document type. <ph rev="2.0">They want</ph> 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
>they also want</ph> to omit the
<xmlelement>related-links</xmlelement> element and disallow topic
nesting.</shortdesc>
<prolog>
Expand All @@ -24,15 +24,9 @@
<conbody>
<example id="example">
<ol>
<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. The constraint module is named
<filepath>acme-TopicConstraint.mod</filepath>.</li>
<li><ph rev="2.0">The architect adds</ph> the following content to
<li><ph rev="2.0">The DITA architect creates a constraint module: </ph><!--<ph rev="2.0"/> 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. The constraint module is named-->
<filepath>acme-TopicConstraint.mod</filepath>.</li>
<li><ph rev="2.0">They add</ph> the following content to
<filepath>acme-TopicConstraint.mod</filepath>:<codeblock>
&lt;!-- ============================================================= -->
&lt;!-- CONSTRAINED TOPIC ENTITIES -->
Expand All @@ -54,11 +48,11 @@
(%prolog;)?,
(%body;)?)"
></codeblock></li>
<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"
<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 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 Down
6 changes: 2 additions & 4 deletions specification/archSpec/base/example-contraints-subset-domain.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,8 @@
<conbody>
<example id="example">
<ol>
<li><ph rev="2.0">They create</ph>
<filepath>reducedHighlightingDomainConstraint.mod</filepath>,
where "reduced" is a string that characterizes the
constraint.</li>
<li rev="2.0">TheDITA architect creates a constraint module:
<filepath>reducedHighlightingDomainConstraint.mod</filepath>.</li>
<li><ph rev="2.0">They add</ph> the following content to
<filepath>reducedHighlightingDomainConstraint.mod</filepath>:<codeblock>&lt;!-- ============================================================= -->
&lt;!-- CONSTRAINED HIGHLIGHT DOMAIN ENTITIES -->
Expand Down
16 changes: 2 additions & 14 deletions specification/archSpec/base/example-rng-constraints-redefine-content-model-attributes.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,20 +21,8 @@
<conbody>
<example id="example">
<ol>
<li><ph rev="2.0">They create</ph> a file named
<filepath>id-requiredSectionContraintMod.rng</filepath>, where
<varname>id-required</varname> is a string that characterizes
the constraint.<draft-comment author="Kristen J Eberlein"
time="17 May 2021">
<p>Comment from Robert Anderson: "Section 8.5.5.2, seems odd to
me that we say "...where id-required is a string that
characterizes the constraint." First, because that's clear
from what we're doing, and second, because the author could
use any name they want."</p>
<p>Reminder to check other example topics (constraint and
expansion) to see how often we provide info about conventions
for file naming, and then talk to Robert about it.</p>
</draft-comment></li>
<li rev="2.0">The DITA architect creates a constraint module:
<filepath>id-requiredSectionContraintMod.rng</filepath>.</li>
<li><ph rev="2.0">They update</ph> the
<filepath>catalog.xml</filepath> file to include the new
constraint module.</li>
Expand Down
13 changes: 3 additions & 10 deletions specification/archSpec/base/example-rng-constraints-redefine-content-model.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,7 @@
<conbody>
<example id="example">
<ol>
<li><ph rev="2.0">They create</ph> a <filepath>.mod</filepath> file
using the following naming conventions:
<filepath><varname>qualifer</varname><varname>Tagname</varname>ConstraintMod.rng</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
<li rev="2.0">The DITA architect creates a constraint module:
<filepath>acme-TopicConstraintMod.rng</filepath>.</li>
<li><ph rev="2.0">They update</ph> the
<filepath>catalog.xml</filepath> file to include the new
Expand All @@ -51,12 +46,10 @@
&lt;/include>
&lt;/div></codeblock><draft-comment author="Kristen J Eberlein"
time="21 April 2021">
<p>We need to change the header to "ATTRIBUTE AND CONTENT MODEL
OVERRIDES" in the constraint module that we ship.</p>
<p>Also, I know that the override won't happen without
<p>I know that the override won't happen without
<codeph>combine="interleave"</codeph>, but I don't know if
we cover that in the coding requirements topic. If people
start with copy-ing-and-pasting from the module that they are
start with copying-and-pasting from the module that they are
overriding, they won't have that and will get errors.</p>
</draft-comment></li>
<li><ph rev="2.0">They then integrate</ph> the constraint module
Expand Down
6 changes: 4 additions & 2 deletions specification/archSpec/base/rng-adding-an-element-to-the-section-element.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,10 @@
to the content model for <xmlelement>section</xmlelement></li>
</ul>
<ol>
<li>First, the DITA architect creates the element domain module
(<filepath>sectionDescDomain.rng</filepath>):<codeblock>&lt;?xml version="1.0" encoding="UTF-8"?>
<li>First, the DITA architect creates the element domain
module: <filepath>sectionDescDomain.rng</filepath>. It contains
the following
code:<codeblock>&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;?xml-model href="urn:oasis:names:tc:dita:rng:vocabularyModuleDesc.rng"
schematypens="http://relaxng.org/ns/structure/1.0"?>
&lt;grammar xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
Expand Down
26 changes: 15 additions & 11 deletions specification/archSpec/base/rules-document-type-shells.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,10 @@
this rule are the following:<ul>
<li>The ditabase document-type shell directly defines the
<xmlelement>dita</xmlelement> element.</li>
<li>RNG-based document-type shells directly specify values for the
<xmlatt>specializations</xmlatt> attribute; these values reflect the details of
the attribute domains that are integrated by the document-type shell.</li>
<li>RNG-based document-type shells directly specify values
for the <xmlatt>specializations</xmlatt> attribute. These
values reflect the details of the attribute domains that
are integrated by the document-type shell.</li>
</ul></p>
</dd>
</dlentry>
Expand All @@ -45,14 +46,17 @@
<dd>
<p>Document-type shells that are not provided by OASIS <term outputclass="RFC-2119"
>MUST</term> have a unique public identifier, if public identifiers are used.</p>
<p>Document-type shells that are not provided by OASIS <term outputclass="RFC-2119">MUST
NOT</term> indicate OASIS as the owner; the public identifier or URN for such
document-type shells <term outputclass="RFC-2119">SHOULD</term> reflect the owner or
creator of the document-type shell. </p>
<p otherprops="examples">For example, if <filepath>example.com</filepath> creates a copy
of the document-type shell for topic, an appropriate public identifier would be
"-//EXAMPLE//DTD DITA Topic//EN", where "EXAMPLE" is the owner identifier component of
the public identifier. An appropriate URN would be
<p>Document-type shells that are not provided by OASIS <term
outputclass="RFC-2119">MUST NOT</term> indicate OASIS as the
owner. The public identifier or URN for such document-type
shells <term outputclass="RFC-2119">SHOULD</term> reflect the
owner or creator of the document-type shell. </p>
<p otherprops="examples">For example, if
<filepath>example.com</filepath> creates a copy of the
document-type shell for topic, an appropriate public identifier
would be "-//EXAMPLE//DTD DITA Topic//EN", where "EXAMPLE" is
the component of the public identifier that identifies the
owner. An appropriate URN would be
<keyword>urn:example.com:names:dita:rng:topic.rng</keyword>.</p>
</dd>
</dlentry>
Expand Down
9 changes: 4 additions & 5 deletions specification/archSpec/base/specialization-including-non-dita-content.dita
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,11 +58,10 @@
declaring the parameter entity before the reference to the
<filepath>svgDomain.ent</filepath> file. Other foreign domains <ph
>might</ph> need similar entities when required by the new vocabulary.</p>
<draft-comment author="robander">The following statement needs to be updated to refer to the
eventual final name of the DITA-techcomm package.</draft-comment>
<p>For more information, see the <filepath>svgDomain.mod</filepath> file that is shipped with
the OASIS DITA distributions. For an example of including the SVG domain in a document-type
shell, see <filepath>task.dtd</filepath>.</p>
<p>For more information, see the <filepath>svgDomain.mod</filepath>
file that is shipped with the <ph rev="2.0">DITA Technical Content
edition</ph>. For an example of including the SVG domain in a
document-type shell, see <filepath>task.dtd</filepath>.</p>
</example>
<!--<example rev="DITA1.3 proposal-13112" id="example-rng"><title>Example of specializing foreign content using RELAX NG</title> The code sample below illustrates how to create a domain declaration for the RELAX NG <xmlelement>grammar</xmlelement> element and integrate it into a document-type shell. Domain modules that include foreign grammars should use the <xmlelement>externalRef</xmlelement> element to refer to the foreign grammar when the grammar specifies a <xmlelement>start</xmlelement> element. When using the <xmlelement>externalRef</xmlelement> element, it is possible to safely include foreign vocabularies that are not in a namespace, because the externally-referenced grammar patterns are not merged with those of the referencing grammar. <p>The following domain specialization specializes <xmlelement>foreign</xmlelement> in order to contain RELAX NG <xmlelement>grammar</xmlelement> elements, for example, to document document types by rendering the grammar markup as diagrams. </p> <codeblock>&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;?xml-model href="urn:oasis:names:tc:dita:rng:vocabularyModuleDesc.rng"
Expand Down

0 comments on commit 8162ee9

Please sign in to comment.