Sometimes I read parts of _why's Poignant Guide to Ruby, and marvel at the inimitable writing style, the pedagogical comics, and the balance between explanations and, uh, story. But the other day I read The Tiger's Vest, and I realized that we in the Perl 6 community need to be really envious about two things in Ruby, otherwise we're not going provide good enough versions of these two things ourselves.
Actually, I'm not sure we need Envy to do this. It might be that this falls well under Hubris, whose definition (in the Perl context) is as follows, according to Wikipedia: "Excessive pride, the sort of thing Zeus zaps you for. Also the quality that makes you write (and maintain) programs that other people won't want to say bad things about."
It might well be that we need not look at other languages to excel in this area, but I think that's the easiest way for us to be motivated. It sets a minimum bar, shows what actually can be done. And what more or less needs to be done so that people won't say bad things about Perl 6.
Oh, and the two things? They're simply the two main things _why talks about in the chapter: an interactive shell and a documentation tool. Will go into detail about these now.
An interactive shell
This is not my main point for tonight, so I'll be brief. Rakudo has a REPL. It's — and I don't like to say this because I prefer to say nice things about Rakudo — not very good. Try it, and you'll see. (Just type perl6, and you're in.) The main thing lacking from it is that you can't declare a variable, hit enter, and then use the variable on the next line.
I understand the technical limitations behind this behaviour; I've had them explained to me. But the explanations just make me want to whisper, really softly, "I want results, not excuses!". Surely Perl 6 isn't so perfectly crystalline in its structure that a proper interactive shell (which, in case I didn't stress this enough, is a really good thing to have) is beyond its reach? I have enough motivation to see this happen that I'm willing to personally go ahead and implement an interactive shell that retains its variables between lines. (As soon as I figger out how to overcome the technical limitations, that is.)
Other non-essential but very desirable features of an interactive shell are also mentioned in the chapter: continuation prompts, nesting depth, tab completion. You get the idea. Envy.
A command-line documentation tool
_why presents Ruby's documentation tool ri with giant brown serifed letters, reverberating with double parentheses as if struck like a heavenly gong. Or as if a chorus of angels were heard from inside of its name, I don't know. It is described in the text, somewhat obliquely, as the "Most Blatantly Great Thing Since Michael Dorn". The bottom line is, easily accessible documentation matters.
And it takes time. Not so much writing the script that displays the documentation for a certain class, method, sub, operator, macro or other syntactic feature — that's an important task, but a relatively easy one compared to putting together all the documentation, making sure it looks nice, is complete, understandable and nice to read. In fact, since it takes time, I think we'd better start now.
I hereby pronounce the Userdocs For Christmas project (U4X) started. Our official goal shall be to provide easy-to-access comprehensive user documentation, through a ridiculously easy-to-access command line tool, providing snippets of Perl 6 clarification so perfectly worded and so brilliantly illustrative that the unsuspecting reader will be brought close to tears.
The documentation writing itself will be done in a controlled manner, where "controlled" means that people with tuits get to make sure that things are consistent. All the documentation will be written in Pod, the Perl 6 version of POD. More information will be found in the U4X README file which I just committed to the Pugs repository.
When I look at all the things that are going on in the Perl 6 community right now, I think that Envy really needn't be one of the Perl virtues. It could very well be Pride. But for that to happen in time for the release of Perl 6.0.0, an interactive shell and exquisitely good documentation are needed. At least if Perl 6 is also to be the most blatantly brilliant thing since Michael Dorn.
Was this a Perl 6 specific thing? I find perldoc to be a wonderful tool myself but I don't know its state in P6.
Re:perldoc vs ri?
masak on 2009-01-14T05:21:00
Was this a Perl 6 specific thing? I find perldoc to be a wonderful tool myself but I don't know its state in P6.
I realize I could have been more clear in this regard. Yes, this was a Perl 6-specific thing; I also like perldoc very much. Both on the command line and on the web.
The reason that the situation is different for Perl 6 is that Perl 6 is a complete rehaul of most everything. We can't just blindly inherit the docs, and we need to prepare new docs of the same high quality before our first major release. Documentation is one of those little things that matter a lot.
In doing this, I think we should take not only perldoc as a model, but also things like ri, and we need to think about how to make maximum use of the web. As has been pointed out elsewhere, the PHP documentation on the web is a real boon for PHP itself, in that it (1) is comprehensive and easy to find, and (2) has very short and intuitive URLs. Wondering about
chop? Go to http://php.net/chop. It doesn't get much shorter and sweeter than that. (Juerd++ has a cool Perl 5 analogue, but it's not official. What if we could design user documentation with cool URLs in mind from the start?)That said, I've yet to come across a language reference with a nicer layout than perldoc.perl.org. Some things, like most of perldoc, we do well already. Now we just need to steal all the best parts, from ourselves and from others.
makes me sad.
Re:learn.perl.org
masak on 2009-01-16T07:21:07
Care to elaborate on that?
Re:learn.perl.org
Eric Wilhelm on 2009-01-16T08:28:13
"So, you want to learn perl? Where to start? A good place is " not one, but two places -- one of which is perlintro, and the other of which is even more places: a bunch of books.
And after that, we're left to just the list of books, or maybe we followed the "perl documentation" link and are now reading the perldoc.perl.org root page, which again has a link to perlintro and then a lot of meta information about perldoc.perl.org.
So, learn.perl.org basically does nothing to capture the first-time reader's interest -- such as getting them started doing something interesting. I would expect a 'learn.something' to have e.g. a series of lessons. It would be better named 'books.perl.org' in its current state.
Re:learn.perl.org
masak on 2009-01-16T09:10:23
"So, you want to learn perl? Where to start? A good place is " not one, but two places -- one of which is perlintro, and the other of which is even more places: a bunch of books.
And after that, we're left to just the list of books, or maybe we followed the "perl documentation" link and are now reading the perldoc.perl.org root page, which again has a link to perlintro and then a lot of meta information about perldoc.perl.org.
So, learn.perl.org basically does nothing to capture the first-time reader's interest -- such as getting them started doing something interesting. I would expect a 'learn.something' to have e.g. a series of lessons. It would be better named 'books.perl.org' in its current state.
Aye. IMO, there's nothing factually wrong with the page; it's just not very captivating. Imagine what you could do if you didn't take the web visitor at her word and just replied "well, there's perlintro, and a couple of books..." -- you could showcase how one could solve cool but tricky problems with just a few lines of Perl, you could show how a few common modules solve even trickier problems. You could have links to a couple of common 'starting points' in Perl: CGI, shell scripting, bioinformatics... there is much that can be done on such a page.
However, I neither have the access to that page, nor the motivation to fix Perl 5 shortcomings right now. There might even be solid reasons for the page to look boring, I dunno.
Re:Agree in full!
masak on 2009-01-28T21:33:05
I looked all over the place to find a solid replacement for irb in the perl world and there really just isn't something like it. I must assume that the reason is that perl people are generally more ok with doing things with perl -e, but the tab completion in irb is enough to make me never want to leave ruby.
You, sir, have understood the point of my post. Now, let's make sure we get tab completion by Christmas. And all the other good stuff.
Re:ipl + tryperl6
masak on 2009-01-29T08:00:08
I think we need to talk more about these issues. Too many perl people seem to be grumpy about this kind of change.
I think that's a slight generalization. In the Perl developer community, and in the Perl 6 one in particular, you're more likely to find openness to new ideas than not. At least that's my experience.
It's like when I posted somewhere about andand for perl5. Everyone's answer (mostly) was just "Don't do that!"
This one? I think the responses were very helpful, with example code and all. Searching the page gives one "don't", which isn't directed towards you. It might be you're expecting too much Ruby syntax out of Perl 5.
:) I think that if we get some kind of ipl going we should go out of our way to make a web based version like _why's tryruby. Imagine telling people about that! Everyone says perl6 is vaporware; but having a web based interpreter would be just so excellent that it might get some more interest!
Here I am able to provide some historical context: there was one just like that at one time, during the heyday of Pugs. (Now-defunct try.pugscode.org.)
Yup, we should do it again. It's a swell idea. Tools enabling this are being built as we speak... but AFAIK, no-one is working on a tryperl6 web page right now. (Hint, hint.)
Also: pugs DOES do what we are talking about, so it shouldn't be too technical of a limitation.
The mere fact that
irbdoes do what we're talking about is evidence enough that it's not too technical of a limitation. Tene++ has promised to look at the technology necessary in Parrot to support variable survival.Re:ipl + tryperl6
frew on 2009-01-29T15:34:55
Glad you agree about ipl.
More on grumpiness: I use the cgiapp framework. In general I think a lot of the wisdom of rails can be used in other web frameworks, even if they aren't as heavy as rails. I recently read a thread about how many actions should be in a controller, how long actions should be, etc.
There were numerous cgiapp people that said that they had 100 actions in their controller, or that their actions were 250 lines long, etc. I think that is a mistake and when new people come in and ask, "What is best" and someone gives and answer that is really just bad programming, it leaves a bad taste in my mouth.
You have a point about perl6. I doubt that is the same. But how many people are writing database applications with perl6 compared to perl5? (as discussed last night, perl6 doesn't have dbi so....)
