William Waites | 2 May 12:10 2011

respec.js for other kinds of documents

Hello, I've been looking at respec.js as part of some work with the
RDF-WG and also with an eye to using it as a documentation tool for my
one of own projects. Would a patch be accepted that introduced a new
specStatus of "other" that basically behaves like "unofficial" except
that the "Status of This Document" defaults to empty (since the boiler
plate of being for a potential specification isn't really applicable
for, e.g. a software manual)?

Cheers,
-w
--

-- 
William Waites                <mailto:ww <at> styx.org>
http://river.styx.org/ww/        <sip:ww <at> styx.org>
F4B3 39BF E775 CF42 0BAB  3DF0 BE40 A6DF B06F FD45

Robin Berjon | 3 May 15:40 2011

Re: respec.js for other kinds of documents

On May 2, 2011, at 12:10 , William Waites wrote:
> Hello, I've been looking at respec.js as part of some work with the
> RDF-WG and also with an eye to using it as a documentation tool for my
> one of own projects. Would a patch be accepted that introduced a new
> specStatus of "other" that basically behaves like "unofficial" except
> that the "Status of This Document" defaults to empty (since the boiler
> plate of being for a potential specification isn't really applicable
> for, e.g. a software manual)?

Yes, that would be perfectly fine. That being said, if you want to handle different types of documents with
different requirements you might wish to check out ReSpec v2. The docs are very sparse but 98% of the stuff
works just like v1. One big addition though is that everything's a plugin so you can add your own document
types as you please (there's an example of doing just that for the "Robineko Reports" document style in the repository).

http://dvcs.w3.org/hg/respec2/

--

-- 
Robin Berjon - http://berjon.com/

Richard Cyganiak | 27 May 20:34 2011
Picon

Some ReSpec extensions and doc improvements

Hi,

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?

(Continue reading)


Gmane