Configure: signbit scan assuming too much

[perl5.git] / pod / perlpod.pod

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 827548b..41053af 100644 (file)
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -98,10 +98,8 @@ heading.  For example:
 
   =head2 Object Attributes
 
 
   =head2 Object Attributes
 

-The text "Object Attributes" comprises the heading there.  (Note that
-head3 and head4 are recent additions, not supported in older Pod
-translators.)  The text in these heading commands can use
-formatting codes, as seen here:
+The text "Object Attributes" comprises the heading there.
+The text in these heading commands can use formatting codes, as seen here:

 
   =head2 Possible Values for C<$/>
 
 
   =head2 Possible Values for C<$/>
 


@@ -155,7 +153,7 @@ Don't put "=headI<n>" commands inside an "=over" ... "=back" region.
 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",
 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
+"=item bar", etc.--namely, things that look nothing like bullets or

 numbers.
 
 If you start with bullets or numbers, stick with them, as
 numbers.
 
 If you start with bullets or numbers, stick with them, as


@@ -238,9 +236,9 @@ region.
 That is, with "=for", you can have only one paragraph's worth
 of text (i.e., the text in "=foo targetname text..."), but with
 "=begin targetname" ... "=end targetname", you can have any amount
 That is, with "=for", you can have only one paragraph's worth
 of text (i.e., the text in "=foo targetname text..."), but with
 "=begin targetname" ... "=end targetname", you can have any amount

-of stuff inbetween.  (Note that there still must be a blank line
+of stuff in between.  (Note that there still must be a blank line

 after the "=begin" command and a blank line before the "=end"
 after the "=begin" command and a blank line before the "=end"

-command.
+command.)

 
 Here are some examples of how to use these:
 
 
 Here are some examples of how to use these:
 


@@ -284,28 +282,35 @@ be for formatting as a footnote).
 X<=encoding> X<encoding>
 
 This command is used for declaring the encoding of a document.  Most
 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>
 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
 
   =encoding koi8-r
 
   =encoding utf8
 
   =encoding koi8-r

-  
+

   =encoding ShiftJIS
   =encoding ShiftJIS

-  
-  =encoding big5

 
 

-=back
+  =encoding big5

 
 C<=encoding> affects the whole document, and must occur only once.
 
 
 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
 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:
 
 
 Some examples of lists include:
 


@@ -383,7 +388,7 @@ C<LE<lt>nameE<gt>>
 
 Link to a Perl manual page (e.g., C<LE<lt>Net::PingE<gt>>).  Note
 that C<name> should not contain spaces.  This syntax
 
 Link to a Perl manual page (e.g., C<LE<lt>Net::PingE<gt>>).  Note
 that C<name> should not contain spaces.  This syntax

-is also occasionally used for references to UNIX man pages, as in
+is also occasionally used for references to Unix man pages, as in

 C<LE<lt>crontab(5)E<gt>>.
 
 =item *
 C<LE<lt>crontab(5)E<gt>>.
 
 =item *


@@ -395,7 +400,7 @@ C<LE<lt>perlsyn/"For Loops"E<gt>>
 
 =item *
 
 
 =item *
 

-C<LE<lt>/"sec"E<gt>> or C<LE<lt>/secE<gt>> or C<LE<lt>"sec"E<gt>>
+C<LE<lt>/"sec"E<gt>> or C<LE<lt>/secE<gt>>

 
 Link to a section in this manual page.  E.g.,
 C<LE<lt>/"Object Methods"E<gt>>
 
 Link to a section in this manual page.  E.g.,
 C<LE<lt>/"Object Methods"E<gt>>


@@ -446,10 +451,10 @@ Or you can link to a web page:
 
 C<LE<lt>scheme:...E<gt>>
 
 
 C<LE<lt>scheme:...E<gt>>
 

-Links to an absolute URL.  For example,
-C<LE<lt>http://www.perl.org/E<gt>>.  But note
-that there is no corresponding C<LE<lt>text|scheme:...E<gt>> syntax, for
-various reasons.
+C<LE<lt>text|scheme:...E<gt>>
+
+Links to an absolute URL.  For example, C<LE<lt>http://www.perl.org/E<gt>> or
+C<LE<lt>The Perl Home Page|http://www.perl.org/E<gt>>.

 
 =back
 
 
 =back
 


@@ -474,7 +479,7 @@ C<EE<lt>verbarE<gt>> -- a literal | (I<ver>tical I<bar>)
 
 =item *
 
 
 =item *
 

-C<EE<lt>solE<gt>> = a literal / (I<sol>idus)
+C<EE<lt>solE<gt>> -- a literal / (I<sol>idus)

 
 The above four are optional except in other formatting codes,
 notably C<LE<lt>...E<gt>>, and when preceded by a
 
 The above four are optional except in other formatting codes,
 notably C<LE<lt>...E<gt>>, and when preceded by a


