Common Lisp Package: TINAA

A simple, yet extensible, Common Lisp documentation package.

README:

FUNCTION

Public

DOCUMENT-SYSTEM (SYSTEM-KIND SYSTEM-NAME DESTINATION &REST ARGS &KEY (SHOW-PARTS-WITHOUT-DOCUMENTATION? T) (WRITE-FILES? T) (PAGE-WRITER-CLASS NIL))

Create TINAA documentation for a system. System-kind should be 'package or some other value for which it makes sense (e.g., an 'asdf-system if ASDFis loaded...). System-name is the identifier of the system. Destination is the location in the file system where you want the documentation to go. Finally, you can pass in other arguments that are specific to the kind of system you are documenting. Note that system-kind will be coerced into a symbol interned in the Tinaa package because this makes Tinaa easier to use. If you happen to write your own system-kind, it will need to be a class defined in the Tinaa package.

Private

BUILD-PERMUTED-INDEX (MAIN-PART PARTS-TO-INDEX HEADING)

A permuted index includes each n-word entry up to n times, at points corresponding to the use of each word in the entry as the sort key. For example, a symbol FOO-BAR would occur twice, once under FOO and BAR. This allows you to use any word in the symbol's name to search for that symbol.

CLASS-GRAPH->DOT (GRAPH)

Returns a string describing graph in DOT format.

CONDITIONP (THING)

Returns true if and only if thing is a condition

CONTENT-THINGS-FROM-PART (PART)

Returns a list of < kind name url > triples for the subparts of part that should be displayed in the table of contents.

FIND-NAME-AND-EMAIL (STRING)

Returns (as multiple values) a name and e-mail address as parsed from a string. Handles only "name <mail>" right now. if the string isn't in this from,then this function assumes that the string contains only a name. Also doesn't handle group projects!

PARTS-MATCHING-SYMBOL (SYMBOL-PART NAME-HOLDER)

Returns a list of parts in name-holder than have the same name as symbol

PATHNAME-FOR-SYSTEM-FILE (SYSTEM FILENAME)

Returns the full pathname in system for filename (which is just the name+type).

RELATIVE-URL (URL)

Returns a URL that points to the same things as `url` but relative to (url *current-part*)

ROOT-PARENT (PART)

Go up the parent chain until there are no parents... that's the root.

URL->FILE (URL &OPTIONAL (EXTENSION html))

