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

[perl #118639] [PATCH] 6248b44 Added example usage and SEE ALSO links to similar modules in doc for if.pm

Thread Next
From:
Tony Cook via RT
Date:
July 2, 2013 02:00
Subject:
[perl #118639] [PATCH] 6248b44 Added example usage and SEE ALSO links to similar modules in doc for if.pm
Message ID:
rt-3.6.HEAD-2552-1372730412-1794.118639-15-0@perl.org
On Fri Jun 28 06:45:00 2013, public@khwilliamson.com wrote:
> On 06/26/2013 03:25 AM, Neil Bowers wrote:
> >> +The following line is taken from the testsuite for L<File::Map>:
> >> ...
> >> +This line is taken from L<Text::Soundex> 3.04,
> >>
> >> I think the references to where the examples came from is more
> >> distracting than enlightening.
> >
> > I know this is a minor point, but I'm quite likely to patch other
>    documentation, so it would be good to resolve it, so I don't
>    needlessly annoy you[1] with every patch.
> >
> > I read almost all perl documentation in a web browser[2], and I
>    personally find it annoying when documentation refers to a module,
>    but the module name isn't a link, as I then have to paste the
>    module name into MetaCPAN.
> >
> > Where there are multiple mentions in the same locality, then perhaps
>    only the first should be a link, and subsequent mentions could be a
>    C<module> (something I broke once in that patch).
> >
> > What say ye, perl patch porters?
> 
> I agree with your statement completely, and look forward to the
>    results
> of your work.
> 
> As to whether or not the the sources for your examples should have
>    been
> included, I am of two minds.  I can see Tony's point, and yet I like
> having real-world examples.  I would have phrased it more like "An
> example comes from the testuite for L<File::Map>."

My reaction to the change was more than a little confused - I felt
uncomfortable with applying the patch as is, but had trouble pinning
down exactly why.  Maybe the word wrapping on the Text::Soundex prose
put me off.

The module mentions were the only text that struck me as "off" about the
patch, which is why I mentioned them, but I suspect now it's the way
they were mentioned, rather than that they were mentioned at all.

Maybe s/The following line is taken from/From/

I'm not sure.

Tony

---
via perlbug:  queue: perl5 status: resolved
https://rt.perl.org:443/rt3/Ticket/Display.html?id=118639

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