[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: DOCBOOK: Re: using docbook for CLOS
Norman Walsh <ndw@nwalsh.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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]