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

Thread Next
Tony Cook via RT
July 2, 2013 02:00
[perl #118639] [PATCH] 6248b44 Added example usage and SEE ALSO links to similar modules in doc for
Message ID:
On Fri Jun 28 06:45:00 2013, 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.


via perlbug:  queue: perl5 status: resolved

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