Although the way to extend operations by additional initargs is somewhat cumbersome, it's possible. Unfortunately, the sugar forms LOAD-SYSTEM, COMPILE-SYSTEM, and TEST-SYSTEM do not take additional initargs.
-T.
diff --git a/asdf.lisp b/asdf.lisp index 92e7f6e..3f230d5 100644 --- a/asdf.lisp +++ b/asdf.lisp @@ -1670,18 +1670,24 @@ created with the same initargs as the original one. (setf (documentation 'operate 'function) operate-docstring))
-(defun load-system (system &rest args &key force (verbose t) version) - "Shorthand for `(operate 'asdf:load-op system)`. See [operate][] for details." +(defun load-system (system &rest args &key force (verbose t) version + &allow-other-keys) + "Shorthand for `(operate 'asdf:load-op system)`. See [operate][] for +details." (declare (ignore force verbose version)) (apply #'operate 'load-op system args))
-(defun compile-system (system &rest args &key force (verbose t) version) - "Shorthand for `(operate 'asdf:compile-op system)`. See [operate][] for details." +(defun compile-system (system &rest args &key force (verbose t) version + &allow-other-keys) + "Shorthand for `(operate 'asdf:compile-op system)`. See [operate][] +for details." (declare (ignore force verbose version)) (apply #'operate 'compile-op system args))
-(defun test-system (system &rest args &key force (verbose t) version) - "Shorthand for `(operate 'asdf:test-op system)`. See [operate][] for details." +(defun test-system (system &rest args &key force (verbose t) version + &allow-other-keys) + "Shorthand for `(operate 'asdf:test-op system)`. See [operate][] for +details." (declare (ignore force verbose version)) (apply #'operate 'test-op system args))
On 2/24/10 Feb 24 -5:54 AM, Tobias C. Rittweiler wrote:
Although the way to extend operations by additional initargs is somewhat cumbersome, it's possible. Unfortunately, the sugar forms LOAD-SYSTEM, COMPILE-SYSTEM, and TEST-SYSTEM do not take additional initargs.
I see that the docstrings for these functions seem to have some form of markup in them that I do not recognize ( [operate][] ). Can you comment on this?
best, r
-T.
diff --git a/asdf.lisp b/asdf.lisp index 92e7f6e..3f230d5 100644 --- a/asdf.lisp +++ b/asdf.lisp @@ -1670,18 +1670,24 @@ created with the same initargs as the original one. (setf (documentation 'operate 'function) operate-docstring))
-(defun load-system (system &rest args &key force (verbose t) version)
- "Shorthand for `(operate 'asdf:load-op system)`. See [operate][] for details."
+(defun load-system (system &rest args &key force (verbose t) version
&allow-other-keys)- "Shorthand for `(operate 'asdf:load-op system)`. See [operate][] for
+details." (declare (ignore force verbose version)) (apply #'operate 'load-op system args))
-(defun compile-system (system &rest args &key force (verbose t) version)
- "Shorthand for `(operate 'asdf:compile-op system)`. See [operate][] for details."
+(defun compile-system (system &rest args &key force (verbose t) version
&allow-other-keys)- "Shorthand for `(operate 'asdf:compile-op system)`. See [operate][]
+for details." (declare (ignore force verbose version)) (apply #'operate 'compile-op system args))
-(defun test-system (system &rest args &key force (verbose t) version)
- "Shorthand for `(operate 'asdf:test-op system)`. See [operate][] for details."
+(defun test-system (system &rest args &key force (verbose t) version
&allow-other-keys)- "Shorthand for `(operate 'asdf:test-op system)`. See [operate][] for
+details." (declare (ignore force verbose version)) (apply #'operate 'test-op system args))
asdf-devel mailing list asdf-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel
Robert Goldman writes:
On 2/24/10 Feb 24 -5:54 AM, Tobias C. Rittweiler wrote:
Although the way to extend operations by additional initargs is somewhat cumbersome, it's possible. Unfortunately, the sugar forms LOAD-SYSTEM, COMPILE-SYSTEM, and TEST-SYSTEM do not take additional initargs.
I see that the docstrings for these functions seem to have some form of markup in them that I do not recognize ( [operate][] ). Can you comment on this?
No it's what was in there.
-T.
On 2/24/10 Feb 24 -9:00 AM, Tobias C. Rittweiler wrote:
Robert Goldman writes:
On 2/24/10 Feb 24 -5:54 AM, Tobias C. Rittweiler wrote:
Although the way to extend operations by additional initargs is somewhat cumbersome, it's possible. Unfortunately, the sugar forms LOAD-SYSTEM, COMPILE-SYSTEM, and TEST-SYSTEM do not take additional initargs.
I see that the docstrings for these functions seem to have some form of markup in them that I do not recognize ( [operate][] ). Can you comment on this?
No it's what was in there.
Hm. Possibly it's some creeping Markdownization. At any rate, unless we're going to adopt some docstring markup scheme for ASDF, which I don't favor (ASDF should not have external dependencies), we should replace all the "( [operate][] )" strings with simply "OPERATE".
I have mixed feelings about &allow-other-keys. In general, I hate it, because it makes the code no longer self-documenting. Anyone's guess how to call the function.
So here's a question for you, should we:
1. Add &allow-other-keys for these wrapper functions or
2. Figure that if you are supplying arbitrary keywords, the safety belts are off and you should be forced to use OPERATE or OOS.
I'm OK with either.
best, r
Robert Goldman rpgoldman@sift.info writes:
On 2/24/10 Feb 24 -9:00 AM, Tobias C. Rittweiler wrote:
Robert Goldman writes:
On 2/24/10 Feb 24 -5:54 AM, Tobias C. Rittweiler wrote:
Although the way to extend operations by additional initargs is somewhat cumbersome, it's possible. Unfortunately, the sugar forms LOAD-SYSTEM, COMPILE-SYSTEM, and TEST-SYSTEM do not take additional initargs.
I see that the docstrings for these functions seem to have some form of markup in them that I do not recognize ( [operate][] ). Can you comment on this?
No it's what was in there.
Hm. Possibly it's some creeping Markdownization. At any rate, unless we're going to adopt some docstring markup scheme for ASDF, which I don't favor (ASDF should not have external dependencies), we should replace all the "( [operate][] )" strings with simply "OPERATE".
I have mixed feelings about &allow-other-keys. In general, I hate it, because it makes the code no longer self-documenting. Anyone's guess how to call the function.
I plan to add necessary magic to slime so valid keywords will be shown in the minibuffer as part of arglist display.
So here's a question for you, should we:
Add &allow-other-keys for these wrapper functions or
Figure that if you are supplying arbitrary keywords, the safety
belts are off and you should be forced to use OPERATE or OOS.
I'm OK with either.
Actually, &allow-other-keys would not be necessary if these weren't normal functions but generic functions. Then methods can add valid keywords. And there's a programmatic protocol to get at all valid keywords.
I'd favor that approach.
-T.
On 2/24/10 Feb 24 -9:22 AM, Tobias C. Rittweiler wrote:
Robert Goldman rpgoldman@sift.info writes:
Actually, &allow-other-keys would not be necessary if these weren't normal functions but generic functions. Then methods can add valid keywords. And there's a programmatic protocol to get at all valid keywords.
[THESE == load-system, etc.]
I'd favor that approach.
I don't see how generic functions would help here, since typically we are going to be calling these functions on strings or on symbols, not on system objects.
Best, r
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.
?
On 2010-02-24, at 15:02 , Robert Goldman wrote:
On 2/24/10 Feb 24 -5:54 AM, Tobias C. Rittweiler wrote:
Although the way to extend operations by additional initargs is somewhat cumbersome, it's possible. Unfortunately, the sugar forms LOAD- SYSTEM, COMPILE-SYSTEM, and TEST-SYSTEM do not take additional initargs.
I see that the docstrings for these functions seem to have some form of markup in them that I do not recognize ( [operate][] ). Can you comment on this?
best, r
-T.
diff --git a/asdf.lisp b/asdf.lisp index 92e7f6e..3f230d5 100644 --- a/asdf.lisp +++ b/asdf.lisp @@ -1670,18 +1670,24 @@ created with the same initargs as the original one. (setf (documentation 'operate 'function) operate-docstring))
-(defun load-system (system &rest args &key force (verbose t) version)
- "Shorthand for `(operate 'asdf:load-op system)`. See [operate]
[] for details." +(defun load-system (system &rest args &key force (verbose t) version
&allow-other-keys)- "Shorthand for `(operate 'asdf:load-op system)`. See [operate]
[] for +details." (declare (ignore force verbose version)) (apply #'operate 'load-op system args))
-(defun compile-system (system &rest args &key force (verbose t) version)
- "Shorthand for `(operate 'asdf:compile-op system)`. See
[operate][] for details." +(defun compile-system (system &rest args &key force (verbose t) version
&allow-other-keys)- "Shorthand for `(operate 'asdf:compile-op system)`. See
[operate][] +for details." (declare (ignore force verbose version)) (apply #'operate 'compile-op system args))
-(defun test-system (system &rest args &key force (verbose t) version)
- "Shorthand for `(operate 'asdf:test-op system)`. See [operate]
[] for details." +(defun test-system (system &rest args &key force (verbose t) version
&allow-other-keys)- "Shorthand for `(operate 'asdf:test-op system)`. See [operate]
[] for +details." (declare (ignore force verbose version)) (apply #'operate 'test-op system args))
asdf-devel mailing list asdf-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel
asdf-devel mailing list asdf-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel
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
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.
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
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
-
james anderson -
Robert Goldman -
Tobias C. Rittweiler