Subject: Fix documentation issues * add more documentation on encoding errors * Implementation moved from Text::Iconv to Encode without updating documentation. Also the change broke Florian's suggestion. * Stripped a number of stray characters of dubious encoding. These appear to be blank in the code, appear as 'A' in the man page, and 'A^' in the CPAN web page. * Added '*' in lest to make man page look correct Author: Florian Ragwitz Last-Update: 2010-08-22 Bug: http://rt.cpan.org/Ticket/Display.html?id=60504 Reviewed-By: Nicholas Bamber --- a/lib/XML/SAX/Writer.pm +++ b/lib/XML/SAX/Writer.pm @@ -437,16 +437,16 @@ =item * new(%hash) -This is the constructor for this object.  It takes a number of +This is the constructor for this object. It takes a number of parameters, all of which are optional. -=item -- Output +=item * -- Output -This parameter can be one of several things.  If it is a simple +This parameter can be one of several things. If it is a simple scalar, it is interpreted as a filename which will be opened for -writing.  If it is a scalar reference, output will be appended to this -scalar.  If it is an array reference, output will be pushed onto this -array as it is generated.  If it is a filehandle, then output will be +writing. If it is a scalar reference, output will be appended to this +scalar. If it is an array reference, output will be pushed onto this +array as it is generated. If it is a filehandle, then output will be sent to this filehandle. Finally, it is possible to pass an object for this parameter, in which @@ -456,11 +456,11 @@ If this parameter is not provided, then output is sent to STDOUT. -=item -- Escape +=item * -- Escape This should be a hash reference where the keys are characters sequences that should be escaped and the values are the escaped form -of the sequence.  By default, this module will escape the ampersand +of the sequence. By default, this module will escape the ampersand (&), less than (<), greater than (>), double quote ("), and apostrophe ('). Note that some browsers don't support the ' escape used for apostrophes so that you should be careful when outputting XHTML. @@ -468,24 +468,24 @@ If you only want to add entries to the Escape hash, you can first copy the contents of %XML::SAX::Writer::DEFAULT_ESCAPE. -=item -- CommentEscape +=item * -- CommentEscape Comment content often needs to be escaped differently from other content. This option works exactly as the previous one except that by default it only escapes the double dash (--) and that the contents can be copied from %XML::SAX::Writer::COMMENT_ESCAPE. -=item -- EncodeFrom +=item * -- EncodeFrom The character set encoding in which incoming data will be provided. This defaults to UTF-8, which works for US-ASCII as well. -=item -- EncodeTo +=item * -- EncodeTo -The character set encoding in which output should be encoded.  Again, +The character set encoding in which output should be encoded. Again, this defaults to UTF-8. -=item -- QuoteCharacter +=item * -- QuoteCharacter Set the character used to quote attributes. This defaults to single quotes (') for backwards compatiblity. @@ -588,10 +588,9 @@ =head1 THE ENCODER INTERFACE Encoders can be plugged in to allow one to use one's favourite encoder -object. Presently there are two encoders: Iconv and NullEncoder, and -one based on C ought to be out soon. They need to implement -two methods, and may inherit from XML::SAX::Writer::NullConverter if -they wish to +object. Presently there are two encoders: Encode and NullEncoder. They +need to implement two methods, and may inherit from +XML::SAX::Writer::NullConverter if they wish to =over 4 @@ -605,6 +604,11 @@ =back +Note that the return value of the convert method is B checked. Output may +be truncated if a character couldn't be converted correctly. To avoid problems +the encoder should take care encoding errors itself, for example by raising an +exception. + =head1 CUSTOM OUTPUT This module is generally used to write XML -- which it does most of the