[asdf-devel] [PATCH] add &allow-other-keys to LOAD-SYSTEM, COMPILE-SYSTEM, TEST-SYSTEM

[Robert Goldman]

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