|Subject:||various documentation issues and complaints about switch from Text::Iconv|
1.) There are a number stray characters in the documentation of dubious encoding. (Documented in patch file). 2.) The implementation of the Encoder was changed from Text::Iconv to Encode without updating the documentation. (Documented in patch file).# 3.) Actually since this is an object oriented implementation what was the point of discontinuing support for Text::Iconv? What would it have cost you to continue maintaining it? 4.)In particular in the Debian packaging of 0.52 it was documented that how one could implement error handling using Text::Iconv. Could you put some thought into encoding error handling? 5.) Could we have proper pod documentation for each of the supported modules?
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. Author: Florian Ragwitz <firstname.lastname@example.org> Last-Update: 2010-08-19 Reviewed-By: Nicholas Bamber <email@example.com> --- 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 -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 @@ -460,7 +460,7 @@ 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. @@ -482,7 +482,7 @@ =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 @@ -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<Encode> 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<not> 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