Tips on publishing ReSpec-based documents

From RDF Working Group Wiki
Revision as of 16:18, 4 July 2013 by Mlanthal (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

ReSpec version to use:

 https://www.w3.org/Tools/respec/respec-w3c-common

RDF local copy of the biblio file in the Mercurial repository:

 rdf/ReSpec.js/bibref/biblio.js

Publication steps:

  1. Check the ReSpec document with the W3C pub rules checker, ignoring the ReSpec-related errors/warnings (style sheet, boiler-plate stuff). Make sure you set the right document type on the checker page. This way you can spot things like HTML and link validation errors.
  2. Get the HTML source (not XHTML) of the ReSpec document with shift-ctrl-alt-S
  3. Save the source, e.g. with Emacs
  4. Place the saved version in the Mercurial repository on the following location: drafts/<short-name>/Overview.html
  5. Add/commit/push the file
  6. Check W3C pub rules on the file. If you find errors, you have to edit the source and redo the steps above, unfortunately.


Issues wrt validation of the HTML source generated by ReSpec:

  • Most likely your document won't validate with the standard validator due to the embedded RDFa. You should use http://validator.w3.org/nu/ instead which supports RDFa.
  • The URL included for the W3C style sheet and the W3C logo start with "https". This generates an pubrules error but is fine. Just make sure to remember the webmaster that it is in fact better to use https
  • The short name you enter for the ReSpec attribute "Latest recommendation" needs to have a trailing slash, as ReSpec forgets to add it, and thus will lead to a redirect warning of the link checker.