develooper Front page | perl.perl5.porters | Postings from December 2012

[perl #116252] Re: [PATCH] Correct nested pod bullets (Was: $(git log --pretty=format:%s HEAD^..))

Thread Previous | Thread Next
Smylers via RT
December 31, 2012 17:49
[perl #116252] Re: [PATCH] Correct nested pod bullets (Was: $(git log --pretty=format:%s HEAD^..))
Message ID:
On Mon Dec 31 02:21:40 2012, nicholas wrote:

> On Mon, Dec 31, 2012 at 12:19:52AM -0800, Smylers wrote:
> > Subject: [PATCH] Correct nested pod bullets
> > 
> > -=item -
> > +=item *
> This is not a "reject this patch" (far from it)
> 1) Without this change, what do Pod formatters do differently, and is it
>    wrong, or just ugly?

Hi. Have you seen the clarification I added to the bug afterwards? (My
apologies for not including it in the first place.)

Without the change the document has the wrong semantics, meaning 'this
item about a hyphen' rather than 'this is an (unlabelled) bullet point'.

Its HTML rendering on MetaCpan looked sufficiently odd that I bothered
to take a look at it and file this bug.

> 2) Assuming the answer to (1) is some form of wrongness, should we
>    note this somewhere as a Pod style guide and going forward try to
>    stick to it?

It isn't really a matter of style; it's simple correctness: C<=item *>
has a special meaning in Pod that C<=item -> just doesn't have.

Has anybody else encountered this issue? If this is the only occurrence
found so far it's probably premature to bother documenting it as
something to watch out for.

However, having nested bullets being distinguished from top-level
bullets (presumably the intent in using hyphens here) sounds good to me.
The Pod formatter used by the perldoc command seems to use mid dots for
all levels; perhaps it'd be an improvement to change that to use hyphens
for level 2.

> 3) Is it possible to get the Pod checker to spot this?

Note that C<=item -> is used correctly in perldebug, describing what
pressing - does in a list of keystrokes; other C<=item foo>s in the list
have different values of foo.

So to avoid flagging genuine uses, a check should be on C<=item -> used
multiple times in the same list. Or possibly on any C<=item foo> (other
than the * and 1.-like special cases) being used more than once in the
same list.



via perlbug:  queue: perl5 status: open

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About