Some ReSpec extensions and doc improvements
Richard Cyganiak <richard <at> cyganiak.de>
2011-05-27 18:34:44 GMT
First of all, thank you Robin and thank you everyone else who has contributed to ReSpec. It's such a nice way
of editing specs. Great work!
As part of my RDF-WG work, I made some extensions to ReSpec:
1. Added an 'otherContributors' configuration parameter that allows adding custom groups of
contributors beyond the currently supported 'Editors' and 'Authors' (can be handy for 'Previous
editors', 'Series editor' and stuff like that)
2. A section element with id "references" is now removed, and its contents dumped into the real references
section. This addresses the same need as the 'refNote' parameter, but allows inclusion of markup.
3. Added documentation for the items above
4. It appears that the best practice numbering only works if a 'practiceNum' configuration parameter is
set -- updated the documentation to reflect that
5. Added a new section to the documentation that explains how to make notes, issues and examples (this isn't
ReSpec-specific but just W3C CSS, but is a handy thing for spec authors to know)
6. Moved some paragraphs out of the General Structure section to other sections where they are easier to
find; for example how to create a Conformance section and how to mark sections as non-normative, which I
moved to the section now called 'RFC 2119 and Conformance'. This is based on my experience as a new ReSpec
user. There were some things I was sure I had read on my first pass over the docs, but then couldn't find when
looking for them.
Do you think that all or some of this would be of general use and should be committed to the official version?