DITA 1.3 proposed feature 13044

Allow elements within %basic.ph; within <data>.

Date and version information

  • Date completed: 1 Oct 2012
  • Champion: Eliot Kimber
  • Email: None

Original requirement

There's no reason to limit the content model of data to the degree it is in 1.2 as it makes an arbitrary and limiting decision about what is and isn't useful as metadata. In particular, data currently allows ph, keyword, and term, but not cite, xref, or q. For publishing applications there is a general requirement to be able to capture as metadata arbitrary content that could also occur within a topic body. Since, for example, <cite> is not a specialization of <ph>, <cite> is not allowed within data, which is unnecessarily limiting. Note also that <ph> allows pretty much all inline elements, so the current constraint is rather toothless anyway.

Use cases

Use cases include:
  • Metadata that includes more comprehensive information, such as content constituting a author biography or additional bibliographic information about a publication or topic.
  • Descriptive metadata that includes additional markup not currently available.

Benefits

This change ensures that the content model of <data> is not over constrained, allowing any kind of phrase within <data>.

Costs

  • Maintainers of the DTDs and XSDs:
    • Update the content model for <data> to use %basic.ph;.
  • Editors of the DITA specification:
    • How many new topics will be required?
      • No new topics
    • How many existing topics will need to be edited?
      • The generated content model description for <data> will reflect the additional elements allowed by %basic.ph;.
    • Will the feature require substantial changes to the information architecture of the DITA specification?
      • The feature does not represent a substantial change to the architecture.
  • Vendors of tools:
    • XML editors will need to allow editing of the updated content model.
  • DITA community-at-large. Will this feature add to the perception that DITA is becoming too complex?
    • This change should not add to the perception of complexity for authors.

Technical requirements

Modify the declarations for <data> (and specializations of <data>) as follows:
DTDs
Modify commonElements.mod by changing the declaration of %data.cnt; to:
<!ENTITY % data.cnt 
  "#PCDATA |
   %basic.ph; |
   %image; |
   %object; |
   %title;
  "
>
XSDs
Modify commonElementMod.xsd by changing the declaration of the "data.cnt" group to:
	<!--<!ENTITY % data.cnt             "%basic.ph;|%image;|%object;|%title;">-->
	<xs:group name="data.cnt">
		<xs:choice>
			<xs:group ref="basc.ph"/>
			<xs:group ref="image"/>
			<xs:group ref="object"/>
			<xs:group ref="title"/>
		</xs:choice>
	</xs:group>
RNC
Modify commonElements.mod.rnc to set the named pattern "data.cnt" to:
text | basic.ph | image | object  | title

Examples

A <data> element within <author>, acting as an author biography:

<topic id="topic_t4p_nr2_th">
  <title>Test of extended content model for &lt;data></title>
  <prolog>
    <author><data
      name="author-bio">Ann Author is the author of many works, including
      <cite>A Book You May Have Read</cite>. Learn more about Ms. Author at <xref
      href="http://example.com/authors/ann-author"
      format="html"
      scope="external">http://example.com/authors/ann-author</xref>.</data></author>
  </prolog>
  <body>
    <p/>
  </body>
</topic>