=encoding in perlpod/perlpodspec

Message-ID: <5.2.1.1.1.20030907030717.00a6aaa0@mailstore.pobox.com>

p4raw-id: //depot/perl@21137

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 732cdfd..955d706 100644 (file)
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -269,6 +269,23 @@ to signal that the text is not raw data, but instead I<is> Pod text
 normal formatting (e.g., may not be a normal-use paragraph, but might
 be for formatting as a footnote).
 
+=item C<=encoding I<encodingname>>
+
+This command is used for declaring the encoding of a document.  Most
+users won't need this; but if your encoding isn't US-ASCII or Latin-1,
+then put a C<=encoding I<encodingname>> command early in the document so
+that pod formatters will know how to decode the document.  For
+I<encodingname>, use a name recognized by the L<Encode::Supported>
+module.  Examples:
+
+  =encoding utf8
+
+  =encoding koi8-r
+  
+  =encoding ShiftJIS
+  
+  =encoding big5
+
 =back
 
 And don't forget, when using any command, that the command lasts up

diff --git a/pod/perlpodspec.pod b/pod/perlpodspec.pod
index 7387258..0b35663 100644 (file)
--- a/pod/perlpodspec.pod
+++ b/pod/perlpodspec.pod
@@ -332,6 +332,29 @@ then "text..." will constitute a data paragraph.  There is no way
 to use "=for formatname text..." to express "text..." as a verbatim
 paragraph.
 
+=item "=encoding encodingname"
+
+This command, which should occur early in the document (at least
+before any non-USASCII data!), declares that this document is
+encoded in the encoding I<encodingname>, which must be
+an encoding name that L<Encoding> recognizes.  (Encoding's list
+of supported encodings, in L<Encoding::Supported>, is useful here.)
+If the Pod parser cannot decode the declared encoding, it 
+should emit a warning and may abort parsing the document
+altogether.
+
+A document having more than one "=encoding" line should be
+considered an error.  Pod processors may silently tolerate this if
+the not-first "=encoding" lines are just duplicates of the
+first one (e.g., if there's a "=use utf8" line, and later on
+another "=use utf8" line).  But Pod processors should complain if
+there are contradictory "=encoding" lines in the same document
+(e.g., if there is a "=encoding utf8" early in the document and
+"=encoding big5" later).  Pod processors that recognize BOMs
+may also complain if they see an "=encoding" line
+that contradicts the BOM (e.g., if a document with a UTF16LE BOM
+has an "=encoding shiftjis" line).
+
 =back
 
 If a Pod processor sees any command other than the ones listed