This is patch.2b1g to perl5.002beta1.

cd to your perl source directory, and type
	patch -p1 -N < patch.2b1g

This patch is just my packaging of Tom's documentation patches
he released as patch.2b1g.

Patch and enjoy,

    Andy Dougherty		doughera@lafcol.lafayette.edu
    Dept. of Physics
    Lafayette College, Easton PA 18042

1 files changed, 75 insertions, 4 deletions

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index b51c9f8fc5..6566ffb357 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
 
@@ -30,6 +30,58 @@ use however it pleases.  Currently recognized commands are
     =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 *
 
@@ -47,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
@@ -74,16 +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.
+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