Scope

Although the DTD has come to be called "XMLspec," it is intended for W3C working drafts, notes, recommendations, and all other document types that fall under the category of "technical reports."

The DTD is responsible for covering three main aspects of XML technical reports:

• Basic W3C technical report structure and content, including paragraphs, lists, cross-references, and so on

• Markup structures specific to the XML-related family of W3C technical reports, such as EBNF productions, validity constraints, and element and attribute names

• Proper headers and metadata for W3C technical reports

Focus

The DTD is intended to support the following functions, in order of priority:

1. Production of technical reports

   First and foremost, the DTD should facilitate hassle-free production and publication. Many of the documents in the scope are made available in several output forms, including source XML and derived HTML, RTF, and PostScript. It is important to produce these outputs in a form that meets W3C requirements, and produce them quickly in order to speed the W3C publication release process. Also, it may be useful to extract different parts of the document content (for example, just the productions) for distribution.

   In recent revisions, the markup has evolved to capture an increasing amount of technical detail, for example, the IDL structures contributed from the DOM work. This is motivated entirely by considerations of successful publication from a single source to multiple outputs, rather than by abstract concerns about source purity; however, it makes an effective illustration of the power of XML.

2. Creation and modification of content

   The DTD should provide an intuitive, efficient interface to the creation process. This means that the DTD shouldn't be overly large or complicated, but that it should provide support for information structures using the jargon, and to the depth, that authors will tend to understand the information.

3. Review of content

   To a lesser degree, the DTD should support the informal workflow that goes on when co-editors pass around drafts for review. To this end, the DTD should provide markup for editor "communication" inside the document source.

4. Proof of concept of XML publishing

   Finally, where possible, this DTD and its associated applications should use good XML practice and conforming XML tools, because many will look to this application as an example.

   This DTD's first few revisions existed before there were any XML parsers, and indeed before XML 1.0 itself was standardized. In today's world, XML's future has been assured and XML tools are plentiful. However, while a "proof of concept" is no longer needed, XMLspec does in fact continue to serve as an example of best practices.

Presentation Independence

The DTD should avoid presentational markup where possible. Sometimes this principle comes into conflict with the production focus, but in general, presentation independence helps serve the goal of production of multiple outputs. In any case, egregious examples of formatting-specific markup should be avoided.

Versioning and Updates

This DTD was previously given a formal public identifier in the following pattern:

-//W3C//DTD XML Specification::yyyymmdd//EN

For easier identification, the DTD now uses a formal public identifier in the following pattern:

-//W3C//DTD XML Specification Version n.n//EN

The current version is identified as:

-//W3C//DTD Specification Version 2.1//EN

The policy, beginning with Version 2.0, is as follows.

Minor revisions (revising n.m to produce n.m+1, for example, going from V2.0 to V2.1 or from V2.1 to V2.2) can add to the markup model, but cannot change it in a backwards-incompatible way. For example, a new kind of list element could be added, but it would not be acceptable for the existing itemized-list model to start requiring two list items inside it instead of only one. Thus, any document conforming to an old version would also conform to the new minor revision.

Major revisions (revising n.m to produce (n+1).0, for example, going from V2.1 to V3.0) can both add to the markup model and make backwards-incompatible changes. Ideally these will be accompanied by XSLT transformation specifications that help legacy documents to conform to the new version.

Always review the change history in any new version of the DTD carefully before deploying it.

Currently, DTD changes are at the discretion of the maintainer and the heaviest users of the DTD within the W3C. A more formal procedure may be put in place later.

This DTD does not yet have an official schema. If you want to refer to the XMLspec vocabulary for namespace management purposes, use the following URI to identify it:

http://www.w3.org/XML/1998/06/xmlspec-v21.dtd

Note that this identifying URI may change in the future.

Naming and Coding Conventions

The element names from the original DTD on which XMLspec was based were mostly kept; changes were made in a few cases only to rationalize the naming scheme.

Hyphens are typically avoided, except in the "w3c-" prefix.

Whitespace and tabs are used relatively sparingly to enhance readability; excessive whitespace is avoided in the interest of a compact and "unthreatening" DTD.

