Content preview: Sabra Crolleton <sabra.crolleton-***@public.gmane.org> wrote: > I put
together a draft of a review of common lisp documentation > generation tools
at https://sites.google.com/site/sabraonthehill/ > lisp-document-generation-apps.
[...]
Content analysis details: (-100.8 points, 5.0 required)
pts rule name description
---- ---------------------- --------------------------------------------------
-100 USER_IN_WHITELIST From: address is in the user's white-list
-0.8 RP_MATCHES_RCVD Envelope sender domain matches handover relay domain
Archived-At: <http://permalink.gmane.org/gmane.lisp.cl-pro/704>
Post by Sabra CrolletonI put together a draft of a review of common lisp documentation
generation tools at https://sites.google.com/site/sabraonthehill/
lisp-document-generation-apps.
Thank you for this feedback. I'm the author of Declt. Here are some
comments.
Post by Sabra CrolletonLicense info: According to the documentation, this should be able to
be passed in the call to declt, but I could not get this to work.
One possible source of confusion is that you need to explicitely pass a
:license keyword to DECLT to get a Copying chapter (:license defaults to
nil). However, Declt will also advertise the contents of the :license
field from the ASDF system definition on the /system/ page, without
processing it. Declt doesn't try to guess the license from the ASDF
:license field because people do whatever they want in this field and it
would be too difficult to be accurate. As a result, if this field says
"GNU GPL" but you pass :LICENSE :BSD to the call to DECLT, then you will
indeed get something inconsistent.
Post by Sabra CrolletonProperly flags the license as MIT, but makes a textual statement about
this being under GPL3
Provided the above, that is not possible. Or, I don't understand you.
BTW, the upcoming release of Declt will support 2 new license types:
:MIT and :LGPL. Others on demand.
Post by Sabra CrolletonInternal symbols: Only if specified in the call to the document
generator. It does not attempt to read the asd file for this
information
I don't understand. Internal symbols are always documented. What has
the ASDF file to do with this ?
Post by Sabra CrolletonClass info: Declt only provides limited information here. It only
provides the name and the document string, unlike other packages which
provide slots, methods, etc
Declt does document generic functions and methods (but they do not
belong to classes). Do you mean that you would like back pointers from
classes to applicable methods ? Given multiple inheritance, that's sort
of frightening. Slots are on my TODO list.
Slot accessors are generic function so they are documented as such. I
agree it would be convenient to have back pointers to them (when slots
are documented).
Post by Sabra CrolletonI may be overly repressed, but I found inserting the name of the declt
version "James T. Kirk" seemed a bit tacky.
I presume you're talking about the small Declt notice that's inserted
in the final document. The next version will give you some control on
this notice by way of a :DECLT-NOTICE keyword argument (possible values:
NIL, :SHORT and :LONG).
Post by Sabra CrolletonInstallation Notes No problems other than the slight irritation of
loading a package called com.dvlsoft.declt instead of something simple
like declt.
Short package names are EVIL. If that really upsets you, you can call
(com.dvlsoft.declt:nickname-package) right after loading it, and from
there on, you can use just DECLT as a nickname. You can even automate
that with CL-RCFILES for example.
Post by Sabra CrolletonAuthor: Yes if defined in the call to declt
Author Email: Yes, if defined in the call to declt
Software Version: You need to explicitly state this in the command to declt
That is incorrect. All of this is extracted from the system definition
if not provided explicitly. The only thing that is not is the license
(see above).
That's incorrect. Conditions are documented and indexed in the Data
Types section.
Post by Sabra CrolletonHomepage: no
Special Variable Values: No Variable names are shown, but not their
current values
[ and some other features ] I don't think those would be very useful
in a /reference/ manual (as opposed to a user manual). Maybe "what calls
what", yeah.
Otherwise, I will look into the backtraces you provided.
Thanks again.
--
Resistance is futile. You will be jazzimilated.
Scientific site: http://www.lrde.epita.fr/~didier
Music (Jazz) site: http://www.didierverna.com