[asdf-devel] [PATCH] add &allow-other-keys to LOAD-SYSTEM, COMPILE-SYSTEM, TEST-SYSTEM

[james anderson]

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