develooper Front page | perl.perl5.porters | Postings from August 2014

[perl #122532] [PATCH] Fix for superfluous line numbers in pod/perlthrtut.pod

Thread Previous
From:
James E Keenan via RT
Date:
August 19, 2014 22:47
Subject:
[perl #122532] [PATCH] Fix for superfluous line numbers in pod/perlthrtut.pod
Message ID:
rt-4.0.18-14841-1408488467-1471.122532-15-0@perl.org
On Thu Aug 14 16:19:56 2014, jkeenan wrote:
> On Wed Aug 13 14:43:25 2014, rolando_pereira@sapo.pt wrote:
> > This is a bug report for perl from rolando_pereira@sapo.pt,
> > generated with the help of perlbug 1.40 running under perl 5.21.3.
> >
> >
> > -----------------------------------------------------------------
> > [Please describe your issue here]
> >
> > Hello list,
> >
> > Looking to the file "pod/perlthrtut.pod" through the
> > "http://perldoc.perl.org" interface causes the example shown in
> > the section "A Complete Example" to have superfluous line
> > numbers.
> >
> > The problem is that although the example already has the line
> > numbers in the pod file, the "perldoc.perl.org" interface also
> > adds an additional set of line numbers to the examples.
> >
> > Since the other code samples don't have line numbers in the pod
> > file this patch fixes the issue by removing the line numbers
> > that are in the example.
> >
> >
> 
> Confirmed: http://perldoc.perl.org/perlthrtut.html#A-Complete-Example
> 
> > Since this is my first post to the list please tell me if I
> > made any mistake in preparing the patch. I tried to follow the
> > steps written in the "perlhack" document so I hope I did
> > everything correctly :)
> >
> >
> > Regards,
> > Rolando Pereira
> >
> 
> Rolando,
> 
> Thanks for your submission.  You have followed the instructions
> carefully and correctly.
> 
> The only problem is that while removing the line numbers will make "A
> Complete Example" look better on perldoc.perl.org, it removes semantic
> information when that example is viewed through *other* POD
> formatters.
> 
> For example, when I apply that patch to a branch based on blead, and
> then say:
> 
> #####
> perldoc pod/perlthrtut.pod
> #####
> 
> ... the line numbers are removed -- but then the text in subsequent
> paragraphs becomes hard to follow:
> 
> #####
> The bulk of the work is done by the "check_num()" subroutine, which
> takes
> a reference to its input queue and a prime number that it's
> responsible
> for. After pulling in the input queue and the prime that the
> subroutine is
> checking (line 11), we create a new queue (line 13) and reserve a
> scalar
> for the thread that we're likely to create later (line 12).
> #####
> 
> There are a total of 5 paragraphs that make reference to the line
> numbering in the example.  If we remove the line number from the text
> of pod/perlthrtut.pod, we improve the situation for perldoc.perl.org,
> but make the situation worse (IMHO) for other POD formatters.
> 
> I think this is mainly a question for those who maintain
> perldoc.perl.org to resolve (should they choose to do so; that site is
> not maintained by Perl 5 Porters).
> 

Rolando, since there has been no further discussion in this ticket, I'm going to close it without applying your patch.  I urge you to take your concerns up with the maintainers of perldoc.perl.org.

Thank you very much.
Jim Keenan

---
via perlbug:  queue: perl5 status: open
https://rt.perl.org/Ticket/Display.html?id=122532

Thread Previous


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