[tocml-list] TOCML 0.1 Draft Specification
Curtis Duhn
curtis@duhn.com
Sun Jan 27 23:54:00 2002
Here's a draft spec for TOCML 0.1. It can be found on the web site at
http://www.duhn.com/tocml/specs/tocml-spec_0.1.txt
Table Of Contents Markup Language
TOCML Version 0.1 Specification
Curtis Duhn - 1/27/2001
1. STATUS
This is a pre 1.0 draft of the TOCML specification. This is not a
standard and should not be used as such. Future revisions may
radically change the specification in incompatible ways.
This document is a product of the TOCML project, at
http://www.duhn.com/tocml/. Development of this document takes place
on tocml-list, which can be found at
http://two.pairlist.net/mailman/listinfo/tocml-list.
If you have feedback on this document, please join tocml-list and
post your comments, or send them to the author at curtis@duhn.com.
2. VERSIONS
The version number of the TOCML specification is in the form "x.y",
where x is the major version number, and y is the minor version number.
The semantics of these numbers are as follows:
The minor version number will be incremented for any change that is
backward compatible with all previous TOCML versions with the same
major version number. This guarantees that any valid TOCML x.y
document is also a valid TOCML x.y+1 document.
The major version number will be incremented whenever TOCML is changed
in a way that is not backward compatible with the previous TOCML
version. When the major version number is incremented, the minor
version number will be reset to 0.
These backward compatibility rules will not be enforced until version
1.0. We reserve the right to make incompatible, and even radical
changes to TOCML versions 0.x while we settle on the baseline spec.
Once version 1.0 has been published, backward compatibility rules will
take effect.
3. THE TOCML DOCUMENT:
A TOCML document is an XML document with a top-level element of <tocml>,
which is described below.
3.1 <tocml> Element
The <tocml> element is required as the top-level element of the TOCML
document. It has one required attribute, "version", and two required
elements, <head> and <body>.
3.1.1 <tocml> Attribute: version
The "version" attribute of <tocml> indicates the version of TOCML with
which this document complies. It is in the form, "x.y", where x is
the major TOCML version, and y is the minor TOCML version.
3.2 <head> Element
The <head> element is required as the first child of the <tocml>
element. It is intended to be a container for any information that
pertains globally to the document as a whole. <head> has no required
attributes, and no required elements. <head> may optionally contain a
single <parent> element.
3.3 <parent> Element
The <parent> element identifies the parent of this document. It has
one required attribute, "link", which specifies the URL of a TOCML
file that the TOCML processor can treat as this document's parent.
If a TOCML document does not provide a <parent> element, the TOCML
processor will treat this document as the root of its own tree.
The TOCML processor may follow <parent> links up the tree until it
finds a parentless document that it can treat as the root.
3.4 <body> Element
The <body> element has no attributes. It must contain exactly one
<node> element, which is the root node of this file's tree.
3.5 <node> Element
The <node> element represents a node of this document's tree. It has
two required attributes, "title" and "id", and three optional
attributes, "description", "link" and "children". The <node> element
may contain zero or more child <node> elements. If a <node> element
contains no children, it is called a leaf node. If a <node> element
contains one or more children, it is called an interior node.
3.5.1 <node> Attribute: title
The required "title" attribute provides a concise title for the
<node>. While there is no limit to the length of the title attribute,
authors should keep it small enough to be rendered on a single line in
a tree control. TOCML processors may truncate long titles if
necessary. The title should not contain any markup, since it may not
be rendered using HTML.
3.5.2 <node> Attribute: id
The required "id" attribute uniquely identifies the node within its
document. This allows other documents to create links to the node by
ending the document's URL with a fragment consisting of # followed by
the ID. The author should ensure that all IDs are unique within a
TOCML document. If duplicate IDs exist within a document, TOCML
processors should select the first matching node encountered.
Note: I'm still on the fence about making id a required attribute. If
we don't require it, documents could still link to individual nodes
using XPointer syntax, but this would require all TOCML processors to be
able to process XPointer fragments, which might be a little heavy for
this first version. Requiring an ID calls for a little extra work on
the part of the document author, but in exchange it simplifies the job
of the linking author and the TOCML processor.
3.5.3 <node> Attribute: description
The optional "description" attribute may contain a longer description
for the node. The TOCML processor may or may not choose to render
this string, so the author shouldn't presume that the user will
necessarily see it. In a Yahoo style interface, this string could be
used as the node's description. In an expanding tree control
interface, this description could be displayed as a tool tip when the
user hovers his mouse over the node. The description should not
contain any markup, since it may not be rendered using HTML.
3.5.4 <node> Attribute: link
The optional "link" attribute may contain a URL pointing to the
resource associated with this node. When the user clicks on the node,
the link URL will be loaded in the browser. If the node has no link
attribute, the node will not load any page in the browser when
clicked.
3.5.5 <node> Attribute: children
The optional "children" attribute points to a URL containing a TOCML
file. If the current node's children attribute doensn't contain a
"#", then the children of the root node of the designated document
will be rendered as children of the current node. If the current
node's children attribute contains a "#" followed by an ID, then the
children of the node with a matching ID in the designated document
will be rendered as children of the current node.
Curtis Duhn
curtis@duhn.com