Reads all files specified in filenames and extract their documentation using the specified output-format driver.

Because it is performing some symbol package resolution it needs packages definition to be, at least loaded. A simple way to satisfy this condition is to load, such as require would, the systems to be documented before starting documentation extraction.

If filenames is an ASDF system then its components files will be retreived first.

The extracted documentation will be written in a newly created file with the same name as the processed one but with the filename extension relatives to the output driver. If dest-dir is non NIL then it will be used to construct the output pathname, otherwise the output pathname will be constructed using the one of the currently processed file. The &rest initargs argument is for driver specific options.

All implementation must support the following option:

• :path-prefix (or null string): a string that will be used to dertermine the source folder where files to be processed can be found. If needed, this path-prefix (string) will be added to each filename of the source list. The destination folder is then constructed given this parameter. If specified, the path-prefix string is pruned from the destination folder in order to give the smallest pathname. Default to: *load-truename*.

  For instance, one could write:

      (extract-documentation 'html "/foo/doc/html" 
         '("foo.lisp" "gee/bar.lisp") 
         :path-prefix "/home/zorglub/prj-foo/src/") 

  to extract the documentation of the files 'foo' and 'gee/bar', that are located in /home/zorglub/prj-foo/src/, under the following tree: /foo/doc/html/foo.html and /foo/doc/html/gee/bar.html.

  But if an ASDF system is given for filenames then the :path-prefix will be found using asdf:component-relative-pathname method. Then to extract the documentation of an ASDF system one could write:

      (extract-documentation 'html "/foo/doc/html" 
         (asdf:find-system :the-foo-system)) 

Writes the given symbol-descriptor on the stream in the wanted output format using the specified output driver.

Writes the given symbol-descriptor documentation on the stream in the wanted output format using the specified output driver.

Returns the string that represent the fully qualified name of the given symbol-descriptor.

Returns string with date and time according to ISO 8601.

Returns the first string found in the given list of forms.

NIL is returned if no string is found before the first non declare form.

Returns a list of the string lines contained in the given string.

Returns a symbol name made from the concatenation of the given parts.

Given the car of a form, finds the appropriate description handler for the form if one exists.

Register the filename extension (a string) that will be associated with the specified output-format.

Returns the filename extension (a string) that is associated to the specified output-format.

Adds the specified prefix to eaxh filename when necessary.

Returns the relative pathname that goes from `from' to `to'.

Returns the common directories between the lisp-file and the dest-dir.

Returns the pathname of the output file where to write the documentation to. The resulting pathname will be relative to the dest-dir. Any common pathname denominator between the lisp-file truename and the dest-dir truename will be pruned.

Returns the home package name of symbol and the name of symbol.

Returns the list of qualifiers if any and the arguments lambda-list.

Returns a list of slot-descriptor object that represent the given list slot definition.

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 returns the descriptor object of the form.

Defines two functions of one parameter to purge from dangerous characters:

• :string-purger (name clauses &rest options): Defines a function of one parameter, a string, that will purge that string of any `dangerous' characters for your driver.

  • name (symbol): the name of the defined string purger function.

  • clauses (list): a list of pair as: (character replacement-string).

  • options (list): supported options: (:documentation string).

• :lambda-list-purger (name clauses &rest options): Defines a function of one parameter, a lambda-list, that will purge that lambda-list of any `dangerous' characters for your driver.

  • name (symbol): the name of the defined lambda-list purger function.

  • clauses (list): a list of pair as: (symbol replacement-string). The symbols are the Common Lisp symbols that might occures in lambda-list.

  • options (list): supported options: (:documentation string).

with-descriptor-read uses open to create a file stream to file named by filespec. Filespec is the name of the file to be opened.

with-descriptor-read evaluates the body as an implicit progn with the descriptor bound to the successive values returned by the handler of the currently readed form. If no handler exists then the name of the readed form will be added to the list of unhandled forms: *unhandled-forms*.

When control leaves the body, either normally or abnormally (such as by use of throw), the file is automatically closed.