--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4L%2Bh1JN7kdi45z_ULgcFwe0VorPUEQosvQqGvLX-nBBwFQ%40mail.gmail.com.
Are they supposed to be associated to objects at runtime or only at expand time? Or will they have no special meaning to the Scheme expander und runtime system but interpreted by a different tool as it is done with Scribble? What is the advantage of doc strings versus Scribble and vice versa?
How to associate doc strings to non-procedure definitions?
How to syntax definitions? Do they work well with case-lambda? Shall doc strings only be associated to top-level definitions or to individual objects?
Scribble and some other documentation systems have some TeX-like markup language that allows to generate rich documentation and to extract meta-information. How are doc strings positioned in this regard?
On Sun, Apr 5, 2020 at 12:34 AM Marc Nieper-Wißkirchen <marc....@gmail.com> wrote:Are they supposed to be associated to objects at runtime or only at expand time? Or will they have no special meaning to the Scheme expander und runtime system but interpreted by a different tool as it is done with Scribble? What is the advantage of doc strings versus Scribble and vice versa?Ideally, they would be associated with objects at runtime. That doesn't mean that they would have to be kept in memory; only that some key for retrieving them would be present. Ideally, a simple API could retrieve a doc string from any object that was defined with one.Sorry, I don't yet know anything about Scribble. I'll try to read up on it.
How to associate doc strings to non-procedure definitions?I've seen systems that have a comment form that can be wrapped around any definition, attaching a string to the binding.
How to syntax definitions? Do they work well with case-lambda? Shall doc strings only be associated to top-level definitions or to individual objects?Scribble and some other documentation systems have some TeX-like markup language that allows to generate rich documentation and to extract meta-information. How are doc strings positioned in this regard?There's no reason that doc strings couldn't use markup as well, e.g. Markdown, but I'd be okay if that were left unspecified.I would just like some simple way to attach a runtime-accessible string to each definition so that the REPL and other interactive tools can display it when requested.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4L%2BTRwdc4mgB1_tBNcuYga04AcK2ouj1T9bAn4edZSGojQ%40mail.gmail.com.
They are available at runtime.
To preserve Scheme-semantics,
(define (foo) "not-a-docstring")
has the return value "not-a-docstring", but no docstring.
In addition, procedures can have properties which can be used to
implement more natural doctests than for example seen in Python:
https://hg.sr.ht/~arnebab/wisp/browse/33b4fcdd8a17aa19d57971e4f6db5fcb7758843c/examples/doctests.scm#L10
Their advantage over Python-doctests is that test and implementation are
uniform: The test uses regular s-exp syntax instead of being
string-parsed as it is done in Python (with all the quoting hassles
string-parsing brings).
Best wishes,
Arne
--
Unpolitisch sein
heißt politisch sein
ohne es zu merken
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/87d08ms24z.fsf%40web.de.
On Sun, Apr 5, 2020 at 12:45 AM Arthur A. Gleckler <a...@speechcode.com> wrote:
Sorry, I don't yet know anything about Scribble. I'll try to read up on it.
Okay, I found 4.5 In-Source Documentation and the In-Source Documentation section of Submodules. The latter gives examples. It is geared to support Racket's contract system, but it does provide a way to add documentation strings accessible at runtime, although in forms separate from the defining forms.
I still prefer documentation strings a la Common Lisp and Emacs Lisp and the example I gave. They're right inside the defining form, which means that the identifier doesn't have to be repeated, and they're less verbose.
It should be easy to add them to lambda
, case-lambda
, define-syntax
, etc. without affecting existing code. Just off the top of my head:
(define section-element
(let ((associate (association-procedure string=? car)))
(lambda (section element-name)
"Return element named `element-name' from `section'."
(let ((association (associate element-name section)))
(and association
(cdr association))))))
(define convui-regexp
(case-lambda
"Match regular expression `pattern', obeying `case-fold?' (default #f), and
use optional `lift' to lift the result."
((pattern) (convui-regexp pattern #f))
((pattern case-fold?)
(convui-regexp pattern case-fold? (lambda (r s) (re-match-extract s r 0))))
((pattern case-fold? lift)
...)))
(define-syntax assert
(syntax-rules ()
"Return the symbol `passed' when the test passes. The unit test
framework..."
((_ (operator argument ...))
...)
((_ (operator argument ...) error-values ...)
...)
((_ expression)
...)
((_ expression error-values ...)
...)))
And for defining forms that haven't been modified to accept documentation strings, e.g. when making a top-level binding to a list, a comment
form like this might work:
or even:
The goals I'd like to achieve:
On Sun, Apr 5, 2020 at 12:45 AM Arthur A. Gleckler <a...@speechcode.com> wrote:
Sorry, I don't yet know anything about Scribble. I'll try to read up on it.
Okay, I found 4.5 In-Source Documentation and the In-Source Documentation section of Submodules. The latter gives examples. It is geared to support Racket's contract system, but it does provide a way to add documentation strings accessible at runtime, although in forms separate from the defining forms.
I still prefer documentation strings a la Common Lisp and Emacs Lisp and the example I gave. They're right inside the defining form, which means that the identifier doesn't have to be repeated, and they're less verbose.
It should be easy to add them to
lambda
,case-lambda
,define-syntax
, etc. without affecting existing code. Just off the top of my head:(define section-element (let ((associate (association-procedure string=? car))) (lambda (section element-name) "Return element named `element-name' from `section'." (let ((association (associate element-name section))) (and association (cdr association)))))) (define convui-regexp (case-lambda "Match regular expression `pattern', obeying `case-fold?' (default #f), and use optional `lift' to lift the result." ((pattern) (convui-regexp pattern #f)) ((pattern case-fold?) (convui-regexp pattern case-fold? (lambda (r s) (re-match-extract s r 0)))) ((pattern case-fold? lift) ...)))
And for defining forms that haven't been modified to accept documentation strings, e.g. when making a top-level binding to a list, a
comment
form like this might work:or even:
The goals I'd like to achieve:
- documentation strings accessible at runtime, e.g. through the REPL or editor tools
- terse definitions
- existing code runs unchanged
Thanks for considering the idea.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4L%2BGAnggE6g8tkH-FJSak0rOuXnm7vyLBQ%2BCCjLU0mdT1g%40mail.gmail.com.
For case-lambda, this would break code that does not understand documentation strings.
The latter form allows "comment" to be implemented as a macro; the former version doesn't. Thus, the latter form is preferable.
A new "define" syntax with three arguments could also be defined.
Am So., 5. Apr. 2020 um 21:44 Uhr schrieb Arthur A. Gleckler <a...@speechcode.com>:On Sun, Apr 5, 2020 at 12:45 AM Arthur A. Gleckler <a...@speechcode.com> wrote:
Sorry, I don't yet know anything about Scribble. I'll try to read up on it.
Okay, I found 4.5 In-Source Documentation and the In-Source Documentation section of Submodules. The latter gives examples. It is geared to support Racket's contract system, but it does provide a way to add documentation strings accessible at runtime, although in forms separate from the defining forms.
One advantage of Racket's model is that it is extensible with Scheme code and that it is expanded and run at different phases than the library itself is expanded and run.Maybe Alex Shinn can explain Chibi's version of Scribble, which is also used to generate package documentation for snow-fort.org.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/AC4965A2-04B8-485E-AEEA-4A08394A5219%40ephemeral.net.
If I understand this correctly, this only is relevant for code with docstrings as part of a library. Not all documented code is necessarily part of a library, I think.
This appears to me, on the surface, as a very complex way to get around fairly simple reader syntax or a lightweight macro or lambda properties solution... I do not see the need for so much extra gunk. (One of my objections to R6 at the time.)
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/11E17341-A8CC-4B5E-8A7C-C67F2A33A026%40ephemeral.net.
elf <e...@ephemeral.net> writes:
> How, then, does one distinguish between a docstring and a string return value? This gets especially hairy if one allows multiline docstrings.
What Guile does: if the string is the only part of the body, then there
is no docstring: it is not a docstring but a return value.
> Anything that I can think of to solve these involves making any reader system so much more complicated as to negate any benefit. Please tell me if I'm wrong here, of course.
The above ensures that a string is only a docstring if using it as a
docstring has no side-effect.
Parsing a docstring is the same as parsing any other string.
It is already allowed in r7rs to have a string as first expression in
the body, so nothing changes in the syntax (different from the
comment-version where there’s new syntax that’s hidden in comments).
What changes is that if the first form in define is a string, and it is
not the last form, then this string becomes the docstring.
The long form is
(set-procedure-property! fun 'documentation "the docstring")
But since there is obviously no consensus about this (strong preferences
both ways), first creating SRFIs might be a better way forward.
Best wishes,
Arne
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/87k12srajc.fsf%40web.de.
Arne Babenhauserheide <arne...@web.de> writes:
> elf <e...@ephemeral.net> writes:
>> How, then, does one distinguish between a docstring and a string return value? This gets especially hairy if one allows multiline docstrings.
>
> What Guile does: if the string is the only part of the body, then there
> is no docstring: it is not a docstring but a return value.
Addition: Parsing comments is harder than this: Any comment parser must
include a full string-parser, because it must distinguish between
comments and multiline-strings. Example:
"foo \\\"
;;> foo "
(define (foo) #f)
>> Anything that I can think of to solve these involves making any reader system so much more complicated as to negate any benefit. Please tell me if I'm wrong here, of course.
>
> The above ensures that a string is only a docstring if using it as a
> docstring has no side-effect.
Addition: I do not know a clean way to document objects that are defined
in a way which does not allow empty expressions.
(define foo "doc" #f) ;; <- syntax error.
(define (foo) "doc" #f) ;; <- valid and nice.
Best wishes,
Arne
--
Unpolitisch sein
heißt politisch sein
ohne es zu merken
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/87imicr96t.fsf%40web.de.
Marc Nieper-Wißkirchen <marc....@gmail.com> writes:
> Am Mo., 6. Apr. 2020 um 15:47 Uhr schrieb Arne Babenhauserheide <
> A string as the first expression is not allowed if you want to have
> internal definitions in the body.
Ah, you’re right. This is a limitation Guile just lifted in 3.0. It was
one of the most jarring things when I learned Scheme.
>> What changes is that if the first form in define is a string, and it is
>> not the last form, then this string becomes the docstring.
>>
>> The long form is
>> (set-procedure-property! fun 'documentation "the docstring")
>>
>> But since there is obviously no consensus about this (strong preferences
>> both ways), first creating SRFIs might be a better way forward.
>>
>
> Isn't it more effective to seek consensus first? Otherwise, we have several
> competing SRFIs and still have no consensus.
Can we reach consensus when there are such strong opinions?
If we can, you’re right.
> At least, we can try to agree on the technical advantages and disadvantages
> and make up our minds accordingly.
That sounds good.
Best wishes,
Arne
--
Unpolitisch sein
heißt politisch sein
ohne es zu merken
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/87ftdgr1ai.fsf%40web.de.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/87pncj2em0.fsf%40web.de.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/87ftdf2axo.fsf%40web.de.
On Tue, Apr 7, 2020 at 11:01 AM Marc Nieper-Wißkirchen <marc....@gmail.com> wrote:
Before we think of any syntax, we should answer the following questions:
(1) Is it enough to document top-level definitions or do we want to be able to attach documentation to any value?
Ideally, I'd like to be able to document all definitions, regardless of level.
I'd also like to be able to document values like procedures and syntax transformers independent of whether they have bindings or where they are bound. It's easy to add an optional slot to both that can hold a documentation string or a key that can be used to fetch one at runtime. For other types, keeping a hash table from values to documentation strings would not be expensive.
(2) Should we make sure that there is absolutely no runtime overhead when documentation is added?
"Absolutely no overhead" is extreme. There are ways to minimize the overhead.
(3) Do we just want to document procedures or any value?
All bindings as well as the values of procedures and syntax transformers.
(4) Do we want to be able to document syntactic keywords?
Yes.
(5) How is the documentation related to the library system?
Unrelated.
(6) Do we want structured documentation or just plain strings?
I'd rather not impose a specific syntax on everyone, but it would be nice to allow implementations to support it. Perhaps reader syntax like the following might work, for example to indicate the use of Markdown markup:
I'm not advocating this specific reader syntax, but just the idea that a string could be labeled concisely to identify what syntax was being used. Alternatively:
(define (factorial n)
(documentation md "Return the factorial of `n`, which must be a nonnegative
integer.") …)
In this example, the language would have to treat documentation
specially in defining forms in addition to or instead of bare strings.
(7) Shall the documentation follow the code-is-data principle of Scheme?
Absolutely. I would like to avoid magic comments, for example.
(8) …
On Tue, Apr 7, 2020 at 2:55 PM John Cowan <co...@ccil.org> wrote:
Should we be able to document:
Objects?
Yes.
Variables? Global only?
Yes. Once the mechanism is in place, there doesn't seem to be a reason to restrict it to top-level definitions.
Variables bound to procedures? Global only?
Yes. No.
Macros? Global only?
Yes. No.
Record types? Global only?
Good idea, and yes. No.
Variables? Global only?
Yes. Once the mechanism is in place, there doesn't seem to be a reason to restrict it to top-level definitions.
Ah, that leads to another question: Let-bindings, or just definitions?
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4LKC2mHCo8P93wC%2BOCsY%2B%2B7qMTJ5bDhJ%3Dr8AuAe0xTCe9g%40mail.gmail.com.
On Tue, Apr 7, 2020 at 7:06 PM Arthur A. Gleckler <a...@speechcode.com> wrote:
I don't see a way to make adding doc strings to let bindings unobtrusive — except bindings of procedures, where there's a natural place to put the documentation string.That would be a documentation of the object rather than the variable; those ideas are disjoint, and you could have both.
On Tue, Apr 7, 2020 at 7:06 PM Arthur A. Gleckler <a...@speechcode.com> wrote:On Tue, Apr 7, 2020 at 3:58 PM John Cowan <co...@ccil.org> wrote:Ah, that leads to another question: Let-bindings, or just definitions?I don't see a way to make adding doc strings to let bindings unobtrusive — except bindings of procedures, where there's a natural place to put the documentation string.That would be a documentation of the object rather than the variable; those ideas are disjoint, and you could have both.
----
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4LKC2mHCo8P93wC%2BOCsY%2B%2B7qMTJ5bDhJ%3Dr8AuAe0xTCe9g%40mail.gmail.com.
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CAD2gp_S0_syyiavNW7PnLKc0XXEErBH56-_MwPvWs8cxT1T30A%40mail.gmail.com.
(1) Documentation cannot be easily attached to non-structured values. It has been suggested to use a weak hash-table, whose equality predicate would most likely be `eq?' or `eqv?'. But what would happen if we documented SRFI 143 with its `fx-width' value, which may in some implementation be 24. We do not want attach documentation to the number 24.
(2) In Scheme, a procedure object is in fact a closure. Usually, we don't want to attach the documentation to the closure but to the underlying `lambda', which doesn't appear as a value, though.
(3) While documentation attached to values is easy to use at the REPL, code has to be run to get access to the values. In general, I am thinking of an intelligent IDE, we don't want code to be run before we retrieve documentation (and other meta-information).
On Wed, Apr 8, 2020 at 5:20 AM Marc Nieper-Wißkirchen <marc....@gmail.com> wrote:(1) Documentation cannot be easily attached to non-structured values. It has been suggested to use a weak hash-table, whose equality predicate would most likely be `eq?' or `eqv?'. But what would happen if we documented SRFI 143 with its `fx-width' value, which may in some implementation be 24. We do not want attach documentation to the number 24.That's why you want to be able to attach documentation to variables as well as values. While the implementation of documentation for bindings and for values is orthogonal, they are conceptually strongly related, which is why it's good to discuss them both at the same time.
(2) In Scheme, a procedure object is in fact a closure. Usually, we don't want to attach the documentation to the closure but to the underlying `lambda', which doesn't appear as a value, though.I disagree. I want the documentation to be attached to the closure itself so that my IDE and REPL can ask for the documentation no matter what variable or data structure it is found in.
(3) While documentation attached to values is easy to use at the REPL, code has to be run to get access to the values. In general, I am thinking of an intelligent IDE, we don't want code to be run before we retrieve documentation (and other meta-information).Actually, I've always thought that the runtime heap is the ultimate data structure for keeping meta-information, and that all the approximations that modern editors do with regular expressions, elaborate partial parsing systems, etc. are inferior to read — or to a version of read that records line numbers, source file pathnames, etc. One of the wonderful things about Scheme is that I can load code even when it is unfinished, e.g. even when some variables are unbound and the code doesn't type check. I can do experiments, run parts of the code, find out what identifiers there are, etc. I would like to add the ability to extract documentation strings to that list of capabilities.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4LKxtBgTJdVxH5mb5az6KDmvbej%3DDG0xDNfNPwnnyFY0oQ%40mail.gmail.com.
If i may add my (probably unwanted at this point) 2c...
there seems to me to be a worrisome trend towards overdefinition in many of the proposals and srfis as of late. This may be a misperception on my part; I have not been as active as i used to be. That said, my understanding of the concept of scheme (and one of the things that makes it so fun to work with and play with and implement and .... etc) is that there's an inherent simplicity, and much of the expressiveness and power stems from the freedom that simplicity brings. A simple system, requiring as few changes as possible, that will serve the purpose of internal run-time documentation, seems to me to be far superior to any over-engineered behemoth that requires changes to every part of the repl and compiler. Making something _extremely_ simple and then seeing how (or if) it evolves in community-useful ways may be a better path than trying to find all the ways that all of us could ever theoretically want to use it ... and it will be less limiting to the next generation who may come up with things that we never thought of.
I am not saying that a complex system is necessary bad or a simple one is necessarily good, just that it might be a good idea to follow a route that requires the least amount of future correction if it turns out not to be what we had hoped.
(I will be unavailable for the next few days due to Passover, so I'm sorry in advance for putting this point out at this time. I will try to catch up on the discussion on Saturday night my time. Only mentioning so you're all free to flame or disagree and not be worried that I got offended and left in a huff. :) )
-elf
>
> Best wishes,
> Arne
> --
> Unpolitisch sein
> heißt politisch sein
> ohne es zu merken
>
> --
> You received this message because you are subscribed to the Google Groups
> "scheme-reports-wg2" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to scheme-reports-...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/scheme-reports-wg2/87ftdgr1ai.fsf%40web.de
> .
>
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CAEYrNrRZ0%3D8teAG%2BN3Xz7Hm3qyzNGzmsK8imWhGiS7ruemapkQ%40mail.gmail.com.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/248001BA-3066-453B-8747-33A65E5F2A7D%40ephemeral.net.
While both are about documentation, I am not sure how much the concepts are related. In any case, it would be good if whatever solution we find for either concept it does not step on the toes of the other.
Through the closure value, the Scheme system could access the lambda form and thus any documentation attached to the code. Or do you really want to have different documentation on different closures of the same procedure?
The Racket editor's understanding of the source is very elaborate, I think. It doesn't have to run the code, though. While at the REPL, this may be true, I don't think that you always want to run code to retrieve documentation. Running general code has usually side effects. Moreover, one run may differ from the next one. We should also note that there are Scheme systems that are not REPL-centered but use the usual compile-and-run cycle.
On Wed, Apr 8, 2020 at 11:40 PM Marc Nieper-Wißkirchen <marc....@gmail.com> wrote:While both are about documentation, I am not sure how much the concepts are related. In any case, it would be good if whatever solution we find for either concept it does not step on the toes of the other.The unifying concept is making documentation available at runtime.
I agree about not stepping on toes.This reminds me of debugging code. Sometimes, you want to set a breakpoint whenever a particular closure is invoked. Other times, you want to set a breakpoint whenever any closure bound to a specific variable is invoked. At the implementation level, they're different concepts, but the user is trying to achieve just one thing: making sure that the debugger is invoked in the precisely correct place.
Through the closure value, the Scheme system could access the lambda form and thus any documentation attached to the code. Or do you really want to have different documentation on different closures of the same procedure?Sorry, I misunderstood what you meant. I'm thinking of an optional slot in each closure that points to the documentation in the same way that the closure points to its code. All closures of the same lambda normally point to the same code object. But maybe it would be better not to include a slot, and to use a weak hash table to map the code objects that are already present to the documentation string. But that's an implementation detail.
The Racket editor's understanding of the source is very elaborate, I think. It doesn't have to run the code, though. While at the REPL, this may be true, I don't think that you always want to run code to retrieve documentation. Running general code has usually side effects. Moreover, one run may differ from the next one. We should also note that there are Scheme systems that are not REPL-centered but use the usual compile-and-run cycle.Those Scheme systems might store the documentation strings in their binaries, if desired.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4LJXZ9jJc1CQfSLgi%3D1e6FuSff%3DgGw17ysb_jdp%2BKxYPKQ%40mail.gmail.com.
The unifying concept is making documentation available at runtime.I don't think that this is common to both concepts. Values exist at runtime, but bindings do not. Note that a compiler may remove and create any binding while processing Scheme code as long as the resulting code is correct.
This reminds me of debugging code. Sometimes, you want to set a breakpoint whenever a particular closure is invoked. Other times, you want to set a breakpoint whenever any closure bound to a specific variable is invoked. At the implementation level, they're different concepts, but the user is trying to achieve just one thing: making sure that the debugger is invoked in the precisely correct place.I'm trying to wrap my head around whether there are really two different concepts invoked in your example. Could you give some example code and describe the two debugging cases with this code?
In this example, it would be sufficient to set a breakpoint with reference to either the variable factorial
or the value that it holds:
On the other hand, if I'm debugging find-in-first-ten
below, I'd like to set the breakpoint with reference to the variable predicate
, not to the procedure, odd?
, to which it is bound:
Sorry, I misunderstood what you meant. I'm thinking of an optional slot in each closure that points to the documentation in the same way that the closure points to its code. All closures of the same lambda normally point to the same code object. But maybe it would be better not to include a slot, and to use a weak hash table to map the code objects that are already present to the documentation string. But that's an implementation detail.How can this concept of attaching information to runtime values *uniformly* extended to other runtime values?
On Thu, Apr 9, 2020 at 9:06 AM Marc Nieper-Wißkirchen <marc....@gmail.com> wrote:The unifying concept is making documentation available at runtime.I don't think that this is common to both concepts. Values exist at runtime, but bindings do not. Note that a compiler may remove and create any binding while processing Scheme code as long as the resulting code is correct.In any context in which someone can refer to a variable by name, the system should be able to retrieve documentation on that variable.Frankly, however, I'm most interested in a proposal that covers bindings of variables to procedures and syntax, where a mapping between the values and the documentation is what is maintained. I'd be happy to forego anything else in the short term following the Pareto principle.This reminds me of debugging code. Sometimes, you want to set a breakpoint whenever a particular closure is invoked. Other times, you want to set a breakpoint whenever any closure bound to a specific variable is invoked. At the implementation level, they're different concepts, but the user is trying to achieve just one thing: making sure that the debugger is invoked in the precisely correct place.I'm trying to wrap my head around whether there are really two different concepts invoked in your example. Could you give some example code and describe the two debugging cases with this code?In this example, it would be sufficient to set a breakpoint with reference to either the variable
factorial
or the value that it holds:On the other hand, if I'm debugging
find-in-first-ten
below, I'd like to set the breakpoint with reference to the variablepredicate
, not to the procedure,odd?
, to which it is bound:
Sorry, I misunderstood what you meant. I'm thinking of an optional slot in each closure that points to the documentation in the same way that the closure points to its code. All closures of the same lambda normally point to the same code object. But maybe it would be better not to include a slot, and to use a weak hash table to map the code objects that are already present to the documentation string. But that's an implementation detail.How can this concept of attaching information to runtime values *uniformly* extended to other runtime values?Doesn't a weak hash table solve that problem?
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4LKe03%2BvtOQ%2BQ-5vL%3DPyc5jQENocabYvE7eUUHoTN2iM%3Dw%40mail.gmail.com.
Thanks for the example. So in both cases, the breakpoints can be associated with the variables (vs with the values) and you get what you want.But what is an example where you really need to associate the breakpoint with a value?
Here, if I'm debugging log
, I want to set a breakpoint on it regardless of what name it's invoked through:
How can this concept of attaching information to runtime values *uniformly* extended to other runtime values?Doesn't a weak hash table solve that problem?No, not uniformly for arbitrary values. A weak hash-table would associate the documentation to an individual closure, not to the underlying code.
On Fri, Apr 10, 2020 at 1:39 AM Marc Nieper-Wißkirchen <marc....@gmail.com> wrote:Thanks for the example. So in both cases, the breakpoints can be associated with the variables (vs with the values) and you get what you want.But what is an example where you really need to associate the breakpoint with a value?Here, if I'm debugging
log
, I want to set a breakpoint on it regardless of what name it's invoked through:
How can this concept of attaching information to runtime values *uniformly* extended to other runtime values?Doesn't a weak hash table solve that problem?No, not uniformly for arbitrary values. A weak hash-table would associate the documentation to an individual closure, not to the underlying code.That's why you need both concepts.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4LLjv6v1MTp-zw%2BbwpEZwb5BNeM-tBdeaBCGUAGnrcO9qw%40mail.gmail.com.
Here, I would associate the breakpoint with the binding of `log'. Of course, we would have to say what this actually means. It would mean that, say, `(define (log parameters) ...` is expanded to `(define log (debugger-maybe-break-here (lambda (parameters) ...)))'
It has to happen at expand/compile time because bindings are no runtime concept (except for bindings at the REPL).
That would raise the concept count to three: documentation associated with values (distinguished by eq? or eqv?), documentation associated with bindings, and documentation associated with particular runtime values (procedures).
> In any context in which someone can refer to a variable by name, the system
> should be able to retrieve documentation on that variable.
How does this work for this?
(define (foo) "doc" #t)
(define bar foo)
I would expect
(procedure-documentation bar)
to retrieve the documentation of foo ("doc").
On Fri, Apr 10, 2020 at 8:39 AM Marc Nieper-Wißkirchen <marc....@gmail.com> wrote:Here, I would associate the breakpoint with the binding of `log'. Of course, we would have to say what this actually means. It would mean that, say, `(define (log parameters) ...` is expanded to `(define log (debugger-maybe-break-here (lambda (parameters) ...)))'I don't see how that's different than associating the breakpoint with the procedure value itself.It has to happen at expand/compile time because bindings are no runtime concept (except for bindings at the REPL).That means that you have to re-expand/compile the code in order to set a breakpoint. That's a common approach, but makes for a much less pleasant debugging experience than using debuggers in other languages, even C.
That would raise the concept count to three: documentation associated with values (distinguished by eq? or eqv?), documentation associated with bindings, and documentation associated with particular runtime values (procedures).I feel like we're going around in circles.I'll say again that I'd be happy with just the ability to associate documentation with procedures and syntax transformers. That's all I was thinking when I started this thread. Other folks asked about associating documentation with bindings or with arbitrary objects, and that would be nice, but I'd like to start with a simple, straightforward proposal.Unfortunately, as SRFI editor, I don't feel comfortable submitting SRFIs myself. It seems like a conflict of interest, especially if I'm the lead author as opposed to just a contributor. But if someone else finds this basic idea useful, I would love to see a proposal.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4LKzW7yNReV%2BMP_3H0ky3ULSu0C4CO66R%2B6axUgBxbtykA%40mail.gmail.com.
Arthur A. Gleckler <a...@speechcode.com> writes:
>> I don't think that this is common to both concepts. Values exist at
>> runtime, but bindings do not. Note that a compiler may remove and create
>> any binding while processing Scheme code as long as the resulting code is
>> correct.
>>
>
> In any context in which someone can refer to a variable by name, the system
> should be able to retrieve documentation on that variable.
How does this work for this?
(define (foo) "doc" #t)
(define bar foo)
I would expect
(procedure-documentation bar)
to retrieve the documentation of foo ("doc").
Best wishes,
Arne
--
Unpolitisch sein
heißt politisch sein
ohne es zu merken
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/87y2r3tfdm.fsf%40web.de.
The problem is that the compiler may have optimized away a lot of code or that log may have been inlined in the procedures so that there is not much to attach to at runtime.
I can submit a SRFI for attaching meta-information like documentation to procedures and syntax transformers, maybe after we have discussed it a bit if you like.I do think the idea to attach such information to procedures and to syntax transformers (and maybe record (types)) is useful so I am willing to help here. As I said, the only thing I do not want is to step on the toes of the orthogonal thing to attach properties to bindings.
On Fri, Apr 10, 2020 at 12:36 PM Marc Nieper-Wißkirchen <marc....@gmail.com> wrote:The problem is that the compiler may have optimized away a lot of code or that log may have been inlined in the procedures so that there is not much to attach to at runtime.A least-common-denominator debugger and runtime system will have this problem, and for that reason, it's hard to standardize debugging tools. But modern compilers for other languages like JavaScript and Smalltalk can de-optimize at runtime for the purpose of the debugger and other tools. I'd love to see that kind of capability in Scheme some day.
I can submit a SRFI for attaching meta-information like documentation to procedures and syntax transformers, maybe after we have discussed it a bit if you like.I do think the idea to attach such information to procedures and to syntax transformers (and maybe record (types)) is useful so I am willing to help here. As I said, the only thing I do not want is to step on the toes of the orthogonal thing to attach properties to bindings.That would be wonderful. Thanks.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4LJM_N35V5M7ZiuXZq4ZPmScRQ_JT%3DcSR1gyQuPPeYQ3%2BA%40mail.gmail.com.
As for the other thing, expanding and compiling Scheme code can be very fast so it is probably not that bad that code has to be recompiled when a breakpoint or some other introspection facility is added.
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/CALnw4LJyJOVz9RdFMPd82FcPwTKguT177jhdn47vhotMrkKiBw%40mail.gmail.com.
Yes, this would be a problem in running code. But without recompiling, we may miss some invocations we would like to trap because the compiler has chosen to inline the procedure at a few places. If we want to make sure that no recompilation is needed, the whole structure of the program has to be preserved. I am wondering whether this means that we have to deal with the fexpr problem (https://en.wikipedia.org/wiki/Fexpr#cite_note-Wa98p189-10) in that no source-to-source rewriting can be made at all.
Best wishes,
Arne
--
Unpolitisch sein
heißt politisch sein
ohne es zu merken
--
You received this message because you are subscribed to the Google Groups "scheme-reports-wg2" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scheme-reports-...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/scheme-reports-wg2/87y2r2bfdj.fsf%40web.de.