[Doc-SIG] a wish list

[James Kerr]

  I've been following the messages in this group for a few weeks
now. It seems as though a lot of attention is being focused on 
the details of the markup language. This is certainly an important
issue, but maybe the *how* of the markup language will be easier
to decide once the *why* is understood.

  For whatever it's worth, I've outlined the ways I would like to
use Python documentation in an ideal world. These items are listed
from most important to least important. Maybe this will provide some
hints about the best way to implement markup.

  BTW, I don't know how much of this has been implemented in the
latest version of IDLE, so some of what follows may already be old
hat.  Also, I haven't much bothered to distinguish between usage in
a GUI environment, vs. an Emacs-like environment that is text-based
but mouse-aware, vs. a command-line environment.

* Search documentation by keyword or phrase, in any combination
  of Library Reference, FAQ, module descriptions, index, etc. The
  focus is on getting a quick answer to a specific question, not on
  broad topical navigation.

  Example: I'm a recent Python convert, I'm typing in my first script,
  and I want quick answers to questions like
      - how do I access command-line options?
      - how do I convert a string to an int?
      - what is the list of built-in operators?

  Preferred solution: type queries like these into a dialog box and
  get references to specific sections of documentation.

  Acceptable alternatives:
      - consult a permuted index
      - do a keyword query instead of a free-form query

  Comments:
    If a semantically-based search algorithm is too hard to write, a
    really good permuted index might be useful. All one-line class and
    function summaries could be part of this index, as could FAQ
    entries, annotations in the library reference, etc. All it would
    take is a small army of volunteers to go through the documentation
    and insert index entries at all relevant locations.

* View all available classes, either alphabetically or hierarchically.

  Preferred solution: A presentation that used indentation to show
  parent/child relationships, with links from class names to both
  documentation and source code. Some allowances would have to be
  made for multiple inheritance.

  Other niceities (available only in a GUI environment):
    - pause the cursor over a class reference, and see a
      1-line summary of the class in a popup window or status line.
    - expand a class (via some kind of mouse or keyboard operation),
      and see a list of all functions defined in the class.
    - pause over a function reference, and see a summary of
      the function in a popup or status line.
    - jump to class or function documentation (or source code)
      from the listing.

* View all the methods that are available in a class.

  This is a little different from the previous item, since inheritance
  allows you to call functions that are defined in a superclass. 

  Preferred solution: both of the following ~
    - a per-class view, that displays the inheritance tree from the
      selected class on upward. The functions defined in each class
      are displayed along with the class.
    - a summary view, that just shows the class you're interested in,
      and uses some kind of annotation to distinguish which methods
      are defined in that class, and which are defined in superclasses.
  
  Acceptable alternative: either of the above. 

* Maintain a list of bookmarks.

  Preferred solution: an easy-to-use tool that allows you to
    - bookmark locations precisely (i.e. down to line-in-a-document
      precision).
    - attach symbolic names to groups of bookmarks (for example,
      "Object Database Support")
    - adjust your bookmarks transparently when new documentation
      rolls out.

  Acceptable alternative: devise a scheme that allows a user to
  define his/her own bookmark files with a text editor.

  Comments:
    I often find myself using a small portion of online docs quite
    heavily when doing a project. It's kind of a pain to have to jump
    back and forth between documents (or parts of documents) to get
    information.  The ability to provide some kind of personalized
    view of documentation would be a real plus.

  
  Hope these challenges aren't too trivial to be interesting ;-)
In all seriousness, I think it's great that so much attention is
being given to the documentation effort, because it really could be
central to the success of Python.

-Jim

-- 
Jim Kerr
Agilent Technologies
1400 Fountaingrove Pkwy, MS 3USZ
Santa Rosa, CA 95403