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