diff options
| author | Sean M. Burke <sburke@cpan.org> | 2003-09-06 19:08:28 -0800 |
|---|---|---|
| committer | Jarkko Hietaniemi <jhi@iki.fi> | 2003-09-09 09:50:13 +0000 |
| commit | a179871ba0a4416951234c6b0cf01884909b8e1f (patch) | |
| tree | 250c9fdeb56c6791dbd86ea7f770f86bc8b5c147 | |
| parent | 8becbb3b066adee4495175867634bdba48ae2c5d (diff) | |
| download | perl-a179871ba0a4416951234c6b0cf01884909b8e1f.tar.gz | |
=encoding in perlpod/perlpodspec
Message-ID: <5.2.1.1.1.20030907030717.00a6aaa0@mailstore.pobox.com>
p4raw-id: //depot/perl@21137
| -rw-r--r-- | pod/perlpod.pod | 17 | ||||
| -rw-r--r-- | pod/perlpodspec.pod | 23 |
2 files changed, 40 insertions, 0 deletions
diff --git a/pod/perlpod.pod b/pod/perlpod.pod index 732cdfd626..955d706ef8 100644 --- 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 7387258634..0b35663d20 100644 --- 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 |