I wasn't going to post this message until I was ready to release
the alpha version of PerlNav, but the amount of "energy" that has
been expended in the recent "Perl IDE" discussion seems to demand
that I let people know what I am doing and when it will be available.
Pre-ANNOUNCE of PerlNav: a Perl Documentation Navigator
PerlNav is a prototype for a documentation manager. It is the
grandchild of a simple perl script that I have used for years to
find things in the perl documentation.
Rationale:
o A complex system that is under-documented is worthless.
o A complex system that is over-documented is almost unheard of! :-)
o Perl is a complex system that has an amazing amount of documentation
available - the main docs + FAQ have something on the order of
30,000 to 45,000 lines, depending on how you count things. At
60 lines to the page, this is on the order of 500 to 700+ pages.
The perl5.004_2 distribution for Win95 includes 164,000 lines
of HTML docs! AND this does *not* include anywhere near all of
the modules at CPAN.
o Telling someone to Read The Friendly Manual is fine, but
*finding* things in the FM can be difficult, particularly
since the manual has no index.
until now ......
PerlNav has a number of features that make it useful for accessing
documentation.
o Web-based interface - everybody has a browser, regardless of OS.
o Runs as a CGI script under an existing web server, OR
o Includes its own, ready to run miniserver. Yes, it works with
the perl5.004_2 binary distribution for Win32.
o Performs paragraph level searching. This means it doesn't tell
you what file the hit was in, but which paragraph.
o Shows hit lists as keywords-in-context-in-paragraph.
o Displays documents with search terms highlighted.
o It's moderately quick. It is definitely faster than me trying
to wander through the docs looking for that example I saw
three months ago and now I need it and where the hell is it?!
PerlNav is:
o not a build-the-index-first type of system, but its performance
seems to be acceptable, certainly for single-user systems.
o not intended to be used on super-large collections of random,
unrelated files.
o not done - it is a work-in-progress. I have several ideas about
future extensions and I know that users will have all sorts of
interesting suggestions.
How Do I Get It?
You can't, yet. I will be asking for alpha-testers sometime
before the end of May. (If you feel that your life is in danger
in the next two weeks and that this is the only thing that can
*might* answer, but wait until the announcement if you can.)
End of Pre-ANNOUNCEment
The following are just my opinions. If you are happy with yours,
you can skip the rest of this message!
[ Sounds of climbing up on a soap box ]
I would like to say a few words about "newbie abuse".
I have been dismayed at the intensity of opinion directed at new
users of Perl. It would seem to me that this is a good place to
apply what your Mom told you - "If you can't say something nice
(or helpful), don't say anything at all". If nothing else it is
a waste of breath/bandwidth/time (yours, mine, and everyone else's).
Yes, there are many clueless people wandering the halls of c.l.p.m.,
but are they any more clueless than *you* were when you first got
into the fever of programming? Remember?
And just because you have been programming for 25 years, have used
30+ languages on 60+ different platforms, and written a gazillion
lines of code for OSes, apps, drivers, etc. - even with all of that
you are *still* a newbie yourself (at some level) when you approach
a new language or a new environment. You are just more experienced
at *being* a newbie than a new newbie is (does that make sense?).
When I first started selling CDB (a C de{*filter*} I wrote in the early
1980's), I remember the 'old guys' standing in the back of the room
during the demo saying:
"adb (an ancient assembly-level de{*filter*}) was good enough for
me and any one who needs one of these newfangled, source-level
de{*filter*}s that do structure dumps and show you the code should
not be allowed near a keyboard. etc. etc. (harumph, harumph)"
Well, that was {*filter*}then and it is still crap. Any tool that can
make programming easier for *someone* has some value. If you don't
want to use it, don't. If you think there is a better tool available,
say so. But don't attack someone just because they are new and
clueless - so is a day-old baby, but many of them grow into real
human beings.
Here are my own contributions to the FAQ.
Q: Is Perl a good language to learn programming in?
A1: Yes, it's cheap, well documented, runs on everything, and is
the basis for much of the dynamic content of web sites.
A2: Yes, but start slowly, using the features one-at-a-time until
you understand what they do.
A3: Yes, but don't ask any questions on c.l.p.m :-)
A4: No, but don't ask me to name a better one.
A5: No. I once heard that Pascal was like the round-nosed scissors
you had in grade shool and that C was like a two-edge razor
(you could do a lot, but you could also bleed to death on the
machine room floor). I would like to extend this by saying
that Perl *looks* like the round-nosed scissors, but is actually
a multi-dimensional laser beam. ("Fenster! Don't run with that
laser beam, you'll delete someone's directory!")
Q: How does a newbie get started?
A1: Buy lots of O'Reilly books and read them cover-to-cover.
A2: Look at the source of modules written by the tribal elders.
A3: Just do it! Programming is a state of mind and the only way
to get there is to be there. I know that sounds a bit Zen
or something, but if you don't make an effort to figure out
your own problems/bugs, you will never develop the mental tools
you need to BE a programmer.
A4: But don't do it in CGI! I think many of the problems that are
posted to c.l.p.m are related to the mind twist you need in
order to understand that the CGI script is being run as the
*server's* user, not as you. This has many subtle (and not so
subtle) implications in terms of working directories, environment,
permissions, etc. Debugging can be difficult enough when
everything is in the same directory. Debugging through a
[browser->network->web server->CGI script] combination can be a
{*filter*}! I have developed a raft of tools for simulating my CGI
environment just so I *don't* have to debug in that tar pit!
But is a newbie going to know that they just decided to learn
to rock climb on a (potentially) Class 6 ascent? I think not.
Q: So what do you do when the 1,000th newbie asks the same question?
A1: Well, by now it sure as hell should be in the FAQ!
A2: Don't say anything. Let someone else yell at them and say RTFM! :-)
A3: Realize that it is probably *the newbie's* first time asking
that question. This is different from someone asking the
same question 1,000 times, true?
Q: But they don't *read* the F****** FAQ!
A: Perhaps they need a little help finding things. (see above)
Q: Newbies drive me crazy! What can I do?
A1: Ignore them.
A2: Stop reading the newsgroup.
A3: Only read postings by people you know are not newbies.
A4: Create a filter (in perl) for the newsgroup that eliminates all
posts containing questions that have an 80+% conceptual similarity
to items in the FAQ. Share it with others!
Q: They want us to do their homework!
A: Well, to hell with them! (you gotta flame *something*! :-)
[ Sounds of falling off soap box ]
Peace,
Peter Rowell
Third Eye Software
Pre-ANNOUNCE of a Perl Documentation Navigator