On 2010-02-24, at 16:42 , Robert Goldman wrote:
[...]
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.
allow me to push this another inch. to see if i can convince to deprecate cross-reference markup.
to start, is there any *manual* generation? is it unreasonable to presume that any "manual" generation process would still need access to the strings through a run-time. whether directly or indirectly. are there any documentation utilities which generate the documentation through a process of strict text transformation?
that they permit (to a large extent) to dispense with the markup is an argument in favor of systems which inspect a live image or generate the equivalent information themselves. the legibility of clear text convinced me to adopt the approach to use markdown for _text_ formatting and leave cross-references to some other mechanism. the utilities which generate [this][1] order of system description introspectively are certainly capable to emit an index and to augment markup with links when they generate documentation or provide equivalent cross-reference information to an external utility.
--- [1]: http://github.com/lisp/de.setf.utility/raw/master/dot/examples/ tsl.pdf