=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<$/>
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
will be completely ignored.
A command "=begin I<formatname>", some paragraphs, and a
-command "=end I<formatname>", mean that the text/data inbetween
+command "=end I<formatname>", mean that the text/data in between
is meant for formatters that understand the special format
called I<formatname>. For example,
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"
command.
=back
-And don't forget, when using any command, that the command lasts up
+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
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.
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 *
=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>>
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
=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
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:
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:
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.
https://perl5.git.perl.org / perl5.git / blobdiff