Docstring question

["Daschbach, John L" <John dot Daschbach at pnl dot gov>]

I do not know how scwm's docstring implementation handles metadata but none of
the small examples I have seen posted cover this.  Without a metadata system it
seems inevitable that a very large amount of hand work will be required to
produce a manual which is organized by topic.   In my experience the best
manuals are structured around usage and provided with alphabetical indexes of
functions and variables.  Two quite good manuals I think are Octave and Emacs
Lisp.  Two bad manuals are the Perl book and the IDL (RSI. Inc.) manuals (two
volumes of functions in alphabetical order with function names often based on
Fortran heritage).  To automatically collect docstring information into relevant
manual sections requires some sort of metadata to be included in the docstring
format.

Another issue is that of examples.  The docstring format does not seem well
suited to providing examples for functions.  It is clear that Unix philosophy
penalizes those who write examples, but this thinking needs to change.  When one
works on many systems, with many programs, and writes in many languages, it's
too hard to remember every little syntactical quirk.  A classic example is the
find command, great once you know it, but a bit frustrating for most to learn.

Thus, I think the system proposed which uses the (documentation VALUE) approach
should be extended to something which might look like:

(documentation VALUE 'syntax)
(documentation VALUE 'use)
(documentation VALUE 'class 'primary)
(documentation VALUE 'class 'list)
(documentation VALUE 'example)

-John