DOCBOOK: Re: using docbook for CLOS

[Henrik Motakef <henrik dot motakef at web dot de>]

Norman Walsh <ndw at nwalsh dot com> writes:

> I think CL documentation fits squarely in DocBook's problem domain. If
> DocBook's not rich enough to document CLOS (or CLisp, or maybe I
> misunderstand something), please tell us how and why.

Maybe it's just because I don't know DocBook well enough, but I have a
hard time deciding how to mark up some Lisp constructs, especially in
refentries.

For example, CL functions/macros can return zero or more values, not
necessarily one, and have really complicated argument lists. For
example, the standard macro WITH-OPEN-FILE (see
<http://www.lispworks.com/reference/HyperSpec/Body/m_w_open.htm>)
takes a list consisting of a symbol, a pathname, arbitrary keyword
options as it's first parameter, and some code as the rest. It's
definition would look something like this:

(defmacro with-open-file ((var pathname &rest keywords) &body forms)
  ...)

Another example: The GETHASH function looks up a key in a hashtable
and returns its value (or a default, if the key is not found), and
another value indicating whether the key was found - that is, two
values, not one list with two items, which is something very
different. 

(See <http://www.lispworks.com/reference/HyperSpec/Body/f_gethas.htm>
for a description of GETHASH, and
<http://www.lispworks.com/reference/HyperSpec/Body/03_ag.htm> for a
discussion of forms returning multiple values.)

In both cases, I have no idea how to properly write a funcsysopsis
without at least misusing some elements in ways not justified by their
intended meaning as documented in TDG. If anybody does, I would be
glad to hear about it. (As I said, my plan to extend DocBook is mostly
justified by my interest to learn more about its inner structure, I
don't think it is the best way to go if there are alternatives without
breaking compatibility with existing tools.)

Regards
Henrik