Re: [PATCH] Encode.pm docs fix

[perl5.git] / pod / perlpod.pod

diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index fd0a1de..765266b 100644 (file)
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -27,6 +27,8 @@ use however it pleases.  Currently recognized commands are
 
     =head1 heading
     =head2 heading
+    =head3 heading
+    =head4 heading
     =item text
     =over N
     =back
@@ -50,8 +52,13 @@ another paragraph to the doc if you're mixing up code and pod a lot.
 
 =item =head2
 
-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 =head3
+
+=item =head4
+
+Head1, head2, head3 and head4 produce first, second, third and fourth
+level headings, with the text in the same paragraph as the "=headn"
+directive forming the heading description.
 
 =item =over
 
@@ -63,15 +70,17 @@ 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.
+The unit of indentation is optional. If the unit is not given the natural
+indentation of the formatting system applied will be used. 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.
 
 =item =for
 
@@ -154,10 +163,11 @@ It will be filled, and maybe even
 justified.  Certain interior sequences are recognized both
 here and in commands:
 
-    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
+    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>     Render code in a typewriter font, or give some other
+                indication that this represents program text
     L<name>     A link (cross reference) to name
                    L<name>             manual page
                    L<name/ident>       item in manual page