Some ReSpec extensions and doc improvements

Previous Topic Next Topic
classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

Some ReSpec extensions and doc improvements

Richard Cyganiak-2

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?

Attached is a patch containing all of the above, generated with "CVS diff". Please let me know if some other patch format would be more helpful, or if you would like a partial patch that omits some of the items above.

Thanks again,

respec.diff (18K) Download Attachment