[PATCH] Correct nested pod bullets #12678

p5pRT · 2012-12-31T08:19:51Z

Migrated from rt.perl.org#116252 (status was 'resolved')

Searchable as RT116252$

p5pRT · 2012-12-31T08:19:51Z

From @Smylers

This is a bug report for perl from Smylers@stripey.com,
generated with the help of perlbug 1.39 running under perl 5.14.2.

From e161b1023da0a980dc9e74ffa37e8dd2e7d9c5c0 Mon Sep 17 00:00:00 2001
From: Smylers <Smylers@stripey.com>
Date: Mon, 31 Dec 2012 07:23:28 +0000
Subject: [PATCH] Correct nested pod bullets

pod/perl5177delta.pod | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)

Inline Patch

diff --git a/pod/perl5177delta.pod b/pod/perl5177delta.pod
index 78d6ff3..70129cd 100644
--- a/pod/perl5177delta.pod
+++ b/pod/perl5177delta.pod
@@ -365,23 +365,23 @@ _charnames from loading via C<$INC{'_charnames.pm'}++>.
 A number of bugs related to assigning a list to hash have been fixed. Many of
 these involve lists with repeated keys like C<(1, 1, 1, 1)>.
 
-=over 8
+=over 4
 
-=item -
+=item *
 
 The expression C<scalar(%h = (1, 1, 1, 1))> now returns C<4>, not C<2>.
 
-=item -
+=item *
 
 The return value of C<%h = (1, 1, 1)> in list context was wrong. Previously
 this would return C<(1, undef, 1)>, now it returns C<(1, undef)>.
 
-=item -
+=item *
 
 Perl now issues the same warning on C<($s, %h) = (1, {})> as it does for
 C<(%h) = ({})>, "Reference found where even-sized list expected".
 
-=item -
+=item *
 
 A number of additional edge cases in list assignment to hashes were
 corrected. For more details see commit 23b7025ebc.
--

1.7.10.4

Flags:
category=docs
severity=low

Site configuration information for perl 5.14.2:

Configured by Debian Project at Tue Nov 27 00:50:56 UTC 2012.

Summary of my perl5 (revision 5 version 14 subversion 2) configuration:

Platform:
osname=linux, osvers=3.2.0-23-generic, archname=x86_64-linux-gnu-thread-multi
uname='linux komainu 3.2.0-23-generic #36-ubuntu smp tue apr 10 20:39:51 utc 2012 x86_64 x86_64 x86_64 gnulinux '
config_args='-Dusethreads -Duselargefiles -Dccflags=-DDEBIAN -D_FORTIFY_SOURCE=2 -g -O2 -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -Dldflags= -Wl,-Bsymbolic-functions -Wl,-z,relro -Dlddlflags=-shared -Wl,-Bsymbolic-functions -Wl,-z,relro -Dcccdlflags=-fPIC -Darchname=x86_64-linux-gnu -Dprefix=/usr -Dprivlib=/usr/share/perl/5.14 -Darchlib=/usr/lib/perl/5.14 -Dvendorprefix=/usr -Dvendorlib=/usr/share/perl5 -Dvendorarch=/usr/lib/perl5 -Dsiteprefix=/usr/local -Dsitelib=/usr/local/share/perl/5.14.2 -Dsitearch=/usr/local/lib/perl/5.14.2 -Dman1dir=/usr/share/man/man1 -Dman3dir=/usr/share/man/man3 -Dsiteman1dir=/usr/local/man/man1 -Dsiteman3dir=/usr/local/man/man3 -Duse64bitint -Dman1ext=1 -Dman3ext=3perl -Dpager=/usr/bin/sensible-pager -Uafs -Ud_csh -Ud_ualarm -Uusesfio -Uusenm -Ui_libutil -DDEBUGGING=-g -Doptimize=-O2 -Duseshrplib -Dlibperl=libperl.so.5.14.2 -des'
hint=recommended, useposix=true, d_sigaction=define
useithreads=define, usemultiplicity=define
useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef
use64bitint=define, use64bitall=define, uselongdouble=undef
usemymalloc=n, bincompat5005=undef
Compiler:
cc='cc', ccflags ='-D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fstack-protector -fno-strict-aliasing -pipe -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
optimize='-O2 -g',
cppflags='-D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fstack-protector -fno-strict-aliasing -pipe -I/usr/local/include'
ccversion='', gccversion='4.7.2', gccosandvers=''
intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678
d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
ivtype='long', ivsize=8, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
alignbytes=8, prototype=define
Linker and Libraries:
ld='cc', ldflags =' -fstack-protector -L/usr/local/lib'
libpth=/usr/local/lib /lib/x86_64-linux-gnu /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib /usr/lib
libs=-lgdbm -lgdbm_compat -ldb -ldl -lm -lpthread -lc -lcrypt
perllibs=-ldl -lm -lpthread -lc -lcrypt
libc=, so=so, useshrplib=true, libperl=libperl.so.5.14.2
gnulibc_version='2.15'
Dynamic Linking:
dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
cccdlflags='-fPIC', lddlflags='-shared -L/usr/local/lib -fstack-protector'