Returns a file spec for the url rooted at *document-root*. The URL must be delimited using forward slashes (#/). The *document-root* can be a logical pathname or a physical pathname on the current platform.

Undocumented

ADD-PACKAGE-TO-DOCUMENT (PACKAGE-NAME)

ANY-INDEXES-P (PART)

BUILD-INDEX (WRITER PART PARTS-TO-INDEX HEADING)

BUILD-INDEX-LETTERS (SYMBOL-LIST PARTS &KEY (KEY 'IDENTITY))

BUILD-LICENSE-PAGE (PART)

BUILD-PART-GRAPH (WRITER ROOT &KEY (DEPTH (DEPTH-FOR-PART WRITER ROOT)))

CANONICAL-PACKAGE-ID (PACKAGE)

CLASS-SORTER (A B)

CLASS-UNINTERESTING-P (CLASS-NAME)

DISPLAY-ARGUMENTS (ARGUMENTS)

DISPLAY-FUNCTION (PART)

DISPLAY-LIST-OF-POTENTIAL-PARTS (PART SUBPART-NAMES SUBPART-KIND)

DISPLAY-PART-FOR-INDEX (WRITER PART STRING)

FILE-DEPTH-BELOW-ROOT (URL)

FILTERED-PACKAGE-SYMBOLS (PART FILTER)

GRAPH-FILE-NAME-FOR-PART (WRITER PART &KEY (PATHNAME-TYPE *GRAPH-IMAGE-FORMAT*))

IGNORE-PACKAGE-P (P)

INDEX-FILE-NAME (PART INDEX-NAME)

INDEX-FOR-KIND-P (PART KIND)

INDEX-PART-P (PART)

INTERESTING-SUBCLASSES (THING)

INTERESTING-SUPERCLASSES (THING)

LML-INSERT-FILE (FILE)

LOCAL-INDEX-URL (PART INDEX-NAME)

MAKE-LOCAL-CLASS-GRAPH (CLASS-PART)

MAKE-STRING-OF-SIZE (SIZE INITIAL-ELEMENT)

MAP-PARTS-FROM-LEAVES (PART FN)

MAP-SUBPART-KINDS (PART FN)

MAYBE-DISPLAY-PART (PARENT NAME KIND MODE)

METHOD-SORTER (M1 M2)

NICE-PACKAGE-NAME (PACKAGE)

NS-TLP (PATHNAME)

OUTPUT-TABLE-SUMMARY (WRITER PART PARTS-PER-ROW)

PACKAGES-TO-DOCUMENT

PACKAGES-TO-IGNORE

PART-CAN-HAVE-DOCUMENTION-P (PART)

PART-HAS-PARENTS-P (PART)

PART-SYMBOL-NAME (PART)

PARTS-WITH-NO-DOCUMENTATION (PART)

PATHNAME->UNIX (PATHNAME)

PERMUTED-INDEX-DELIMITER-P (CH)

PERMUTED-INDEX-LOCATIONS (SYMBOL DELIMITER-P)

PRINC-N-SPACES (STREAM N)

SET-FLAGS (PART VALUE)

SLOT-WRITER-NAME (WRITER)

SOME-PARENT (PART)

STYLESHEET-URL (PART)

SUBPART-INFO (PART KIND)

SYMBOL-COUNT (PACKAGE KIND)

SYMBOL-NAME-TREE (X)

SYSTEM-PACKAGES (PART SYSTEM-CLOSURE?)

TINAA-HOME

UPDATE-DOCUMENT-PART-P (PACKAGE)

URL-NAME (URL)

WRITE-CSS-FILE (WRITER DESTINATION &REST ARGS &KEY (IF-EXISTS SUPERSEDE) &ALLOW-OTHER-KEYS)

WRITE-PART-GRAPH (WRITER PART)

MACRO

Private

FN (EXPR)

A general-purpose function-builder. EXPR should be of the form (OPERATOR . ARGUMENTS). Will return a function equivalent to (lambda (arg0 arg1 ... arg1) (mapcar #'fn arguments)). e.g. (fn (and integerp oddp)) => (lambda (x) (and (integerp x) (oddp x))). U:COMPOSE is treated specially, so that (fn (u:compose integerp oddp)) => (lambda (x) (integerp (oddp x))). (This is the same as (fn (integerp (oddp))))

Undocumented

DOCUMENTING (PART &BODY BODY)

DOCUMENTING-PAGE ((PART &KEY TITLE FORCE-CONTENTS-LINK?) &BODY BODY)

WITH-HTML-OUTPUT ((STREAM) &BODY BODY)

GENERIC-FUNCTION

Public

DISPLAY-PART (PAGE-WRITER PART MODE &KEY (SPACES 0) &ALLOW-OTHER-KEYS)

Output information about a part. Example modes are :subpart-list, :detail, :summary.

MAKE-PART (PARENT KIND NAME &ALLOW-OTHER-KEYS)

Make a part named 'name' of kind 'kind' whose parent is 'parent'.

PART-DOCUMENTATION (PART)

Returns whatever documentation is available for part using the Common Lisp documentation function.

PARTNAME-LIST (PART PART-KIND)

Returns a list of the names of the subparts of part of type 'part-kind'. Usually, these will be symbols but they could be strings too.

SUBPART-KINDS (ASSEMBLY)

Returns a list of the kinds of the subparts of assembly. This is a list of instances of subpart-kind.

Private

DOCUMENT-PART-P (NAME-HOLDER PART)

DOCUMENT-PART-TO-FILE (PAGE-WRITER PART)

DOCUMENT-SYSTEM-PART (SYSTEM PART STREAM)

DOCUMENTATION-EXISTS-P (PART MODE)

FIND-PART (ANCESTER KIND NAME)

Returns a existing part if it can be found.

FINISH-GROVEL (PART)

GROVEL-PART (PART)

INCLUDE-KIND-IN-INDEX-P (PART KIND)

Returns true if part should include kind in it's index.

INDEX-KINDS (PART)

Returns a list describing what indexes to generate for this part. This list is a list of lists of subpart kinds. Each item in the list generates one index and the index will include all of these part kinds.

MAKE-SYSTEM-PART (SYSTEM PART-KIND PART-NAME &KEY)

OUTPUT-TABLE-SUMMARY-OF-PARTS (WRITER PART SUBPART-NAME HEADING)

PART-NAME (PART)

Returns the name of the part as a string

SHORT-DOCUMENTATION (PART)

Returns the first bit of the documentation for part. Change *short-documentation-length* to determine how much is returned.

SHOW-PART-PARENTS (PART)

Generate HTML to show the parents of a part. Called for a part only when it actually has parents (using an around method).

SPAN-CLASS-FOR-PART-NAME (NAME-HOLDER PART)

Returns the class to be used when displaying the part's name.

URL-FOR-PART (PART)

Returns the url for the part, creating it if necessary.

Undocumented

ADD-PART-VERTEX (GRAPH PART)

ARGS (CONDITION)

BUILD-CONTENTS-PAGE (WRITER ROOT TOP-LEVEL-THINGS)

BUILD-DOCUMENTATION (WRITER PART ROOT &KEY (ERASE-FIRST? NIL) &ALLOW-OTHER-KEYS)

BUILD-INDEXES (WRITER PART)

CSS-FILE-FOR-WRITER (WRITER)

DEPTH-FOR-PART (WRITER PART)

DIRECT-INSTANCE (SLOT)

DIRECT-PARENT (SLOT)

DOCLISP-HEADER (PART &KEY FORCE-CONTENTS-LINK?)

EDGE-KINDS-FOR-PART-GRAPH (WRITER ROOT PART)

GRAPH-PART-P (WRITER PART)

INCLUDE-IN-CONTENTS-P (PART)

KIND (CONDITION)

LAYOUT-ENGINE-FOR-PART (WRITER PART)

LAYOUT-GRAPH-TO-FILE (GRAPH LAYOUT-ENGINE OUTPUT-TYPE OUTPUT-BASE)

MAKE-PART-GRAPH (WRITER PART)

MAKE-ROOT-POINTING-URL (PART NAME)

MAYBE-SHOW-DOCUMENTATION (PART)

PART-KIND-ABBREVIATION (PART)

REASON (CONDITION)

START-GROVEL (PART)

STRING->HTML (STRING &OPTIONAL (MAX-LENGTH))

SYSTEM-FILES (PART SYSTEM-CLOSURE?)

SLOT-ACCESSOR

Public

INSTANCE (OBJECT)

An instance of this part.

NAME (X)

The

Undocumented

PARENTS (OBJECT)

SETFPARENTS (NEW-VALUE OBJECT)

Private

Undocumented

AUTHOR-MAIL (OBJECT)

AUTHOR-NAME (OBJECT)

CSS-FILE (OBJECT)

SETFCSS-FILE (NEW-VALUE OBJECT)

SETFDIRECT-PARENT (NEW-VALUE OBJECT)

DOCUMENT? (OBJECT)

SETFDOCUMENT? (NEW-VALUE OBJECT)

ENOUGH-FILENAME (OBJECT)

FILENAME (OBJECT)

FLAG? (OBJECT)

SETFFLAG? (NEW-VALUE OBJECT)

SETFHEADER (NEW-VALUE OBJECT)

HEADING (OBJECT)

INDEX? (OBJECT)

LABEL (OBJECT)

MAINTAINER-MAIL (OBJECT)

MAINTAINER-NAME (OBJECT)

NAME-HOLDER (OBJECT)

PAGE-WRITER (OBJECT)

PAGE-WRITER-CLASS (OBJECT)

PART (OBJECT)

PART-KIND (OBJECT)

PART-TYPE (OBJECT)

ROOT-PART (OBJECT)

SUBPARTS (OBJECT)

SYMBOL-KINDS (OBJECT)

SETFSYMBOL-KINDS (NEW-VALUE OBJECT)

SYSTEM (OBJECT)

URL (OBJECT)

SETFURL (NEW-VALUE OBJECT)

VARIABLE

Public

*CSS-FILE*

If set, this should point to the CSS file that Tinaa should use.

Private

*GRAPH-IMAGE-FORMAT*

The image format to use for graph files

*GRAPHVIZ-DIRECTORY*

The location of the various GraphViz files. In particular, dot, neato, circo and twopi should live in this directory.

*MAKE-PART-METHODS*

Used to help ensure that we don't use up the stack trying to find a good method... Probably too baroque.

*SHORT-DOCUMENTATION-LENGTH*

The number of characters of documentation to show in summaries.

Undocumented

*CURRENT-INDEX*

*CURRENT-PART*

*CURRENT-PART-INDEX*

*DEFAULT-PACKAGES-TO-IGNORE*

*DOCUMENT-FILE*

*DOCUMENT-ROOT*

*DOCUMENT-STREAM*

*GRAPH-SIZE-IN-INCHES*

*OUTPUT-CALLS*

*PACKAGES-TO-DOCUMENT*

*REQUIRED-INDEX-CONTENTS*

*ROOT-PART*

*TINAA-HOME-PAGE*

*TINAA-VERSION*

CLASS

Public

DOCLISP-ASSEMBLY

A part with sub-parts.

DOCLISP-PART

A part without pieces (a leaf).

Private

Undocumented

BASIC-DOCLISP-PART

BASIC-PAGE-WRITER

DIRECT-DEPENDENCY-EDGE

DIRECT-PACKAGE-EDGE

DOCLISP-ASDF-SYSTEM

DOCLISP-CLASS

DOCLISP-CONDITION

DOCLISP-CONSTANT

DOCLISP-FILE

DOCLISP-FUNCTION

DOCLISP-GENERIC-FUNCTION

DOCLISP-MACRO

DOCLISP-METHOD

DOCLISP-PACKAGE

DOCLISP-SLOT

DOCLISP-SYMBOL

DOCLISP-VARIABLE

NAME-HOLDER-MIXIN

OTHER-DEPENDENCY-EDGE

OTHER-PACKAGE-EDGE

PAGE-WRITER-WITH-GRAPHS

SIMPLE-PAGE-WRITER

SUBPART-KIND

TINAA-ASDF-SYSTEM-VERTEX

TINAA-EDGE

TINAA-GRAPH

TINAA-PACKAGE-VERTEX

TINAA-PART-GRAPH

TINAA-PART-VERTEX

TINAA-VERTEX

CONDITION

Public

CANNOT-MAKE-PART

This error is signaled when a part cannot be created.

Private

Undocumented

PART-KIND-UNKNOWN-ERROR