Publishing the specs in HTML5

I have now converted the build for the XSLT 3.0 and the F+O 3.1 specifications to generate HTML5, and I have committed the base stylesheets used to achieve this. These two specs (including the diff versions) now validate correctly as HTML5, though there is probably still work needed to get them to validate against pubrules.

Here's the link to F+O

http://www.w3.org/XML/Group/qtspecs/specifications/xpath-functions-31/html/Overview.html <http://www.w3.org/XML/Group/qtspecs/specifications/xpath-functions-31/html/Overview.html>

So editors of other specs should now proceed to do the same...

I would recommend getting rid of the "tidy" step from the build (which you can do by setting

<property name="skiptidy" value="true"/>

I've committed the new versions of the base stylesheets as xmlspec-2016.xsl and xsl-query-2016.xsl. So the first thing to do is to update the imports from local spec-specific stylesheets to pick up these versions.

The xsl-query-2016 stylesheet produces the HTML5 vocabulary, but serializes it as XML. This leaves an XML file available for further processing, e.g. for indexing to create the /etc index files. I then use a one-line query to serialize the XML as HTML5. The typical path is:

     <xslt in="${merged-spec.xml}"
       out="${dist.dir}/Overview.xml"
       style="${spec.style}" force="yes"
       classpathref="saxon9.classpath">
     </xslt>
     
     <antcall target="xml-to-html5">
       <param name="xml-to-html5.input" value="${dist.dir}/Overview.xml"/>
       <param name="xml-to-html5.output" value="${dist.dir}/Overview.html"/>
     </antcall>

To get this to work, my process was:

* generate the Overview.html file

* commit it

* run the W3C validator at https://validator.w3.org/nu/

* fix the errors

* repeat about a dozen times until you get it right

* then do the same on the diff version

Most of the errors related to

(a) use of styling attributes on HTML elements, e.g. width, padding, valign, etc. The base stylesheets handle this if the attributes are present in the source, but it will need attention in the case of tables (etc) generated by the stylesheets themselves.

(b) nested paragraphs (p elements where not expected). In nearly all cases this was fixed by correcting the markup in the original XML. Typical errors are to have a <table> or <ulist> inside a <p>. (In F+O, this is often not caught by the DTD because the spec in "xmlspec" form is generated from the structured function catalog, which therefore bypasses DTD validation).

(c) balancing tables: there needs to be the same number of <td>s in every <tr>.

Any questions, I will try to help.

Carine: one thing that isn't currently working in F+O is the "Quick Contents" list (imediately after the Status section), which for some reason is displayed as one paragraph per entry. I can't work out why (wish I understood CSS better...) Any ideas? 

Michael Kay
Saxonica