Locally applied patches:

@INC for perl 5.14.2:
/home/smylers/lib/perl5/site_perl
/home/smylers/lib/perl5
/etc/perl
/usr/local/lib/perl/5.14.2
/usr/local/share/perl/5.14.2
/usr/lib/perl5
/usr/share/perl5
/usr/lib/perl/5.14
/usr/share/perl/5.14
/usr/local/lib/site_perl
.

Environment for perl 5.14.2:
HOME=/home/smylers
LANG=en_GB.utf8
LANGUAGE=en_GB:en
LC_COLLATE=C
LD_LIBRARY_PATH (unset)
LOGDIR (unset)
PATH=/home/smylers/bin:/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin:/usr/games
PERL5LIB=/home/smylers/lib/perl5/site_perl:/home/smylers/lib/perl5
PERL_BADLANG (unset)
PERL_CPANM_OPT=--sudo --prompt
SHELL=/bin/bash

p5pRT · 2012-12-31T08:59:11Z

From @Smylers

Sorry, I messed the subject line up in invoking perlbug; now fixed in RT.

Also, I realized the problem this patch fixes may not be obvious.C<=item
-> generates a list of named items, with the item being named C<->. But
from the content here it's obvious that a (nested) bullet list is what's
desired, which is indicated in Pod with C<=item *>.

In perldoc's manpage-like output C<=item -> looks like it generates a
bullet list, because named items short enough to fit fully inside the
indented margin have the rest of the item stay on the same line.

But in the HTML output named items are conveyed with <dl> elements, with
the hyphens as item headings, which obviously looks silly:
https://metacpan.org/module/DROLSKY/perl-5.17.7/pod/perldelta.pod#Selected-Bug-Fixes

p5pRT · 2012-12-31T10:21:40Z

From @nwc10

On Mon, Dec 31, 2012 at 12:19:52AM -0800, Smylers wrote:

Subject: [PATCH] Correct nested pod bullets

-=over 8
+=over 4

-=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?

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

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

Nicholas Clark

p5pRT · 2012-12-31T10:21:41Z

The RT System itself - Status changed from 'new' to 'open'

p5pRT · 2012-12-31T17:49:17Z

From @Smylers

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

p5pRT · 2013-01-26T18:03:42Z

From @khwilliamson

Thanks, applied as
0970002
and
073d685

--
Karl Williamson

p5pRT · 2013-01-26T18:03:42Z

@khwilliamson - Status changed from 'open' to 'resolved'

p5pRT · 2013-01-26T18:04:40Z

@khwilliamson - Status changed from 'resolved' to 'open'

p5pRT · 2013-01-26T18:06:18Z

From @khwilliamson

I carelessly resolved this instead of the ticket I meant to resolve, so
am reopening it. Sorry

On Sat Jan 26 10:03:42 2013, khw wrote:

Thanks, applied as
0970002
and
073d685

--
Karl Williamson

p5pRT · 2013-01-26T18:23:09Z

From @khwilliamson

If you attach your patch to an email instead of inlining it, I will
apply it. I'm also forwarding it to pod-people email list for
discussion about whether Pod::Simple should check for something like this.

p5pRT · 2013-01-26T20:28:06Z

