| | 334 | |
| | 335 | =item "=encoding encodingname" |
| | 336 | |
| | 337 | This command, which should occur early in the document (at least |
| | 338 | before any non-US-ASCII data!), declares that this document is |
| | 339 | encoded in the encoding I<encodingname>, which must be |
| | 340 | an encoding name that L<Encoding> recognizes. (Encoding's list |
| | 341 | of supported encodings, in L<Encoding::Supported>, is useful here.) |
| | 342 | If the Pod parser cannot decode the declared encoding, it |
| | 343 | should emit a warning and may abort parsing the document |
| | 344 | altogether. |
| | 345 | |
| | 346 | A document having more than one "=encoding" line should be |
| | 347 | considered an error. Pod processors may silently tolerate this if |
| | 348 | the not-first "=encoding" lines are just duplicates of the |
| | 349 | first one (e.g., if there's a "=use utf8" line, and later on |
| | 350 | another "=use utf8" line). But Pod processors should complain if |
| | 351 | there are contradictory "=encoding" lines in the same document |
| | 352 | (e.g., if there is a "=encoding utf8" early in the document and |
| | 353 | "=encoding big5" later). Pod processors that recognize BOMs |
| | 354 | may also complain if they see an "=encoding" line |
| | 355 | that contradicts the BOM (e.g., if a document with a UTF-16LE |
| | 356 | BOM has an "=encoding shiftjis" line). |
