#:g1: Portable Utilities for Common Lisp: USER-MANUALの紹介

Posted 2014-09-14 01:45:00 GMT

(LISP Library 365参加エントリ)

 LISP Library 365 の257日目です。

Portable Utilities for Common Lisp: USER-MANUALとはなにか

 Portable Utilities for Common Lisp: USER-MANUALは、Mark Kantrowitz氏作のCommon Lispのコードからドキュメントを生成してくれるツールです。

パッケージ情報

パッケージ名Portable Utilities for Common Lisp: USER-MANUAL
Quicklisp×
配布サイトUser Manual: Automatical User Manual Creation

インストール方法

 配布サイトからダウンロードしてロードします。ANSI CLでも特に問題なく読み込めると思います。

試してみる

 Portable Utilities for Common Lisp: USER-MANUALは、Mark Kantrowitz氏が1990年頃に立ち上げていた、Portable Utilities for Common LispというCommon Lispのユーティリティを充実させようというプロジェクトの成果物です。
やっていることといえば、ソースファイルを読み込んでドキュメンテーション文字列を抽出してまとめる、というもの。
生成するドキュメントの形式は、テキスト、Subscribe、LaTeXとなっていますが、試してみた感じでは、Scribeはサポートしているツールがないので確認できないのと、LaTeXもどうも現在のlatexコマンドでは生成されたファイルが上手く処理できないようです。
とはいえ、出力でやっていることは単純なので直したり、新しい形式に対応させたりするのは簡単かなと思います。テキスト形式で出力するとこんな感じです。

(user-manual:create-user-manual "user-manual.lisp")
;>> ;;;
;>> ;;; *USERMAN-VERSION* ("2.0 20-oct-94")                             [PARAMETER]
;>> ;;;    Current verison number/date for User-Manual.
;>> ;;;
;>> ;;; USERMAN-COPYRIGHT (&optional (stream *standard-output*))         [FUNCTION]
;>> ;;;    Prints a User Manual copyright notice and header upon startup.
;>> ;;;
;>> ;;; EXTRACT-DOCUMENTATION (body)                                        [MACRO]
;>> ;;;
;>> ;;; ATOM-OR-CAR (list-or-atom)                                       [FUNCTION]
;>> ;;;
;>> ;;; *DOCUMENTATION-HANDLERS* ((make-hash-table :test #'equal))       [VARIABLE]
;>> ;;;    Hash table of entries of the form (handler description),
;>> ;;;    where definer is the car of the definition form handled (for
;>> ;;;    example, DEFUN or DEFMACRO), handler is a function which takes the
;>> ;;;    form as input and value-returns the name, argument-list and
;>> ;;;    documentation string, and description is a one-word equivalent of
;>> ;;;    definer (for example, FUNCTION or MACRO).
;>> ;;;
;>> ;;; DEFINE-DOC-HANDLER (definer arglist description &body body)         [MACRO]
;>> ;;;    Defines a new documentation handler. DEFINER is the car of the
;>> ;;;    definition form handled (e.g., defun), DESCRIPTION is a one-word
;>> ;;;    string equivalent of definer (e.g., "function"), and ARGLIST
;>> ;;;    and BODY together define a function that takes the form as input
;>> ;;;    and value-returns the name, argument-list, documentation string,
;>> ;;;    and a list of any qualifiers of the form.
;>> ;;;
;>> ;;; FIND-DOC-HANDLER (definer)                                       [FUNCTION]
;>> ;;;    Given the car of a form, finds the appropriate documentation
;>> ;;;    handler for the form if one exists.
;>> ;;;
;>> ;;; LISTIFY (x)                                                      [FUNCTION]
;>> ;;;
;>> ;;; NULL-OR-CDR (l)                                                  [FUNCTION]
;>> ;;;
;>> ;;; NULL-OR-CADR (l)                                                 [FUNCTION]
;>> ;;;
;>> ;;; *FAILED-DEFINITION-TYPES* (nil)                                  [VARIABLE]
;>> ;;;    List of definition types that create-user-manual couldn't handle.
;>> ;;;
;>> ;;; CREATE-USER-MANUAL (filename &key (output-format :text)          [FUNCTION]
;>> ;;;                     (output-stream *standard-output*)
;>> ;;;                     (purge-latex t))
;>> ;;;    Automatically creates a user manual for the functions in a file by 
;>> ;;;    collecting the documentation strings and argument lists of the
;>> ;;;    functions and formatting the output nicely. Returns a list of the
;>> ;;;    definition types of the forms it couldn't handle. Output-format
;>> ;;;    may be either 'TEXT, 'SCRIBE or 'LATEX. In this last case the extra
;>> ;;;    keyword 'purge-latex' may be specified: if non nil the latex
;>> ;;;    filter will try to substitute possible dangerous characters like '&',
;>> ;;;    '\' and '#'.
;>> ;;;
;>> ;;; HANDLE-FORM-OUTPUT (form &optional (output-format 'text)         [FUNCTION]
;>> ;;;                     (stream *standard-output*) (purge-latex t))
;>> ;;;    This function takes a form as input and outputs its documentation
;>> ;;;    segment to the output stream.
;>> ;;;
;>> ;;; FIND-KEYWORD (sym)                                               [FUNCTION]
;>> ;;;
;>> ;;; OUTPUT-FRAME-DOCUMENTATION (name type args documentation         [FUNCTION]
;>> ;;;                             &optional
;>> ;;;                             (stream *standard-output*))
;>> ;;;    Prints out the user guide entry for a form in FrameMaker(tm) mode.
;>> ;;;
;>> ;;; OUTPUT-TEXT-DOCUMENTATION (name type args documentation          [FUNCTION]
;>> ;;;                            args-tab-pos type-pos
;>> ;;;                            &optional (stream *standard-output*))
;>> ;;;    Prints out the user guide entry for a form in TEXT mode.
;>> ;;;
;>> ;;; OUTPUT-SCRIBE-DOCUMENTATION (name type args documentation        [FUNCTION]
;>> ;;;                              &optional
;>> ;;;                              (stream *standard-output*))
;>> ;;;    Prints out the user guide entry for a form in SCRIBE mode.
;>> ;;;
;>> ;;; OUTPUT-LATEX-DOCUMENTATION (name type args documentation         [FUNCTION]
;>> ;;;                             &optional (stream *standard-output*)
;>> ;;;                             (purge-documentation t))
;>> ;;;    Prints out the user guide entry for a form in LaTeX mode.
;>> ;;;
;>> ;;; PURGE-STRING-FOR-LATEX (a-string purge-doc)                      [FUNCTION]
;>> ;;;    Tries to purge a string from characters that are potentially
;>> ;;;    dangerous for LaTeX.
;>> ;;;
;>> ;;; PREPROCESS-LAMBDA-KEYWORDS (args)                                [FUNCTION]
;>> ;;;    Unused
;>> ;;;
;>> ;;; PREPROCESS-LISP-LATEX-CLASHES (args purge-doc)                   [FUNCTION]
;>> ;;;    This function is used to make the strings for the arguments of the
;>> ;;;    form digestible for LaTeX, e.g. by removing '#' and '&'.
;>> ;;;
;>> ;;; PREPROCESS-CHARACTER (c)                                         [FUNCTION]
;>> ;;;    Low level processing of single characters, when passed as defaults
;>> ;;;    to optional, key and aux parameters.
;>> ;;;
;>> ;;; PREPROCESS-SPECIALS (list-form purge-doc)                        [FUNCTION]
;>> ;;;    Processing of some 'special' forms. Only 'quote' and 'function' are
;>> ;;;    treated for the time being.
;>> ;;;
;>> ;;; SPLIT-STRING (string width &optional arglistp filled             [FUNCTION]
;>> ;;;               (trim-whitespace t))
;>> ;;;    Splits a string into a list of strings, each of which is shorter
;>> ;;;    than the specified width. Tries to be intelligent about where to
;>> ;;;    split the string if it is an argument list. If filled is T,
;>> ;;;    tries to fill out the strings as much as possible. This function
;>> ;;;    is used to break up long argument lists nicely, and to break up
;>> ;;;    wide lines of documentation nicely.
;>> ;;;
;>> ;;; SPLIT-POINT (string max-length &optional arglistp filled)        [FUNCTION]
;>> ;;;    Finds an appropriate point to break the string at given a target
;>> ;;;    length. If arglistp is T, tries to find an intelligent position to
;>> ;;;    break the string. If filled is T, tries to fill out the string as
;>> ;;;    much as possible. 
;>> ;;;
;>> ;;; LAMBDA-LIST-KEYWORD-POSITION (string                             [FUNCTION]
;>> ;;;                               &optional end trailer-only)
;>> ;;;    If the previous symbol is a lambda-list keyword, returns
;>> ;;;    its position. Otherwise returns end.
;>> ;;;
;>> ;;; BALANCED-PARENTHESIS-POSITION (string &optional end)             [FUNCTION]
;>> ;;;    Finds the position of the left parenthesis which is closest to END
;>> ;;;    but leaves the prefix of the string with balanced parentheses or
;>> ;;;    at most 1 unbalanced left parenthesis.
;>> ;;;
;>> ;;; UM-BUILD-SYMBOL (symbol &key (prefix nil prefix-p)               [FUNCTION]
;>> ;;;                  (suffix nil suffix-p) (package nil package-p))
;>> ;;;    Build a symbol concatenating prefix (if not null), symbol, and suffix
;>> ;;;    (if not null). The newly generated symbol is interned in package, if
;>> ;;;    not null, or in the SYMBOL-PACKAGE of symbol, otherwise. 
;>> ;;;
;>> ;;; CREATE-MANUALS (files &key (extension '.cl)                      [FUNCTION]
;>> ;;;                 (output-format 'text))
;>> ;;;
;>> ;;; PARSE-WITH-DELIMITER (line &optional (delim #\newline))          [FUNCTION]
;>> ;;;    Breaks LINE into a list of strings, using DELIM as a 
;>> ;;;    breaking point.
;>> ;;;
;=> (DEFINE-DOC-HANDLER WHEN USERMAN-COPYRIGHT IN-PACKAGE)
                    

まとめ

 今回は、Portable Utilities for Common Lisp: USER-MANUALを紹介してみました。
自分が知る限りでは、Portable Utilities for Common Lispは、オープンソースなユーティリティ共有のプロジェクトとしては、最初期のものですが、CMUのAIレポジトリもこのプロジェクトのLisp ユーティリティー置き場が発展してできたもののようです。

comments powered by Disqus