Tips on publishing ReSpec-based documents

From RDF Working Group Wiki
Revision as of 18:57, 7 May 2013 by Sandro (Talk | contribs)

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:

  • The URL included for the W3C style sheet and the W3C logo start with "https". This generates an pubrules error. Change to "http" in the Overview.html (so you have to repeat this in every cycle :( ).
  • 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.
  • If you want to prevent HTML validation errors you must switch off the feature for generating RDFa (at end of the ReSpec attribute section).