The attached file contains a completion function for figlet[1] that I just
finished writing, and I would like to donate it to the zsh distribution.
I don't think I've done anything terrible, but then again, this is 
my first completion function, so it wouldn't be surprising if I made
a few mistakes.  If there's anything wrong w/ it, please let me know.


I also have a few questions:

  regarding $opt_args
    Is it only set when you use the '->state' mechanism?
    It seems to be empty, otherwise.

  arguments to _arguments
    The following is a line from the completion function:

        "-d+[directory]:directory:_path_files -/" \
                        ^^^^^^^^^

    What is the purpose of the underlined string?
    When might this string be useful to someone who is
    writing completion functions?  Is their a proper name
    for the strings that go there?


[1] a program for rendering text using ascii art fonts
    http://ianchai.50megs.com/figlet.html


PS: I'm going to use this as the basis for a little article on writing
    completion functions.  I still need to improve my understanding of
    how this all works, though.  Zsh is so complicated...  My head
    hurts from RTFM.

    Many times, I've wished for a tool like perldoc.  It could be called
    zdoc, and you'd be able to do things like:

    Reading about modifiers
        zdoc -m :q
        zdoc -m :r

    Reading about flags
        zdoc -F @
        zdoc -F U

    Reading about options
        zdoc -o promptsubst

    Reading about functions that come w/ the distribution
        zdoc -f _arguments
        zdoc -f _tags

    etc. 

    just another perl hacker (spoiled by perldoc)