XHTML and the website

[Ceri Davies]

On Mon, Apr 07, 2003 at 11:10:41AM +0100, Ceri Davies wrote:
> On Sun, Apr 06, 2003 at 04:03:07PM -0700, Bruce A. Mah wrote:
> > If memory serves me right, Ceri Davies wrote:
> > 
> > > In August last year, a commit was made to change the website to XHTML, and
> > > since then, all the documents built from SGML have been happily announcing
> > > in their DOCTYPE declaration that they are XHTML 1.0 Transitional.
> > > However, with the exception of the front page of the web site, they aren't;
> > > none of them validate.
> > 
> > I might note that all of the documents in our documentation set also
> > claim to be XHTML.  I wonder about them?  If they're compliant, fixing
> > *them* might be kind of hard since a lot of the XHTML is generated
> > from the toolchain.
> 
> It won't take me long to find out how hard this is likely to be; I'll take
> a look at it sometime this week.

OK, here's the update.

www/ is really really easy, but there is the donkey work that we previously
discussed.

As Bruce suggested, fixing them in the default case is going to be hard, as
the toolchain won't allow it - the documents don't validate because attributes
must be in lower case, and the toolchain doesn't generate lower case attributes.

However, if we use the xsl stylesheets, then we stand a chance (although there
is no way that we can make this the default; the XML stuff doesn't support a
number of things that we use; see item 4 below for one).

I've put a patch that gets doc/ building again with STYLESHEET_TYPE set to
"xsl" up at http://submonkey.net/FreeBSD/xsl.diff.

Here are the caveats (that I remember):

1. The stuff in doc.docbook.mk is really ugly; not a major concern for me
   at the moment though.

2. Some of the documents still don't validate; this is because the footer from
   freebsd-html.xsl reads like this:

  <xsl:template name="user.footer.content">
    <p align="center"><small>This, and other documents, can be downloaded 
    from <a href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/</a></small></p>

    <p align="center"><small>For questions about FreeBSD, read the 
    <a href="http://www.FreeBSD.org/docs.html">documentation</a> before 
    contacting <<a href="mailto:questions at FreeBSD.org">questions at FreeBSD.org</a>>.<br/>
    For questions about this documentation, e-mail <<a href="mailto:doc at FreeBSD.org">doc at FreeBSD.org</a>>.</small></p>
  </xsl:template>

  For some reason that I just cannot fathom, xsltproc is messing up the <p>
  elements and inserting this:

	<p xmlns="http://www.w3.org/TR/xhtml1/transitional"
	align="center"><small>This, and other documents, can be
	[...]

  Since that's not a valid attribute for the p element in XHTML, the final
  pages don't validate.  Other than that, they mostly seem fine (see #3).

3. The committer's guide doesn't build properly; the first page is missing.
   I suspect this is due to something in the way it's marked up, but haven't
   investigated fully yet.

4. The handbook doesn't build properly.
   This is because we're using parameter entities within marked sections and
   they don't work with XML docs.  The problematic bits are:

	<![ %chap.mail;                     [ &chap.mail;                 ]]>

   The chapters just get omitted from the built document.

5. You get reams of warnings from sgmlnorm when ${DOC}.xml is being created.
   The pre-patch version of doc.docbook.mk redirected them to a file, but I'm
   having it show them, as I don't know how to shut it up.

So to summarize, the docs/ are no good as XHTML; I'd still like to get the
stuff under www/ to validate, but it may be worth switching away from XHTML
again anyway due to the doc/ problems (although whether this actually *is* a
problem is open to debate).

I'd like to commit the attached patch if there are no objections, as it
does at least allow the build to finish, even if some of the documents are
broken; at the moment the build fails almost immediately.
Yes, my patch cheats.

Also, does anyone know if a command line version of the w3c's validator is
available ?  I'm getting rather bored of visiting their website...

Cheer,

Ceri
-- 
As Zeus said to Narcissus, "Watch yourself."