=end X
The "=pod" directive does nothing beyond telling the compiler to lay
-off of formatting through the next "=cut". It's useful for adding another
-paragraph to the doc if you're mixing up code and pod a lot.
+off parsing code through the next "=cut". It's useful for adding
+another paragraph to the doc if you're mixing up code and pod a lot.
Head1 and head2 produce first and second level headings, with the text in
the same paragraph as the "=headn" directive forming the heading description.
or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use
"=item foo", "=item bar", etc., i.e., things that looks nothing like bullets
or numbers. If you start with bullets or numbers, stick with them, as many
-formatters use the first "=item" type to decide how to format the list.
+formatters use the first "=item" type to decide how to format the list.
For, begin, and end let you include sections that are not interpreted
as pod text, but passed directly to particular formatters. A formatter
paragraph is in the format indicated by the first word after
"=for", like this:
- =for html <br>
+ =for html <br>
<p> This is a raw 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 particular format.
+paragraph with a matching "=end" are treated as a particular format.
Here are some examples of how to use these:
And don't forget, when using any command, that the command lasts up until
the end of the B<paragraph>, not the line. Hence in the examples below, you
-can see the blank lines after each command to end its paragraph.
+can see the empty lines after each command to end its paragraph.
Some examples of lists include:
I<text> italicize text, used for emphasis or variables
B<text> embolden text, used for switches and programs
S<text> text contains non-breaking spaces
- C<code> literal code
+ C<code> literal code
L<name> A link (cross reference) to name
L<name> manual page
L<name/ident> item in manual page
L</"sec"> ditto
F<file> Used for filenames
X<index> An index entry
- ZE<lt>E<gt> A zero-width character
+ Z<> A zero-width character
E<escape> A named character (very similar to HTML escapes)
E<lt> A literal <
E<gt> A literal >
=head1 Embedding Pods in Perl Modules
You can embed pod documentation in your Perl scripts. Start your
-documentation with a "=head1" command at the beginning, 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__
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
=item *
Pod translators usually will require paragraphs to be separated by
-completely empty lines. If you have an apparently blank line with
+completely empty lines. If you have an apparently empty line with
some spaces on it, this can cause odd formatting.
=item *
=item *
The script F<pod/checkpods.PL> in the Perl source distribution
-provides skeletal checking for lines that look blank but aren't
+provides skeletal checking for lines that look empty but aren't
B<only>, 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
projects / p5sagit/p5-mst-13.2.git / blobdiff