Revising Perl's OO docs - a new OO tutorial
Dave Rolsky
goal for the Perl docs to revise all of the existing OO documentation.
My new document is available online for review:
http://urth.org/~autarch/new-pod/html/perlootut.pod.html
http://urth.org/~autarch/new-pod/pod/perlootut.pod
This document has several goals. First, I want to introduce the reader to
general OO concepts like classes and methods. Second, I want to explain
how these are done in Perl. Finally, I want to get them started with
writing OO code as quickly as possible.
That final goal means I _do not_ explain lots of low-level stuff about how
to create objects. I just point the reader to CPAN and say "here's some OO
frameworks to explore".
Right now we have the following:
perltoot - Tom's object-oriented tutorial for perl
perltooc - Tom's OO Tutorial for Class Data in Perl
perlboot - Beginner's Object-Oriented Tutorial
To the best of my knowledge, all of these documents date back to the
initial Perl 5 release. No offense intended to Tom or Randal (the
authors), but these documents have become extremely out of date in the
intervening 16+ years. Basically, there's a _lot_ of low-level stuff that
folks new to Perl 5 OO don't need to think about.
I'd like to remove all of these documents. They no longer reflect modern
Perl 5 OO practice, and I think any newbie reading them will just be
massively confused.
We also have:
perlbot - Bag o' Object Tricks (the BOT)
This document includes both tricks (aka weird shit you can do with Perl)
and some best practices. The best practices are generally are still
relevant, but the rest of the document is very out of date (there's a
section on using SDBM!).
Finally, we have:
perlobj - Perl objects
This is basically reference documentation. This could probably use some
revision, but we obviously still want a reference.
So my proposal is ...
* Replace all the existing tutorial docs with my new document
* Consider rewriting perlbot into a perloobp document (OO Best Practices),
or just remove it, since there's lots of best practice advice available
elsewhere.
* Revise perlobj to make sure it as complete and clear as possible.
Now I'll just put on my asbestos suit.
-dave
/*============================================================
http://VegGuide.org http://blog.urth.org
Your guide to all that's veg House Absolute(ly Pointless)
============================================================*/
Leon Timmermans
> I've been working on a new OO tutorial for Perl. This is part of a larger
> goal for the Perl docs to revise all of the existing OO documentation.
>
> My new document is available online for review:
>
> http://urth.org/~autarch/new-pod/html/perlootut.pod.html
> http://urth.org/~autarch/new-pod/pod/perlootut.pod
Thank you for this, it looks really good. I've been wanting to have
this to lead people to for quite some time. Thank you.
> To the best of my knowledge, all of these documents date back to the initial
> Perl 5 release. No offense intended to Tom or Randal (the authors), but
> these documents have become extremely out of date in the intervening 16+
> years. Basically, there's a _lot_ of low-level stuff that folks new to Perl
> 5 OO don't need to think about.
>
> I'd like to remove all of these documents. They no longer reflect modern
> Perl 5 OO practice, and I think any newbie reading them will just be
> massively confused.
I *fully* support this. The current tutorials are confusing and
irrelevant to newbies. I feel they are doing more harm than good, and
would favor their removal even without this new document.
> perlobj - Perl objects
>
> This is basically reference documentation. This could probably use some
> revision, but we obviously still want a reference.
Agreed. Actually I think some parts of perltoot's text could be moved
there. It's well written, it's just not relevant to someone who just
wants to get work done.
Leon
Abigail
> I've been working on a new OO tutorial for Perl. This is part of a larger
> goal for the Perl docs to revise all of the existing OO documentation.
>
> My new document is available online for review:
>
> http://urth.org/~autarch/new-pod/html/perlootut.pod.html
> http://urth.org/~autarch/new-pod/pod/perlootut.pod
>
> This document has several goals. First, I want to introduce the reader to
> general OO concepts like classes and methods. Second, I want to explain
> how these are done in Perl. Finally, I want to get them started with
> writing OO code as quickly as possible.
I've only had time to briefly skim the document, but if I have to summarize
the document, it seems to boil down to "Don't do objects yourself. Use
something that doesn't come with Perl".
Without further judging the content of the document, that just feels wrong.
Not that I have much of a solution though.
Abigail
Christian Walde
> Without further judging the content of the document, that just feels wrong.
I think it feels wrong too. That however is due to no fault of the document itself and unless the real problem is fixed i see no reason that the document would need to be changed. It is in fact the right advice.
--
With regards,
Christian Walde
Bram
<aut...@urth.org> wrote:
> I've been working on a new OO tutorial for Perl. This is part of a
> larger goal for the Perl docs to revise all of the existing OO
> documentation.
>
> My new document is available online for review:
>
> http://urth.org/~autarch/new-pod/html/perlootut.pod.html
> http://urth.org/~autarch/new-pod/pod/perlootut.pod
>
I'm going to ask some questions at the risk of starting a long thread:
Who is the 'primary target' of the documentation that is shipped with Perl?
a) novice users OR
b) advanced users OR
c) novice users and advanced users
Is it 'correct' to document something in core that is not shipped with core?
(Moose/Mouse/... are not shipped with core last time I checked)
What with the low level stuff of perltoot/perltooc/perlboot?
You're saying beginning users may not need them and/or might become
confused about them but what about advanced users that do understand
(and/or need) the information? Is all the information still available
in other pods?
Best regards,
Bram
Disclaimer-1: I only skimmed over your document and did not read it fully.
Disclaimer-2: I'm merley asking the question; I'm not expression an
opinion on what is right and wrong.
Dave Rolsky
> Who is the 'primary target' of the documentation that is shipped with Perl?
> a) novice users OR
> b) advanced users OR
> c) novice users and advanced users
This is a really good question, and I was thinking of starting a separate
thread on this.
Basically, my answer is all of ...
A) Novice users new to Perl who may or may not be new to programming. For
them, we have intro-to-language docs (perlsyn, perldata), tutorials, and
faqs.
B) Experienced users who need to look something specific up. They're more
likely to look in the reference docs, use "perldoc -f", etc. They should
not need to look in the tuturials.
C) Experienced users looking to learn something new. For example, someone
might know Perl really well but now they want to learn XS, or they want to
hack on the core. These users are novices _in a particular area_, and they
still want focused tutorials on these particular areas.
For the record, my new tutorial is squarely aimed at category A.
Some other questions to think about ...
* What kind of background do we expect novices to have? Do they know C?
Unix? Sed/awk/shell?
The old answer was yes to all of the above, which explains a lot about
some of the docs. The new answer is _none_ of the above.
* What are our goals for novices?
I think the existing docs have the wrong goal in many cases. The goal of
existing docs seems to be to impart a full and complete understanding of
the topic at hand. I think the goal should be to help the reader get up to
speed on modern Perl 5 as quickly as possible.
> Is it 'correct' to document something in core that is not shipped with core?
> (Moose/Mouse/... are not shipped with core last time I checked)
Yes, why not? One of the great things about Perl is CPAN. Should we
pretend it doesn't exist?
I think the best path for a novice to quickly (and safely) write Perl OO
code is to use an object system off CPAN.
> What with the low level stuff of perltoot/perltooc/perlboot?
When these docs were written, it made sense for a tutorial to cover the
gory details. My best guess is that their primary audience was existing
Perl 4 developers.
> You're saying beginning users may not need them and/or might become confused
> about them but what about advanced users that do understand (and/or need) the
> information? Is all the information still available in other pods?
That's what perlobj is for. We should have a good from-the-ground-level-up
reference on Perl OO, but a tutorial is not a reference.
Leon Timmermans
> I've only had time to briefly skim the document, but if I have to summarize
> the document, it seems to boil down to "Don't do objects yourself. Use
> something that doesn't come with Perl".
>
> Without further judging the content of the document, that just feels wrong.
>
> Not that I have much of a solution though.
I can understand that. I think it feels wrong to everyone, but doing
it all by hand like it's 1997 all over again feels significantly more
wrong. Besides, the right answer to almost anything non-trivial in
Perl is «check CPAN first».
Leon
Johan Vromans
> I've only had time to briefly skim the document, but if I have to summarize
> the document, it seems to boil down to "Don't do objects yourself. Use
> something that doesn't come with Perl".
>
> Without further judging the content of the document, that just feels wrong.
It's okay to point to some elegant OO modules on CPAN, but the document
should describe all the basics that are part of and implementable with
core Perl.
Leon Timmermans <faw...@gmail.com> writes:
> [...] but doing it all by hand like it's 1997 all over again feels
> significantly more wrong. Besides, the right answer to almost anything
> non-trivial in Perl is «check CPAN first».
Many Perl documents describe algorithms and code that are better handled
in CPAN modules. The standard Perl documents describes core Perl, not
CPAN Perl.
-- Johan
Leon Timmermans
> It's okay to point to some elegant OO modules on CPAN, but the document
> should describe all the basics that are part of and implementable with
> core Perl.
Why should that be part of a tutorial? What would be the usefulness of that?
Leon
Richard Foley
>
> > Now I'll just put on my asbestos suit.
>
Good idea.
Ciao
Richard
--
Richard Foley
Ciao - shorter than AufWiederSehen!
http://www.rfi.net/books.html
Richard Foley
> perltoot - Tom's object-oriented tutorial for perl
> perltooc - Tom's OO Tutorial for Class Data in Perl
> perlboot - Beginner's Object-Oriented Tutorial
>
Definitely confusing. A rewrite is a good idea, although I'm not sure
replacing all 5 documents with a single one is the right way to go. Taking
the regex docs as a starting point might be an idea.
perloo - starting point + quick + reference to other docs.
perlootut - tutorial
perlooref - reference
perloosa - smart arse + clever tricks
Ciao
Richard
--
Richard Foley
Ciao - shorter than AufWiederSehen!
http://www.rfi.net/books.html
Dave Rolsky
>
>> perltoot - Tom's object-oriented tutorial for perl
>> perltooc - Tom's OO Tutorial for Class Data in Perl
>> perlboot - Beginner's Object-Oriented Tutorial
>> perlbot - Bag o' Object Tricks (the BOT)
>> perlobj - Perl objects
>>
> Definitely confusing. A rewrite is a good idea, although I'm not sure
> replacing all 5 documents with a single one is the right way to go. Taking
> the regex docs as a starting point might be an idea.
>
> perloo - starting point + quick + reference to other docs.
> perlootut - tutorial
> perlooref - reference
> perloosa - smart arse + clever tricks
I was not proposing to replace all of them. At a minimum, I think we need
a tutorial and a reference. The existing perlobj document is already a
reference, and I'd like to simply revise it, rather than replacing it.
Richard Foley
>
were only talking about the first three. Apologies for any misunderstanding
on my part.
I think your basic premise, of a solid restructuring of the docs., is a valid
one and would be beneficial, in particular to newcomers but also to the rest
of us. Of course, that's a big can of worms wriggling about in the pod dir/
and no doubt some chinese gentleman once said: "even a one thousand mile
journey begins with a single step" :-)
Ciao
Richard
--
Richard Foley
Ciao - shorter than AufWiederSehen!
http://www.rfi.net/books.html
Philip Monsen
>
> http://urth.org/~autarch/new-pod/html/perlootut.pod.html
> http://urth.org/~autarch/new-pod/pod/perlootut.pod
>
> This document has several goals. First, I want to introduce the reader to
> general OO concepts like classes and methods. Second, I want to explain
> how these are done in Perl. Finally, I want to get them started with
> writing OO code as quickly as possible.
After reading the new tutorial, I agree that it meets these goals.
> That final goal means I _do not_ explain lots of low-level stuff about how
> to create objects. I just point the reader to CPAN and say "here's some OO
> frameworks to explore".
It does this very charitably, steering newbies away from diving right
into bare-bones core OO but often mentioning the availability of
low-level details (with cross-references) if interest or need warrants
consulting
those.
> To the best of my knowledge, all of these documents date back to the
> initial Perl 5 release. No offense intended to Tom or Randal (the
> authors), but these documents have become extremely out of date in the
> intervening 16+ years. Basically, there's a _lot_ of low-level stuff that
> folks new to Perl 5 OO don't need to think about.
Arguably folks "old" to Perl 5 OO also don't need or want to think about
these most or all of the time.
I agree that it is time to synchronize the bundled documentation with
modern practice while keeping just enough low-level detail available
to assure that the core behaviors are documented. I'd much rather start
with this tutorial, given the OO frameworks available today,
than with any of the existing bundled ones. It's not that the bundled ones
don't have inherent value, it's more that modern practice has eclipsed
their being a reasonable starting point for doing Perl OO.
> * Replace all the existing tutorial docs with my new document
> * Consider rewriting perlbot into a perloobp document (OO Best Practices),
> or just remove it, since there's lots of best practice advice available
> elsewhere.
> * Revise perlobj to make sure it as complete and clear as possible.
Agreed on all points. Thanks for putting time and effort into getting
the ball rolling on this.
--Phil Monsen
Tom Christiansen
that tells people they can't use the standard distribution.
If you want to include something in the standard distribution
whose entire focus is outside the standard distribution, then
you should bring the thing that is outside, inside.
--tom
Tom Christiansen
>whose entire focus is outside the standard distribution, then
>you should bring the thing that is outside, inside.
Or vice versa.
--tom
Matt Sergeant
> Please don't include anything in the standard distribution
> that tells people they can't use the standard distribution.
>
I'm sure you have a distinction, but I'd be curious what it is.
Tom Christiansen
It's exactly what Abigail said way back on Monday:
I've only had time to briefly skim the document, but if I
have to summarize the document, it seems to boil down to
"Don't do objects yourself. Use something that doesn't come
with Perl".
Without further judging the content of the document,
that just feels wrong.
Not that I have much of a solution though.
It feels wrong because it *is* wrong. You cannot tell people,
beginners especially, that they cannot use the Perl that came
with their distribution for OO programming.
That is not acceptable.
--tom
Matt Sergeant
> Matt Sergeant<ma...@sergeant.org> wrote
>
>>> Please don't include anything in the standard distribution
>>> that tells people they can't use the standard distribution.
>>>
>>>
>> perlfaq is full of this sort of advice though.
>>
>> I'm sure you have a distinction, but I'd be curious what it is.
>>
>
> It's exactly what Abigail said way back on Monday:
>
> I've only had time to briefly skim the document, but if I
> have to summarize the document, it seems to boil down to
> "Don't do objects yourself. Use something that doesn't come
> with Perl".
>
> Without further judging the content of the document,
> that just feels wrong.
>
> Not that I have much of a solution though.
>
suggest a solution, but rather MANY solutions. And it doesn't even
suggest the solutions until the end of the document, which left me
reading the document going "But that code won't work unless you ...".
Perhaps I'm the wrong audience, but I do like to think I can still read
a document as though I were a beginner.
More specifically, I think it almost tries too hard to not cover
"bless". You could just add in a comment in there saying "Person->new
hides the bless call in this example.".
I just disagree with the basic sentiment of "don't tell people to do
things that they can't do with the standard distro" as we tell people to
do that in a number of places in the docs.
> It feels wrong because it *is* wrong. You cannot tell people,
> beginners especially, that they cannot use the Perl that came
> with their distribution for OO programming.
>
> That is not acceptable.
>
I don't think it does say that [*], but I think it could say better what
it sets out to do.
Matt
[*] Specifically it says: If you want to know how Perl OO works under
the hood, the perlobj <http://search.cpan.org/perldoc?perlobj> document
explains the nitty gritty details.
Jesse Vincent
We can _certainly_ tell them that there are a number of modern OO
frameworks for Perl that are more feature complete and easier to work
with than building their own from Perl's OO primitives, so long as we
also point to reference docs about how those primitives work.
Teaching beginners that their first experience with object oriented perl
should be to roll their own OO system was a perfectly reasonable choice
in 1996. In 2011, it is not a reasonable choice.
Perl and CPAN are inextricably linked. _Not_ recommending that users
look to CPAN for complex and interesting functionality is wrong.
When Dave and I spoke about his OO documentation overhaul, my
requirement was that he continue to document the details of how
the internals of Perl's OO system as reference documentation rather
than as the first trout we smack a new Perl programmer with.
-Jesse
Steffen Mueller
On 03/03/2011 08:06 PM, Tom Christiansen wrote:
> It feels wrong because it *is* wrong. You cannot tell people,
> beginners especially, that they cannot use the Perl that came
> with their distribution for OO programming.
>
> That is not acceptable.
I agree. But I have a hunch that our assessment of the optimal solution
to this might be very different.
Hint: I would love to include Dave's tutorial.
--Steffen
Tom Christiansen
>> beginners especially, that they cannot use the Perl that came
>> with their distribution for OO programming.
>>
>> That is not acceptable.
> I agree. But I have a hunch that our assessment of the optimal
> solution to this might be very different.
I doubt it. :)
I am betting that the "optimal" solution is to import some 'mungous CPAN
framework into the core distribution, trade TMTOWTDI in for TOOWTDI, and
tell people that this is now *THE* way that Thou Shalt Do Objects in Perl.
Are we ready to do that?
Ok.
--tom
Tom Christiansen
> objects (or anything) makes my skin crawl.
Well, yes. :(
--tom
Abigail
Hash::Util::FieldHash *is* part of the core distribution, so we can
promote PBP's suggestion for inside out objects without adding more
modules to the core. ;-/
Of course, Dave's document is silent about it, and there are probably
another dozen modules/techniques outthere that aren't discussed either.
Picking one technique and promoting it as *THE* way of doing objects
(or anything) makes my skin crawl.
Abigail
Leon Timmermans
> I am betting that the "optimal" solution is to import some 'mungous CPAN
> framework into the core distribution, trade TMTOWTDI in for TOOWTDI, and
> tell people that this is now *THE* way that Thou Shalt Do Objects in Perl.
To me perltoot and friends already suggest there's only one way to do
it, and that's rolling out your own code by hand. From a TIMTOWTDI
point of view I think perlootut is very much an improvement IMHO.
Leon
Tom Christiansen
>> framework into the core distribution, trade TMTOWTDI in for TOOWTDI, and
>> tell people that this is now *THE* way that Thou Shalt Do Objects in Perl.
>To me perltoot and friends already suggest there's only one way to do
>it, and that's rolling out your own code by hand. From a TIMTOWTDI
>point of view I think perlootut is very much an improvement IMHO.
I have no problem with including some Big OO Framework in the core
distribution. It's just that a document about something so fundamental
to the language as OO should not need to go outside the core to get
the overwhelming majority of its point across.
If the conclusion is that you should *not* do OO in Perl *without*
a Big OO Framework, then Perl has to have one of those in its core.
--tom
Tom Christiansen
> discussing and dissecting put aside, we should give some mad
> credit to Dave for doing the work. Writing awesome docs is as hard
> as writing madly clever code. This isn't aimed at Tom or anybody
> specifically, by the way.
Absolutely. 1000%.
--tom
Jesse Vincent
> Picking one technique and promoting it as *THE* way of doing objects
> (or anything) makes my skin crawl.
I count Dave's document as describing _three_ systems. It also
starts off by saying:
This document provides an introduction to object-oriented programming in
Perl. It begins with a brief overview of the concepts behind object
oriented programming. Then it introduces several different OO systems
from CPAN which build on top of what Perl provides.
If you want to know how Perl OO works under the hood, the perlobj
document explains the nitty gritty details.
That's hardly promoting "one way to do it."
Tom Christiansen
I don't mind changing what core is.
--tom
Steffen Mueller
"We," as in the loose band of opinions that p5p are, are certainly not.
Neither am I.
Instead, I think we should slowly build our (or "our") way up from what
we have towards what has been proven to work in terms of interfaces.
Alas. It's hard work both technically and politically. Worse yet, I am
not up for it but can't prevent myself from saying I'd like to see that.
Best regards,
Steffen
(who's talk to code ratio is going to fall over if he replies to one
more email and thus needs to go back to work now.)
Matt Sergeant
> What I would maily like is for the core to talk mainly about the core.
>
> I don't mind changing what core is.
>
of base.pm? The docs for parent.pm suggest it is a fork of base.pm - is
there a reason those changes shouldn't be merged back into base.pm?
Matt.
Christian Walde
>>> It feels wrong because it *is* wrong. You cannot tell people,
>>> beginners especially, that they cannot use the Perl that came
>>> with their distribution for OO programming.
>>>
>>> That is not acceptable.
>
>> I agree. But I have a hunch that our assessment of the optimal
>> solution to this might be very different.
>
> I am betting that the "optimal" solution is to import some 'mungous CPAN
> framework into the core distribution, trade TMTOWTDI in for TOOWTDI, and
> tell people that this is now *THE* way that Thou Shalt Do Objects in Perl.
Why does importing one object system into Perl core translate to 'TOOWTDI'? Saying "if you want you can use <premade thing> or any of <premade things on cpan> or roll your own" still seems very much TMTOWTDI to me.
I feel by arguing along that line you're guiding discussion down along a path that is separate from the reality of the proposed actions.
--
With regards,
Christian Walde
John Peacock
> BTW did I miss some reason the document suggests using parent.pm instead
> of base.pm? The docs for parent.pm suggest it is a fork of base.pm - is
> there a reason those changes shouldn't be merged back into base.pm?
base.pm does some profoundly odd things, too. Check out the behavior
when the "base" class doesn't include a $VERSION scalar...
John
Christian Walde
As far as i understand it base comes with some extra features that bloat it up unnecessarily (fields) and are only very seldomly used.
parent removed those and thus simplified it to a module that concerns itself only with inheritance. As such a merging isn't really possible, as it'd need to remove features from base.
brian d foy
<ma...@sergeant.org> wrote:
> Tom Christiansen wrote:
> > Please don't include anything in the standard distribution
> > that tells people they can't use the standard distribution.
> >
> perlfaq is full of this sort of advice though.
However, I try to show a core Perl example whenever reasonable. If the
task would take more than 50 lines of Perl, I'm just going to punt to
CPAN.
brian d foy
<tch...@perl.com> wrote:
The summary: can we reduce the size of the list in perl.pod and replace
major sections of the docs with new material not based on what's
already there?
Some of Dave's work on his new OO tutorial may have come out of a Perl
heretic talk I gave in Minneapolis around Halloween:
http://www.slideshare.net/brian_d_foy/perldocs
The non-core-reference documented has accreted in an unplanned way
based on whatever people wanted to contribute. It's nice that the
information is there, but not so nice for the person who has to find it
or decide what to read. The terse naming scheme and lack of hierarchy
confuses ordinary people.
For instance, where do you find the rules and documentation about
creating variables? It's not in perlvar. While it might make sense to
us that it's in perlsyn, to the newbie who sees a doc page that says
"var", that's the first place they'd naturally want to look.
Similarly, we have swirling around the core reference various quick
starts, tutorials, faqs, and so on.
So, when it comes to OO, what should the new person read? Although Dave
doesn't go so far as saying that he wants to replace the various
non-reference pods, I think that's what should happen. Can we collapse
perltoot, perlboot, perlobj, perlmod, and perlmodlib into fewer
documents? Do we have to keep a particular document merely because it
has always been there evne though no one is updating it?
The problem, of course, is that you have to treat several topics almost
simultaneously, including the Perl object system, the package and
namespace system, references, and distributions, as well as popular
add-ons from CPAN. Dave also correctly recognizes that most people
suffer because they don't grasp OO from the start, so they already have
a disadvantage.
So, there are various fantasies I have about what the pod/ directory
could be and how that might help people.
First, I'd want to organize it:
pod/
reference
tutorials
quickstarts
faq
os-specific
changes
unicode
&c.
Those are the easy ones, but then we can get a little sloppy. Old docs
don't have to go away, they just have to find a new home that's out of
the way. We can also be a bit looser with contributions, like Dave's,
pod/
contributed (third-party, whatever)
legacy (old, unsupported, whatever)
I also hear that we are abandoning the 8.3 filesnames, which some of
the pod files already ignore, so can we make better names and get rid
of the useless four characters at the front (except maybe for
installing man pages):
pod/
references/
variables.pod
syntax.pod
operators.pod
If we really wanted to get crazy:
pod/
references/
functions/
open.pod
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`
People don't have to know the hierarchy to find the docs with perldoc
because we'll do that for them. However, when they go to
perldoc.perl.org or a similar site where they aren't using perldoc,
they have a leg up.
Next, in various docs, as appropriate and especially for tutorials, I'd
put in hints on what the reader should already have looked at, and add
more cross references. The goal is to reduce the repeated information
(such as the here docs stuff I just patched in perlfaq and perldiag).
From there, I'd make a map that shows the relationship of the docs (as
we say in the Army "A graphical depiction of the earth as seen from
above"). It would be grand if I could also figure out how to direct the
person the the right starting point in the map. Although I could do
that in Inform, maybe, then we'd have to add a z-code runner to core.
:)
Some of this begs for a bit more structure. We don't do much with X<>,
and it would be nice to have structured info that comes out of X<> or
L<> or maybe something new ( R<reference>? ) that allows us to make
that map as part of building perl.
That's enough for tonight.
H.Merijn Brand
wrote:
Enough? :)
I like the idea, but worry about what old-school people like me would
have to type when using "man" instead of "perldoc". What manual pages
would it generate?
$ man perlvar
and
$ man perlrun
are things I still type on a pretty regular basis (regular in the sense
of recurring, not as that I type it twice a day)
I don't like the prospect to have to type
$ man perl-objects-tutorial-references
or any other long sequence and I *certainly* do not want to go in the
direction that "info" went and make any documentation useless unless
completely printed on dead trees. (That obviously belongs in
hates-software and not here)
So, did you also had ideas about "man" naming schemes?
--
H.Merijn Brand http://tux.nl Perl Monger http://amsterdam.pm.org/
using 5.00307 through 5.12 and porting perl5.13.x on HP-UX 10.20, 11.00,
11.11, 11.23 and 11.31, OpenSuSE 10.1, 11.0 .. 11.3 and AIX 5.2 and 5.3.
http://mirrors.develooper.com/hpux/ http://www.test-smoke.org/
http://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/
Johan Vromans
> I like the idea, but worry about what old-school people like me would
> have to type when using "man" instead of "perldoc". What manual pages
> would it generate?
>
> $ man perlvar
> $ man perlrun
I must admit that I didn't even know you could do that.
Perl comes with perldoc, so why man, except for perl.1 ?
The current perl.1 already exclusively refers to the use of perldoc.
A quick look reveals that there are 177 perl*1 documents in my man tree,
176 of them do not belong there. Not in man1, man7 maybe, but I doubt
they should be in man at all, again, given that we have perldoc.
IMHO, perlrun.1 would be a better candidate for perl.1; all the other
documents can be used with perldoc.
-- Johan
demerphq
> 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`
I hope we don't ever stop supporting the old names.
I don't mind renaming them provided we support the old names as
aliases: there is just too much documentation material, forms, and
emails out there for a total deprecation to be reasonable.
I can't imagine how many Perlmonks pages would be invalidated if we
dropped 'perlsyn'
cheers,
Yves
--
perl -Mre=debug -e "/just|another|perl|hacker/"
Abigail
>
> 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.
Making "perldoc perlsyntax" and "perldoc syntax" do the same seems
fine to me.
Abigail
Leon Timmermans
> Some of this begs for a bit more structure. We don't do much with X<>,
> and it would be nice to have structured info that comes out of X<> or
> L<> or maybe something new ( R<reference>? ) that allows us to make
> that map as part of building perl.
As I said before, perl's documentation is very much manpage-oriented,
and one aspect of that is the perl prefix to almost all core docs. I
think it would be better if man is demoted to being one format among
equals (in theory that is already the case, in practice it doesn't
quite feel that way).
Leon
Tom Christiansen
>> I like the idea, but worry about what old-school people like me would
>> have to type when using "man" instead of "perldoc". What manual pages
>> would it generate?
>>
>> $ man perlvar
>> $ man perlrun
> I must admit that I didn't even know you could do that.
> Perl comes with perldoc, so why man, except for perl.1 ?
Sicut erat in principio...
> The current perl.1 already exclusively refers to the use of perldoc.
> A quick look reveals that there are 177 perl*1 documents in my
> man tree, 176 of them do not belong there.
"Not belong"? Sure they do.
> Not in man1, man7 maybe,
Well, ok. But I'd say section 5 in some cases.
Perl itself belongs in section 6, of course.
> but I doubt they should be in man at all, again, given that we
> have perldoc.
That isn't right. Never put something in perldoc that isn't in man.
Don't make people run different tools to get at different subsets
of the system documentation. That's abhorrent.
> IMHO, perlrun.1 would be a better candidate for perl.1;
Yes, I see what you mean.
> all the other documents can be used with perldoc.
I must admit that I have never used this perldoc thing.
Ever. Truly.
If I can't do what I need to do with "man" and "man -k",
I just cd to the build directory and do fancier queries.
--tom
***RUN THIS***
:g/^[^>].*\.$/s/$/ :)/
Peter Scott
> Picking one technique and promoting it as *THE* way of doing objects (or
> anything) makes my skin crawl.
We don't have to do that. The docs should be honest about what's so:
(1) The most commonly agreed best practice O-O framework is Moose.
Here's how to use it.
(2) A best practice is not the only practice.
(3) Some people pick alternatives because x, y, z (including legacy).
(4) What's going on under the hood (reference material) is: ...
The only part of the scenario that makes my skin crawl is how many
modules we'd have to add to the core to insert Moose. Because it would
be insulting and/or inconsistent for core documentation to recommend a
*best* practice that couldn't be implemented without a CPAN sojourn.
--
Peter Scott
Tom Christiansen
> The only part of the scenario that makes my skin crawl is how many
> modules we'd have to add to the core to insert Moose. Because it would
> be insulting and/or inconsistent for core documentation to recommend a
> *best* practice that couldn't be implemented without a CPAN sojourn.
Peter, thank you for saying that so well -- especially the second sentence,
but also the first one.
--tom
brian d foy
<AANLkTik9vTTVAuMist7y_...@mail.gmail.com>, Leon
Timmermans <faw...@gmail.com> wrote:
> As I said before, perl's documentation is very much manpage-oriented,
> and one aspect of that is the perl prefix to almost all core docs.
To insert into "foreign" systems, I figured we could traverse our own
doc tree, add a "perl" on the front of each filename, and inject it
into man in the right place.
If you're talking about translating the Pod constructs to *roff, I say
we do the best we can and not worry about some ideas that *roff might
not be able to handle. We wouldn't cripple the man pages, but we
wouldn't let them hold back the pod either.
brian d foy
<abi...@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.
Matt Sergeant
> I must admit that I have never used this perldoc thing.
>
> Ever. Truly.
>
documentation for perl functions by loading "man perlfunc" and searching
through, most do "perldoc -f <function>". And when helping people out on
IRC or mailing lists I never load up each perlfaq file and grep through
- perldoc -q is MUCH more efficient.
I'm actually surprised you've never used either of those features.
It's also very useful (vital even) on Windows (except Cygwin) where
there is no "man".
Matt.
Abigail
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").
Matt Sergeant
where it's available. I've been on systems where the time wait for
perldoc to parse the pod is significant enough that man is much faster.
Matt.
Dave Rolsky
> On Fri, Mar 04, 2011 at 10:56:37AM -0600, Dave Rolsky wrote:
>>
>> I also think we should consider writing the docs assuming they will be
>> mostly viewed on the web,
>
> Personally, I find that an almost alien thought.
>
> Why would anyone use a web interface for something that's already
> there locally?
Because people are used to reading docs on the web for almost everything.
Heck, even for Perl modules, I often go to search.cpan.org because it
provides a better interface for reading the docs.
Frankly, it's somewhat shameful that Perl doesn't ship with a great
in-browser doc reader app for installed docs. At the very least, we should
be generating html every time a Perl module is installed.
Just because you (and other people on this list) are very comfortable with
the status quo does not mean that it's good for everyone. I think we need
to spend a lot more effort thinking about what's best for new users. What
does a college kid getting into programming need to get started with Perl?
I don't want to start ranting about Perl dying, but I do think that
catering to potential new Perl programmers is very, very important. Right
now the Perl core docs don't do a very good job of that.
-dave
/*============================================================
http://VegGuide.org http://blog.urth.org
Your guide to all that's veg House Absolute(ly Pointless)
============================================================*/
David E. Wheeler
To me this is simply making the case to add a proper, canonical, simple OO implementation to core perl, starting with three keywords: class, has, and meth(?:od). CPAN modules will update to take advantage of them (hell, most of them *want* to), and we could document a very simple OO interface in the docs, and then point to Moose or whatever for users who need more.
The lack of a decent OO interface that takes care of many of the mundane details of OO implementation is an embarrassment.
Best,
David
Dave Rolsky
> So, when it comes to OO, what should the new person read? Although Dave
> doesn't go so far as saying that he wants to replace the various
> non-reference pods, I think that's what should happen. Can we collapse
> perltoot, perlboot, perlobj, perlmod, and perlmodlib into fewer
Actually, I _do_ want to replace all the existing tutorials with my new
one. My plan is to end up with:
perlootut - my new tutorial
perlobj - covers OO from the ground up in detail
I agree that a larger view is probably a good idea.
> documents? Do we have to keep a particular document merely because it
> has always been there evne though no one is updating it?
To answer that question, no.
> First, I'd want to organize it:
I generally agree with you. We need a hierarchy. The current flat
organization is hard to deal with, and the 8.3 naming is really painful,
made more painful because everything starts with "perl".
> 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`
Sounds good to me.
I also think we should consider writing the docs assuming they will be
mostly viewed on the web, especially for new users. Mostly that just means
really good cross linking, linking to other websites, etc.
Abigail
>
> mostly viewed on the web,
Personally, I find that an almost alien thought.
Why would anyone use a web interface for something that's already
there locally?
Abigail
Abigail
> Tom Christiansen wrote:
>> I must admit that I have never used this perldoc thing.
>>
>> Ever. Truly.
>>
> I think you're in a minority there - very few people look for the
> documentation for perl functions by loading "man perlfunc" and searching
> through, most do "perldoc -f <function>". And when helping people out on
> IRC or mailing lists I never load up each perlfaq file and grep through
> - perldoc -q is MUCH more efficient.
I'm one of the users that mostly uses perldoc in combination with -f;
for perldoc -q, I usually don't remember the question. And I'd never use
perldoc manpage; if only because 'man' is less than half the characters
of 'perldoc'. Though sometimes 'perldoc Some::Module' for a module that
hasn't been installed in the usual way can be handy.
> I'm actually surprised you've never used either of those features.
>
> It's also very useful (vital even) on Windows (except Cygwin) where
> there is no "man".
Yeah, but then, Windows doesn't come with Perl either.... ;-)
Abigail
Jesse Vincent
On Fri, Mar 04, 2011 at 11:11:02AM -0600, Dave Rolsky wrote:
>
> Frankly, it's somewhat shameful that Perl doesn't ship with a great
> in-browser doc reader app for installed docs.
Assuming a minimal dep chain and a good run of CPAN development
beforehand, I'd consider such a thing in core for 5.16
H.Merijn Brand
I almost NEVER use HTML presenters for perldoc. I use "man" 95% of the
time and 4% the quick ref guide and 1% the books.
So viewing from the web is a no-op for me.
H.Merijn Brand
wrote:
Even though I know perldoc, I still read the manual pages with man. I
*do* use perldoc, but seldomly to read the pod. I use the -l and -m
option to perldoc a lot. Code speaks quicte often loader than words.
Tom Christiansen
> If you're talking about translating the Pod constructs to
> *roff, I say we do the best we can and not worry about some
> ideas that *roff might not be able to handle. We wouldn't
> cripple the man pages, but we wouldn't let them hold back the
> pod either.
Oh? What sort of things might those be, Brian?
As far as I know, troff should be able to accommodate
anything in pod. After all, troff is bazoodles of times
more-complicated/unplain than pod is! Roff is unpod.
If you mean some of the meta-stuff like C<< X<> >> indexing and
C<< =for stopwords >> and stuff, well, that isn't really its job.
That's for a higher-level tool.
Speaking of high-level stuff, for a long while, only pod2man
alone handled such user-friendly dwimmercraft as this:
Besides the obvious pod conversions, Pod::Man also takes
care of formatting func(), func(3), and simple variable
references like $foo or @bar so you don't have to use code
escapes for them; complex expressions like $fred{'stuff'}
will still need to be escaped, though. It also translates
dashes that aren't used as hyphens into en dashes, makes
long dashes--like this--into proper em dashes, fixes
"paired quotes," makes C++ look right, puts a little space
between double underscores, makes ALLCAPS a teeny bit
smaller in troff, and escapes stuff that *roff treats as
special so that you don't have to.
Being smart like that to "just do the right thing" is very in
keeping with pod. Don't make programmers be page-layerouters. :)
I'm sure it must have been a bit gnarly for Russ Allbery
when he created a Pod::Man to emulate the old behavior:
# For right now, default to turning on all of the magic.
$$self{MAGIC_CPP} = 1;
$$self{MAGIC_EMDASH} = 1;
$$self{MAGIC_FUNC} = 1;
$$self{MAGIC_MANREF} = 1;
$$self{MAGIC_SMALLCAPS} = 1;
$$self{MAGIC_VARS} = 1;
But he did so, and it looks good; pod2man is still the best way
to generate Postscript/PDF to send to the printer.
I don't believe Allison's Pod::Pseudopod does any of that magic.
Pod::Html has a little bit of that, just functions and manpages
I think. It doesn't use CSS to get proper sᴍᴀʟʟ ᴄᴀᴘs in the font.
I am quite surprised and perhaps even a bit distressed to see
that pod2html never got rewritten to inherit from something more
robust in its parsing.
No wonder I keep getting bug reports on it. :(
--tom
Abigail
> On Fri, 04 Mar 2011 11:11:28 -0500, Matt Sergeant <ma...@sergeant.org>
> wrote:
>
> > Matt Sergeant wrote:
> > > Tom Christiansen wrote:
> > >> I must admit that I have never used this perldoc thing.
> > >>
> > >> Ever. Truly.
> > > I think you're in a minority there - very few people look for the
> > > documentation for perl functions by loading "man perlfunc" and
> > > searching through, most do "perldoc -f <function>". And when helping
> > > people out on IRC or mailing lists I never load up each perlfaq file
> > > and grep through - perldoc -q is MUCH more efficient.
> > >
> > > I'm actually surprised you've never used either of those features.
> > >
> > > It's also very useful (vital even) on Windows (except Cygwin) where
> > > there is no "man".
> > I should clarify: I'm not suggesting removing the option of using "man"
> > where it's available. I've been on systems where the time wait for
> > perldoc to parse the pod is significant enough that man is much faster.
>
> Even though I know perldoc, I still read the manual pages with man. I
> *do* use perldoc, but seldomly to read the pod. I use the -l and -m
> option to perldoc a lot. Code speaks quicte often loader than words.
I didn't know about the -m and -l options, and I'd automatically typed
"man perldoc" to find out what they mean. ;-)
Abigail
Tom Christiansen
>in-browser doc reader app for installed docs.
No, it's completely shameful that people think it doesn't.
--tom
Tom Christiansen
> the mundane details of OO implementation is an embarrassment.
Sure seems to be a lot of misplaced shame and embarrassment
going around today.
--tom
Tom Christiansen
>>
>> Ever. Truly.
> I think you're in a minority there - very few people look for the
> documentation for perl functions by loading "man perlfunc" and searching
> through, most do "perldoc -f <function>". And when helping people out on
> IRC or mailing lists I never load up each perlfaq file and grep through
> - perldoc -q is MUCH more efficient.
What in the world would I type 10 characters instead of 3???
I had no idea what those do, since I don't use the program.
Let's see...
As for the FAQ, um well, I don't have a great deal of cause
to consult it. :)
Just kidding. Actually, I would always rather run my own searches.
> I'm actually surprised you've never used either of those features.
> It's also very useful (vital even) on Windows (except Cygwin) where
> there is no "man".
Considering there's no "tchrist" there, either, it's immaterial to me.
I have negative reason to recreate a perfectly functioning wheel. :)
That said, a very long time ago I wrote a spec, and a program,
that did a lot of neat stuff with perl documentation. Because I
couldn't find a Prisoner of Bill to make sure it ran there for me,
it died.
--tom
Matt Sergeant
> On Fri, 4 Mar 2011 18:02:54 +0100, Abigail<abi...@abigail.be> wrote:
>
>
>> On Fri, Mar 04, 2011 at 10:56:37AM -0600, Dave Rolsky wrote:
>>
>>> I also think we should consider writing the docs assuming they will be
>>> mostly viewed on the web,
>>>
>> Personally, I find that an almost alien thought.
>>
>> Why would anyone use a web interface for something that's already
>> there locally?
>>
> I almost NEVER use HTML presenters for perldoc. I use "man" 95% of the
> time and 4% the quick ref guide and 1% the books.
>
> So viewing from the web is a no-op for me.
>
rather think gathering opinions here (me personally: 90% perldoc, 10%
search.cpan.org) is probably not the best place.
Matt.
Matt Sergeant
> What in the world would I type 10 characters instead of 3???
Because there is no "man" equivalent of "perldoc -f".
Because there is no "man" equivalent of "perldoc -q" (yes I don't use it
personally either, but I *do* refer newbies to the FAQ pages, which
still requires making sure the query finds what they need to know)
Because there's no "man" equivalent of "perldoc -m"
Because man can't read the pod prettily in a local file.
Because you can alias perldoc to "pd" if you want to, so a number of
characters argument is silly.
Because man can't deal with documentation from multiple perl installations.
There are plenty of reasons to prefer perldoc to man.
Again, not arguing against man, but because of the multiple uses of
perldoc I prefer to stick to one tool. (much like I stick to perl
instead of hacking bash and awk and sed together).
Matt.
Jesse Vincent
way that they're unusable from the commandline or in a browser.
There's nothing wrong with providing links to additional resources on the
web that will help perl programmers write better programs, as long as our
core docs don't defer coverage of essential topics to external websites.
Programmers need to be able to use Perl's docs on an airplane or in a
secure environment that has no Internet access, but there's no reason
to go all Harrison Bergeron on programmers who aren't cut off from the
Internet.
Similarly, if our docs can be reasonably cross-linked such that
programmers viewing them in a documentation reader capable of following
links have links to follow, that's great. If the only way to read
Perl's docs is to have a WebGL enabled copy of Firefox with an embedded
PDF viewer and a copy of TeX ported to Javascript, that's not so great.
Some of us do not read pod in a browser. Some of us do not
read pod with perldoc. Some of us do not read pod with man. Myself,
I only read pod with green eggs and ham. Anything we can do to help
people read docs is a good thing.
Johan Vromans
> That isn't right. Never put something in perldoc that isn't in man.
> Don't make people run different tools to get at different subsets of
> the system documentation.
Right... So let's stick to the system conventions. On *x, this means
man. Make perldoc call man underneath.
At any price, avoid having multiple sets of the same documentation in
different places. They won't stay the same.
-- Johan
Tom Christiansen
> Tom Christiansen wrote:
>> What in the world would I type 10 characters instead of 3???
>(*Why, I assume)
Yes.
> Because there is no "man" equivalent of "perldoc -f".
Sure there is. Did you forget to run splitpod?
The functions are in section 3. Of course.
> Because there is no "man" equivalent of "perldoc -q" (yes I
> don't use it personally either, but I *do* refer newbies to the
> FAQ pages, which still requires making sure the query finds
> what they need to know)
See below.
> Because there's no "man" equivalent of "perldoc -m"
Bah.
% pmpath Lingua::EN::Inflect
/usr/local/lib/perl5/site_perl/5.12.2/Lingua/EN/Inflect.pm
% pmcat Lingua::EN::Inflect | grep -c '^sub\b'
42
% catpod `pmpath Lingua::EN::Inflect` | grep -c '^=\w'
71
% catpod perl-git/*.c | grep -c apidoc
78
% podgrep api perl-git/av.c
=head1 av.c chunk 70
=for apidoc av_create_and_push
=head1 av.c chunk 89
=for apidoc av_create_and_unshift_one
% stdpods | wc -l
595
% sitepods | wc -l
5533
% podtoc `pmpath File::Spec`
/usr/local/lib/perl5/5.12.3/darwin-thread-multi-2level/File/Spec.pm
NAME
SYNOPSIS
DESCRIPTION
METHODS
* canonpath
* catdir
* catfile
* curdir
* devnull
* rootdir
* tmpdir
* updir
* no_upwards
* case_tolerant
* file_name_is_absolute
* path
* join
* splitpath
* splitdir
* catpath()
* abs2rel
* rel2abs()
SEE ALSO
AUTHOR
COPYRIGHT
% pmdirs
/usr/local/lib/perl5/site_perl/5.12.3/darwin-thread-multi-2level
/usr/local/lib/perl5/site_perl/5.12.3
/usr/local/lib/perl5/5.12.3/darwin-thread-multi-2level
/usr/local/lib/perl5/5.12.3
/usr/local/lib/perl5/site_perl/5.12.2/darwin-thread-multi-2level
/usr/local/lib/perl5/site_perl/5.12.2
/usr/local/lib/perl5/site_perl/5.11.3
/usr/local/lib/perl5/site_perl/5.10.0
/usr/local/lib/perl5/site_perl
.
% pmls Pod::PseudoPod
-r--r--r-- 1 root wheel 17809 Jun 18 2009 /usr/local/lib/perl5/site_perl/5.10.0/Pod/PseudoPod.pm
% pmls feature
-r--r--r-- 1 root wheel 5863 Feb 14 07:36 /usr/local/lib/perl5/5.12.3/feature.pm
% pmls version
-r--r--r-- 1 root wheel 6494 Dec 19 13:15 /usr/local/lib/perl5/site_perl/5.12.3/darwin-thread-multi-2level/version.pm
> Because man can't read the pod prettily in a local file.
Yeah, right.
% pod2text `pmpath Lingua::EN::Inflect`
% pod2man `pmpath Lingua::EN::Inflect` | groff -mandoc -Tps
% pmvers Lingua::EN::Inflect
1.893
% pmeth File::Basename
_strip_trailing_sep
basename
dirname
fileparse
fileparse_set_fstype
as_heavy via Exporter
export via Exporter
export_fail via Exporter
export_ok_tags via Exporter
export_tags via Exporter
export_to_level via Exporter
import via Exporter
require_version via Exporter
DOES via UNIVERSAL
VERSION via UNIVERSAL
can via UNIVERSAL
[overridden] import via UNIVERSAL
isa via UNIVERSAL
% pmfunc Lingua::EN::Inflect::classical
sub classical
{
if (!@_) {
%classical = %all_classical;
return;
}
if (@_==1 && $_[0] !~ $classical_mode) {
%classical = $_[0] ? %all_classical : ();
return;
}
while (@_) {
my $arg = shift;
if ($arg !~ $classical_mode) {
die "Unknown classical mode ($arg)\n";
}
if (@_ && $_[0] !~ $classical_mode) { $classical{$arg} = shift; }
else { $classical{$arg} = 1; }
if ($arg eq 'all') {
%classical = $classical{all} ? %all_classical : ();
}
}
}
% pmexp File::Basename
File::Basename automatically exports fileparse, fileparse_set_fstype, basename, and dirname
% pmexp Carp
Carp automatically exports confess, croak, and carp
Carp optionally exports cluck, verbose, longmess, and shortmess
% pmexp Lingua::EN::Inflect
Lingua::EN::Inflect optionally exports classical, inflect, PL, PL_N, PL_V, PL_ADJ, NO, NUM, A, AN, PL_eq, PL_N_eq, PL_V_eq, PL_ADJ_eq, PART_PRES, ORD, NUMWORDS, WORDLIST, def_noun, def_verb, def_adj, def_a, and def_an
Lingua::EN::Inflect export tag `ALL' includes classical, inflect, PL, PL_N, PL_V, PL_ADJ, NO, NUM, A, AN, PL_eq, PL_N_eq, PL_V_eq, PL_ADJ_eq, PART_PRES, ORD, NUMWORDS, WORDLIST, def_noun, def_verb, def_adj, def_a, and def_an
Lingua::EN::Inflect export tag `ARTICLES' includes classical, inflect, NUM, A, and AN
Lingua::EN::Inflect export tag `COMPARISONS' includes classical, PL_eq, PL_N_eq, PL_V_eq, and PL_ADJ_eq
Lingua::EN::Inflect export tag `INFLECTIONS' includes classical, inflect, PL, PL_N, PL_V, PL_ADJ, PL_eq, NO, NUM, A, AN, and PART_PRES
Lingua::EN::Inflect export tag `NUMERICAL' includes ORD and NUMWORDS
Lingua::EN::Inflect export tag `PLURALS' includes classical, inflect, PL, PL_N, PL_V, PL_ADJ, NO, NUM, PL_eq, PL_N_eq, PL_V_eq, and PL_ADJ_eq
Lingua::EN::Inflect export tag `USER_DEFINED' includes def_noun, def_verb, def_adj, def_a, and def_an
% pminst | head
version
Lingua::Stem::Snowball
String::Approx
Term::ReadLine::Gnu
Term::ReadLine::Gnu::XS
CPAN::Meta::YAML
ExtUtils::CBuilder
ExtUtils::CBuilder::Base
ExtUtils::CBuilder::Platform::aix
ExtUtils::CBuilder::Platform::cygwin
% pminst Lingua::EN
Lingua::EN::Numbers
Lingua::EN::Inflect
Lingua::EN::Segmenter
Lingua::EN::Splitter
Lingua::EN::StopWords
Lingua::EN::Segmenter::Baseline
Lingua::EN::Segmenter::Evaluator
Lingua::EN::Segmenter::TextTiling
Lingua::EN::Numbers::Ordinate
5.10.0::Lingua::EN::Numbers::Ordinate
5.12.2::Lingua::EN::Inflect
5.12.2::Lingua::EN::Segmenter
5.12.2::Lingua::EN::Splitter
5.12.2::Lingua::EN::StopWords
5.12.2::Lingua::EN::Segmenter::Baseline
5.12.2::Lingua::EN::Segmenter::Evaluator
5.12.2::Lingua::EN::Segmenter::TextTiling
5.12.3::Lingua::EN::Numbers
5.13.0::Lingua::EN::Inflect
% pmdesc | head
Cwd (3.29) - get pathname of current working directory
DB_File (1.82) - Perl5 access to Berkeley DB version 1.x
Encode (2.33) - character encodings
encoding (2.6_01) - allows you to write your script in non-ascii or non-utf8
IO (1.23) - load various IO modules
Safe (2.16) - Compile and execute code in restricted compartments
Storable (2.18) - persistence for Perl data structures
threads (1.72) - Perl interpreter-based threads
XSLoader (0.10) - Dynamically load C libraries into Perl code
B::Debug (1.11) - Walk Perl syntax tree, printing debug info about ops
% pmload IO::Handle
/usr/local/lib/perl5/5.12.3/XSLoader.pm
/usr/local/lib/perl5/5.12.3/Carp.pm
/usr/local/lib/perl5/5.12.3/darwin-thread-multi-2level/IO/Handle.pm
/usr/local/lib/perl5/5.12.3/Exporter.pm
/usr/local/lib/perl5/5.12.3/strict.pm
/usr/local/lib/perl5/5.12.3/SelectSaver.pm
/usr/local/lib/perl5/5.12.3/warnings.pm
/usr/local/lib/perl5/5.12.3/Symbol.pm
/usr/local/lib/perl5/5.12.3/darwin-thread-multi-2level/IO.pm
% pmload WWW::Mechanize
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Compress/Raw/Zlib.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Status.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/List/Util.pm
/usr/local/lib/perl5/5.13.0/IO/Uncompress/Adapter/Inflate.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Fcntl.pm
/usr/local/lib/perl5/5.13.0/Symbol.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Scalar/Util.pm
/usr/local/lib/perl5/site_perl/5.13.0/URI.pm
/usr/local/lib/perl5/5.13.0/Exporter.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/File/Spec.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/File/Glob.pm
/usr/local/lib/perl5/5.13.0/File/GlobMapper.pm
/usr/local/lib/perl5/5.13.0/warnings/register.pm
/usr/local/lib/perl5/5.13.0/XSLoader.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/Gzip.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Encode/Alias.pm
/usr/local/lib/perl5/site_perl/5.11.3/HTML/Tagset.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Encode/Config.pm
/usr/local/lib/perl5/5.13.0/IO/Uncompress/Base.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Encode/Encoding.pm
/usr/local/lib/perl5/site_perl/5.13.0/LWP/MemberMixin.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Config_git.pl
/usr/local/lib/perl5/5.13.0/utf8.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/auto/Storable/autosplit.ix
/usr/local/lib/perl5/5.13.0/IO/Uncompress/Gunzip.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTML/Form.pm
/usr/local/lib/perl5/5.13.0/bytes.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/File/Spec/Unix.pm
/usr/local/lib/perl5/5.13.0/Exporter/Heavy.pm
/usr/local/lib/perl5/5.13.0/vars.pm
/usr/local/lib/perl5/5.13.0/strict.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Request.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Config_heavy.pl
/usr/local/lib/perl5/5.13.0/IO/Compress/Base.pm
/usr/local/lib/perl5/5.13.0/AutoLoader.pm
/usr/local/lib/perl5/site_perl/5.13.0/darwin-thread-multi-2level/HTML/Entities.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Headers.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/Zlib/Extra.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Storable.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/IO/Handle.pm
/usr/local/lib/perl5/site_perl/5.13.0/darwin-thread-multi-2level/HTML/Parser.pm
/usr/local/lib/perl5/site_perl/5.13.0/WWW/Mechanize.pm
/usr/local/lib/perl5/5.13.0/SelectSaver.pm
/usr/local/lib/perl5/5.13.0/Compress/Zlib.pm
/usr/local/lib/perl5/5.13.0/Time/Local.pm
/usr/local/lib/perl5/5.13.0/warnings.pm
/usr/local/lib/perl5/site_perl/5.13.0/LWP/UserAgent.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Date.pm
/usr/local/lib/perl5/site_perl/5.13.0/darwin-thread-multi-2level/HTML/TokeParser.pm
/usr/local/lib/perl5/site_perl/5.13.0/darwin-thread-multi-2level/HTML/PullParser.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Response.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/Gzip/Constants.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/RawDeflate.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/Adapter/Deflate.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/auto/Compress/Raw/Zlib/autosplit.ix
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/IO/Seekable.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Encode.pm
/usr/local/lib/perl5/5.13.0/base.pm
/usr/local/lib/perl5/5.13.0/IO/Uncompress/RawInflate.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Config.pm
/usr/local/lib/perl5/site_perl/5.13.0/LWP.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/IO.pm
/usr/local/lib/perl5/5.13.0/Carp.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Message.pm
/usr/local/lib/perl5/5.13.0/FileHandle.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/Base/Common.pm
/usr/local/lib/perl5/5.13.0/constant.pm
/usr/local/lib/perl5/site_perl/5.13.0/LWP/Protocol.pm
/usr/local/lib/perl5/5.13.0/overload.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/IO/File.pm
/usr/local/lib/perl5/site_perl/5.13.0/URI/Escape.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/DynaLoader.pm
(Some people don't know what they're getting into, I see.)
> Because you can alias perldoc to "pd" if you want to, so a number of
> characters argument is silly.
I like using things I know how work.
> Because man can't deal with documentation from multiple perl installations.
Of course it can. You just have to know how to set up correctly.
> There are plenty of reasons to prefer perldoc to man.
As soon as perldoc can do ALL OF WHAT I ALREADY DO *AND MORE*,
then and only then shall I consider it.
Until then, there is no reason for me to regress to such an
embarrassing primitive tool when I have an entire toolbox at
my fingertips, one infinite in variation.
Those who ignore Unix are doomed to repeat it. Badly.
--tom
Matt Sergeant
> Tom Christiansen<tch...@perl.com> writes:
>
>> That isn't right. Never put something in perldoc that isn't in man.
>> Don't make people run different tools to get at different subsets of
>> the system documentation.
>>
>
> Right... So let's stick to the system conventions. On *x, this means
> man. Make perldoc call man underneath.
>
"man"s have man -M?
Matt.
Tom Christiansen
> Some do not read pod with browser.
> Some do not read pod with man.
> Some do not read pod with perldoc.
> I will read pod with green ham.
More, more! :)
--tom
Tom Christiansen
> "man"s have man -M?
Any place *I* log into does, especially if I
alias man to ~tchrist/scripts/tcman. :)
--tom
Matt Sergeant
> Matt Sergeant<ma...@sergeant.org> wrote:
>
>> Because there is no "man" equivalent of "perldoc -f".
>>
>
> Sure there is. Did you forget to run splitpod?
> The functions are in section 3. Of course.
>
for us?
But what happens with this:
$ man 3 open
open(3pm) Perl Programmers Reference Guide
open(3pm)
NAME
open - perl pragma to set default PerlIO layers for input and output
SYNOPSIS
use open IN => ":crlf", OUT => ":bytes";
? (I genuinely don't know, because I rarely use man for perl docs).
>
>> Because there's no "man" equivalent of "perldoc -m"
>>
>
> Bah.
>
> % pmpath Lingua::EN::Inflect
> /usr/local/lib/perl5/site_perl/5.12.2/Lingua/EN/Inflect.pm
>
> % pmcat Lingua::EN::Inflect | grep -c '^sub\b'
> 42
>
*snip*
So in arguing that we shouldn't recommend things that aren't in the perl
core you're ... recommending using something that isn't in the perl
core? ;-)
None of the boxes I work on have those tools installed, and I wouldn't
even know where to find them.
>
>> Because man can't read the pod prettily in a local file.
>>
>
> Yeah, right.
>
> % pod2text `pmpath Lingua::EN::Inflect`
>
> % pod2man `pmpath Lingua::EN::Inflect` | groff -mandoc -Tps
>
I don't see you invoking "man" there, just using tools that don't come
with perl again.
Matt.
Tom Christiansen
> $ man 3 open
> open(3pm) Perl Programmers Reference Guide
> open(3pm)
Since we already have to differentiate between...
man 2 open
man 3 open
...one merely elects a different section for 3pf.
I had thought the pm* tools were long generally
available. My own file dates on them are antemillennial.
It's probably the "we hates programmesses" CPAN bug.
Perldoc is just a dodgy band-aide for prisoners of Bill.
It's not at all as good as Unix-style tools, as I believe
I have demonstrated. It holds nothing for me.
--tom
Leon Timmermans
> Because people are used to reading docs on the web for almost everything.
> Heck, even for Perl modules, I often go to search.cpan.org because it
> provides a better interface for reading the docs.
Me too. `perldoc -f` is the only perldoc functionality I use, anything
longer I'll open a tab for in my browser.
> Just because you (and other people on this list) are very comfortable with
> the status quo does not mean that it's good for everyone. I think we need to
> spend a lot more effort thinking about what's best for new users. What does
> a college kid getting into programming need to get started with Perl?
Part of it is a generation gap. I can't noticing the man-users are
primarily people who (AFAIK) started using perl in the early 90s.
Leon
Mark A. Stratman
On Mar 4, 2011, at 11:44 AM, H.Merijn Brand wrote:
> On Fri, 4 Mar 2011 18:02:54 +0100, Abigail <abi...@abigail.be> wrote:
>
>> On Fri, Mar 04, 2011 at 10:56:37AM -0600, Dave Rolsky wrote:
>>>
>>> I also think we should consider writing the docs assuming they will be
>>> mostly viewed on the web,
>>
>> Personally, I find that an almost alien thought.
>>
>> Why would anyone use a web interface for something that's already
>> there locally?
>
> I almost NEVER use HTML presenters for perldoc. I use "man" 95% of the
> time and 4% the quick ref guide and 1% the books.
>
> So viewing from the web is a no-op for me.
I believe it is important that we begin making a stronger distinction between tutorials and reference materials.
I'm willing to speculate that nearly ALL people reading tutorials are doing so on the web. Of course *you* folks might not read Perl tutorials on the web, but *you* are hardly the audience of a tutorial.
I'm probably taking this a step further than Dave was getting at.... But there are a lot of great things HTML brings us that POD is incapable of. And these sorts of things are extremely useful teaching tools in tutorials:
* Images
* Lists
* Tables
* Videos
* etc
To say that we should disregard critical, modern communication tools when teaching Perl newcomers, simply because Unix hackers would be inconvenienced should they ever decide to read a tutorial on their commandline tool of choice is.... absurd.
I certainly concede that reference materials should be be easily viewable on a standalone machine, and should lose no critical content when looked at with 'man' or 'perldoc' on the terminal. These are the everyday go-to documents we quickly pull up whenever necessary.
A tutorial on the other hand is typically read once. And I think this line of reasoning applies similarly in deciding whether to use CPAN examples to teach a Perl concept. The goal of a tutorial should not be to teach a newcomer to work within the constraints of core perl, but instead to teach them how we (most often) *actually* work with the language.
Jan Dubois
>
> I had thought the pm* tools were long generally available.
They are: http://search.cpan.org/dist/pmtools/
However, just like Moose, they are not part of the core...
Cheers,
-Jan
Tom Christiansen
>>
>> I had thought the pm* tools were long generally available.
>They are: http://search.cpan.org/dist/pmtools/
Thank you, Jan.
--tom
Tom Christiansen
> Part of it is a generation gap. I can't noticing the man-users are
> primarily people who (AFAIK) started using perl in the early 90s.
Not I. :)
--tom
Mark A. Stratman
** What is our goal of Perl tutorials? **
The answer to this determines everything else.
My opinion, for what it's worth, is...
A tutorial should make the newcomer fall in love with Perl, and want to use it more. It should dangle a carrot, enticing them into a brisk walk, then throw it in the direction of more substantial references for them to jog toward.
A tutorial isn't a marathon. It's a slow, gentle, and appealing walk. It is OK to leave out details.
Of course there's more than one way to do it, but a newcomer doesn't need to see them all on day 1. That's what references, and search.cpan.org are for.
If Dave's submission otherwise meets our goal for an OO Perl tutorial, and does so better than blessed hashes can (and I wholeheartedly believe it does)... then who cares about CPAN dependencies? This is a 15 second hurdle for a newcomer reading through a tutorial which pays off tenfold in its elegance, simplicity, appeal, and just plain sexiness.
If relying on CPAN is the big reservation here, we need to weigh how much a core-Perl OO tutorial serves our goal vs. how much the CPAN dependency takes away from our goal.
demerphq
He was being polite, and left out the "(or from before the dawn of
time itself)".
Yves
--
perl -Mre=debug -e "/just|another|perl|hacker/"
Tom Christiansen
>>> primarily people who (AFAIK) started using perl in the early 90s.
>> Not I. :)
> He was being polite, and left out the "(or from before the dawn
> of time itself)".
So I guess there's antemillennia...
...and then there's antediluvian.
But it's not true. I never used perl0. :)
--tom
Abigail
I'd think they are the people who've actually have the experience of
debugging a problem on a box in the server room, with just a dumb
terminal and no easy access to the big bad outside world.
Now, *I*'m Perl savvy enough I know there's perldoc. But not everyone
who needs to do debugging at 3 AM will realize that. Unix system
adminstrators know man. They expect man to work. And they'll consider
anything that doesn't come with man pages broken (and resist having
such applications installed).
Now, I don't care what people do with perldoc. Make it use <blink> and
play podcasts of someone reading the documentation.
Just leave the man pages.
Abigail
brian d foy
<tch...@perl.com> wrote:
> brian d foy wrote at 9:40am CST on Friday, Marth 4th, 2011:
>
> > If you're talking about translating the Pod constructs to
> > *roff, I say we do the best we can and not worry about some
> > ideas that *roff might not be able to handle. We wouldn't
> > cripple the man pages, but we wouldn't let them hold back the
> > pod either.
>
> Oh? What sort of things might those be, Brian?
I don't know anything about troff, which is why I don't pretend to know
what might go wrong with my plans. We don't worry about the things
another format can do, so all that's left to worry about is the things
it might not do.
What those things might be I don't know because I haven't added any
special features to the existing docs yet. :)
brian d foy
Peter Scott <Pe...@PSDT.com> wrote:
> (1) The most commonly agreed best practice O-O framework is Moose.
> Here's how to use it.
I don't think you can support this statement. A very small slice of
Perlers know what Moose is and like it. A slightly larger slice know
that it exists but don't use it yet. Most people have never heard of
it, just like most Perlers don't use most of Perl's features. There's
a bit of echo chamber there.
That's nothing against Moose or its future. Let's just not misrepresent
it.
brian d foy
<abi...@abigail.be> 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`
> You're talking about a deprecation cycle. Either you intend the remove
> the current location, or you don't.
That deprecation cycle might be 5 years. :) And, there is no location.
There is just a name and something that knows how to find something
connected to that name.
Peter Scott
I don't think it's misrepresenting. The fact that most people using Perl
don't know what Moose is doesn't alter the fact that among people who have
the knowledge to make an informed choice, the most common choice *now* is
Moose.
Look at it this way. Is the best practice to use some other framework, if
so, which one? Is the best practice to use *no* framework? Hardly. The
most *common* practice is probably no framework, but our job is to educate
people as to the *best* way to do things, not regurgitate the
underinformed choices of the majority back to them.
A best practice isn't necessarily one that enjoys a large popular
following, only that the people writing the documentation come to a
consensus that it is so. Among the people who influence the
documentation, I contend that Moose is considered the best O-O framework
by a clear majority, over any other framework or none at all.
By all means, let's not state that Moose is used by the majority of Perl
programmers, that would be very wrong.
--
Peter Scott
Jesse Vincent
demerphq <deme...@gmail.com> wrote:
>On 4 March 2011 06:17, brian d foy <brian...@gmail.com> 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`
>
>I hope we don't ever stop supporting the old names.
>
I'd be thrilled to see a massive doc naming cleanup for 5.16.
There is no reason for us not to support the traditional names forever or to teach perldoc to whine at programmers who use the old names, even if we stop advertising them.
--
Sent from my Android phone with K-9 Mail. Please excuse my brevity.
H.Merijn Brand
I just did a round of hands-up at the Dutch Perl Workshop with about 45
people present ranging from beginner to expert.
Who uses ... to read perl (module) documentation:
- grep/cat 5
- man 12
- perldoc almost all
- perldoc -f almost all
- perldoc -m 4
- perldoc -l 3
- perldoc -q 4
- local html 1
- cpan site all
- other web 7
- vi 6
--
H.Merijn Brand http://tux.nl Perl Monger http://amsterdam.pm.org/
using 5.00307 through 5.12 and porting perl5.13.x on HP-UX 10.20, 11.00,
11.11, 11.23 and 11.31, OpenSuSE 10.1, 11.0 .. 11.3 and AIX 5.2 and 5.3.
http://mirrors.develooper.com/hpux/ http://www.test-smoke.org/
http://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/
Peter Rabbitson
> On Fri, 04 Mar 2011 17:40:05 -0600, brian d foy wrote:
>> In article <2011030414315...@lists-nntp.develooper.com>, Peter
>> Scott <Pe...@PSDT.com> wrote:
>>
>>> (1) The most commonly agreed best practice O-O framework is Moose.
>>> Here's how to use it.
>> I don't think you can support this statement. A very small slice of
>> Perlers know what Moose is and like it. A slightly larger slice know
>> that it exists but don't use it yet. Most people have never heard of it,
>> just like most Perlers don't use most of Perl's features. There's a bit
>> of echo chamber there.
>>
>> That's nothing against Moose or its future. Let's just not misrepresent
>> it.
>
> I don't think it's misrepresenting. The fact that most people using Perl
> don't know what Moose is doesn't alter the fact that among people who have
> the knowledge to make an informed choice, the most common choice *now* is
> Moose.
>
> Look at it this way. Is the best practice to use some other framework, if
> so, which one? Is the best practice to use *no* framework? Hardly. The
> most *common* practice is probably no framework, but our job is to educate
> people as to the *best* way to do things, not regurgitate the
> underinformed choices of the majority back to them.
There is best practice and there is best practice. I am horrified by the
idea that Moose can (already is) becoming a staple of many dependency
chains. I have nothing against people using Moose in their personal work,
but do realize that by giving extra core(!) endorsement to Moose you are
also giving a nod towards "hardware is cheap, we declare the season of
CPAN Moosification open".
Of course you might be wondering "well, what's wrong with that?" - the
wrong starts the moment you leave the web-dev echo-chamber. The liberal
(ab)use of *runtime* types actively encouraged by Moose more or less
guarantees that your data will be examined N times in an identical way when
traversing your lovely stack of neatly connected CPAN pieces. No matter how
fast is your choice of iron, N checks will always suck N times more.
So please think about the extra implications/dangers of making sweeping
statements "Moose is the way to go" - it often isn't (in my line of work it
in fact *never* is, to a point where I am contemplating Test::NoMoose to
catch Moosification of my dependencies)
brian d foy
Peter Scott <Pe...@PSDT.com> wrote:
> Look at it this way. Is the best practice to use some other framework, if
> so, which one? Is the best practice to use *no* framework?
I think you miss the point of best practice. Outside of a started
context, you can't say what is best, good, not optimal, or anything
else. There is no way to compare anything when you don't know what the
task is, and pretending everyone else in the world has the same goals,
constraints, or resources as you is dishonest.
Beyond that, until something is tried widely and its consequences are
know, you can't say anything is a best practice.
People might want Moose to be a best practice, and people who write
documentation may wish it were so, but that doesn't allow any of us to
skip the careful analysis and deep thought it should take to elevate it
to an actual best practice. Why are so many past best practices out of
favor now? No one relly thought about both sides of the issue, and no
one required anyone else to be intellectually rigorous and honst about
it.
Christian Walde
> I think you miss the point of best practice. Outside of a started
> context, you can't say what is best, good, not optimal, or anything
> else. There is no way to compare anything when you don't know what the
> task is, and pretending everyone else in the world has the same goals,
> constraints, or resources as you is dishonest.
This makes me wonder about just what a "best practice" is. So far i took it to mean "behavior that is better than other related behaviors in more situations". But you seem to say it means "behavior that is better than all other related behaviors in all situations". I'm not sure i'm reading you right there, but i'm wondering.
Would you mind elaborating on just what a "best practice" is?
--
With regards,
Christian Walde
Dave Rolsky
> People might want Moose to be a best practice, and people who write
> documentation may wish it were so, but that doesn't allow any of us to
> skip the careful analysis and deep thought it should take to elevate it
> to an actual best practice. Why are so many past best practices out of
> favor now? No one relly thought about both sides of the issue, and no
> one required anyone else to be intellectually rigorous and honst about
> it.
FWIW, the tutorial I wrote does not say anything like "using Moose is a
best practice. It does say:
We strongly recommend that you use one of these systems. Even the most
minimal of them eliminates a lot of repetitive boilerplate. There's
really no good reason to write your classes from scratch in Perl.
The phrase "one of these" is meant to mean any object framework. This
paragraph comes before introducing the three specific object frameworks
that I cover.
The Moose section highlights several of Moose's features and then says "Of
course, C<Moose> isn't perfect." After that, I mostly talk about the
compile time speed hit and the fact that it has more deps than the other
two systems I cover. I _do_ say:
Before you panic, know that many people do use C<Moose> for
command-line tools and other startup-sensitive code. We encourage you
to try C<Moose> out first before worrying about startup speed.
The conclusion is:
As we said before, Perl's minimal OO system has lead to a flourishing
of OO systems on CPAN. While you can still drop down to the bare metal
and write your classes by hand, there's really no reason to do that in
2011.
We encourage you to play with and evaluate L<Moose>,
L<Class::Accessor>, and L<Object::Tiny> to see which OO system is right
for you.
So I hardly thing this document says anything like "Moose is a best
practice". I'd be fine with any or all of:
- adding more caveats about Moose, Class::Accessor, or Object::Tiny
- mentioning other systems in the conclusion, or just mentioning that many
other options exist
- some waffling near the end about how nothing's set in stone, things
change, blah de blah blah, as long as it's near the end.
-dave
/*============================================================
http://VegGuide.org http://blog.urth.org
Your guide to all that's veg House Absolute(ly Pointless)
============================================================*/
Tom Christiansen
First, Dave, thanks for your work. Your documentation is clear,
understandable, and useful.
> FWIW, the tutorial I wrote does not say anything like "using
> Moose is a best practice. It does say:
> We strongly recommend that you use one of these systems. Even
> the most minimal of them eliminates a lot of repetitive
> boilerplate. There's really no good reason to write your
> classes from scratch in Perl.
Isn't this in effect saying that you strongly recommend *not*
using anything that Perl ships with to write classes with? I
really don't feel a document that ships with Perl should say
that, because it's completely self-defeating. It says the
Perl you get isn't good enough to do Perl in. That's sad.
> So I hardly thing this document says anything like "Moose is a best
> practice". I'd be fine with any or all of:
> - adding more caveats about Moose, Class::Accessor, or Object::Tiny
> - mentioning other systems in the conclusion, or just mentioning that
> many other options exist
> - some waffling near the end about how nothing's set in stone, things
> change, blah de blah blah, as long as it's near the end.
Couldn't you please talk about things that Perl ships with, and
preferably first?
I know of two: Class::Struct and Hash::Util::FieldHash. One is too
simplistic and the other too complicated, but both have had their uses.
--tom
Jesse Vincent
Tom,
You've been very clear that you don't think core documentation should be
recommending that Perl programmers look to modules distributed on CPAN
to find the best way to do things in Perl. I disagree with that
assertion quite strongly. In 2011, I consider teaching new Perl
programmers that they should prefer to build their own functionality
when there are many better options on CPAN to be actively harmful
to our users and to our community.
It may be that in 18 months, you'll all have my head on a pike and the
community will rally around the task of undoing the atrocities
perpetrated during my reign of terror as Pumpking. For now, however,
this discussion is moot. Recommending CPAN modules as best current
practices is a best current practice.
Best,
Jesse
--
Tom Christiansen
running off to CPAN just to get Unicode work done in Perl, as apparently I
must in order to get OO work done in Perl. At least this shows we do
recognize where our core competency and true focus are, and it's not in OO.
--tom
brian d foy
<mith...@yahoo.de> wrote:
> On Sat, 05 Mar 2011 20:28:51 +0100, brian d foy <brian...@gmail.com> wrote:
>
> > I think you miss the point of best practice. Outside of a started
> > context, you can't say what is best, good, not optimal, or anything
> > else. There is no way to compare anything when you don't know what the
> > task is, and pretending everyone else in the world has the same goals,
> > constraints, or resources as you is dishonest.
>
> This makes me wonder about just what a "best practice" is. So far i took it
> to mean "behavior that is better than other related behaviors in more
> situations". But you seem to say it means "behavior that is better than all
> other related behaviors in all situations".
Nope, I'm not implying either of those. I'm saying that you can't say
"best practice" unless you specify the context. It's not a game of
which situations dominate. You should think very carefully about what a
best practice actually is before trying to recommend it to anyone else
in any context.
Basically, the practicality of "best practice" is that people use it as
a way to not think and to appeal to authority to win an argument. The
actual best practice is to figure out the benefits and costs and
consequences over any decision, rank those based on what's important in
the particular situation, and then make a judgement call. Instead,
"best practice" has turned into "do what I say without questioning it".
A real discussion of practices includes both sides-what you get and
what you give up. However, once given an answer, people stop thinking.
Peter used the word "informed" to describe the people who are telling
people to do it their way without knowing what the rest of the world is
trying to accomplish. That's an anti-best practice.
Reini Urban
Moose is good and nice and the only to be recommended OO framework for perl.
But it is immature and slow, partially because it still has no proper
perl core support.
You can compare it to the simple straightforward and simple PCL
implementation of CLOS,
which was used in the first 5 years of CLOS usage.
Anybody can write this, but nobody would recommend it.
- http://www.cs.cmu.edu/afs/cs/project/ai-repository/ai/lang/lisp/oop/clos/pcl/0.html
It works, includes most of the needed features, but is not integrated
into core at all.
Modern CLOS frameworks which are commonly used are tightly integrated.
E.g. every variable has a class pointer (and not in the 2nd struct),
method lookups
are optimized beforehand, and much more. I'm not into that anymore.
We e.g. only have a stash (class) pointer, which is looked up by name
at run-time, not by ptr. This can be fixed.
Class traversal and name lookup is by name not by ptr, class hashes
are even not optimized. This can be fixed.
mro caches a bit.
Calling subs is painfully slow on perl, calling methods similar. This
cannot be fixed with our current layout.
We do not even optimize on subs/methods.
You can safely recommend the Moose API, because it is established and
is basically a CLOS port to perl.
But recommending Moose as *the* OO on perl is silly, and Moosifying
more on CPAN is even sillier, as silly
as using Module::Build now.
No, I don't want to optimize Moose (nor Module::Build).
I personally hate overblown OO at all, if it's CLOS or Moose.
If I would choose I would go with golang.
Replies here with fixed subject if one really has to:
And Module::Build should have first started with
getting the dependency chaining right, if your goal
is to write a make replacement.
--
Reini Urban
Peter Scott
I said we should say:
(1) The most commonly agreed best practice O-O framework is Moose.
Here's how to use it.
(2) A best practice is not the only practice.
(3) Some people pick alternatives because x, y, z (including legacy).
(4) What's going on under the hood (reference material) is: ...
I believe we should give people the benefit of our best judgement as to
what to use. People learning something need to know where to focus their
attention. It's not hard to find all the information about Perl. What's
hard is knowing where to start and what you can ignore at first. A
common problem when experts write documentation for beginners is that
they try to teach them to become experts right out of the gate.
If I go into a doctor's office and ask how to lose weight I don't want
him to hand me a stack of American Medical Journals and tell me I'll be
better off for figuring it out for myself. I want to start with his best
thinking on the topic and when I've assimilated that I'll be better
qualified to question it.
I don't think it reflects well on the Perl community for our OO tutorials
to promulgate a seemingly level playing field between dozens of choices
and force the beginner to become an expert in framework evaluation before
they can write their first program. If there's a clear front runner for
beginners we should say so.
I agree that context matters. We're talking about a tutorial, so the
context is learnability. Performance takes a back seat.
--
Peter Scott
Christian Walde
Ah, this is less about the specific situation at hand, but more against the use of the term "best practice" as a thought-terminating cliché. That makes sense.
Abigail
I'd prefer a somewhat different list:
1) List commonly used OO frameworks/implementations.
2) For each, point out their pros and cons.
3) If possible, point out situations where you want to use
which framework, and why.
I'm very hesitant to use big words like "best practice" or "most commonly
agreed" without much data to back it up - specially when it's controversial
(as this thread alone shows).
I also think one should readers of the documentation with respect, and
asume that, given the appropriate arguments, readers can make the right
decision for their situation.
> I believe we should give people the benefit of our best judgement as to
> what to use. People learning something need to know where to focus their
> attention. It's not hard to find all the information about Perl. What's
> hard is knowing where to start and what you can ignore at first. A
> common problem when experts write documentation for beginners is that
> they try to teach them to become experts right out of the gate.
>
> If I go into a doctor's office and ask how to lose weight I don't want
> him to hand me a stack of American Medical Journals and tell me I'll be
> better off for figuring it out for myself. I want to start with his best
> thinking on the topic and when I've assimilated that I'll be better
> qualified to question it.
Actually, my doctor tells me it's better for me to lose weight. She
tells me why. She tells me some ways how to do that. She tells me the
pros and cons of each way. She considers my way of life. She 1) doesn't
stick to one method she thinks works best, and tells every patient to
use that method, and 2) lets the choice be mine.
> I don't think it reflects well on the Perl community for our OO tutorials
> to promulgate a seemingly level playing field between dozens of choices
> and force the beginner to become an expert in framework evaluation before
> they can write their first program. If there's a clear front runner for
> beginners we should say so.
They don't have to be experts if we give them the arguments. But they are
the experts on *their environment*. We cannot know.
If their would be a clear front runner for beginners, appropriate to
most situations, we should say so, I agree. But, IMO, there isn't such
a front runner.
Peter Scott
> If their would be a clear front runner for beginners, appropriate to
> most situations, we should say so, I agree. But, IMO, there isn't such a
> front runner.
That much is becoming apparent in this thread. Forgive me for assuming
otherwise based on many articles aimed at beginners and the post that
started this thread. I am disappointed that after all this time we have
no consensus on how to say in Perl "Class X has attribute Y" when so many
other languages have solutions that have freed their users' minds up to
move on to higher-level problems.
--
Peter Scott