develooper Front page | perl.perl5.porters | Postings from March 2011

Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a newOO tutorial)

Thread Previous | Thread Next
From:
Abigail
Date:
March 4, 2011 08:12
Subject:
Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a newOO tutorial)
Message ID:
20110304161211.GB28401@almanda
On Fri, Mar 04, 2011 at 09:38:30AM -0600, brian d foy wrote:
> In article <20110304131330.GE30220@almanda>, Abigail
> <abigail@abigail.be> wrote:
> 
> > On Thu, Mar 03, 2011 at 11:17:47PM -0600, brian d foy wrote:
> > > 
> > > With some changes to Pod::Perldoc, we can support the hierarchy with
> > > the old names as a deprecation cycle:
> > > 
> > >      $ perldoc5.16 perlsyn
> > >      Warning: perlsyn is now syntax, use `perldoc syntax`
> 
> 
> > Oh, that's a good candidate for hates-software.
> > 
> > People just seem to enjoy software that knows what they mean, but
> > isn't going to do it because one didn't use the right magic incantation.
> 
> 
> I think maybe you agree with him, but to clarify my point: that's a
> warning not an error. We can make the software do the right thing
> because we know what the user really wants, but at the same time
> educate the reader about the new locations. 
> 
> Of course, they aren't going to read the warning because they will skim
> right over it to read the good bits.


You're talking about a deprecation cycle. Either you intend the remove
the current location, or you don't. And in the latter case, the warning
is pointless (and there's no deprecation).

Look, if one thinks it's a huge improvement to no longer type "perl" in
front of syntax, wouldn't it be much better to educate perldoc? If $ARGV [0]
cannot be found, and $ARGV [0] !~ /^perl/, try again with "perl" . $ARGV [0].
Or use a table that maps $ARGV [0] to a canonical name.

That can be part of 5.14, noone has to learn a new names, old references
continue to work, and one doesn't have to wear out the p, e, r, and l
keys.


Abigail (or course "man perlsyn" is still shorter than "perldoc syntax").

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