From @Smylers

Karl Williamson via RT writes:

If you attach your patch to an email instead of inlining it, I will
apply it.

Attached.

Should I have done that in the first place then? I attempted to follow
the 'Super Quick Patch Guide' at the top of perlhack, and so however the
patch was sent should be whatever the perlbug command does by default.

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

p5pRT · 2013-01-26T20:28:06Z

From @Smylers

0001-Correct-nested-pod-bullets.patch

From e161b1023da0a980dc9e74ffa37e8dd2e7d9c5c0 Mon Sep 17 00:00:00 2001
From: Smylers <[email protected]>
Date: Mon, 31 Dec 2012 07:23:28 +0000
Subject: [PATCH] Correct nested pod bullets

---
 pod/perl5177delta.pod |   10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/pod/perl5177delta.pod b/pod/perl5177delta.pod
index 78d6ff3..70129cd 100644
--- a/pod/perl5177delta.pod
+++ b/pod/perl5177delta.pod
@@ -365,23 +365,23 @@ _charnames from loading via C<$INC{'_charnames.pm'}++>.
 A number of bugs related to assigning a list to hash have been fixed. Many of
 these involve lists with repeated keys like C<(1, 1, 1, 1)>.
 
-=over 8
+=over 4
 
-=item -
+=item *
 
 The expression C<scalar(%h = (1, 1, 1, 1))> now returns C<4>, not C<2>.
 
-=item -
+=item *
 
 The return value of C<%h = (1, 1, 1)> in list context was wrong. Previously
 this would return C<(1, undef, 1)>, now it returns C<(1, undef)>.
 
-=item -
+=item *
 
 Perl now issues the same warning on C<($s, %h) = (1, {})> as it does for
 C<(%h) = ({})>, "Reference found where even-sized list expected".
 
-=item -
+=item *
 
 A number of additional edge cases in list assignment to hashes were
 corrected. For more details see commit 23b7025ebc.
-- 
1.7.10.4

p5pRT · 2013-01-26T23:57:41Z

From @khwilliamson

Thanks, applied as
7a4cf48
--
Karl Williamson

p5pRT · 2013-01-26T23:57:41Z

@khwilliamson - Status changed from 'open' to 'resolved'

p5pRT · 2013-01-26T23:59:38Z

From @khwilliamson

On 01/26/2013 01:27 PM, Smylers wrote:

Karl Williamson via RT writes:

If you attach your patch to an email instead of inlining it, I will
apply it.

Attached.

Should I have done that in the first place then? I attempted to follow
the 'Super Quick Patch Guide' at the top of perlhack, and so however the
patch was sent should be whatever the perlbug command does by default.

Smylers

It's a lot more convenient to have an attached patch. I don't know what
perlhack should say instead of what it does.

p5pRT closed this as completed Jan 26, 2013

p5pRT added Severity Low distro-Linux documentation hasPatch labels Oct 19, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[PATCH] Correct nested pod bullets #12678

[PATCH] Correct nested pod bullets #12678

p5pRT commented Dec 31, 2012

p5pRT commented Dec 31, 2012

p5pRT commented Dec 31, 2012

p5pRT commented Dec 31, 2012

p5pRT commented Dec 31, 2012

p5pRT commented Dec 31, 2012

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

[PATCH] Correct nested pod bullets #12678

[PATCH] Correct nested pod bullets #12678

Comments

p5pRT commented Dec 31, 2012

p5pRT commented Dec 31, 2012

From @Smylers

p5pRT commented Dec 31, 2012

From @Smylers

p5pRT commented Dec 31, 2012

From @nwc10

p5pRT commented Dec 31, 2012

p5pRT commented Dec 31, 2012

From @Smylers

p5pRT commented Jan 26, 2013

From @khwilliamson

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

From @khwilliamson

p5pRT commented Jan 26, 2013

From @khwilliamson

p5pRT commented Jan 26, 2013

From @Smylers

p5pRT commented Jan 26, 2013

From @Smylers

p5pRT commented Jan 26, 2013

From @khwilliamson

p5pRT commented Jan 26, 2013

p5pRT commented Jan 26, 2013

From @khwilliamson