This is a raw HTML paragraph
+ +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 particular format. + +Here are some examples of how to use these: + + =begin html + +
literal code
+ C literal code
L A link (cross reference) to name
- L manpage
- L item in manpage
- L section in other manpage
- L<"sec"> section in this manpage
+ L manual page
+ L item in manual page
+ L section in other manual page
+ L<"sec"> section in this manual page
(the quotes are optional)
L ditto
F Used for filenames
X An index entry
- Z<> A zero-width character
+ Z<> A zero-width character
+ E A named character (very similar to HTML escapes)
+ E A literal <
+ E A literal >
+ (these are optional except in other interior
+ sequences and when preceded by a capital letter)
+ E Character number n (probably in ASCII)
+ E Some non-numeric HTML entity, such
+ as E
=back
@@ -111,7 +159,7 @@ to look like paragraphs (block format), so that they stand out
visually, and so that I could run them through fmt easily to reformat
them (that's F7 in my version of B). I wanted the translator (and not
me) to worry about whether " or ' is a left quote or a right quote
-within filled text, and I wanted it to leave the quotes alone dammit in
+within filled text, and I wanted it to leave the quotes alone, dammit, in
verbatim mode, so I could slurp in a working program, shift it over 4
spaces, and have it print out, er, verbatim. And presumably in a
constant width font.
@@ -136,22 +184,53 @@ B, B, and B.
=head1 Embedding Pods in Perl Modules
You can embed pod documentation in your Perl scripts. Start your
-documentation with a =head1 command at the beg, and end it with
-an =cut command. Perl will ignore the pod text. See any of the
-supplied library modules for examples. If you're going to put
-your pods at the end of the file, and you're using an __END__
-or __DATA__ cut mark, make sure to put a blank line there before
-the first pod directive.
+documentation with a "=head1" command at the beginning, and end it
+with a "=cut" command. Perl will ignore the pod text. See any of the
+supplied library modules for examples. If you're going to put your
+pods 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.
__END__
+
=head1 NAME
modern - I am a modern module
-If you had not had that blank line there, then the translators wouldn't
+If you had not had that empty line there, then the translators wouldn't
have seen it.
+=head1 Common Pod Pitfalls
+
+=over 4
+
+=item *
+
+Pod translators usually will require paragraphs to be separated by
+completely empty lines. If you have an apparently empty line with
+some spaces on it, this can cause odd formatting.
+
+=item *
+
+Translators will mostly add wording around a LEE link, so that
+Cfoo(1)E> becomes "the I(1) manpage", for example (see
+B for details). Thus, you shouldn't write things like CfooE manpage>, if you want the translated document to read
+sensibly.
+
+=item *
+
+The script F in the Perl source distribution
+provides skeletal checking for lines that look empty but aren't
+B, but is there as a placeholder until someone writes
+Pod::Checker. The best way to check your pod is to pass it through
+one or more translators and proofread the result, or print out the
+result and proofread that. Some of the problems found may be bugs in
+the translators, which you may or may not wish to work around.
+
+=back
+
=head1 SEE ALSO
L and L