ReSpec Documentation 1.0

1.1.1. Splitting (@TODO)

The tool should know how to create a multipage document by splitting on the root sections, naming the pages based on the ID of that section, and know how to rewrite all the internal links so that they work (look for the ID, then its section ancestors, and point to that).

1.1.2. Relinking (@TODO)

The links in the spec should only ever point to IDs, so that the XSLT can decide which extension to use.

1.1.3. Multi-styling

Through the use of a sensible base stylesheet, it ought to be possible to produce new styles easily by overriding a minimal amount of templates.

1.1.4. RelaxNG (@PARTIAL)

RelaxNG should be embeddable straight into the specification, along with annotations that describe the elements and attributes, as well as ways to override the auto-generated description. The style of the RNG will have to be specific. The XSLT will then auto-generate descriptions of the element and attributes based on that. Weenies will want RNC, they get that option but later. The RNG may get some syntax highlighting.

1.1.5. RFC2129 keyword highlighting

Automatically any capitalized MUST, SHOULD, SHALL, MAY, possibly followed by a NOT will find themselves wrapped in an <rfc2119> element which'll be transformed into something nice by the XSLT.

1.1.6. Acronym detection

Any occurence of an abbr or acronym element will cause a search so that all the other occurences of the same term that aren't marked up will be marked up.

1.1.7. IDL support (@TODO)

Handling IDL is horrible. We will use an XML syntax that will fully describe the IDL and the spec prose, and that will be used to generate both the prose and the IDL snippets. The IDL may get some syntax highlighting. Or not. We might just parse the IDL using some code that has been written for SVG.

1.1.8. Autogenerated appendices (@TODO)

Based on the above, lists of elements, attributes, and interfaces can be generated if need be for the appendix.

1.1.9. Glossary support (@TODO)

If a glossary is defined, links will be auto-generated from occurences to it. This should ideally be done without elements to mark defined terms.

1.1.10. Autobundling (@TODO)

All the dependencies of a spec can be listed and then packed into a zip file and a tarball.

1.1.11. Various checks (@TODO)

When being published a Re-Spec document will have its spelling, its pubrules-validity, and various other things validated. One thing that notably needs to be checked is that when an internal link to an anchor is created, it needs to exist.

1.1.12. Bibliography database

Many specs tend to reuse always the same set of bibliographic references. Rather than having to always create or copy them anew, ReSpec provides a pre-existing database using the typical keys for those references. Simply using the square-bracket markup will cause the right entry to be added to the bibliography.

1.1.13. Testable assertion management (@TODO)

Each section can be categorised by normativity (reference, content, ua, discussion, etc.). Then a tool would expose present the various sections that have a given normativity (ua for test suite production, content for validation suite production) and in those split each sentence that it would present on separate lines. For each of those sentences one could say if it's a testable assertion or not, and if it is give it an ID. The tool would save that information in a separate document, using both the XPath relative to the closest ancestor with a given ID and the text of the sentence. This is to be used once the text is reasonably stable, but when reloading a document it would make a best effort to re-locate things that have changed. One could also associate TAs with tests, produce a coverage report, etc.

2.1.1. The specification element

This is the root element for all documents. The version attribute must be present and its value must currently be equal to "1.0". Note that this is not currently enforced.

Typically, it would contain one <metadata> element and several <section> elements.

<define name='specification'>
  <element name='specification'>
  </element>
</define>

2.1.2. The section element

The section element defines a section inside a specification, and can be nested to arbitrary depths. It must have an 'xml:id' attribute, may have a 'type' attribute, must have a <title> child, and may then contain a variety of XHTML block-level elements such as <p>, <ul>, or <table>.

<define name='section'>
  <element name='section'>
  </element>
</define>

The 'type' attribute has a variety of predefined values with specific behaviours.

abstract

Identifies the section as an abstract. This removes it from the TOC.

w3c-abstract

Identifies the section as an abstract following W3C style. This removes it from the TOC and also applies some W3C specific processing.

w3c-sotd

Identifies the section as a state of this document section following W3C style. This removes it from the TOC and also applies some W3C specific processing.

toc

