X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlpod.pod;h=6a578caec355647754ced1d061ee961e98cdf21e;hb=b4793f7f58b137d8b2f6d505d6c77dee2cd8cb25;hp=5485f6c3b904e365970b744b9495887a076be233;hpb=c7c9f95670eaf6ce7e8b31208e8675de7ad925dc;p=p5sagit%2Fp5-mst-13.2.git
diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 5485f6c..6a578ca 100644
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -36,16 +36,16 @@ use however it pleases. Currently recognized commands are
=end X
The "=pod" directive does nothing beyond telling the compiler to lay
-off of 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 on
-the same paragraph as "=headn" forming the heading description.
+Head1 and head2 produce first and second level headings, with the text in
+the same paragraph as the "=headn" directive forming the heading description.
-Item, over, and back require a little more explanation: Over starts a
-section specifically for the generation of a list using =item commands. At
-the end of your list, use =back to end it. You will probably want to give
-"4" as the number to =over, as some formatters will use this for indentation.
+Item, over, and back require a little more explanation: "=over" starts a
+section specifically for the generation of a list using "=item" commands. At
+the end of your list, use "=back" to end it. You will probably want to give
+"4" as the number to "=over", as some formatters will use this for indentation.
This should probably be a default. Note also that there are some basic rules
to using =item: don't use them outside of an =over/=back block, use at least
one inside an =over/=back block, you don't _have_ to include the =back if
@@ -54,47 +54,48 @@ 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., 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 and begin/end let you include sections that are not interpreted as pod
-text, but in a format that a particular formatter is looking for. A
-formatter that can utilize that format will use the section, otherwise it
-will be completely ignored. "=for" specifies that the entire paragraph
-should is in the format indicated by the first word after "=for", like this:
+For, begin, and end let you include sections that are not interpreted
+as pod text, but passed directly to particular formatters. A formatter
+that can utilize that format will use the section, 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
+ =for html
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.
+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
-
+
Figure 1.
-
+
=end html
-
+
=begin text
-
+
---------------
| foo |
| bar |
---------------
-
+
^^^^ Figure 1. ^^^^
-
+
=end text
Some format names that formatters currently are known to accept include
"roff", "man", "latex", "tex", "text", and "html". (Some formatters will
treat some of these as synonyms.)
-And don't forget, when using any command, that that command lasts up until
+And don't forget, when using any command, that the command lasts up until
the end of the B, 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:
@@ -131,7 +132,7 @@ here and in commands:
I italicize text, used for emphasis or variables
B embolden text, used for switches and programs
S text contains non-breaking spaces
- C literal code
+ C literal code
L A link (cross reference) to name
L manual page
L item in manual page
@@ -141,7 +142,7 @@ here and in commands:
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 >
@@ -183,20 +184,21 @@ 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
@@ -206,7 +208,7 @@ have seen it.
=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 *
@@ -220,7 +222,7 @@ sensibly.
=item *
The script F 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, 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