[docs] User documentation for xml.sax.xmlreader.Locator

[Steve White]

Martijn Pieters and I exlplored the issue was further at that link.

He pointed out that if the superclass initializer of the Handler is
properly called,
then an undocumented private member "._locator" ought to be
initialized, by which
the user could get the needed Locator object.

This is of course very poor.

If this member is to be used, it should be documented, and it should
be documented when it is initialized.

MUCH BETTER would be to provide a public user interface to obtain this
needed member, such as
handler.getDocumentLocator() (and to document that!!)

Cheers!

On Mon, Mar 18, 2013 at 2:44 PM, Steve White <stevan.white at gmail.com> wrote:
> Hi,
>
> The documentation for xml.sax.xmlreader.Locator leaves something to be
> desired, from the point of view of a user (as opposed to someone who
> is writing a parser.)
>
> A user, for example, might *just* want to parse an XML file, somehow
> keeping track of the element line numbers.
>
> It would be helpful to point out that the Locator interface is
> implemented by real parsers, such as those produced by make_parser,
> and further to explain how to make use of a locator for a given
> parser.
>
> For instance, the (barely documented) ExpatParser which is by default
> produced by make_parser, defines its own Locator, ExpatLocator, which
> can be used... if only you know it's there and how to use it.
>
> I provided an example at
> http://stackoverflow.com/questions/15477363/xml-sax-parser-and-line-numbers-etc
>
> Cheers!