Bug #84695 for Encode: Update piconv documentation

Attached patch improves documentation for piconv.

From dfbf5a241ace75e3838944ed2e030fd06d1ae04d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20P=C3=ADsa=C5=99?= <ppisar@redhat.com> Date: Wed, 17 Apr 2013 13:09:03 +0200 Subject: [PATCH] Update piconv documentation This adds undocumented options to usage output and POD text. --- bin/piconv | 56 +++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 35 insertions(+), 21 deletions(-) diff --git a/bin/piconv b/bin/piconv index 9fdebd1..1172c9c 100755 --- a/bin/piconv +++ b/bin/piconv @@ -147,9 +147,13 @@ sub help { my $message = shift; $message and print STDERR "$name error: $message\n"; print STDERR <<"EOT"; -$name [-f from_encoding] [-t to_encoding] [-s string] [files...] +$name [-f from_encoding] [-t to_encoding] + [-p|--perlqq|--htmlcref|--xmlcref] [-C N|-c] [-D] [-S scheme] + [-s string|file...] $name -l $name -r encoding_alias +$name -h +Common options: -l,--list lists all available encodings -r,--resolve encoding_alias @@ -161,13 +165,17 @@ $name -r encoding_alias -s,--string string "string" will be the input instead of STDIN or files The following are mainly of interest to Encode hackers: - -D,--debug show debug information -C N | -c check the validity of the input + -D,--debug show debug information -S,--scheme scheme use the scheme for conversion -Those are handy when you can only see ascii characters: - -p,--perlqq - --htmlcref - --xmlcref +Those are handy when you can only see ASCII characters: + -p,--perlqq transliterate characters missing in encoding to \x{HHHH} + where HHHH is the hexadecimal Unicode code point + --htmlcref transliterate characters missing in encoding to &#NNN; + where NNN is the decimal Unicode code point + --xmlcref transliterate characters missing in encoding to &#xHHHH; + where HHHH is the hexadecimal Unicode code point + EOT exit; } @@ -180,12 +188,11 @@ piconv -- iconv(1), reinvented in perl =head1 SYNOPSIS - piconv [-f from_encoding] [-t to_encoding] [-s string] [files...] + piconv [-f from_encoding] [-t to_encoding] + [-p|--perlqq|--htmlcref|--xmlcref] [-C N|-c] [-D] [-S scheme] + [-s string|file...] piconv -l - piconv [-C N|-c|-p] - piconv -S scheme ... - piconv -r encoding - piconv -D ... + piconv -r encoding_alias piconv -h =head1 DESCRIPTION @@ -198,17 +205,17 @@ place of iconv for virtually any case. piconv converts the character encoding of either STDIN or files specified in the argument and prints out to STDOUT. -Here is the list of options. Each option can be in short format (-f) -or long (--from). +Here is the list of options. Some options can be in short format (-f) +or long (--from) one. =over 4 -=item -f,--from from_encoding +=item -f,--from I<from_encoding> Specifies the encoding you are converting from. Unlike B<iconv>, this option can be omitted. In such cases, the current locale is used. -=item -t,--to to_encoding +=item -t,--to I<to_encoding> Specifies the encoding you are converting to. Unlike B<iconv>, this option can be omitted. In such cases, the current locale is used. @@ -229,6 +236,10 @@ and common aliases work, such as "latin1" for "ISO-8859-1", or "ibm850" instead of "cp850", or "winlatin1" for "cp1252". See L<Encode::Supported> for a full discussion. +=item -r,--resolve I<encoding_alias> + +Resolve I<encoding_alias> to Encode canonical encoding name. + =item -C,--check I<N> Check the validity of the stream if I<N> = 1. When I<N> = -1, something @@ -240,15 +251,18 @@ Same as C<-C 1>. =item -p,--perlqq -=item --htmlcref +Transliterate characters missing in encoding to \x{HHHH} where HHHH is the +hexadecimal Unicode code point. -=item --xmlcref +=item --htmlcref -Applies PERLQQ, HTMLCREF, XMLCREF, respectively. Try +Transliterate characters missing in encoding to &#NNN; where NNN is the +decimal Unicode code point. - piconv -f utf8 -t ascii --perlqq +=item --xmlcref -To see what it does. +Transliterate characters missing in encoding to &#xHHHH; where HHHH is the +hexadecimal Unicode code point. =item -h,--help @@ -258,7 +272,7 @@ Show usage. Invokes debugging mode. Primarily for Encode hackers. -=item -S,--scheme scheme +=item -S,--scheme I<scheme> Selects which scheme is to be used for conversion. Available schemes are as follows: -- 1.8.1.4