- From: CVS User rberjon2 <cvsmail@w3.org>
- Date: Fri, 30 Aug 2013 15:14:07 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/ReSpec.js
In directory roscoe:/tmp/cvs-serv9799
Modified Files:
documentation.html
Log Message:
redirect to new docs
--- /sources/public/2009/dap/ReSpec.js/documentation.html 2013/01/23 15:48:14 1.58
+++ /sources/public/2009/dap/ReSpec.js/documentation.html 2013/08/30 15:14:07 1.59
@@ -1,1060 +1,14 @@
<!DOCTYPE html>
<html>
<head>
- <title>ReSpec.js — W3C Specification Writing Tool</title>
- <meta http-equiv='Content-Type' content='text/html;charset=utf-8' />
- <script src='js/respec.js' class='remove'></script>
- <script class='remove'>
- var respecConfig = {
- // document info
- specStatus: "ED",
- shortName: "respec-js",
- // publishDate: "2009-08-06",
- // previousMaturity: "WD",
- // previousPublishDate: "2009-03-15",
- // previousURI : "http://dev.w3.org/2009/dap/ReSpec.js/documentation.html",
- copyrightStart: "2009",
- edDraftURI: "http://dev.w3.org/2009/dap/ReSpec.js/documentation.html",
- // lcEnd: "2010-08-06",
- // extraCSS: ["../css/respec.css"],
- extraCSS: ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],
-
- // editors
- editors: [
- { name: "Robin Berjon", url: "http://berjon.com/",
- company: "Robineko", companyURL: "http://robineko.com/" },
- ],
-
- // WG
- wg: "People Who Like To Write Specs Help Group",
- wgURI: "http://berjon.com/",
- wgPublicList: "spec-writers-anonymous",
- wgPatentURI: "",
- };
- </script>
+ <title>ReSpec — The stark raving awesome way to write specs</title>
+ <meta charset="utf-8">
+ <meta http-equiv="refresh" content="0;URL='http://w3.org/respec/'">
</head>
<body>
- <section id='abstract'>
- This is the documentation for <a title='ReSpec'>ReSpec.js</a>, a tool that helps with specification editing primarily
- within a W3C context.
- </section>
-
- <section id='sotd'>
- <p>
- This paragraph is here to demonstrate that it is possible to add a completely custom
- piece of HTML inside the SotD.
- </p>
- </section>
-
- <section>
- <h2>A Word of Warning</h2>
- <p>
- The documentation you are reading here is the documentation that was written for ReSpec v1. The
- current release of ReSpec as of this writing is v3.1. That may sound worrying, but it really isn't,
- for the following reasons:
- </p>
- <ul>
- <li>
- If you're still on v1, unless you've done something weird or bad, you should have
- completely smooth compatibility when upgrading. You really should upgrade though as v1 is no longer
- supported at all and v3 is a lot better.
- </li>
- <li>
- This means that the documentation here is still accurate. It's just incomplete. But given that I
- haven't released new documentation yet (though I will) you can stick to reading this guide.
- </li>
- </ul>
- <p>
- You can upgrade <em>now</em> by replacing whichever way you're referencing ReSpec with:
- <code><script src='http://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script></code>.
- If in doing so you bump into problems, I really need to look at your spec. So please email me!
- </p>
- </section>
-
- <section class='informative'>
- <h2>Introduction</h2>
- <p>
- <dfn>ReSpec</dfn> is a Javascript [[ECMA-262]] based tool that unobtrusively allows editors
- to write a specification focusing on the actual features and correctness, while needing to
- pay as little attention as possible to issues pertaining to styling, referential integrity,
- and the friendly dragon to slay that are the W3C Publication Rules.
- </p>
- <p>
- There are many good existing tools that can be used to produce W3C specifications. A
- non-exhaustive list includes:
- </p>
- <ul>
- <li><a href='http://www.w3.org/2002/xmlspec/'>XMLSpec</a></li>
- <li><a href='http://www.w3.org/Style/Group/css3-src/bin/postprocess'>CSS3 Module PostProcessor</a></li>
- <li><a href='http://anolis.gsnedders.com/'>Anolis</a></li>
- <li><a href='http://dev.w3.org/2006/webapi/ReSpec/'>ReSpec</a> (Perl version)</li>
- <li>Many I forget...</li>
- </ul>
- <p>
- But I was dissatisfied with all of them, including the one I wrote. The primary reason for
- that was that they all require one to run a tool in between editing and reloading the
- browser — an extra step that at the end of a long day's work editing is one step too many.
- Beyond that there are some smaller issues that I personally have with each, but it is
- largely a matter of taste.
- </p>
- <p>
- At this point I have applied at least cursory testing to this tool using Firefox 3.5,
- Opera 10, and Safari 4. Without testing I would expect it to work in a reasonably recent
- Chrome, and not in any version of Internet Explorer (patches welcome).
- </p>
- </section>
-
- <section>
- <h2>Support</h2>
- <p>
- The official support channel for ReSpec is <a href='mailto:spec-prod@w3.org'>spec-prod@w3.org</a>.
- The archives are available at
- <a href='http://lists.w3.org/Archives/Public/spec-prod/'>http://lists.w3.org/Archives/Public/spec-prod/</a>.
- You can subscribe by sending email to
- <a href='mailto:spec-prod-request@w3.org?Subject=subscribe'>spec-prod-request@w3.org</a> with
- "subscribe" as the subject line.
- </p>
- <p>
- <strong>Please</strong> use that instead of emailing me (Robin) directly as the chances are that questions
- or enhancement ideas will be shared by others. Thanks!
- </p>
- </section>
-
- <section>
- <h2>Concepts</h2>
- <p>
- The fundamental ideas that underlie <a title='ReSpec'>ReSpec.js</a> are:
- </p>
- <dl>
- <dt>It Just HTML</dt>
- <dd>
- You just edit HTML, with some extra convention but nothing extra. All the decoration is
- performed by the script, informed by some very basic configuration. There is a simple
- <a href='template.html'>template</a> that you can use to get started.
- </dd>
- <dt>No Tool</dt>
- <dd>
- You never have to run a tool outside of your editor and browser. While the specification
- is being developed that's all that's needed. When a snapshot is needed for publication,
- all it takes is saving the generated DOM to a file (the script is very careful to cleanly
- remove itself and its dependencies so that you should normally get a document that's
- PubRules-OK).
- </dd>
- <dt><acronym title="Don't Repeat Yourself">DRY</acronym></dt>
- <dd>
- You shouldn't have to repeat anything within a specification, or across specifications
- (apart from the template). For instance, marking RFC 2119 keywords is automatic, the
- WebIDL support makes it possible to specify both the WebIDL and its documentation in
- the same place without repeating a single part of it, etc..
- </dd>
- </dl>
- </section>
-
- <section>
- <h2>General Structure</h2>
- <p>
- Most of what is described here will make a whole lot more sense if you look at the
- <a href='template.html'>template</a>'s source before you get started.
- </p>
- <p>
- The general structure of a <a>ReSpec</a> document is that of an HTML5 [[!HTML5]] document, with a
- few extra conventions so that the <a>ReSpec</a> processor may infer additional semantics.
- </p>
- <p>
- Inside <code>head</code>, the <code>title</code> element contains the title that will also
- be used to generate the <code>h1</code> in the specification's header. Then external <code>script</code>
- element loads in <a>ReSpec</a>, and another one inlines the basic configuration that it requires.
- </p>
- <p>
- Inside the <code>body</code>, each section of the specification is contained inside a
- <code>section</code> element. At least one of these MUST have an <code>id</code> of
- "abstract" (and MUST contain just the text of the abstract). Sections can be
- nested to any depth and are expected to have a heading title. Any of
- <code>h2</code>-<code>h6</code> is acceptable as they will be automatically renamed to
- the <em>hN</em> applicable to that depth.
- </p>
- <p>
- If there is a <code>section</code> element with <code>id</code> "sotd" anywhere with the
- document, it will be removed, and its content will be inserted inside the <em>Status of
- this Document</em> as additional custom content.
- </p>
- <p>
- If there is a <code>section</code> element with <code>id</code> "conformance" in the document
- (and that element MAY be completely empty), it will be replaced with a template conformance
- section that mentions the RFC 2119 keywords and the such. If it has any content it will be
- appended after that template.
- </p>
- <p>
- During processing, <code>section</code> elements will be converted to <code>div</code>
- elements with <code>class</code> "section".
- </p>
- <p>
- Any section at the beginning that has a <code>class</code> of "introductory" will not
- be included in the Table of Contents. The first root-level section with a <code>class</code> of
- "appendix" will start the appendices section, labelled with letters.
- </p>
- <p>
- Each <code>section</code> MAY have an <code>id</code> — if not, one will be generated
- based on the <code>textContent</code> of its heading.
- </p>
- <p>
- Any <code>section</code> that has a <code>class</code> of "informative" will be marked as
- "non-normative" in the output using the usual text.
- </p>
- <p>
- You MUST NOT create sections for the <em>Status of this Document</em>, the <em>ToC</em>, or
- the <em>References</em> as they will be automatically generated for you.
- </p>
-<p>Same document references may be created using the following
- formatting:
-<pre>
-<a href="#general-structure" class="sectionRef"></a>
-</pre>(It is
- necessary for the explicit closing tag to be present.)
-The class signals that this will be replaced with a link containing
- the section number and title as follows:
-<pre><a href="#general-structure" class="sectionRef">section Section-Number Section-Title</a></pre>
-</p>
- </section>
- <section>
- <h2>Configuration</h2>
- <p>
- The only part of <a>ReSpec</a> that isn't just straightforward HTML is the configuration, which
- thankfully is minimal (and a lot simpler than the HTML that it generates and which is
- required in all W3C specifications).
- </p>
- <p>
- The configuration is stored in a Javascript object called <code>respecConfig</code>.
- </p>
- <dl>
- <dt>specStatus</dt>
- <dd>
- <p>
- This is the status of the document, as keyed in the following table. If in doubt,
- use <code>ED</code>.
- </p>
- <table class='simple'>
- <thead>
- <tr>
- <th>key</th>
- <th>value</th>
- </tr>
- </thead>
- <tbody>
- <tr><td>NOTE</td><td>Note</td></tr>
- <tr><td>FPWD-NOTE</td><td>First Public WG Note</td></tr>
- <tr><td>WG-NOTE</td><td>Working Group Note</td></tr>
- <tr><td>CG-NOTE</td><td>Co-ordination Group Note</td></tr>
- <tr><td>IG-NOTE</td><td>Interest Group Note</td></tr>
- <tr><td>Member-SUBM</td><td>Member Submission</td></tr>
- <tr><td>Team-SUBM</td><td>Team Submission</td></tr>
- <tr><td>XGR</td><td>Incubator Group Report</td></tr>
- <tr><td>MO</td><td>Member-Only Document</td></tr>
- <tr><td>ED</td><td>Editor's Draft</td></tr>
- <tr><td>FPWD</td><td>First Public Working Draft</td></tr>
- <tr><td>WD</td><td>Working Draft</td></tr>
- <tr><td>LC</td><td>Last Call Working Draft</td></tr>
- <tr><td>CR</td><td>Candidate Recommendation</td></tr>
- <tr><td>PR</td><td>Proposed Recommendation</td></tr>
- <tr><td>PER</td><td>Proposed Edited Recommendation</td></tr>
- <tr><td>REC</td><td>Recommendation</td></tr>
- <tr><td>RSCND</td><td>Rescinded Recommendation</td></tr>
- <tr><td>unofficial</td><td>An unofficial draft. Use this if you're producing a document outside of W3C</td></tr>
- <tr><td>base</td><td>Just the basic template, not a specification</td></tr>
- </tbody>
- </table>
- <p>
- The <code>specStatus</code> is used to pick the base style sheet, as well as to configure
- various parts of the specification's header and <em>Status of this Document</em>. Some of
- the header notably depends on whether the specification is on "Rec-track", which is the
- case if the <code>specStatus</code> is one of: "FPWD", "WD", "LC", "CR", "PR", "PER", or "REC".
- </p>
- </dd>
- <dt>shortName</dt>
- <dd>
- The specification's short name, as in http://www.w3.org/TR/<strong>short-name</strong>/. Note
- that short names are assigned by the Director — ask your Team contact or Chair in advance of
- publication.
- </dd>
- <dt>subtitle</dt>
- <dd>
- W3C specifications have an optional subtitle that is displayed
- below the title in the heading section. Define yours here if you have
- one.
- </dd>
- <dt>copyrightStart</dt>
- <dd>
- Some W3C specifications have a copyright that spans a range of years.
- You can specify the optional starting year with this parameter.
- </dd>
- <dt>publishDate</dt>
- <dd>
- When a draft is made ready for publication it is often done several days in advance. In that
- case, set this to the desired date in YYYY-MM-DD format. Otherwise comment it out, it'll
- default to today.
- </dd>
- <dt>previousPublishDate</dt>
- <dd>
- If there is a previously published version of this draft, set this to its date in YYYY-MM-DD
- format. If there isn't simply comment it out (or set it to a false value).
- </dd>
- <dt>previousMaturity</dt>
- <dd>
- If there is a previously published version of this draft, set this to its maturity level.
- </dd>
- <dt>previousURI</dt>
- <dd>
- If the previous version wasn't in the W3C TR space, you can supply an explicit URI. If it
- is in TR space then the URI will be automatically determined.
- </dd>
- <dt>additionalCopyrightHolders</dt>
- <dd>
- If there are additional copyright holders in addition to the W3,
- they can be listed in this parameter. For example, if the copyright
- notice without <code>additionalCopyrightHolders</code> reads
- "Copyright © 2009 W3C ... " then with
- "Foo" listed it will read "Copyright © 2009 Foo &
- W3C ... ".
- </dd>
- <dt>edDraftURI</dt>
- <dd>
- If there a publicly available Editor's Draft, this is the link to it. This will typically be
- the link to the CVS version of the document you're editing.
- </dd>
- <dt>lcEnd</dt>
- <dd>
- If the draft is a Last Call WD it needs to have a review period with a given end date. This is
- that date in YYYY-MM-DD format. This is otherwise ignored.
- </dd>
- <dt>crEnd</dt>
- <dd>
- If the draft is a Candidate Recommendation it needs to have an end date that is the promised
- <em>minimal</em> date before which it will not transition to PR. This is that date in YYYY-MM-DD format.
- This is otherwise ignored.
- </dd>
- <dt>prevRecShortname</dt>
- <dd>If there is an earler version of this specification at the
- Recommendation level, set this to the shortname of that
- version. This is
- optional and not usually necessary.
- <dt>prevRecURI</dt>
- <dd>An optional URI if the previous recommendation specified by prevRecShortname
- needs a specific URI as opposed to just the simple shortname
- in TR space at W3C.</dd>
- <dt>prevRecHeader</dt>
- <dd>An optional header if the previous recommendation reference needs a more specific
- header than the default "Latest recommendation".</dd>
- <dt>testSuiteURI</dt>
- <dd>Specifies the optional URI to the test suite for the specification.</dd>
- <dt>implementationReportURI</dt>
- <dd>Specifies the optional URI to the implementation report for the specification. This is normally only used during the Proposed Recommendation phase of publication.</dd>
- <dt>extraCSS</dt>
- <dd>
- <strong>This configuration parameter is now deprecated and you should avoid using it. In ReSpec v3 it's
- a noop.</strong>
- This is an array that contains URI references (that may be absolute or relative) to additional
- CSS style sheets that you may wish to be loaded into the document. It is RECOMMENDED that you
- include <code>http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css</code> as one of those, though
- you may of course skip it and take care of the additional styles yourself.
- </dd>
- <dt>editors</dt>
- <dd>
- <p>
- An array describing editors that contains objects with the following fields:
- </p>
- <table class='simple'>
- <thead>
- <tr><th>key</th><th>optional</th><th>description</th></tr>
- </thead>
- <tbody>
- <tr>
- <td>name</td>
- <td>No</td>
- <td>
- The name of the editor.
- </td>
- </tr>
- <tr>
- <td>url</td>
- <td>Yes</td>
- <td>
- The URL to the editor's website.
- </td>
- </tr>
- <tr>
- <td>company</td>
- <td>Yes</td>
- <td>
- The editor's affiliation.
- </td>
- </tr>
- <tr>
- <td>companyURL</td>
- <td>Yes</td>
- <td>
[670 lines skipped]
Received on Friday, 30 August 2013 15:14:09 UTC