Just fixed a few bugs to HEΛP.
- *Earmuffed* entries are now retrieved correctly; this was an issue with a file transfer to a Windows machine.
- Package non-external entries are now marked as such in the main documentation page (they are marked "internal").
Thanks to Faré and everybody else who wrote me (publicly or in private) pointing out initial issues.
I finally managed to push a preliminary version of my documentation generation system to Sourceforge. The project's site (and the links to the git repository) are at https://sourceforge.net/projects/helambdap/. The project's main web page (obviously self-generated) is http://helambdap.sourceforge.net. the
gitrepository can be found there.
You are all welcome to play around with the code (it has a BSD license) and to suggest (better: provide) improvements.
An example of what HEΛP can do with a third party system is here: the documentation generated for the UIOP portability substrate of ASDF3.
The actual call used to generate UIOP's documentation is below (comments follow).
(document #P"asdf/uiop/" :documentation-title "UIOP" :everything t :exclude-files (list #P"/Path/To/asdf3/asdf/uiop/asdf-driver.asd") :special-methods-defs-files (list #P"/This/file/here/helambda-asdf3.lisp") )
documentfunction is called on a folder (
"asdf/uiop/") with an obvious title. The other arguments have the following meaning:
:everything ttells HEΛP to generate documentation pages for everything; these are stored in the
dictionarysubfolder with file-names which should be relatively obvious. Ordinarily, HEΛP would generate doc pages only for public (i.e., exported) interfaces.
:exclude-filesis a list of files to forget about; UIOP has one file with an unqualified
DEFSYSTEMin, which confuses HEΛP.
special-methods-defs-filesis a list of files containing specialized definitions to handle a library extra "definition" forms and macros. UIOP has a number of them.
The results are, IMHO, pretty good. Also note that I used HEΛP on the pure set of UIOP files. The actual intended use of HEΛP is to generate documentation of a loaded (and, possibly, compiled) library or system.
So, give it a spin and let me know what you think. If you want, you can subscribe to the mailing lists at the following link: https://sourceforge.net/p/helambdap/mailman/.
HEΛP depends on XHTMΛ. For the time being you have to fetch them directly from the relative sites. Eventually they will be submitted to Quicklisp.
In a current thread on c.l.l. there was a discussion about how to "hide" bits and pieces of a data structure (the discussion was really about mutable strings). That got me thinking about how to provide more "hiding" than what you can achieve with the package system and with CLOS.
The following is a cute - I believe - hack to make the life of the
slot-value user much more difficult. Remember that
slot-value is just a function.
CL-USER 7 > (defclass foo () ((#.(gensym (random 42)) :reader foo-slot :initarg :slot))) #
CL-USER 8 > (describe (make-instance 'foo)) # is a FOO G21 # CL-USER 9 > (describe (make-instance 'foo :slot 42)) # is a FOO G21 42 CL-USER 10 > (defclass foo () ((#.(gensym (random 42)) :reader foo-slot :initarg :slot))) # CL-USER 11 > (describe (make-instance 'foo :slot 42)) # is a FOO G5 42
So, the trick is to generate random slot names, which can be accessed only via CLOS accessors (readers and writers). Plus, in order to make life difficult for any program "inspecting" the guts of a class, you can just redefine it at random times during your application's lifetime.
Not foolproof, but, as I said, cute.