DocNav has not been updated in sometime. I rarely use Perl any more,
having taken a trip through PHP-land (yuck) and decided that
Python is a much nicer language. This doesn't mean that
the basic idea of DocNav is not needed, just that I
need to rewrite it in Python and aim it at the
Python docs, which are almost as much of a pain in the a** as
the Perl docs were.
DocNav
What is DocNav?
DocNav is a program for navigating through large collections
of documentation. It is template-driven and can be customized
for each collection by describing the grouping of the documents,
lists of additional resources, etc.
It is intended to be the one place you need to go to find help,
FAQs, tutorials, glossaries and, of course, the reference manual.
DocNav's search differs from most other systems in that it works at
the paragraph level instead of the document level. Instead of
being told that your hit is some where in a 50-odd page file,
it shows you the matching paragraphs. Clicking on
a result takes you to that point in the master document. Future
versions of DocNav will optionally return results at the
subsection, section or chapter levels.
The first collection DocNav has been applied to is the
documentation for the Perl programming language. This is
appropriate since DocNav is written entirely in Perl.
DocNav has also been applied to other collections
such as those for Java®, the Apache server and the FreeBSD
version of UN*X.
I was motivated to release DocNav for two reasons:
- I hoped others might find it as useful as I have.
- People just starting out in Perl have to confront a
virtual mountain of documentation. This is a Good Thing and a Bad Thing.
Because there is so much of it, newbies don't know where to start looking
and so they post something to a newsgroup - often resulting in a
mini-flamefest about RTFM, etc. With DocNav they
will no longer have the excuse that searching through all of the docs
takes too long. (And the rest of us won't have to post/read all
of the flames. :-)
So DocNav is my contribution to better informed newbies (and others) and
to more pleasant interactions in the newsgroups. Together we can
not only RTFM (Read The Friendly Manual) but also
FIITFM (Find It In The Friendly Manual).
DocNav has a number of useful features. It:
- has a web-based interface - pretty much everybody has at least a
simple browser. DocNav is even somewhat Lynx-friendly and could be
made to be more so if necessary.
- runs as a CGI script under an existing web server, OR
- includes its own, ready-to-run miniserver. Yes, it works with
the perl5.004_2 and ActivePerl 5.005_3 binary distributions for
Windows.
- performs paragraph-level searching. This means it doesn't tell
you what file the hit was in, but which paragraph.
- shows hit lists as keywords-in-context-in-paragraph.
- displays documents with search terms highlighted.
- is 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?!
However, DocNav is:
- not a build-the-index-first type of system, but its performance
seems to be acceptable, certainly for single-user systems.
Future versions will include a more sophisticated
search mechanism, but the current one will serve for the moment.
- not intended to be used on super-large collections of random,
unrelated files.
- 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.
Running Demo
It's not running and won't be.
Most of the time, there is a running version of DocNav at
http://www.datahedron.com.
Please feel free to play with it to see if it is useful enough
to download and install. Since the site it is running on is a friend's
personal machine, please don't use it for everyday.
There are several advantages to install DocNav locally:
- It will search all of the modules you have installed,
instead of the ones I have installed.
- You can tweak the setup files and have it search other collections
that I have never heard of.
- It will be much faster to download long pages (like perlfunc)
if it is all on your local machine or local net.
The DocNav License
DocNav is released under the terms of the Artistic License, a
copy of which is included with every perl distribution.
It basically says to leave the copyright alone, mark
your changes, and play nice with others.
Continue to
Downloading and Installing DocNav.
Author
DocNav was written by me, Peter Rowell.
It started life as
a simple little perl script to make it easier to find things
in the perl documentation. I wanted to share something with
the Perl coummunity, to which I have owed so much over the years.