X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlpod.pod;h=6a578caec355647754ced1d061ee961e98cdf21e;hb=1b3f7d2103791ceee4a17b0f9f5860baa1512c7a;hp=46693f179380a4ba5b8b5702730ad983d252fcd1;hpb=a0d0e21ea6ea90a22318550944fe6cb09ae10cda;p=p5sagit%2Fp5-mst-13.2.git
diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 46693f1..6a578ca 100644
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -1,6 +1,6 @@
=head1 NAME
-pod - plain old documentation
+perlpod - plain old documentation
=head1 DESCRIPTION
@@ -29,6 +29,99 @@ use however it pleases. Currently recognized commands are
=item text
=over N
=back
+ =cut
+ =pod
+ =for X
+ =begin X
+ =end X
+
+The "=pod" directive does nothing beyond telling the compiler to lay
+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.
+
+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
+the list just runs off the document, 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., 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.
+
+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
+
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"sec"> ditto
F Used for filenames
- Z<> A zero-width character
+ X An index entry
+ 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
That's it. The intent is simplicity, not power. I wanted paragraphs
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.
@@ -73,9 +178,64 @@ the way, but I've gotten along surprisingly well with just these.
Note that I'm not at all claiming this to be sufficient for producing a
book. I'm just trying to make an idiot-proof common source for nroff,
TeX, and other markup languages, as used for online documentation.
-Both B and B translators exist.
+Translators exist for B (that's for nroff(1) and troff(1)),
+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 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 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
-=head1 Author
+=head1 AUTHOR
Larry Wall