Date: Sun, 13 Apr 2003 21:00:45 +0100 From: Ceri Davies <ceri@FreeBSD.org> To: bmah@FreeBSD.org, www@FreeBSD.org, doc@FreeBSD.org Subject: Re: XHTML and the website Message-ID: <20030413200045.GA97520@submonkey.net> In-Reply-To: <20030407101041.GA4506@submonkey.net> References: <20030405151719.GA75703@submonkey.net> <20030406230307.GA33473@intruder.bmah.org> <20030407101041.GA4506@submonkey.net>
next in thread | previous in thread | raw e-mail | index | archive | help
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@FreeBSD.org">questions@FreeBSD.org</a>>.<br/> For questions about this documentation, e-mail <<a href="mailto:doc@FreeBSD.org">doc@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."
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030413200045.GA97520>