Pre-ANNOUNCE of a Perl Documentation Navigator 
Author Message
 Pre-ANNOUNCE of a Perl Documentation Navigator

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



Fri, 03 Nov 2000 03:00:00 GMT  
 Pre-ANNOUNCE of a Perl Documentation Navigator

[mailed && posted]


Quote:

> [...]
>     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.

Sounds like a really *GREAT* tool!

I want a copy as soon as it'll be available! :-)

I also volunteer for alpha and beta testing.

- Show quoted text -

Quote:
> The following are just my opinions.  If you are happy with yours,
> you can skip the rest of this message!
> 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?).

Yes, a lot!

Great statement, which I fully agree with!

Quote:
> [...]

Yours sincerely,
--

    Free Perl and C Software for Download: www.engelschall.com/u/sb/download/
    "Perl is like sex: If you never had it, you wonder what the fuss is all
     about. Once you had it, you never want to be without it again." (unknown)


Fri, 03 Nov 2000 03:00:00 GMT  
 
 [ 2 post ] 

 Relevant Pages 

1. ANNOUNCE: Tutorial # 27: A navigator for foreign keys in MySQL table schema

2. Announce: Macro.pm - macro pre-processor with embedded perl capability

3. ANNOUNCE: Win32 IProc,ISync,MemMap Perl modules (and complete extensive documentation)

4. ANNOUNCE Perl 5.005_02 Documentation in HTMLHelp format

5. ANNOUNCE: New Perl documentation available

6. ANNOUNCE: DocNav 0.02 - Navigating the Perl Documentation

7. ANNOUNCE: PERCEPS, A Documentation Generator for C++ written in Perl

8. ANNOUNCE: PERCEPS A C++ Documentation generator written in Perl

9. Pre-announce

10. Pre-announce: New module called FSM::Command

11. Pre-Announce: Tie::Handle 1.0 in the making

12. Pre-Announce: TextDB: tie plain text DB-like files to hash

 

 
Powered by phpBB® Forum Software