develooper Front page | perl.perl5.porters | Postings from March 2001

Re: pods patched

From:
Michael Stevens
Date:
March 17, 2001 02:44
Subject:
Re: pods patched
Message ID:
20010317104455.A6984@firedrake.org
On Sat, Mar 17, 2001 at 10:06:21AM +0000, Michael Stevens wrote:
> Anyway, my attitude is that IF we warn about it, AND the documentation
> doesn't make it clear the warning is inappropriate (eg if we warned
> about the =turnip tag being inappropriate, and the documentation explained
> the =turnip tag and said it could and SHOULD be used in all documents),
> I will probably do patches. I'm personally not too fussed if we change
> the checkers (and, presumably the standard, which is probably unclearly
> written if someone experienced enough to write Pod::Checker was able to
> misunderstand it), or the docs. I'm just personally more inclined to produce
> doc patches. I've been working on the assumption that podchecker 
> encapsulates a long established standard, and who am I to change it?

But if we *do* want to change it... (I'm lazy, someone else can check
all the pod parsers in existence to see if they handle this correctly)

diff -urN perl-current.orig/lib/Pod/Checker.pm perl-current/lib/Pod/Checker.pm
--- perl-current.orig/lib/Pod/Checker.pm	Sat Mar 17 10:27:53 2001
+++ perl-current/lib/Pod/Checker.pm	Sat Mar 17 10:30:02 2001
@@ -222,11 +222,6 @@
 
 =end _disabled_
 
-=item * No numeric argument for =over
-
-The C<=over> command is supposed to have a numeric argument (the
-indentation).
-
 =item * previous =item has no contents
 
 There is a list C<=item> right above the flagged line that has no
@@ -822,12 +817,8 @@
             my $indent = 4; # default
             if($arg && $arg =~ /^\s*(\d+)\s*$/) {
                 $indent = $1;
-            } else {
-                $self->poderror({ -line => $line, -file => $file,
-                     -severity => 'WARNING', 
-                     -msg => "No numeric argument for =over"});
             }
-            # start a new list
+            # start a new list
             $self->_open_list($indent,$line,$file);
         }
         elsif($cmd eq 'item') {
diff -urN perl-current.orig/pod/perlpod.pod perl-current/pod/perlpod.pod
--- perl-current.orig/pod/perlpod.pod	Sat Mar 17 10:28:01 2001
+++ perl-current/pod/perlpod.pod	Sat Mar 17 10:35:22 2001
@@ -70,15 +70,17 @@
 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
 



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About