The goal of Re-Spec is to provide a convenient framework in which to write specifications of various kinds but mostly orientated towards the W3C style. It does not claim or intend to be a perfect specification framework or better than other solutions such as XMLSpec [XMLSpec] or XHTML+classes. Simply, it has been created to suit the needs of its author, and perhaps those of like-minded individuals, assuming such entities even exist. It does, however, have a much cooler name than any of the other options.
Please note that some parts of this document are loosely described compared to what a proper specification would mandate. This is because here we are merely documenting how the one and only implementation of Re-Spec works, not specifying in order to make independent interoperable implementations. If you are interested in implementing Re-Spec differently from the current single implementation, please contact the author and I will tighten up this document.
A first pass at implementing the features below has been done but a fair number remains. The latter are identified by @TODO or @PARTIAL. The version of ReSpec documented here is 0.04.
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
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 section presents a rather simplified descriptions of the elements which are available for use within Re-Spec. The categories may not be the most intuitive in all cases.
All elements are in the
namespace, unless otherwise specified.
Most elements in this draft documentation don't have a corresponding RNG snippet yet. They'll get one as things go.
These elements define the backbone of the document.
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
The section element defines a section inside a specification,
and can be nested to arbitrary depths. It must have an
The title element is used to capture titles. Inside the
While most of the time only its textual content will be used, for section
This is used to include other documents (which are not required to be ReSpec
documents, they only need to be XML) with the
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
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.
Inline elements are used to markup regular text in a variety of convenient ways.
This element is used to mark that its content is an attribute name. The
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.
These elements are used in the creation of bibliographies.
This is the root of a bibliography. Future versions may distinguish
between normative and informative ones. It contains a series of
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
It is required that there be an
Describes a single bibliographic entry. This is expected to have
Contains a single IRI that is the link to that entry. Currently only online resources may be referenced in a bibliography.
A variety of elements are available to describe what can be vaguely called metadata. They are not restricted to the metadata headers in the document but are also reused in other contexts such as bibliographic entries.
This is the header element for the entire specification. It contains
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 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 following elements have been lifted as is from XHTML. For convenience their namespace is the ReSpec one: p, a, abbr, acronym, code, dl, dd, dt, ol, ul, li, table, thead, tbody, tfoot, caption, tr, th, td, em, strong, br.
All their attributes in no namespace are copied over as is. If they have an xml:id attribute (the only to be recognised as an ID inside ReSpec) the output will also have a matching id attribute.
The following elements are described for completeness' sake, but are not actually available for use while editing ReSpec documents. They are automatically generated in the pre-processing phase of a ReSpec run, and the downstream XSLT then handles them. It may therefore be useful to XSLT authors to know about them.
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).
The one and only PI understood by the ReSpec processor is
This instructs the final step style sheet to generate a table of contents in place of the PI.
It is generally considered a bad idea to introduce new URI schemes, and the introduction of this one has been given extensive thought. In the end, I figured that since it would never be used in the wild but only within ReSpec documents (that are not meant for widespread distribution). When ReSpec documents are transformed, all mentions of the respec: scheme are removed.
The goal of this scheme is to provide locators for resources that are bundled with ReSpec, so that the ReSpec processor may access them easily. A typical use for this would be to specify an additional style sheet that ships with ReSpec and have it copied to the publish directory.
Currently, the only two sorts of resources that ReSpec knows to locate through this scheme are its CSS and XSLT style sheets. Simply provide the sheet's name and it will know where to look for it. This may be extended to include more resource types.
Links to the following special identifiers are generated for some various items in the
grammar. More will be added for EBNF and IDL support. If you give this ID to
a section, the
Generated for properties, where
Generated for events, where
Generated for elements, where
Generated for attributes, where
Generated for attributes that are local to a given element, where
Generated for processing instructions, where
Unlike the previous instances, this is not a generated link but rather a generated
anchor, so that using such an ID will cause duplicate IDs to be present in the document.
Needless to say, don't do that. Use this to link to RelaxNG schema snippets from the body
of the specification. Whenever the ReSpec processor finds a RelaxNG