[asdf-devel] [PATCH] add &allow-other-keys to LOAD-SYSTEM, COMPILE-SYSTEM, TEST-SYSTEM
Robert Goldman
rpgoldman at sift.info
Wed Feb 24 15:19:35 UTC 2010
On 2/24/10 Feb 24 -9:09 AM, james anderson wrote:
>
> i wondered that. looks like markdown link-w/o-the-reference-id
> syntax. (is supported by docudown?)
> but then, it's not clear were it finds it's definition. (work-in-
> progress?)
>
> which brings up larger questions.
> as i was writing docstrings for de.setf.amqp, i wondered, while
> markdown is most definitely less obnoxious than html, why does a lisp
> documentation system require markup in its docstrings?
> when the documentation is processed, a closed world can be arranged.
>
> the documentation generation code - as i've read and written it,
> crawls packages and/or live images, so there's a lot it can do
> without the markup hints. given that information, it is possible to
> recognize almost every pertinent reference without the hints in terms
> of bindings on symbols present in every package reachable from the
> respective function definition minus common-lisp.
I don't completely follow this argument. Let's say that I want to say
"see also OPERATE" in my docstring. Without /some/ form of markup, how
do you detect that this is a cross-reference (without solving the whole
AI problem :->)? Similarly, how do you know that this is a cross
reference to a function, instead of a type or variable?
AFAICT if we want to have cross-referencing in something we get out of
our docstrings, then we must have some form of markup.
If we really wanted to do this, I would propose that we add some species
of markup, shadow DEFUN and other definers, so that they cache the
markup-infested docstrings somewhere, and scrape the markup out of the
docstrings before recording them as DOCUMENTATION.
However I don't think we do really want to do this because, handy as it
would be to have better documentation, I fear that this would push our
version 2 out sometime into the 22nd Century....
[I'd be OK with adding some markup processor as long as it had no, zip,
zero, emptyset of dependencies and someone else did the work....]
cheers,
r
More information about the asdf-devel
mailing list