How-to: writing documentation with respec

The head section

Title of the document

The head section of the HTML file must contain the title of the page using tags <title<...</title>. respec will automatically extract the title and put it into the <h1>...</h1> tags of the body.

Including respec

The respec script is included in the head section of the html file with:

	    <script src="http://pandora.aptest.com/w3c/respec-style/builds/respec-w3c-common.js"
	    class="remove">
	    </script>

Online it is possible to find other URLs through which import respec, but using them I experienced problems, so I strongly advice to use this one from aptest.

Settings for respec

Writing documentation is as simple as writing an HTML file, but a few lines of javascript are necessary to set respec parameters. An example is reported here:

<script class='remove'>
    var respecConfig = {

    // document info
    specStatus:           "ED",
    shortName:            "sap",
    copyrightStart:       "2017",
    edDraftURI:           "http://github.com/desmovalvo/sap-documentation",
    extraCSS:             ["css/respec.css"],

    // editors
    editors:  [{
        name: "Fabio Viola",
        url: "http://wot.arces.unibo.it",
        mailto: "fabio.viola@unibo.it",
        company: "ARCES",
        companyURL: "http://wot.arces.unibo.it"
    },
    {
        name: "Luca Roffia",
        url: "http://wot.arces.unibo.it",
        mailto: "luca.roffia@unibo.it",
        company: "ARCES",
        companyURL: "http://wot.arces.unibo.it"
    }],

    // WG
    wg:           "Web of Things working group of the ARCES laboratory",
    wgURI:        "http://wot.arces.unibo.it/",
};
</script>

For a complete list of javascript variables have a look at the respec wiki on github

The body section

The body of the HTML page is structured defining one or more (eventually nested) <section>...</section> blocks, each one provided with a proper <h*>...</h*> tag (to state the title of the (sub)section).

The abstract

The first <section>...</section> block should be named abstract and should contain the abstract of the document. Here's an example:

<section id="abstract">
    <p>
        This is a simple abstract for my document.
    </p>
</section>

Status of the document

If a section named sotd is present, then respec will build the section "Status of this document". Inside every section, text should be organized in paragraphs using <p>...</p>. Examples of source code should be enclosed between <pre class="example">...</pre>, while short pieces of code should be enclosed between <code>...</code>.

Keywords

respec automatically recognizes the following keywords: MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY,

References

If you need to refer to a document present on SpecRef (pay attention, specref, not respec!), the process is really easy! Find the document and take note of the friendly name. Then, references can be included in an easy way with a couple of double square brackets surrounding the friendly name. If this name is preceeded by an exclamation mark, then it is a normative reference, otherwise it is an informative reference. For example to refer to the JSON RFC, we simply look for JSON on specref and find that [[rfc7159]] may be right for us. It produces: [[rfc7159]].

Writing acknowledgements

To include acknowlegements in a document a particular section belonging to class appendix must be created.

Introduction