Preparing your document

Echidna expects to retrieve one of the three possible resources:

1. A tar file, containing at least an HTML5 document named Overview.html
2. A staged HTML5 document, which will handed down to the checkers before publication
3. A manifest file (anything that does not start with < will be considered a manifest file)

(Manifest detection assumes that a valid HTML5 document has a doctype at the very beginning, so Echidna looks at the first character and checks if it's a < or not, to distinguish those two cases.)

Staged HTML5 document

When your specification doesn't make use of additional resources, ie no images or external style sheets, and is ready to be published. The document needs to be somewhere publicly available on the web (github.io, personal web server, etc).

Only the HTML document will get published if the checkers are happy.

TAR file

You can also send a TAR file to Echidna containing at least the document named Overview.html at its root.

foobar.tar
├── Overview.html
├── css
│   └── style.css
├── sample.html
├── sample.pdf
└── images
    ├── 1.png
    └── 2.jpg

Note: compressed tar files (.tgz, .tar.gz, .tar.bz2, etc) are not supported

How to create a tar for Echidna

The following command will create /tmp/foobar.tar containing a file Overview.html.

cd <path to your spec>
tar cvf /tmp/foobar.tar Overview.html

If you need to create a tar containing multiple files:

tar cvf /tmp/foobar.tar Overview.html <file1> <file2> ...

Manifest file

When your specification does make use of additional resources, i.e. images or external style sheets. Echidna is expected to download all of the additional resources listed in the manifest and publish them all.

The manifest file is simply a list of the resources needed to publish your document, one line per resource. Like the "Staged HTML5 document" method, the manifest should be publicly available on the web.

Notes:

• Use # ... to comment part of a line, it will be ignored by the parser
• if the resource contains a whitespace, the spec-generator will process the file (see below)
• otherwise it will be a relative resource to be fetched and published

It is important to note that the first line in your manifest will be treated as the entry file into your specification. Its name is not relevant (it will be renamed Overview.html by the system before publication).

spec-generator

Echidna will use the spec-generator if a line in the manifest contains a space. The syntax of that line is as follows:

<relative link> <type>

Echidna will then invoke the spec-generator with the link, the type, and today's date.

Note that, at the moment at least, the link itself needs to contain both shortName and specStatus parameters as well when using respec.

Here is a simple manifest line that will trigger the spec-generator with respec:

index.html?specStatus=WD;shortName=frame-timing respec

The resulted output from the spec-generator will then be given to the checkers and eventually published.

Example of manifest

Let's say your manifest is located at http://example.org/foobar/manifest.txt, all the files listed in there are expected to be relative to that manifest. So if you have the following manifest:

index.html
images/manifest-src-directive.svg

echidna will download http://example.org/foobar/index.html and http://example.org/foobar/images/manifest-src-directive.svg

data-editor-id

Specberus (the replacement for the current pubrules checker) will expect you to add editor ids in your document. This is the id associated with the W3C account of the individual, such as '56102', and it needs to appear in the markup:

<dd data-editor-id="6457">plh</dd>

You can find your own id using myprofile, which gets redirected to https://www.w3.org/users/[USER_ID]. Alternatively, you can get this data for anyone using the person search form and scraping the resulting page after search with document.querySelector('#Content a').href.split('/').pop().

Or more neatly, with the W3C API.

data-deliverer

In the case of working group notes only, metadata about the group(s) reponsible for the spec is needed, too:

<p data-deliverer="@@ID1@@,@@ID2@@,...">

ID(s) being the numeric identifier(s) of the corresponding group(s).