Un-revert "[MERGE] add+use si_cxsubix field"

[perl5.git] / pod / perlpod.pod

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 7333fcc..9f494a6 100644 (file)
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -154,7 +154,11 @@ And perhaps most importantly, keep the items consistent: either use
 "=item *" for all of them, to produce bullets; or use "=item 1.",
 "=item 2.", etc., to produce numbered lists; or use "=item foo",
 "=item bar", etc.--namely, things that look nothing like bullets or
-numbers.
+numbers.  (If you have a list that contains both: 1) things that don't
+look like bullets nor numbers,  plus 2) things that do, you should
+preface the bullet- or number-like items with C<ZE<lt>E<gt>>.  See
+L<ZE<lt>E<gt>|/ZE<lt>E<gt> -- a null (zero-effect) formatting code>
+below for an example.)
 
 If you start with bullets or numbers, stick with them, as
 formatters use the first "=item" type to decide how to format the
@@ -282,11 +286,16 @@ be for formatting as a footnote).
 X<=encoding> X<encoding>
 
 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
+users won't need this; but if your encoding isn't US-ASCII,
+then put a C<=encoding I<encodingname>> command very 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:
+module.  Some pod formatters may try to guess between a Latin-1 or
+CP-1252 versus
+UTF-8 encoding, but they may guess wrong.  It's best to be explicit if
+you use anything besides strict ASCII.  Examples:
+
+  =encoding latin1
 
   =encoding utf8
 
@@ -296,14 +305,16 @@ module.  Examples:
 
   =encoding big5
 
-=back
-
 C<=encoding> affects the whole document, and must occur only once.
 
-And don't forget, when using any other command, that the command lasts up
+=back
+
+And don't forget, all commands but C<=encoding> last up
 until the end of its I<paragraph>, not its line.  So in the
 examples below, you can see that every command needs the blank
-line after it, to end its paragraph.
+line after it, to end its paragraph.  (And some older Pod translators
+may require the C<=encoding> line to have a following blank line as
+well, even though it should be legal to omit.)
 
 Some examples of lists include:
 
@@ -499,7 +510,7 @@ in decimal, as in C<EE<lt>181E<gt>>.
 Note that older Pod formatters might not recognize octal or
 hex numeric escapes, and that many formatters cannot reliably
 render characters above 255.  (Some formatters may even have
-to use compromised renderings of Latin-1 characters, like
+to use compromised renderings of Latin-1/CP-1252 characters, like
 rendering C<EE<lt>eacuteE<gt>> as just a plain "e".)
 
 =back
@@ -533,6 +544,41 @@ EE<lt>...E<gt> code sometimes.  For example, instead of
 the "E<lt>" so they can't be considered
 the part of a (fictitious) "NE<lt>...E<gt>" code).
 
+Another use is to indicate that I<stuff> in C<=item ZE<lt>E<gt>I<stuff...>>
+is not to be considered to be a bullet or number.  For example,
+without the C<ZE<lt>E<gt>>, the line
+
+ =item Z<>500 Server error
+
+could possibly be parsed as an item in a numbered list when it isn't
+meant to be.
+
+Still another use is to maintain visual space between C<=item> lines.
+If you specify
+
+ =item foo
+
+ =item bar
+
+it will typically get rendered as
+
+ foo
+ bar
+
+That may be what you want, but if what you really want is
+
+ foo
+
+ bar
+
+you can use C<ZE<lt>E<gt>> to accomplish that
+
+ =item foo
+
+ Z<>
+
+ =item bar
+
 =for comment
  This was formerly explained as a "zero-width character".  But it in
  most parser models, it parses to nothing at all, as opposed to parsing