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 _______________________________________________ asdf-devel mailing list asdf-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel