Pub-Process

From SPARQL Working Group
Jump to: navigation, search

Here is a wiki write-up of my initial email about the publication process:

I use a Mac, so the xsltproc step (3) might be different for others.

  1. Adjust your .xml file (for me that is xmlspec.xml in the entailment folder)
    1. <!ENTITY draft.year "2012">
    2. <!ENTITY draft.month.name "January">
    3. <!ENTITY draft.month "01">
    4. <!ENTITY draft.day "02"> to the new pub date and possibly
    5. <!ENTITY maturity.level "WD"> (as fits, LC is also WD)
    6. Within the <prevlocs> tag, update the previous version date to the last WD, e.g., for the current doc the previous version tag should be <loc href="http://www.w3.org/TR/2011/WD-sparql11-entailment-20110512/">http://www.w3.org/TR/2011/WD-sparql11-entailment-20110512/</loc>
    7. Change <spec w3c-doctype="review" xml:lang="en"> to <spec w3c-doctype="wd" xml:lang="en">, i.e., review is replaced by wd
    8. Change status section
      1. Non-LC: Change the status section to have a sentence like <p>This document is a <a href="http://www.w3.org/2005/10/Process-20051014/tr.html#RecsWD">Working Draft</a>.</p> instead of <p>This document is an <a href="http://www.w3.org/2005/10/Process-20051014/tr.html#RecsWD">Editors' Draft</a>.</p>
      2. LC: Change the status section to have a sentence like <p>This document is a <a href="http://www.w3.org/2005/10/Process-20051014/tr.html#last-call">Last Call Working Draft</a>. Publication as a Last Call Working Draft indicates that the <a href="http://www.w3.org/2001/sw/DataAccess/">SPARQL Working Group</a> believes it has addressed all substantive issues and that the document is stable. The Working Group expects to advance this specification to <a href="http://www.w3.org/2004/02/Process-20040205/tr.html#RecsW3C">Recommendation Status</a>.</p><p>Comments on this document should be sent to public-rdf-dawg-comments@w3.org, a mailing list with a public archive. Comments on this working draft are due on or before <strong>29 July 2011</strong>.</p> (see Entailment regimes example)
    9. Double check in a browser the all dates are correct and the file still displays correctly
  2. Open a shell and cd to the folder of the xml file (xmlspec.xml in my case)
  3. xsltproc -o gen.html xmlspec.xml
    This will generate the html version of my file which can be checked by the pub rule tools
  4. Check if the "This version:" link is the correct link to the supposed final link in the html file, for example: <dt>This version:</dt><dd><a href="http://www.w3.org/TR/2012/WD-sparql11-entailment-20120102/">http://www.w3.org/TR/2012/WD-sparql11-entailment-20120102/</a></dd>
  5. Truncate the CVS log to entries since the last WD, this also addresses the requirement that the WD publication

includes a log of changes since the last published version.

  1. Commit the generated gen.html into CVS
  2. Figure out the complete URL of gen.html
    I go to the WG wiki, click on my editor's draft link and change xmlspec.xml to gen.html
  3. Now we can do the checking. When the checking shows errors, I try to fix all the errors in the xmlspec.xml and start again from the top. This way I won't have to change the same errors in each publication round.
    1. Go to pub rules webpage and enter the complete URL for gen.html and run the checker or enter http://www.w3.org/2009/sparql/docs/entailment/gen.html,pubrules, i.e., yourURL,pubrules
      This should give one error at least:
      http://www.w3.org/TR/2010/WD-sparql11-entailment-20101014/ (1 occurrence)
      -> 404 (Not Found)
      Since the doc that we are going to publish on 14 Oct 2010 is not yet there, we are just preparing the publication.
      Other errors have to be explained I guess (e.g., we have the rif:imports URI which is a placeholder and does not yet exist)
    2. On the pub rules result page there is a menu on the right hand side with a Tools section. From there I select the link checker.
      This should give an error such as
      Line: 42 http://www.w3.org/TR/2010/WD-sparql11-entailment-20101014/
      Status: 404 Not Found
      because the document is not yet published, but already mentioned in the boilerplate stuff.
      Other errors should be fixed (latest by the chairs).
    3. From the pub rules page there is also a link to the markup validator or enter http://www.w3.org/2009/sparql/docs/entailment/gen.html,validate
      This should not give errors.
    4. Finally, I go to the CSS validator from the pub rules Tools menu and enter the URL for gen.html
      This should not give errors.
    5. W3C requires conformance with Web Content Accessibility Guidelines 2.0, Level AA. This can be checked with AChecker
      I never did that before and now that I did I found that xmlspec.xsl does not produce accessible html files. I fixed that now (b tags for bold should be strong tags, i should be em, tables from ednotes should not have a summary) and my document now validates.
  4. Copy the checked gen.html into the folder pub into a subfolder labeled with the pub date and there into a subfolder for the file (entailment in my case), this folder lies under WWW/2009/sparql/docs/pub on CVS.
  5. Change your xml version back to editors' draft (xmlspec.xml in the entailment folder for me)
    1. Change <spec w3c-doctype="wd" xml:lang="en"> back to <spec w3c-doctype="review" xml:lang="en">
    2. Change the status section back to have a sentence like <p>This document is an <a href="http://www.w3.org/2005/10/Process-20051014/tr.html#RecsWD">Editors' Draft</a>.</p> instead of <p>This document is a <a href="http://www.w3.org/2005/10/Process-20051014/tr.html#RecsWD">Working Draft</a>.</p>
  6. Commit everything to CVS.


All done, up to Lee, Axel and the webmasters now I hope.