[XML-SIG] Documentation and problems

[Lars Marius Garshol]

* Simon Pepping
| 
| Check it out at http://www.hobby.nl/~scaprea/XML/index.html.

I've now read through your document more thoroughly and have some
corrections to it:

 - the application should _not_ register the driver as a locator.
   The drivers that provide location information do this themselves
   before calling the startDocument method. Those that don't simply 
   do not register a locator.

   In fact, you have no guarantee that the parser and the locator are
   the same object...

 - In <URL:http://www.hobby.nl/~scaprea/XML/t128.html> the last
   paragraph repeats this.

 - In <URL:http://www.hobby.nl/~scaprea/XML/t141.html> you write:

   "A SAX application must contain the handler classes
   DocumentHandler, DTDHandler, EntityResolver, and ErrorHandler,
   which should implement the methods prescribed by the SAX
   specification."

   SAX applications don't have to implement any of these at all, and
   in fact there exists an application that doesn't (saxtimer.py).
   
   So the text should say 'can' instead of 'must'. (A nit, I know, but
   one that would confuse literal-minded people like myself. :)

 - In <URL:http://www.hobby.nl/~scaprea/XML/t141.html> it would be
   nice if you mentioned a little-known fact:

     - saxutils.py defines two useful error handlers: ErrorPrinter and
       ErrorRaiser, both of which can be used directly if their
       behaviour is what your application needs.

 - In the same page you write on the last line:

   "At the end of the parse, your application may stop. Or it may
   continue, especially if it has stored data in memory."

   Perhaps it's better to say:

   "At the end of the parse, the SAX driver returns from the parse or
   parseFile method and your application is free to do whatever it
   wants."

 - In <URL:http://www.hobby.nl/~scaprea/XML/t173.html> you write:

   "The saxexts module defines a ParserFactory class. Upon import it
   makes an instance of it, called XMLParserFactory, which lists all
   known SAX-compliant XML parsers (actually it lists their driver
   modules). [It also makes instances with known validating XML
   parsers, HTML parsers and SGML parsers.]"

   A consequence of this is that you are wrong when you write on the
   previous page that "SAXparser=xml.sax.saxexts.make_parser()" is
   always the best method. It's not if you have special parser
   requirements.

Despite this I think this is a very useful document and that it
definitely fills a need. I've linked to it from the saxlib home page.
(The link may not become visible before tomorrow.)

--Lars M.