nmEdit - website

Public Site	Documentation

Documenting a DTD

This page describes the forrest website extension for documenting a DTD. The document type extends the 'document-v11.dtd' DTD with the element 'dtd' that can be used inside the 'body'- or 'section'-tags of a forrest-site.

Naming convention

To link the XSL-stylesheet with the XML-document its filename must match the pattern:

*.dtd-ref.xml

Linking declared elements

Each element of the DTD-reference has an anchor that is composed by the string:

"elem." + <element-name>

For example to open the declaration of the 'attribute'-tag use the link.

<link href="#elem.attribute">attribute</link>

Typical invokation

Use the following document type for a forrest site that wants to use the DTD-reference element set.

<!DOCTYPE document PUBLIC "-//nmedit//DTD DTDdocumentation V1.0//EN"
      "DTDdocumentation-v10.dtd">

The DTD extends Forrest's document-v11.dtd with the additional elements.

DTDdocumentation v1.0 DTD - Reference

Top-level element(s)

dtd

Element declarations

attribute

Defines the attribute of an element. Note that only one of the attributes 'required', 'implied', 'implicit-value', 'default-value' can be used. implied='true' means that the value of the attribute is implied. A given 'implicit-value'-attribute means that the value of the attribute is implied, the value will we visible in the reference. A given 'default-value'-attribute means that the attribute has a default value, this value will be visible in the reference. required='true' means that this attribute is required, but has neither an implied- nor a default-value.

Content model:

( attribute-type, dtd-hint ? )

Used inside

entity

Attributes:

name	type: CDATA	required attribute

required	possible values: true, false	implied attribute implicit value: 'false'

implied	possible values: true, false	implied attribute

default-value	type: CDATA	implied attribute

implicit-value	type: CDATA	implied attribute

attribute-type

Defines the type of an attribute. The type must by either given by a text-representation or a list of 'option'-tags each of them describing a possible value.

Content model:

( #PCDATA | option ) *

Used inside

attribute

Attributes:

- none -

contains

Use this to define which elements can be used inside the tag. The element supports mixed text and 'element'-tags. Conditions must be represented as text. If the 'contains'-tag is missing, the 'Content model:'-output will be the string 'EMPTY' (without quotes). Example content: ( #PCDATA | <element entity-name="element" /> ) *

Content model:

( #PCDATA | element ) *

Used inside

entity

Attributes:

- none -

dtd (top-level element)

This element can be used inside the 'body'- and the 'section'-tag of a forrest-site.

Content model:

entity *

Used inside

- none -

Attributes:

title	type: CDATA	required attribute
Used to generate the reference section-title. The reference will be named "$title - Reference", where $title represents the value of this attribute.
show-top-level-elements	possible values: true, false	default value: 'true'
If true, the "Top-level element(s)"-List will be shown. All top-level elements are listed alphabetically.
show-element-list	possible values: true, false	default value: 'true'
If true, the "List of elements"-List will be shown. All defined elements are listed alphabetically.

dtd-hint

Text containing some description. Notice: The entity %content.mix; is defined in document-v11.mod. It can be found in the forrest-directory forrest/main/webapp/resources/schema/dtd/.

Content model:

( %content.mix; ) *

Used inside

attribute, entity

Attributes:

- none -

element

Content model:

EMPTY

Used inside

contains

Attributes:

entity-name	type: CDATA	required attribute
Name of a tag. If the element is defined it will automatically be linked. The 'element'-tag should be used for undefined tags, too.

entity

Content model:

( dtd-hint ? , contains ? , attribute * )

Used inside

dtd

Attributes:

name	type: CDATA	required attribute
The name of a xml-tag.
root	possible values: true, false
Set this to true if a tag is a top-level element.

option

A possible value for an attribute.

Content model:

EMPTY

Used inside

attribute-type

Attributes:

value	type: CDATA	required attribute

Website-configuration

List of required or modified files.

src/documentation/classes/CatalogManager.properties - setup accordingly that cocoon finds catalog.xcat
src/documentation/resources/schema/dtd/DTDdocumentation-v10.dtd - the document type
src/documentation/resources/schema/catalog.xcat - links the XML-document with the local DTD
src/documentation/resources/stylesheets/dtdRef2document.xsl - XSL stylesheet that transforms DTD-reference elements to forrest-site elements
src/documentation/sitemap.xmap - links the XML-document with the local DTD (see Naming convention)
src/documentation/skinconf.xml - extra-css contains additional css used to improve the DTD reference view