Re: [Docutils-users] XHTML question

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Greg Ward wrote:
> By default Docutils generates HTML that starts with these two lines:
> 
> <?xml version="1.0" encoding="us-ascii"?>

This is known as the "XML declaration".  The "<?...?>" construct is
a "processing instruction".  I've added a space just before the
closing "?>" in the writer; it's legal, shouldn't hurt, and may make a
difference.

Processing instructions have been around since the beginning of SGML,
so are already a part of HTML.  SGML processing instructions look a
bit different though: "<?...>"; no closing "?".

> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
> "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

This is the "document type declaration".  It declares the "document
type definition" (DTD) which is the schema of the document.

> That looks fine to me, but the web hosting provider for my personal
> web page (www.gerg.ca) is using some server-side software that gags
> on it.  For example, compare
>   http://www.gerg.ca/software/optik/basic.html
> with 
>   http://optik.sourceforge.net/basic.html
> 
> If I remove the "<?xml ... ?>" line from the www.gerg.ca copy, it
> works just fine.
> 
> I'm 99% sure that Docutils is in the right, and the server-side
> expansion done by my web hosting provider is broken.  However, I
> would like to be able cite chapter and verse of the XHTML spec to
> prove my point.  Can someone point me in the right direction?

The XHTML spec is here: <http://www.w3.org/TR/xhtml1>.  Appendix C is
a must-read.  HTML's spec is here: <http://www.w3.org/TR/html>.

The XML spec is here: <http://www.w3.org/TR/REC-xml>.  Section 2.1,
"Well-Formed XML Documents", lists the constructs making up an XML
document.  Section 2.8, "Prolog and Document Type Declaration",
states:

    [Definition: XML documents should begin with an XML declaration
    which specifies the version of XML being used.]

The spec lists the exact meaning of "should".  It wouldn't be
difficult to add a setting/option to avoid outputting the XML
declaration.  However, XHTML appendix C.1, "Processing Instructions
and the XML Declaration", says

    Be aware that processing instructions are rendered on some user
    agents. However, also note that when the XML declaration is not
    included in a document, the document can only use the default
    character encodings UTF-8 or UTF-16.

US-ASCII *is* a subset of UTF-8, however ISO-Latin-1 *is not*.

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/