@@ -501,7 +506,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
 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
 rendering C<EE<lt>eacuteE<gt>> as just a plain "e".)
 
 =back


@@ -533,7 +538,7 @@ EE<lt>...E<gt> code sometimes.  For example, instead of
 "C<NEE<lt>ltE<gt>3>" (for "NE<lt>3") you could write
 "C<NZE<lt>E<gt>E<lt>3>" (the "ZE<lt>E<gt>" breaks up the "N" and
 the "E<lt>" so they can't be considered
 "C<NEE<lt>ltE<gt>3>" (for "NE<lt>3") you could write
 "C<NZE<lt>E<gt>E<lt>3>" (the "ZE<lt>E<gt>" breaks up the "N" and
 the "E<lt>" so they can't be considered

-the part of a (fictitious) "NE<lt>...E<gt>" code.
+the part of a (fictitious) "NE<lt>...E<gt>" code).

 
 =for comment
  This was formerly explained as a "zero-width character".  But it in
 
 =for comment
  This was formerly explained as a "zero-width character".  But it in


@@ -557,9 +562,8 @@ using an C<E> code:
 This will produce: "C<$a E<lt>=E<gt> $b>"
 
 A more readable, and perhaps more "plain" way is to use an alternate
 This will produce: "C<$a E<lt>=E<gt> $b>"
 
 A more readable, and perhaps more "plain" way is to use an alternate

-set of delimiters that doesn't require a single ">" to be escaped.  With
-the Pod formatters that are standard starting with perl5.5.660, doubled
-angle brackets ("<<" and ">>") may be used I<if and only if there is
+set of delimiters that doesn't require a single ">" to be escaped.
+Doubled angle brackets ("<<" and ">>") may be used I<if and only if there is

 whitespace right after the opening delimiter and whitespace right
 before the closing delimiter!>  For example, the following will
 do the trick:
 whitespace right after the opening delimiter and whitespace right
 before the closing delimiter!>  For example, the following will
 do the trick:


@@ -582,6 +586,12 @@ And they all mean exactly the same as this:
 
     C<$a E<lt>=E<gt> $b>
 
 
     C<$a E<lt>=E<gt> $b>
 

+The multiple-bracket form does not affect the interpretation of the contents of
+the formatting code, only how it must end.  That means that the examples above
+are also exactly the same as this:
+
+    C<< $a E<lt>=E<gt> $b >>
+

 As a further example, this means that if you wanted to put these bits of
 code in C<C> (code) style:
 
 As a further example, this means that if you wanted to put these bits of
 code in C<C> (code) style:
 


@@ -625,13 +635,17 @@ B<pod2fm>.  Various others are available in CPAN.
 =head2 Embedding Pods in Perl Modules
 X<POD, embedding>
 
 =head2 Embedding Pods in Perl Modules
 X<POD, embedding>
 

-You can embed Pod documentation in your Perl modules and scripts.
-Start your documentation with an empty line, a "=head1" command at the
-beginning, and end it with a "=cut" command and an empty line.  Perl
-will ignore the Pod text.  See any of the supplied library modules for
-examples.  If you're going to put your Pod at the end of the file, and
-you're using an __END__ or __DATA__ cut mark, make sure to put an
-empty line there before the first Pod command.
+You can embed Pod documentation in your Perl modules and scripts.  Start
+your documentation with an empty line, a "=head1" command at the
+beginning, and end it with a "=cut" command and an empty line.  The
+B<perl> executable will ignore the Pod text.  You can place a Pod
+statement where B<perl> expects the beginning of a new statement, but
+not within a statement, as that would result in an error.  See any of
+the supplied library modules for examples.
+
+If you're going to put your Pod at the end of the file, and you're using
+an C<__END__> or C<__DATA__> cut mark, make sure to put an empty line there
+before the first Pod command.

 
   __END__
 
 
   __END__
 


@@ -708,8 +722,8 @@ that could cause odd formatting.
 Older translators might add wording around an LE<lt>E<gt> link, so that
 C<LE<lt>Foo::BarE<gt>> may become "the Foo::Bar manpage", for example.
 So you shouldn't write things like C<the LE<lt>fooE<gt>
 Older translators might add wording around an LE<lt>E<gt> link, so that
 C<LE<lt>Foo::BarE<gt>> may become "the Foo::Bar manpage", for example.
 So you shouldn't write things like C<the LE<lt>fooE<gt>

-documentation>, if you want the translated document to read sensibly
--- instead write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or
+documentation>, if you want the translated document to read sensibly.
+Instead, write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or

 C<LE<lt>the Foo::Bar documentation|Foo::BarE<gt>>, to control how the
 link comes out.
 
 C<LE<lt>the Foo::Bar documentation|Foo::BarE<gt>>, to control how the
 link comes out.