Parameter Entity Typology

Parameter entities are used in several different capacities in the DTD. To indicate their different roles, unique suffixes are used as follows:

descrip.att

The name, declared value, and default value specifications for a set of one or more attributes.

Some descriptions may have a sub-suffix, such as -req, which means that the attribute (or one of the attributes) in question is required.

descrip.class

A set of related elements that are typically available as options in certain content model "free mixtures" (repeatable-OR groups). These entities are referenced from within descrip.mix entity declarations and content models.

If you add a new standalone or phrase-level element, make sure that you add it to the appropriate class entity, or create a new class for it. If you create a new class, incorporate references to that class in the appropriate mixture entity declarations.

descrip.mix

A set of elements that are available to writers in certain contexts as a "free mixture" (repeatable-OR group). These entities are referenced from within content models.

descrip.pcd.mix

A set of #PCDATA and elements that are available to writers in certain contexts as a "free mixture" (repeatable-OR group). These entities are referenced from within content models. The presence of #PCDATA makes these "mixed" content models, which means that document creators can type regular text here and that downstream applications will need to take account of whitespace found here.

local.descrip.att

An empty placeholder that is available to be used in extending an attribute list.

local.descrip.class

An empty placeholder that is available to be used in extending an element class.

descrip.mdl

A content model fragment (other than a "free mixture") that is common or customizable.

The goal in naming the entities was to be consistent and brief, without losing readability. The keyword indicating the entity type always appears last because the location of an entity reference will already give a clue as to the entity type, and so this is not the information that needs to be seen first when the DTD is read. This naming scheme also allows for easier searching.

XML and XLink Usage

The DTD conforms to XML V1.0 and makes use of the XML and XLink namespaces. Because DTDs and namespaces don't mix well, the xlink namespace prefix has been hardwired. (The xml prefix is hardwired into the XML specification itself.)

While XLink is used for all URI-style linking, the IDREF addressing mechanism is still used heavily for internal links. As support for the XPointer construct xpointer(id("xxx")) grows and that specification stabilizes, we will consider moving to this style of addressing for internal linking.

This version of the DTD does not yet conform fully to the latest working draft of the XLink specification, because this would have required backwards-incompatible changes. When the XLink specification reaches Recommendation status and if such backwards-incompatible changes are still required, a new major version of this DTD will be published that will require changes to legacy documents.

Parameterization

The DTD is beginning to be used more widely by W3C contributors (as well as by authors of non-W3C specifications). While this DTD was designed with the needs of XML technical reports firmly in mind, quite a lot of the markup design would be useful for technical reports produced by others in the W3C. Therefore, the DTD has been parameterized to allow for:

• Modification of certain content models that are likely to be subject to personal and Working Group preference

• Addition of new elements at the "standalone" and "phrase" levels

• Some limited removal of existing elements at the "standalone" and "phrase" levels

• Addition of new attributes to an attribute list

If it is found that the DTD can be made more widely useful solely by heavier parameterization, it would probably be worth it to add the new parameters.

Heed the following advice if you plan to develop a variant of the DTD:

• Plan and document both the substance of your changes and the reasons for them.

• Build variants only by redefining the original parameter entities, if possible; don't edit any of the original DTD files.

• If you plan to interchange your files with other DTD users, favor markup changes that place tighter validation restrictions on documents (subsets), rather than changes that would allow instances that no longer conform to the standard DTD (extensions).

• Avoid confusion by using a different formal public identifier for your DTD variant if you have changed any element or attribute markup characteristics. You may want to indicate the derivation with an identifier that uses the following pattern:

  -//owner-ID//DTD XML Specification Version n.n-Based your-descrip-and-version//lang
  

  
  
  

2000 February 15

Added proto element, its arg subelement, and the %argtypes; entity.

Added function, var, sub, sup, phrase, el, att, attval elements.

Expanded emph to %p.pcd.mix;.

Allowed status and abstract to appear in the opposite order.

Updated XLink usage to the latest WD, except for href and source.

Removed the xml:attributes attribute from graphic.

Added %local.graphic.att; to graphic.

Added common diff attribute.

Added div5 element.

Broadened content models of publoc, prevlocs, and latestloc.

Added head, source, resolution, and status attribute to issue.

Added cr, issues, and dispcmts to w3c-doctype attribute on spec.

Added example element.

1999 July 2

Added %loc.class; to all PCD mixes that didn't already have it.

Removed unused %loc.pcd.mix;.

Made version in spec header optional.

Added three new attributes to spec.

Broadened content of edtext.

Added optional copyright element to header.

Reorganized XLink-related parameter entities; added xmlns:xlink.

Changed edtext content from #PCDATA to %p.pcd.mix;.

Added show/actuate atts and default values to all href elements.

Changed versioning scheme from 8-digit dates to version numbers.

Added w3c-doctype, other-doctype, status atts to spec element.

Added prodrecap element inside scrap.

Added headstyle attribute to scrap.

1998 December 3

Fixed character entities with respect to escaping of ampersands.

Added many more explanatory comments.

1998 November 30

Added new unused elements to support DocBook translation.

Updated maler phone numbers.

1998 August 22

Fixed %illus.class; to mention table instead of htable.

Added definitions to %illus.class; for DOM model.

Added DOM definitions element and its substructure.

Updated XLink usage in %href.att; to use xlink:form and #IMPLIED.

Added clarifying comments to HREF-using elements.

1998 May 21

Declared generic constraint and constraintnote elements.

Added constraintnote to %note.class;.

Added constraint to %eg.pcd.mix; and prod content model.

1998 May 14

Fixed mdash, ldquo, and rdquo character entities.

Switched to the full HTML 4.0 table model.

Removed htable/htbody elements and replaced them with table/tbody.

Added issue element to %note.class; and declared it.

Allowed prevlocs and latestloc in either order.

Added key-term, htable, htbody, and statusp as unused elements.

Removed real statusp element in favor of plain p.

1998 March 23

Cleaned up some comments and removed some others.

Added xml:space semi-common attribute to eg and bnf elements.

Added show and embed attributes on all the uses of href.

Added %common.att; to all HTML table elements.

Added a real URI to the "typical invocation" comment.

1998 March 10

Merged the character entity and table modules into the main file.

Added ldquo and rdquo entities.

Added common attributes to prodgroup.

Made the email element in header optional.

Removed reference to the SGML Open table model.

Added ednote element.

Added quote element.

Updated XLink usage to reflect 3 March 1998 WD.

Added "local" entities to the class entities for customization.

Parameterized several content models to allow for customization.

1997 December 29

Moved #PCDATA occurrences to come before GIs in content models.

Removed use of the SGML Open table module.

Added xspecref element.

Ensured that all FPIs contain 4-digit year.

(Modified the character entity module.)

1997 November 28

Added support for prodgroup and its attributes.

Added support for HTML tables.

Added loc and bibref to content of com.

Added loc to general p content models.

Allowed p as alternative to statusp in status.

Added non-null system IDs to external parameter entity declarations.

(Modified the SGML Open table module to make it XML-compliant.)

(Modified the character entity module.)

1997 October 16

Added SGML Open Exchange tables.

1997 October 14

Fixed "unused" div content model to move nested div to mixture.

1997 September 30

Added character entity module and added new entities.

Removed p from appearing directly in self; created %p.mix;.

Added inform-div (non-normative division) element.

Fixed xtermref comment to mention HREF, not ref.

Extended orglist model to allow optional affiliation.

Modified author to make affiliation optional.

Added %speclist.class; and %note.class; to %obj.mix; and %p.mix;.

Added %note.class; and %illus.class; to %termdef.pcd.mix;.

Added unused HTML elements.

Put empty system ID next to public ID in entity declarations.

1997 September 14

Changed main attribute of xtermref from def to href.

Added termdef.class to label contents.

1997 September 12

Allowed term element in general text.

Changed bibref to EMPTY.

Added ref.class to termdef.pcd.mix.

1997 September 10

Updated FPI.

Removed namekey element and put key attribute on name element.

Made statusp element and supporting entities.

Added slist element with sitem+ content.

Required head on scrap and added new bnf subelement.

Added an xnt element and allowed it and nt in regular text and rhs.

Removed the ntref element.

Added back the com element to the content of rhs.

Added a key attribute to bibl.

Removed the ident element.

Added a term element to be used inside termdef.

Added an xtermref element parallel to termref.

Beefed up DTD comments.

1997 August 18

Did a major revision.

id Attribute

role Attribute

diff Attribute

Key Attribute

Definition Attribute

Reference Attribute

XLink-Related Attributes

Description

The spec element contains, in order, a header; an optional front; a body; and an optional back.

The header provides metadata about the specification document (see the section called Specification Header (header) for more information). The front matter is for prefatory material. The body matter is primary content. The back matter is supplementary content. All three are organized into divisions.

The elements front and body contain one or more div1 elements. The main element for structuring content is div1, the equivalent of a preface, chapter, or appendix. It can be subdivided to four additional levels, down to div5. At each level, the division contains a head (title), optionally followed by a mixture of standalone elements (see Table 7-1), optionally followed by the next level of subdivision (except in the case of div4).

The back element contains div1 and/or inform-div1 (non-normative or informational division) elements. If both are present, the normative divisions must appear first. The back element cannot be empty.

Attributes

In addition to the common attributes, the spec element has three unique attributes:

w3c-doctype

Indicates the type of document, so that the appropriate stylesheet or workflow routing can be applied. It can optionally have a value of "rec" (Recommendation), "pr" (Proposed Recommendation), "cr" (Candidate Recommendation), "wd" (Working Draft), "note" (Note), "issues" (Issues List), "dispcmts" (Disposition of Comments), or "other". It should not generate any text (such as the "REC-" or "NOTE-" prefix on the W3C designation content). It has no default. If this value is "other", other-doctype should be filled in.

other-doctype

If w3c-doctype is "other", this value should be filled in with a keyword chosen or negotiated by the document authors and rendering application developers. It has no default.

status

Indicates the stage of review of the document. It has no default.

Processing Expectations

Divisions are expected to be numbered, and a report of the numbers and heads should normally be made into a Table of Contents before any front content.

The w3c-doctype attribute should not be used to generate any text (such as the "REC-" or "NOTE-" prefix on the W3C designation content). The value of the status attribute might affect the stylesheet's treatment of editorial notes (for example, whether to output them).

Rationale

Originally, divisions went down to four levels total (to div4), but the MathML specification required one more level.

Elements serving the same function were merged to make a cleaner design.

The original text element, which wrapped all the non-header content, was removed because it didn't add anything to the structure, and its meaning ("a text") doesn't seem very relevant to W3C specifications. The original header contents have been consolidated under the header element, which meant that the original front element was no longer required because its titlepage contents have been done away with. The original backtabs element was removed, as agreed.

The original type attributes on the division elements were removed, as agreed.

Here is where it becomes apparent that the original "special lists" were removed from their special place in the division content models.

Description

The header contains an ordered series of metadata elements:

title

The title of the technical report, for example, "Extensible Cheese Language (ECL)".

This was previously the wd-title element. It contains character data (see Table 7-2).

subtitle (optional)

The subtitle of the technical report, if it has one. It contains character data (see Table 7-2).

version (optional)

The version of the technical report, for example, "Version 4.0". It contains character data (see Table 7-2).

w3c-designation

The code by which the technical report is known in URIs and such, for example, "WD-xcl-991231".

This was previously the wd-num element. It contains character data (see Table 7-2).

w3c-doctype

The full name for the type of W3C technical report, for example, "W3C Working Draft" or "W3C Note". It contains character data (see Table 7-2).

pubdate

The day (optionally), month, and year of publication of the document, separated out into day, month, and year elements. This should be the date on which the final text has been handed over to the W3C for official publication. Note that in internal interim drafts, you may want to provide a notice explaining the situation. The day, month, and year elements contain character data (see Table 7-2).

This was previously the wd-date element.

notice (optional and repeatable)

A generic notice to readers, for example, "This draft is for public discussion." You can add as many notices as are required.

The notice element contains a mixture of standalone elements (see Table 7-1).

publoc

The one or more Web resources corresponding to the different published forms (for example, XML, HTML, and PostScript) of this technical report. It contains character data and phrase-level elements (see Table 7-2), typically just one or more loc elements.

This was previously the thisver element.

prevlocs (optional; can appear after latestloc)

The one or more Web resources corresponding to the previously published versions of this technical report. It contains character data and phrase-level elements (see Table 7-2), typically just one or more loc elements. If there are no previous versions, the prevlocs element itself should not be provided.

This was previously the previousver element.

latestloc (optional; can appear before prevlocs)

The one or more Web resources corresponding to the latest version of this technical report. It contains character data and phrase-level elements (see Table 7-2), typically just one or more loc elements.

This was previously the latestver element.

authlist

The list of editors contributing to the document. It contains one or more author elements, each of which contains a name (has an optional key attribute), followed by an optional affiliation, followed by an optional email. The last requires an href attribute. The name, affiliation, and email elements contain character data (see Table 7-2).

This was previously the authors element. The affiliation element is optional because some editors may not be affiliated with any organization. The email element is optional to help avoid spamming of the editors.

copyright (optional)

A copyright notice. W3C now requires that specifications have copyright notices.

The copyright element contains a mixture of standalone elements (see Table 7-1). Note that its content should be "cooked," that is, the author should not rely on a rendering process to produce a copyright symbol, punctuation, or other style elements that might make up a proper copyright notice. These should be provided directly in the XML source.

abstract (can appear after status)

A brief description of the document contents. It contains a mixture of zero or more standalone elements (see Table 7-1). Putting the abstract after the status statement is deprecated.

status (can appear before abstract)

A description of the status of the document, following W3C rules. This element contains a normal mixture of standalone elements (see Table 7-1). Putting the status statement before the abstract is deprecated.

pubstmt (optional)

A brief bibliographic statement about this publication according to Text Encoding Initiative rules, for example, "Burlington, Seekonk, et al.: World-Wide Web Consortium, XML Working Group, 1999." It contains a mixture of standalone elements (see Table 7-1), so the example text would have to be inside a p.

sourcedesc (optional)

A brief statement about the original source for this document, for example, "Created in electronic form." It contains a mixture of standalone elements (see Table 7-1), so the example text would have to be inside a p.

langusage

A catalog of languages used in the document. It contains one or more language elements, each of which might have an id attribute on it so that it can be referenced from prod elements. The language element contains character data (see Table 7-2).

revisiondesc

A catalog of changes made to the document, in more or less rigorous form. It contains a mixture of zero or many standalone elements (see Table 7-1); typically, an slist element would be used, with its sitem elements corresponding to individual change descriptions and dates.

Processing Expectations

The various parts of the header are used in creating a title page that follows W3C rules. The content of some elements is used twice or more, while the content of other elements is suppressed from display. Some of the elements (such as publoc) should cause heading text to be generated.

The element name has, in addition to the common attributes, a key attribute, which optionally provides a sort-key string for use in collecting and outputting names mentioned in a document.

The element email has common attributes and a required href attribute.

Rationale

The content of publoc, prevlocs, and latestloc was broadened so that the various published forms and auxiliary resources of a specification can be mentioned. For example, the XML Schema specifications refer not only to the XML source and the HTML published form, but also to the special stylesheet used to produce the output and normative DTDs and schemas associated with the specification.

W3C publication guidelines require the abstract to come before the status statement; it is allowed after the status statement only for backwards compatibility with V2.0 of the DTD.

The content model of header has been parameterized so that the metadata can be customized, subsetted, and extended as necessary.

The metadata elements that were in the original DTD were cherry-picked, based on the data found in a survey of typical W3C technical report cover and title pages. Where an element is optional, generally content is required inside it to ensure that it's not abused or accidentally left empty. The version element was made optional for Version 2.0 of the DTD because versions are not required on Working Drafts.

The subtitle element was added unilaterally because it seemed like a generally good idea.

The w3c-doctype element should perhaps more properly be an attribute with a small set of enumerated values, if the DTD gets wider use and the types are quantified. So far, the element formulation has stood us in good stead because we began to publish "notes" in addition to "working drafts" and did not need to make any stylesheet changes.

