document-type-declaration

rule

Syntax
document-type-declaration condition?
   local-declaration*
   action*


Purpose

document-type-declaration is a rule that fires on the document type declaration (DTD), if any, of a parsed input. As a region rule, document-type-declaration fires on the whole of the DTD and must process either %c or #content. Both in the rule guard and in the body of the rule, the built-in shelf #doctype can be used to access the DTD's name. In the body of the rule, #doctype can be assigned to change the actual document type of the input being processed.

Modifying document type

The following SGML input defines element a as the document type. 

  <!doctype a [
  <!element a - - (#pcdata)>
  <!element b o o (a)>
  <!element c - - (#pcdata)>
  ]>
  <a>Hello, World!</a>

If we wanted to change this to b to, for instance, perform additional processing, we could use a simple document-type-declaration rule, as in the program below: 

  process
     do sgml-parse document scan #main-input
        output "%c"
     done
  
  document-type-declaration
     set #doctype to "b"
     suppress
  
  element #implied
     output "<%q>%c</%q>"

Execution of this program would yield the output 

  <B><A>Hello, World!</A></B>

When changing the document type in this fashion, the transformation must result in a markup stream that conforms to the validation rules in effect for the input. For instance, in the example SGML DTD above, element b was declared as being omissible and its content model allowed for one instance of element a. It could thus serve as a parent element for the element a that appeared explicitly in the input, even though it itself does not appear in the input. If, on the other hand, we had attempted to change the document type to c, three validation errors would have been triggered:

  • the start tag for element c is not omissible, and therefore must be physically present in the document instance,
  • element c cannot contain element a, and
  • the end tag for element c is not omissible, and therefore must be physically present in the document instance.

Similarly, if we had attempted to change the document type to d, a run-time error would have been triggered, since there is no such element in the DTD.

Relation to other rules

The document-type-declaration rule completes its execution before any prolog-end rule is fired.

The document-type-declaration rule begins its execution before any external-text-entity #dtd rule is fired, but completes is execution after any external-text-entity #dtd has completed.

A document-type-declaration rule cannot appear in the same module as a dtd-start rule, nor as a dtd-end rule.

Related Syntax
Related Concepts