I rewrote some of the rewrite to perlpod. The changes I made include:
Added "=for :name" and "=begin :name"/"=end :name". Prefixing the
format name is explained in perlpodspec, but there was no mention
in perlpod.
The description of interior sequences seemed to have outgrown its
verbatim paragraph, It has been rewritten using =over/=item/=back.
In addition to =head1..=head4 and =item, one should be able to link
to X<topic> sequences. So instead of conflating "sec" and "ident"
in L<> sequences to "sec", it is now conflated to "node", which
is less descriptive.
Added E<colon> (a literal ":"), to prevent links that look like
URLs from being interpreted as such.
Changed some intances of "empty line" to "blank line".
And a patch with the actual changes:
--- perlpod.1.pod Sat Aug 18 14:12:56 2001
+++ perlpod.pod Sun Aug 19 16:48:46 2001
@@ -113,14 +113,11 @@
=item =pod
-You usually start a pod block with an "=item" or a "=head1" or the
-like; and a line beginning with a "=" and a word is sufficient to
-signal that Perl code has stopped and pod has begun. But if you just
-wanted to have a pod block starting not with an item or a heading or
-the like, but with an ordinary paragraph or a verbatim paragraph, just
-preface it with a "=pod" command, and a blank line. The "=pod"
-command by itself doesn't do much of anything, but it signals to Perl
-(and pod formatters) that a pod block starts here.
+The "=pod" command by itself doesn't do much of anything, but it
+signals to Perl (and pod formatters) that a pod block starts here. A
+pod block starts with any command paragraph, so a "=pod" command is
+usually used when you want to start a pod block with an ordinary
+paragraph or a verbatim paragraph.
=item =for
@@ -131,13 +128,21 @@
For, begin, and end let you include regions of text/code that are not
generally interpreted as pod text, but are passed directly to
particular formatters. A formatter that can utilize that format will
-use the region, otherwise it will be completely ignored. The
-directive "=for" specifies that the entire next paragraph is in the
-format indicated by the first word after "=for", like this:
+use the region, otherwise it will be completely ignored.
+The directive "=for" specifies that the entire next paragraph is in
+the format indicated by the first word after "=for", like this:
+
=for html <br>
<p> This is a raw HTML paragraph </p>
+To indicate that the content I<is> pod text, but only meant for
+particular formatters, precede the format name with a colon ":", like
+this:
+
+ =for :html E<lt>br>
+ <p> This is a B<cooked> HTML paragraph </p>
+
The paired commands "=begin" and "=end" work very similarly to "=for",
but instead of only accepting a single paragraph, all text from
"=begin" to a paragraph with a matching "=end" are treated as a
@@ -166,9 +171,11 @@
include "roff", "man", "latex", "tex", "text", and "html". (Some
formatters will treat some of these as synonyms.)
+=back
+
And don't forget, when using any command, that the command lasts up
until the end of its B<paragraph>, not its line. Hence in the
-examples below, you can see the empty lines after each command to end
+examples below, you can see the blank lines after each command to end
its paragraph.
Some examples of lists include:
@@ -197,67 +204,148 @@
=back
-=back
-
=head2 Ordinary Block of Text
It will be filled, and maybe even justified. Certain B<interior
sequences> are recognized both here and in commands:
- I<text> Italicize text, used for emphasis and variables
- B<text> Embolden text, used for switches and programs
- S<text> Text contains non-breaking spaces
- C<code> Render code in a typewriter font, or give some other
- indication that this represents program text
- F<file> Used for filenames
+ I<text>
+ B<text>
+ S<text>
+ C<code>
+ F<file>
+ L<link>
+ X<topic>
+ Z<>
+ E<escape>
- L<name> A link (cross reference) to name:
- L<name> manual page (e.g., L<Net::Ping>)
- L<name/"sec"> section in other manual page
- or L<name/sec>
- L</"sec"> section in this manual page
- or L</sec> or L<"sec">
- (A section is started by the named heading or item.
- For example, L<perlvar/$.> or L<perlvar/"$."> both
- link to the section started by "=item $." in perlvar;
- and L<perlsyn/For Loops> or L<perlsyn/"For Loops">
- both link to the section started by "=head2 For Loops"
- in perlsyn.
+=over 4
- Same as above, but only "text" is used for output:
- L<text|name>
- L<text|name/"sec"> or L<text|name/sec>
- L<text|/"sec"> or L<text/sec> or L<text|"sec">
-
- (Text, name, and section cannot contain the characters
- '/' and '|', and any '<' or '>' should be matched.
- Moreover, name should not contain spaces.)
-
- L<scheme:...> link to an absolute URL
- e.g., L<http://www.perl.org/>
- (There is no corresponding L<name|scheme:...> syntax,
- for various reasons.)
+=item IZ<><>
- X<topic> An index entry (ignored by most formatters; always
- renders as empty-string)
- Z<> A zero-width character (rarely used)
+Italicize text, used for emphasis and variables.
- E<escape> A named character (very similar to HTML escapes)
- E<lt> A literal <
- E<gt> A literal >
- E<sol> A literal /
- E<verbar> A literal |
- (The above are optional except in other interior
- sequences, notably L<>, and when preceded by a
- capital letter)
- E<0n> ASCII character number n (octal)
- E<n> ASCII character number n (decimal)
- E<0xn) ASCII character number n (hex)
- E<html> Some non-numeric HTML entity, such
- as E<Agrave>
- (Older pod formatters might not recognize octal or
- hex numeric escapes.)
+=item BZ<><>
+Embolden text, used for switches and programs.
+
+=item SZ<><>
+
+Text contains non-breaking spaces.
+
+=item CZ<><>
+
+Render code in a typewriter font, or give some other indication that
+this represents program text.
+
+=item FZ<><>
+
+Used for filenames.
+
+=item LZ<><>
+
+Used for links or cross references.
+
+=over 4
+
+=item LZ<><name>
+
+A link to a manual page. For example:
+
+ L<perldata> Perl documentation
+ L<Net::Ping> Perl module
+ L<crontab(5)> Unix man page
+
+=item LZ<><name/"node">
+
+=item LZ<><name/node>
+
+A link to a node in some other manual page. A node may be any
+heading, item or index entry. For example:
+
+ L<perlsyn/For Loops> =head2 For Loops in perlsyn
+ L<perlvar/$.> =item $. in perlvar
+ L<perlfunc/-e> X<-e> in perlfunc
+
+=item LZ<></"node">
+
+=item LZ<></node>
+
+=item LZ<><"node">
+
+A link to a node in this manual page.
+
+=item LZ<><scheme:...>
+
+A link to an absolute URL. For example:
+
+ L<http://www.perl.org/>
+ L<news:comp.lang.perl.misc>
+ L<mailto:[EMAIL PROTECTED]>
+
+=item LZ<><text|name>
+
+=item LZ<><text|name/"node">
+
+=item LZ<><text|name/node>
+
+=item LZ<><text|/"node">
+
+=item LZ<><text|/node>
+
+=item LZ<><text|"node">
+
+Same as the corresponding "text"-less links, but only "text" is used
+for output. There is no corresponding LZ<><name|scheme:...> syntax,
+for various reasons.
+
+=back
+
+The "text", "name", and "node" parts of a link cannot contain the
+characters '/' and '|', and any '<' or '>' should be matched.
+Moreover, "name" should not contain spaces.
+
+=item XZ<><>
+
+An index entry. Always renders to an empty-string. Rarely used.
+Ignored by most older pod formatters.
+
+=item ZZ<><>
+
+A zero-width character. Rarely used, although useful in escaping
+command paragraphs and interior sequences. For example:
+
+ Z<>=head1 This is I<not> a command paragraph
+ and it contains no BZ<><bold> characters.
+
+The alternative is to use normal EZ<><escape> sequences, like so:
+
+ E<61>head1 This is I<not> a command paragraph
+ and it contains no BE<lt>bold> characters.
+
+=item EZ<><>
+
+A named character, very similar to HTML escapes:
+
+ E<lt> A literal <
+ E<gt> A literal >
+ E<sol> A literal /
+ E<verbar> A literal |
+ E<colon> A literal :
+
+The above are optional except in other interior sequences, notably
+LZ<><>, and when preceded by a capital letter.
+
+ E<n> Character number n (decimal)
+ E<0n> Character number n (octal)
+ E<0xn) Character number n (hex)
+ E<html> Some non-numeric HTML entity, such
+ as E<Agrave>
+
+Older pod formatters might not recognize octal or hex numeric escapes.
+
+=back
+
Most of the time, you will only need a single set of angle brackets to
delimit the beginning and end of interior sequences. However,
sometimes you will want to put a right angle bracket (or greater-than
@@ -315,12 +403,12 @@
=head2 Embedding Pods in Perl Modules
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
+Start your documentation with a blank line, a "=head1" command at the
+beginning, and end it with a "=cut" command and a blank 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 directive.
+you're using an __END__ or __DATA__ cut mark, make sure to put a
+blank line there before the first pod directive.
__END__
@@ -328,7 +416,7 @@
modern - I am a modern module
-Without that empty line before the "=head1", many translators wouldn't
+Without that blank line before the "=head1", many translators wouldn't
have recognized the "=head1" as starting a pod block.
=head2 Common Pod Pitfalls
--
Tim Gim Yee
[EMAIL PROTECTED]
