On 2/24/10 Feb 24 -9:35 AM, james anderson wrote: > > On 2010-02-24, at 16:19 , Robert Goldman wrote: > >> 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? > > i do follow your argument, but i do not agree with your conclusion. > yes, the the reference is not context free. > no, i suggest, given a coherent context, one does not have to solve > the halting problem to make a reasonable quess. > yes, "see also" does not add anything to the nature of a found binding. > on the other hand, meta-. is mostly satisfactory - even with no > context at all. > and then, there is always the possibility to mediate through an index.
Sorry, we were talking at cross-purposes. In docstrings, typically the purpose of adding markup has been to support (at least partially) automatic generation of something like a manual or web page from the docstrings. I agree --- if we are just going to be using these through the DOCUMENTATION function (and in the context of something like SLIME), then there is no need for markup. We only need markup for manual generation. E.g., if we were autogenerating HTML pages from these docstrings, we wouldn't have Meta-. to rely on, and we'd need hints for cross-reference. Similarly, since HTML isn't ASCII, we'd typically want markup for, e.g., code examples, names of parameters, etc. cheers, r _______________________________________________ asdf-devel mailing list asdf-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel
