Add documentation for default UNIVERSAL methods

[p5sagit/p5-mst-13.2.git] / pod / perlpod.pod

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 46693f1..6566ffb 100644 (file)
--- 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,59 @@ use however it pleases.  Currently recognized commands are
     =item text
     =over N
     =back
+    =cut
+    =pod
+
+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.  
+
+Head1 and head2 produce first and second level headings, with the text on
+the same paragraph as "=headn" 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 indention.
+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 you the first =item type to decide how to format the list.  
+
+And don't forget, when using any command, that that 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 it's paragraph.
+
+Some examples of lists include:
+
+ =over 4
+
+ =item *
+
+ First item
+
+ =item *
+
+ Second item
+
+ =back
+
+ =over 4
+
+ =item Foo()
+
+ Description of Foo function
+
+ =item Bar()
+
+ Description of Bar function
+
+ =back
 
 =item *
 
@@ -46,7 +99,9 @@ here and in commands:
                    L<name/"sec">       section in other manpage
                    L<"sec">            section in this manpage
                                        (the quotes are optional)
+                   L</"sec">           ditto
     F<file>    Used for filenames
+    X<index>   An index entry
     Z<>         A zero-width character
 
 That's it.  The intent is simplicity, not power.  I wanted paragraphs
@@ -73,9 +128,33 @@ 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<pod2html> and B<pod2man> translators exist.
+Translators exist for B<pod2man>  (that's for nroff(1) and troff(1)),
+B<pod2html>, B<pod2latex>, and B<pod2fm>.
+
+=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.
+
+    __END__
+
+    =head1 NAME
+
+    modern - I am a modern module
+
+If you had not had that blank line there, then the translators wouldn't
+have seen it.
+
+=head1 SEE ALSO
+
+L<pod2man> and L<perlsyn/"PODs: Embedded Documentation">
 
-=head1 Author
+=head1 AUTHOR
 
 Larry Wall