PubrulesHowTo

From DAP WG Wiki
Jump to: navigation, search

Workflow for the current PubRules checker

  1. Change the ReSpec metadata appropriately (e.g. WD instead of LC, previous publication date and status, etc.). Set the publication date to the following Tuesday or Thursday.
  2. Commit, reload, make sure everything looks fine. Note that due to the browser security model it is currently required to generate the final draft *online* and not from your local drive copy.
  3. If all looks good, hit Ctrl-Alt-Shift-S to bring up the save dialog. Click on "Save as HTML (Source)". This will give you a dump of the source. Copy that into a new document in the repo (called e.g. WD2.html, LC.html, etc.), add, commit.
  4. Visit the static snapshot. If it looks good, check it using http://www.w3.org/2005/07/pubrules. The "Auto checker" setting works well. Alternatively, use the "Manual checked" and set the option to "Show only errors and warnings" which makes for a shorter, much easier to read report. If you do pick the manual approach, also select "Check namespaces manually" (it'll be faster and will avoid false negatives) and hand pick the right "Document status". You can leave the rest untouched.
  5. If pubrules reports a problem, it can fall into several categories:
    1. It's actually a core pubrules problem (rare). If so, it's probably a bug in ReSpec or a problematic configuration setting.
    2. It's a CSS validity error. Following the provided link to the CSS validator; if all you see is a handful of warnings about CSS 3 properties being used in a CSS 2 context you can ignore it.
    3. It's an HTML validity error. That's probably a real problem with the draft. Often it's duplicated IDs, or some similar issues. The painful thing here is that you might need to go all the way back to step 2 when fixing those errors. If they're few and small enough, what you may want to do is fix both the source (so it doesn't bite me next time) and the generated snapshop without going through the regeneration phase.
  6. Once pubrules is good to go, head to http://validator.w3.org/checklink. You don't need to tinker with the options, just run the checker. You will *always* get a line in the report indicating that "Accessing links with this URI scheme has been disabled in link checker." Ignore that (it's for the mailto:). You will also always get a 404 for the "This version" URI since by definition it hasn't been published. Ignore that too. Beyond that, every 404 is something you will need to fix (possibly returning to step 2, but again generally just fix the links in both source and snapshot directly). Additionally, pay attention to what it reports on anchors: it is also disallowed to have internal links in the document that don't resolve, or even links to external documents that don't give a 404 but for which the #fragID doesn't resolve. Again, fix.

Congrats! You now have a document that's ready to publish \o/

Note that this isn't the end, depending on the maturity level the chair may need to do a TranReq. Then the document needs to be sent to WebReq. And then for some documents you need a transition announcement. But let's keep those fascinating topics for a future tutorial ;-)

This guide is adapted from Robin Berjon's most helpful email. Thanks Robin for this fascinating primer to the wonderful world of pubrules :-)