Identifies the section as a table of contents. This removes it from the TOC. Note that this does not cause a TOC to be generated, you need the <?respec-toc?> processing instruction for that.

appendix

Identifies the section as an appendix. This causes its numbering to use letters instead of numbers in the present style sheets.

2.1.3. The title element

The title element is used to capture titles. Inside the <metadata> element it's the specification's title, inside other elements it applies directly to its parent element (<section>, <section>, <example>, <schema>, etc.).

While most of the time only its textual content will be used, for section titles the <at>, <pi>, <ev>, <prop>, and <el> elements will be processed specially.

<define name='title'>
  <element name='title'>
  </element>
</define>

2.1.4. The include element

This is used to include other documents (which are not required to be ReSpec documents, they only need to be XML) with the 'href' attribute pointing relative to the document in which the element occurs. Future improvements will likely include the ability to have absolute links, respec: links, and to taking xml:base into account. Some XPointer schemes, notably the xpath scheme, may be considered as well.

Note that fragment identifiers will always be processed as if the linked document was of type application/xml, which is to say that the element with the given ID will be included. This is often used to include part of an external RelaxNG schema inside a <schema> element (this document does precisely that).

<define name='include'>
  <element name='include'>
  </element>
</define>

2.1.5. The ednote element

This element is meant to flag that part of the document is an editorial note. This normally causes them to stick out strongly. Editorial notes are not normally meant for public consumption. It is possible that future versions will provide a flag to turn them on and off.

This element can contain pretty much anything else.

<define name='ednote'>
  <element name='ednote'>
  </element>
</define>

2.1.6. The schema element

The schema element is used to capture schemata. These can be of several types. Currently, RelaxNG is largely supported (at least for many simple RelaxNG constructs), EBNF is supported but will be extended, and IDL support is planned for very soon. The way the type is decided is by looking at the child elements. It should also contain a title child. XML Schema support may be added some day.

<define name='schema'>
  <element name='schema'>
  </element>
</define>

namespace is RelaxNG

If the namespace of its content is the RelaxNG namespace, then this mode is used.

ebnf

If it contains an <ebnf> element then the EBNF mode is used. The <ebnf> element contains an EBNF grammar in raw text that will be re-indented and should in the future gain autogenerated links.

idl

If it contains an <idl> element then the IDL mode is used. The <idl> element contains an IDL interface in raw text that once supported will be re-indented and gain autogenerated links with specific IDs for cross-referencing.

2.2.1. The at element

This element is used to mark that its content is an attribute name. The 'el' attribute can be used to say that it's an attribute that belongs to that given element. The content must be an attribute name, and that only. A link will be generated to an ID as per the rules documented in the section on special identifiers.

<define name='at'>
  <element name='at'>
  </element>
</define>

2.2.2. The el element

This element is used to mark that its content is an element name. The content must be an element name, and that only. A link will be generated to an ID as per the rules documented in the section on special identifiers.

<define name='el'>
  <element name='el'>
  </element>
</define>

2.2.3. The ev element

This element is used to mark that its content is an event name. The content must be an event name, and that only. A link will be generated to an ID as per the rules documented in the section on special identifiers.

<define name='ev'>
  <element name='ev'>
  </element>
</define>

2.2.4. The pi element

This element is used to mark that its content is a PI name. The content must be a PI name, and that only. A link will be generated to an ID as per the rules documented in the section on special identifiers.

<define name='pi'>
  <element name='pi'>
  </element>
</define>

2.2.5. The prop element

This element is used to mark that its content is a property name. The content must be a property name, and that only. A link will be generated to an ID as per the rules documented in the section on special identifiers.

<define name='prop'>
  <element name='prop'>
  </element>
</define>

2.3.1. The bibliography element

This is the root of a bibliography. Future versions may distinguish between normative and informative ones. It contains a series of <bibentry> elements.

