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