develooper Front page | perl.perl5.porters | Postings from February 2013

Re: Recent pod

Thread Previous | Thread Next
From:
Smylers
Date:
February 26, 2013 09:19
Subject:
Re: Recent pod
Message ID:
20130226091912.GA2143@stripey.com
Mark Overmeer writes:

> * David E. Wheeler (david@justatheory.com) [130225 22:38]:
> 
> > perlpodspec:
> > >        ·   An "=over" ... "=back" region containing only
> > >        "m/\A=item\s+\d+\.?\s*\z/" paragraphs, each one (or each
> > >        group of them) followed by some number of ordinary/verbatim
> > >        paragraphs, other nested "=over" ... "=back" regions,
> > >        "=for..." paragraphs, and/or "=begin"..."=end" codes.  Note
> > >        that the numbers must start at 1 in each section, and must
> > >        proceed in order and without skipping numbers.
> > > 
> > >            (Pod processors must tolerate lines like "=item 1" as
> > >            if they were "=item 1.", with the period.)
> 
> In perlpod:
>     ·   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.--namely, things that
>         look nothing like bullets or numbers.
> 
> No idea whether perlpodspec changed or perlpod doesn't tell the whole
> picture with respect to numbered lists.

The above two don't actually contradict each other:

* perlpod tells Pod authors to use "1.", "2." or to use "things that
  look nothing like bullets or numbers".

  Clearly "1" doesn't fall in the category of something that doesn't
  look like a number, so by perlpod authors shouldn't be using it.

* perlpodspec tells Pod tools developers that if an author does use "1"
  they should treat it like "1.".

Cheers

Smylers
-- 
http://twitter.com/Smylers2

Thread Previous | Thread Next


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