If you wish to only use the bibliographic database without bothering to create the entries yourself, you can have an empty bibliography element to which the entries will get added at generation time. Please keep in mind though that the DB is currently somewhat limited (but I'm adding to it as I go).

<define name='bibliography'>
  <element name='bibliography'>
  </element>
</define>

2.3.2. The bibentry element

Captures a single entry, or a group of entries that are commonly referred in most cases. If it is a single entry, the entry is described directly inside this element. If a group entry, then there may be several <p> elements introducing the group followed by several <entry> elements which will capture individual entries. The content model for the single entry version is described as part of the <entry> element.

It is required that there be an 'xml:id' attribute that corresponds exactly to the short name of the entry used in the specs' references.

<define name='bibentry'>
  <element name='bibentry'>
  </element>
</define>

2.3.3. The entry element

Describes a single bibliographic entry. This is expected to have a <title>, a <link>, a <date>, and an <authors> element.

<define name='entry'>
  <element name='entry'>
  </element>
</define>

2.3.4. The link element

Contains a single IRI that is the link to that entry. Currently only online resources may be referenced in a bibliography.

<define name='link'>
  <element name='link'>
  </element>
</define>

2.4.1. The metadata element

This is the header element for the entire specification. It contains a <title>, <styling> information, a <date>, and possibly <editors> and <authors>.

<define name='metadata'>
  <element name='metadata'>
  </element>
</define>

2.4.2. Elements describing people

Describing people is always a tricky business, and this set of elements is just about as ad hoc as many other attempts. It simply tries to capture what is normally used in specifications.

The <editors> and <authors> elements contain a list of <person> elements who are editors or authors of a specification or reference.

The <person> element describes an individual, and is rendered differently depending on its location. The various child elements that it may contain are <name> for the full name, <email> for that person's email, <url> for the person's IRI, <company> being the company that person works for, and <company-url> its IRI.

<define name='editors'>
  <element name='editors'>
  </element>
</define>
<define name='authors'>
  <element name='authors'>
  </element>
</define>
<define name='person'>
  <element name='person'>
  </element>
</define>
<define name='company'>
  <element name='company'>
  </element>
</define>
<define name='company-url'>
  <element name='company-url'>
  </element>
</define>
<define name='url'>
  <element name='url'>
  </element>
</define>
<define name='email'>
  <element name='email'>
  </element>
</define>
<define name='name'>
  <element name='name'>
  </element>
</define>

2.4.3. The date element

The date element contains three attributes for the year, month and day. The intent is to use it to generate dates in specification headers but it is not currently implemented. It is expected that this will be remedied very soon.

<define name='date'>
  <element name='date'>
  </element>
</define>

2.4.4. The styling element

The styling element contains metadata about the style of the specification. It's type attribute provides the type of the specification, a set currently limited to "W3C", "robin", and "Expway" but which can be extended.

The status attribute indicates the current status of the specification. This is currently mostly useful for the "W3C" type. The possible values are: ED (Editor's Draft), EDMO (the same, but Member-only), N (Note), INF (informal document), MO (Member-only informal document), WD, LC, CR, PR, and REC. I am aware that this does not capture all document types that can be produced within W3C and will be adding more as needed.

<define name='styling'>
  <element name='styling'>
  </element>
</define>

2.4.5. Elements describing versions

The <versions> element, contained inside the <metadata> element, is used to include pointers to multiple versions of the document. It is currently extremely ad hoc and it is expected that a better scheme will be provided in the close future. It contains three elements: <current>, <latest> and <previous>, the content of each of which is merely a link to the version being either the current, latest, or previous one.

<define name='versions'>
  <element name='versions'>
  </element>
</define>
<define name='current'>
  <element name='current'>
  </element>
</define>
<define name='latest'>
  <element name='latest'>
  </element>
</define>
<define name='previous'>
  <element name='previous'>
  </element>
</define>

2.6.1. The rfc2119 element

Whenever an RFC 2119 [RFC2119] keyword in uppercase is found, it gets wrapped in this element.

<define name='rfc2119'>
  <element name='rfc2119'>
  </element>
</define>

2.6.2. The bibref element

Whenever a bibliographic reference is found, it is wrapped in this element (the square brackets are not removed, they are placed right before and right after the element).

<define name='bibref'>
  <element name='bibref'>
  </element>
</define>

2.7.1. The respec-toc processing instruction

This instructs the final step style sheet to generate a table of contents in place of the PI.