HYPERDOC - unreleased

     by Tobias C Ritweiler
Repository:
 
     darcs get http://common-lisp.net/project/editor-hints/darcs/hyperdoc/
 
Download:
 
     hyperdoc-unreleased.tar.gz
 

Contents

  1. What is Hyperdoc?
  2. Notes on the API
  3. Limitations
  4. Usage (IDE User)
  5. Usage (IDE Hacker)
  6. Usage (Library Hacker)
  7. Dictionary
    1. *DOCUMENTATION-TYPES*
    2. LOOKUP
    3. REGISTER-DOCUMENTATION

 

What is Hyperdoc?

    Hyperdoc is a hypertext documentation support system for Common Lisp, licensed under a MIT-style
    license. Basically, it takes a symbol and outputs a URL to that symbol's documentation.

    It's supposed to be used a) by Common Lisp development environments to provide arbitrary
    documentation look up on key press, and b) by library authors to make their library's
    documentation conveniently available to users of their library.
 

Notes on the API

    Although I have made Hyperdoc available to the public, I do not consider it to be released yet.
    The effective difference between these two states is that you won't get any guarantee from me
    regarding backwards-incompatible changes -- although I'll try to avoid them, such changes may
    turn out to be necessary to overcome current limitations of Hyperdoc.
 

Limitations

    Hyperdoc currently only supports introspective look up of documentation -- this means that the
    symbols you want to inquire documentation for must be loaded into the running Lisp image (along
    their respective packages, of course.)

    In particular, generating a static indexing for all symbols of a package to avoid the necessity of
    introspection is not currently supported. Likewise, downloading documentation to the hard disk for
    offline usage is not supported either.

    The reason behind these restrictions is that personally, I can live with an introspective, online
    facility for now. Patches are welcome, of course. (In fact, it may be a nice down-to-the-earth
    project to use Drakma and Montezuma for this purpose.)
 

Usage (IDE User)

    A "user" means here someone who is primarely interested in being able to look up
    documentation during development. In that case, you should only know that Hyperdoc exists for the
    case that you want to make the documentation of your own software easily accessible to others. Your
    development environment should actually care for everything. (If it doesn't, pleaser refer the
    respective authors to this document and nicely ask them to add support for Hyperdoc.)

    In case you're using Slime, you have to enable the slime-hyperdoc contrib (or the slime-fancy
    meta contrib), and the key combination "C-c C-d h" will inquire hyperdoc about the symbol
    at your cursor's position.
 

Usage (IDE Hacker)

    foo.
 

Usage (Library Hacker)

    Registering your project's documentation to Hyperdoc is very easy. Depending on how
    complicated the linking scheme of your documentation generation tool is, the efforts range from
    being straightforward to being a bit more involved.

    You have to perform the following steps:     For example, registering documentation that has been created via Edi Weitz'
    Documentation-Tool is trivial: 

   (defvar *ediware*
     '(:capi-overview
       :chunga
       :cl-dongle
       :cl-fad
       ;; ...
       ))
  
   (dolist (package *ediware*)
     (register-documentation package
       :base-uri (format nil "http://weitz.de/~(~A~)/" package)
       :relative-uri-function (formatter "#~(~A~)")))


    Notice how first a output string stream, then the symbol being looked up, and then the desired
    documentation type is passed to relative-uri-function -- as you can see, this makes it
    viable to concisely specify everything that is needed by using FORMATTER in trivial cases.

    See REGISTER-DOCUMENTATION for further discussion.
 

 

Dictionary


[Special variable]
*documentation-types*

  Description:

Documentation types used by Hyperdoc. These correspond to what DOCUMENTATION uses with a few
additions.


[Function]
lookup package-designator symbol-name &optional doc-types => result

  Argument and Values:

package-designator: T
symbol-name: T
doc-types: T
result: T
  Description:
Looks up documentation for symbol named by symbol-name in the package designated by
package-designator.

doc-types may either be a symbol from *DOCUMENTATION-TYPES*, or a list of such symbols. If
doc-types are given, the lookup is restricted to documentation of the entities associated
with the given doc-types. doc-types defaults to *DOCUMENTATION-TYPES.

LOOKUP returns a list of applicable (DOC-TYPE . URI-STRING) pairs.

If the designated package does not exist, or if no the designated symbol does not exist, or if no
documentation for the designated symbol is found, NIL is returned.


[Function]
register-documentation packages &rest keys &key base-uri relative-uri-function extra-types-function normalize-types-function all-symbols &allow-other-keys => result

  Argument and Values:

packages: T
keys: T
base-uri: T
relative-uri-function: T
extra-types-function: T
normalize-types-function: T
all-symbols: T
result: T
  Description: 
  packages      ::= package-designator | (package-designators+)
  keys          ::= { :BASE-URI string
                      :RELATIVE-URI-FUNCTION fn
                    [ :EXTRA-TYPES-FUNCTION fn ] }+

This documentation was generated on 2009-12-2 from a Lisp image using some home-brewn, duct-taped,
evolutionary hacked extension of Edi Weitz' DOCUMENTATION-TEMPLATE.