Front page | perl.perl5.porters |
Postings from December 2012
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. Cheers Smylers --- via perlbug: queue: perl5 status: open https://rt.perl.org:443/rt3/Ticket/Display.html?id=116252Thread Previous | Thread Next