The pubdate contains, in order, day (optional), month, and year elements so that different forms of the date could be published in different locations: "31 December 1999" on the title page and "December 1999" on the cover, for example. The content model of pubdate has been parameterized so that a different form of date information can be supplied if necessary.

The status element originally required the statusp variant of the p element because Dan indicated that HTML-style links should be allowed only where they're appropriate. Because inclusions are not allowed in XML and we wanted this DTD to be XML compliant, the only way to allow status to contain loc was to give it a special subelement where loc is allowed. However, we've since found that it's very difficult to excise all need for HTML-style links in the body of the spec, so we ended up extending p to allow it to contain loc and, in preparation for losing statusp entirely, allowed p inside status. Now, statusp is obsolete and has been removed from the DTD.

It was decided to make the copyright element contain "cooked" content for simplicity and so that it is most likely that various renderings of the document will contain the correct copyright notice, whole and uncut. It is expected that if the XML source itself needs to have explicit copyright protection, an XML comment (in each file making up the document) is the right tool for the job.

Description

The p element is a general-purpose paragraph which can contain regular character data, phrase-level elements, and some nested standalone elements (see Chapter 7).

Attributes

The p element has the common attributes (see the section called Attributes Appearing on Every Element in Chapter 2):

Processing Expectations

This element should be presented as vertically set off from other surrounding elements, and its inline text contents should be wrapped as appropriate to fit in the line size available.

Rationale

Originally, only p was made available, and it contained loc . Dan requested that the loc element not be made generally available, because properly these should only occur in the status section of a technical report, and statusp was therefore created because SGML exceptions, which would have allowed for a clean implemention of the restriction, aren't available in XML-compliant DTDs. However, later all the editors came to the conclusion that it was too restrictive not to allow loc anywhere else, and we added loc to regular paragraphs and p to the status section.

The statusp element was a special version of a paragraph that was created to allow loc (see the section called URI Reference (loc) in Chapter 5) inside it. A statusp contained a mixture of one or more %statusobj.mix; and/or %statusp.pcd.mix;. However, this element has finally been removed for simplicity, since p can do the job itself.

Unordered List (ulist) and Ordered List (olist)

Simple List (slist)

Glossary List (glist)

Bibliography List (blist)

Organization List (orglist)

Regular Note (note)

Issue (issue)

Constraint Notes (wfcnote, vcnote, and constraintnote)

Code Example (eg)

Example (example)

Graphic (graphic)

Code Scrap (scrap)

HTML-Style Table (table)

IDL Definitions (definitions)

The definitions element structure was contributed by the W3C DOM Working Group. No detailed descriptions, processing expectations, or design rationales have been supplied. This section offers only a structural description.

Following are the IDL element classes. Every class entity has the naming scheme %name.class;, and has an empty %local.name.class; entity in it for customization purposes.

• Descriptive elements (%idl-desc.class;)

  Paragraph (p)

  Note (note)

• Type definition elements (%idl-tdef.class;)

  typedef

  constant

  exception

  reference

  group

• Module/interface elements (%idl-mod.class;)

  module

  interface

• Struct elements (%idl-struct.class;)

  struct

  enum

  sequence

  union

  typename

• Method/attribute elements (%idl-meth.class;)

  method

  attribute

Table 4-1 shows the element mixtures built up out of the IDL-related elements.

The model for definitions is as follows.

The models for group, interface, module, reference, constant, and exception are as follows.

The model for typedef and its contents is as follows.

The models for method and attribute are as follows.

Function Prototype (proto)

Description

The footnote element serves as both a marker for the location of the footnote callout and a container for the footnote content. It contains one or more elements in the %obj.mix; mixture.

Attributes

The footnote element has the common attributes (see the section called Attributes Appearing on Every Element in Chapter 2):

Processing Expectations

For print, the location of the footnote element should be given a generated superscripted number or symbol that serves as a callout, and the footnote content should be presented along with the callout at the bottom of the page. In online presentation, the footnote could be presented as a pop-up dialog box keyed to an icon placed at the location of the footnote element.

Defined Term (term)

Term Definition (termdef)

Emphasized Text (emph)

Phrase (phrase)