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).

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

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.

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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

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

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

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.

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.

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.

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.

Whenever an RFC 2119 [RFC2119] keyword in uppercase is found, it gets wrapped in this 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).

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