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

Re: [perl #116963] Add documentation on the advantages of perldocfor man users to perl.pod

Thread Previous | Thread Next
From:
H.Merijn Brand
Date:
February 28, 2013 15:33
Subject:
Re: [perl #116963] Add documentation on the advantages of perldocfor man users to perl.pod
Message ID:
20130228163255.7f3a762f@pc09.procura.nl
On Thu, 28 Feb 2013 08:20:40 -0700, Tom Christiansen <tchrist@perl.com>
wrote:

> 
> Reuben Thomas <rrt@sc3d.org> wrote
>    on Thu, 28 Feb 2013 10:39:26 GMT: 
> 
> >On 28 February 2013 02:36, tchrist1 via RT <perlbug-followup@perl.org> wrote:
> >> Reuben Thomas <rrt@sc3d.org> wrote
> >>    on Thu, 28 Feb 2013 00:23:14 GMT:
> >>
> >>>See issue #62136 for a sample. As far as I can tell, it's more of a
> >>>limitation of converting perldoc to man.
> >>
> >> Hm, you mean this issue?
> >>
> >>     % man -w sort
> >>     /usr/local/man/man3/sort.3
> >>     /usr/share/man/cat1/sort.0
> >>     /usr/share/man/cat3p/sort.0
> >>
> >>     % man -w open
> >>     /usr/local/man/man3/open.3
> >>     /usr/share/man/cat2/open.0
> >>     /usr/share/man/cat3p/open.0
> 
> >I'm sorry, I'm not sure what issue you're describing there.
> 
> I was trying to figure out what the confusion was.  I thought it 
> might be because there is more than one sort or open manpage.

Part of the reason that I liked (and committed) the patch (eventually)
is that 'man' is only available on *nix. I just checked on Windows7

C:\Users\Merijn>man perlrun
man wordt niet herkend als een interne
of externe opdracht, programma of batchbestand.

perldoc perlrun works fine. perldoc has improved over time and is by
now certainly worth mentioning in the docs as alternative to man, if
not the preferred to read perl docs. I admit I myself still use man,
but it probably more like muscle-memory.

> >The issue is this: man pages and perldoc support different sets of
> >lookup keys. man pages support really just one, names of pages.
> >perldoc supports several (FAQ entries, variable names, page names
> >&c.), not all of which map on to man pages.
> 
> >Hence, my patch points out this problem (in more concrete terms) and
> >offers a solution, namely to use perldoc. It attempts to place the
> >text where man users are likely to find it (near the start of the
> >principal man page).
> 
> Well, it wasn't supposed to be that way, and never used to be.  
> Perhaps somebody gratuitously futzed with the pod spec and so broke 
> the manpage conversion.  It used to work just fine.
> 
>     See the sort function in the perlfunc manpage.
> 
>     See "Why shouldn't I use defined on an array or hash" in the perlfaqXXX manpage.
> 
> Those should be perfectly fine.  If somebody broke that, they shouldn't have.

-- 
H.Merijn Brand  http://tux.nl   Perl Monger  http://amsterdam.pm.org/
using perl5.00307 .. 5.17   porting perl5 on HP-UX, AIX, and openSUSE
http://mirrors.develooper.com/hpux/        http://www.test-smoke.org/
http://qa.perl.org   http://www.goldmark.org/jeff/stupid-disclaimers/

Thread Previous | 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