[racket-dev] New error messages for *SL
I just pushed a commit that updates the error messages of the teaching languages. With this update, *SL now agrees with the rules of the error message composition guidelines we sent last month. If you try the *SL languages from the git repository, you will now see that the error messages restrain themselves to a smaller vocabulary base. The sentences are now simpler, and more consistent between error messages. The error messages of check-expect, world and universe are now consistent with those of the language itself. I also updated the documentation to the new vocabulary, and cleaned their layout a bit. Here are a few examples of the changes you will see. old error messagenew error message - image: name is not defined, not a image: this variable is not defined parameter, and not a primitive name planes-direction: this selectorplanes-direction: expects 1 argument, expects 1 argument, here it is but found none provided 0 arguments define: expected a name for thedefine: expected a variable, but function's 1st argument, but found found something else something else function call: expected a defined function call: expected a function function name or a primitive after the open parenthesis, but found operation name after an open a number parenthesis, but found a number cons: second argument must be of cons: second argument must be a type , given 1list, but received 1 and 2 and 2 --- This is a somewhat large patch, and it does not limit itself to changing strings, as one might expect. I had to change a fair amount of code to get the new error messages working, notably in places where *SL leaked error messages from the professional language. So, to everyone reading this, [1]Please make sure all the code you use to teach it still works correctly. If something breaks, e-mail me and I will try to address the problem right away. [2]If you are the author of a teachpack, please update your error messages to match this new style. You can follow the error message completion guidelines, which are now in the main documentation under the "How to Design Programs Teachpacks" header. Send me e-mail if you need help. [3]There is a layout problem in my new documentation I need help with. I tried to abstract the common text between the documentation of the different levels. Possibly because I didn't do it correctly, the macro I am using confuses the layout engine, and it is now inserting lots of spurious new lines whenever there is a @defform. Look at the documentation for beginner's COND, you'll see what the problem is. As always, let us know what you think, feedback is welcome, etc. Guillaume _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
At Wed, 6 Jul 2011 05:59:30 -0400, Guillaume Marceau wrote: > [3]There is a layout problem in my new documentation I need help with. > I > tried to abstract the common text between the documentation of the > different levels. It's possible that the HtDP languages should be different in this respect than the rest of the documentation, but duplicating text during a document build is generally against our documentation style guidelines. When text is duplicated programmatically, the content has a single point of control, but readers of the documentation have to read everything multiple times. For example, the fact that ISL's `cond' is the same as BSL's `cond' is probably interesting to a reader of the documentation, but this fact now can be determined only by comparing the copied text of the two `cond' documentations. More generally, it's now more difficult to determine how the languages differ. For typical documentation, short boilerplate is ok to duplicate, such as "Strong muon fields interefere with this function's result; see section 5 for more information." Otherwise, if X is the same as Y, it's better to put literally "X is the same as Y" in the documentation and let a hyperlink do its job, instead of duplicating the description of X. In the case of the HtDP languages, was the choice to duplicate all the text deliberate, or was it a side-effect of some other change? _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Wed, Jul 6, 2011 at 9:14 AM, Matthew Flatt wrote: > In the case of the HtDP languages, was the choice to duplicate all the > text deliberate, or was it a side-effect of some other change? Yes, this was a deliberate move away from the no-duplication style used in the professional documentation, for pedagogical reasons. At each language level, I gathered in a separate section called "Common Syntax" the forms that that level has in common with the previous level. The idea is to make it possible to get a quick sense of of the commonality between the levels, while giving the students confidence that documentation page they are looking at is comprehensive. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
At Wed, 6 Jul 2011 09:36:35 -0400, Guillaume Marceau wrote: > On Wed, Jul 6, 2011 at 9:14 AM, Matthew Flatt wrote: > > In the case of the HtDP languages, was the choice to duplicate all the > > text deliberate, or was it a side-effect of some other change? > > Yes, this was a deliberate move away from the no-duplication style > used in the professional documentation, for pedagogical reasons. > > At each language level, I gathered in a separate section called > "Common Syntax" the forms that that level has in common with the > previous level. The idea is to make it possible to get a quick sense > of of the commonality between the levels, while giving the students > confidence that documentation page they are looking at is > comprehensive. Ok, I didn't pick up on that part of the organization at all. I guess "Common Syntax" sounded to me like "syntax that is commonly used", rather than "syntax that is the same as the previous level". _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Why is it pedagogical to repeat information in the ISL documentation that the BSL documentation already presented? -- Matthias On Jul 6, 2011, at 9:36 AM, Guillaume Marceau wrote: > On Wed, Jul 6, 2011 at 9:14 AM, Matthew Flatt wrote: >> In the case of the HtDP languages, was the choice to duplicate all the >> text deliberate, or was it a side-effect of some other change? > > Yes, this was a deliberate move away from the no-duplication style > used in the professional documentation, for pedagogical reasons. > > At each language level, I gathered in a separate section called > "Common Syntax" the forms that that level has in common with the > previous level. The idea is to make it possible to get a quick sense > of of the commonality between the levels, while giving the students > confidence that documentation page they are looking at is > comprehensive. > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
If you read the documentation as a textbook when you start programming, I can see wanting to see something that says "cond is the same as before". But, if you read the documentation as a reference when you have a problem it is frustrating to chase through a few links to get the "real" documentation. Is that the idea, Guillaume? Jay 2011/7/6 Matthias Felleisen : > > > Why is it pedagogical to repeat information in the > ISL documentation that the BSL documentation already > presented? > > -- Matthias > > > > > > On Jul 6, 2011, at 9:36 AM, Guillaume Marceau wrote: > >> On Wed, Jul 6, 2011 at 9:14 AM, Matthew Flatt wrote: >>> In the case of the HtDP languages, was the choice to duplicate all the >>> text deliberate, or was it a side-effect of some other change? >> >> Yes, this was a deliberate move away from the no-duplication style >> used in the professional documentation, for pedagogical reasons. >> >> At each language level, I gathered in a separate section called >> "Common Syntax" the forms that that level has in common with the >> previous level. The idea is to make it possible to get a quick sense >> of of the commonality between the levels, while giving the students >> confidence that documentation page they are looking at is >> comprehensive. >> _ >> For list-related administrative tasks: >> http://lists.racket-lang.org/listinfo/dev > > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev > -- Jay McCarthy Assistant Professor / Brigham Young University http://faculty.cs.byu.edu/~jay "The glory of God is Intelligence" - D&C 93 _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
If it is a click away and if the idea is that students got to B because they went thru A? I admit that there are instructors who use only ISL+ or ASL. But should we accommodate the special ones or the ones that use the language hierarchy as intended? On Jul 6, 2011, at 5:51 PM, Jay McCarthy wrote: > If you read the documentation as a textbook when you start > programming, I can see wanting to see something that says "cond is the > same as before". But, if you read the documentation as a reference > when you have a problem it is frustrating to chase through a few links > to get the "real" documentation. > > Is that the idea, Guillaume? > > Jay > > 2011/7/6 Matthias Felleisen : >> >> >> Why is it pedagogical to repeat information in the >> ISL documentation that the BSL documentation already >> presented? >> >> -- Matthias >> >> >> >> >> >> On Jul 6, 2011, at 9:36 AM, Guillaume Marceau wrote: >> >>> On Wed, Jul 6, 2011 at 9:14 AM, Matthew Flatt wrote: In the case of the HtDP languages, was the choice to duplicate all the text deliberate, or was it a side-effect of some other change? >>> >>> Yes, this was a deliberate move away from the no-duplication style >>> used in the professional documentation, for pedagogical reasons. >>> >>> At each language level, I gathered in a separate section called >>> "Common Syntax" the forms that that level has in common with the >>> previous level. The idea is to make it possible to get a quick sense >>> of of the commonality between the levels, while giving the students >>> confidence that documentation page they are looking at is >>> comprehensive. >>> _ >>> For list-related administrative tasks: >>> http://lists.racket-lang.org/listinfo/dev >> >> _ >> For list-related administrative tasks: >> http://lists.racket-lang.org/listinfo/dev >> > > > > -- > Jay McCarthy > Assistant Professor / Brigham Young University > http://faculty.cs.byu.edu/~jay > > "The glory of God is Intelligence" - D&C 93 _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
A click away can be one too many. Students have enough difficulty finding documentation as it is. The reference for ISL cond should include all the necessary details of ISL cond. How about we have a note saying that ISL cond is the same as ASL cond, then write it all out anyway. And presumably we don't need to do it by duplicating code, we can define it one place in Scribble and just use that text twice. --Carl On Wed, Jul 6, 2011 at 6:31 PM, Matthias Felleisen wrote: > > If it is a click away and if the idea is that students got to B because they > went thru A? > > I admit that there are instructors who use only ISL+ or ASL. But should we > accommodate the special ones or the ones that use the language hierarchy as > intended? > > > > > > On Jul 6, 2011, at 5:51 PM, Jay McCarthy wrote: > >> If you read the documentation as a textbook when you start >> programming, I can see wanting to see something that says "cond is the >> same as before". But, if you read the documentation as a reference >> when you have a problem it is frustrating to chase through a few links >> to get the "real" documentation. >> >> Is that the idea, Guillaume? >> >> Jay >> >> 2011/7/6 Matthias Felleisen : >>> >>> >>> Why is it pedagogical to repeat information in the >>> ISL documentation that the BSL documentation already >>> presented? >>> >>> -- Matthias >>> >>> >>> >>> >>> >>> On Jul 6, 2011, at 9:36 AM, Guillaume Marceau wrote: >>> On Wed, Jul 6, 2011 at 9:14 AM, Matthew Flatt wrote: > In the case of the HtDP languages, was the choice to duplicate all the > text deliberate, or was it a side-effect of some other change? Yes, this was a deliberate move away from the no-duplication style used in the professional documentation, for pedagogical reasons. At each language level, I gathered in a separate section called "Common Syntax" the forms that that level has in common with the previous level. The idea is to make it possible to get a quick sense of of the commonality between the levels, while giving the students confidence that documentation page they are looking at is comprehensive. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev >>> >>> _ >>> For list-related administrative tasks: >>> http://lists.racket-lang.org/listinfo/dev >>> >> >> >> >> -- >> Jay McCarthy >> Assistant Professor / Brigham Young University >> http://faculty.cs.byu.edu/~jay >> >> "The glory of God is Intelligence" - D&C 93 > > > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev > > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Jul 6, 2011, at 7:11 PM, Carl Eastlund wrote: > A click away can be one too many. Students have enough difficulty > finding documentation as it is. The reference for ISL cond should > include all the necessary details of ISL cond. How about we have a > note saying that ISL cond is the same as ASL cond, then write it all > out anyway. And presumably we don't need to do it by duplicating > code, we can define it one place in Scribble and just use that text > twice. I tend to agree with that... although I'm not sure we can always just replicate the prose, because a student in BSL has less vocabulary than one in ISL or ASL. Stephen Bloch sbl...@adelphi.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Wed, Jul 6, 2011 at 7:11 PM, Carl Eastlund wrote: > A click away can be one too many. Students have enough difficulty > finding documentation as it is. Yes... On Wed, Jul 6, 2011 at 5:51 PM, Jay McCarthy wrote: > But, if you read the documentation as a reference > when you have a problem it is frustrating to chase through a few links > to get the "real" documentation. ...and yes. That's the idea. > If it is a click away and if the idea is that students got to B because they > went thru A? This change is targeted at people who use the language tower as intended (in order, from BSL to ISL). By the time students get to BSL+abbr, they are still very shaky on BSL. You can't say "these forms are just like BSL" and expect them to be able to recall the details of BSL. They will have to click through the link, but most likely they won't click, and they will remain confused. It is better to have all the information right there in the first place. > How about we have a > note saying that ISL cond is the same as ASL cond, then write it all > out anyway. Right now all the forms that are borrowed from the previous level are gathered together under the "Common Syntax" subsection header. But it looks like people find this too subtle, so I'll add something more visible. > And presumably we don't need to do it by duplicating > code, we can define it one place in Scribble and just use that text > twice. That's how it's coded at the moment. Though because of the how the layout engine interacts with the macros I'm using to avoid the dictation, I'm getting all these extra new lines, but hopefully we fix that before the release. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Jay McCarthy writes: > If you read the documentation as a textbook when you start > programming, I can see wanting to see something that says "cond is the > same as before". But, if you read the documentation as a reference > when you have a problem it is frustrating to chase through a few links > to get the "real" documentation. For the record, I fully agree with Guillaume. I was puzzling over the exact same issue when I was doing the docs for the DMdA teaching languages, came out with the exact same reasoning as Guillaume, and ran against the exact same problem (as Eli may remember). Generally, redundancy is often a useful and appropriate tool in documentation. So it would be great if Scribble would provide more direct support for it. -- Cheers =8-} Mike Friede, Völkerverständigung und überhaupt blabla _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
25 minutes ago, Michael Sperber wrote: > For the record, I fully agree with Guillaume. I was puzzling over > the exact same issue when I was doing the docs for the DMdA teaching > languages, came out with the exact same reasoning as Guillaume, and > ran against the exact same problem (as Eli may remember). (I don't...) > Generally, redundancy is often a useful and appropriate tool in > documentation. So it would be great if Scribble would provide more > direct support for it. It's just code, so you do have direct support. -- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life! _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Eli Barzilay writes: > 25 minutes ago, Michael Sperber wrote: >> For the record, I fully agree with Guillaume. I was puzzling over >> the exact same issue when I was doing the docs for the DMdA teaching >> languages, came out with the exact same reasoning as Guillaume, and >> ran against the exact same problem (as Eli may remember). > > (I don't...) > > >> Generally, redundancy is often a useful and appropriate tool in >> documentation. So it would be great if Scribble would provide more >> direct support for it. > > It's just code, so you do have direct support. Yeah, well, except you run into trouble almost immediately because that code contains references, and Scribble is sensitive to all kinds of side conditions involving references. At the time, you proposed a complicated macro to work around the ensuing problems. -- Cheers =8-} Mike Friede, Völkerverständigung und überhaupt blabla _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Four minutes ago, Michael Sperber wrote: > Eli Barzilay writes: > > It's just code, so you do have direct support. > > Yeah, well, except you run into trouble almost immediately because > that code contains references, and Scribble is sensitive to all > kinds of side conditions involving references. I'm not sure which references you're talking about here, but yes, you need to be aware of things -- for example, since `racket' is a macro, you need to have any abstraction over its contents be a macro too. (That's the only kind of reference I can think of ATM.) > At the time, you proposed a complicated macro to work around the > ensuing problems. (I still don't remember... Maybe it was Matthew? (I'm often confused with him when it gets to scribble...)) -- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life! _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Eli Barzilay writes: >> Yeah, well, except you run into trouble almost immediately because >> that code contains references, and Scribble is sensitive to all >> kinds of side conditions involving references. I'm talking about the references to identifiers, and sections. Guillaume and I want pure, verbatim duplication of a piece of documentation. >> At the time, you proposed a complicated macro to work around the >> ensuing problems. No, it was you. This must have been in 2009. -- Cheers =8-} Mike Friede, Völkerverständigung und überhaupt blabla _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
9 minutes ago, Michael Sperber wrote: > > Eli Barzilay writes: > > >> At the time, you proposed a complicated macro to work around the > >> ensuing problems. > > No, it was you. This must have been in 2009. Now I'm even more curious. Pointer? -- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life! _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Thu, Jul 7, 2011 at 2:48 AM, Michael Sperber wrote: > > Eli Barzilay writes: > >>> Yeah, well, except you run into trouble almost immediately because >>> that code contains references, and Scribble is sensitive to all >>> kinds of side conditions involving references. > > I'm talking about the references to identifiers, and sections. > Guillaume and I want pure, verbatim duplication of a piece of > documentation. Is the issue is that you want the links in one copy of the docs to go to one place and the links in another copy to go in another place and Scribble's use of lexical scope to do linking is getting in your way? Robby _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On 07/06/2011 03:59 AM, Guillaume Marceau wrote: [...] [2]If you are the author of a teachpack, please update your error messages to match this new style. You can follow the error message completion guidelines, which are now in the main documentation under the "How to Design Programs Teachpacks" header. Send me e-mail if you need help. Shouldn't the documentation be in the "HtDP Languages as Libraries" manual instead? My understanding was that the "*How to Design Programs* Teachpacks" manual was for students and the "HtDP Languages as Libraries" manual was for implementors. Ryan _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Robby Findler writes: > On Thu, Jul 7, 2011 at 2:48 AM, Michael Sperber > wrote: >> >> Eli Barzilay writes: >> Yeah, well, except you run into trouble almost immediately because that code contains references, and Scribble is sensitive to all kinds of side conditions involving references. >> >> I'm talking about the references to identifiers, and sections. >> Guillaume and I want pure, verbatim duplication of a piece of >> documentation. > > Is the issue is that you want the links in one copy of the docs to go > to one place and the links in another copy to go in another place and > Scribble's use of lexical scope to do linking is getting in your way? Yes. -- Cheers =8-} Mike Friede, Völkerverständigung und überhaupt blabla _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
I've clarified with Mike the problem, and that email. For reference,
that email had a macro that had some complication in that it
implemented a raw `include' with scribble syntax -- but putting the
code inside a scribble file makes that unnecessary.
So there are two problems: the first is that he wants to use
identifiers in the documentation-generating macro that depend on the
lexical context where the macro is used. In other words, he wants to
use a macro that breaks hygiene... which means that something like
this should work for that purpose:
(define-macro (foo x . body)
`@splice{
Blah blah blah, @racket[x], blah blah.
@,@body}); <-- "@" is for scribble, ",@" is as usual
Or even better, just avoid the `define-macro' guessing of context at
all:
(define-syntax (foo stx)
(syntax-case stx ()
[(_ x body ...)
(with-syntax ([x (syntax->datum #'x)]
[(body ...) (syntax->datum #'(body ...))])
#'@splice{
Blah blah blah, @racket[x], blah blah.
@|body ...|})])); <-- have `body' followed by `...'
(Funny that it's a similar kind of breakage that the literate
programming thing is doing.)
The other problem is that he wants the macro to generate a section
too, with references, which means that each use needs to generate
different tags. Instead of fighting with some gensym, what I
suggested earlier is to have some part of the tag be an input to the
macro, so it ends up like
(define-syntax (foo stx)
(syntax-case stx ()
[(_ tagpart x body ...)
(with-syntax ([x (syntax->datum #'x)]
[(body ...) (syntax->datum #'(body ...))]
[tag (format "foo-~a" (syntax->datum #'tagpart))])
#'@splice{
Blah blah blah, @racket[x], blah blah.
@subsection[#:tag tag]{Some Title}
More blah blah blah.
@|body ...|})]))
(Warning: I'm too tired to actually try the above... so it's
untested.)
--
((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay:
http://barzilay.org/ Maze is Life!
_
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Jul 7, 2011, at 5:31 AM, Ryan Culpepper wrote: > On 07/06/2011 03:59 AM, Guillaume Marceau wrote: >> >> [...] >> >> [2]If you are the author of a teachpack, please update your error >> messages >> to match this new style. You can follow the error message completion >> guidelines, which are now in the main documentation under the "How to >> Design Programs Teachpacks" header. Send me e-mail if you need help. > > Shouldn't the documentation be in the "HtDP Languages as Libraries" manual > instead? My understanding was that the "*How to Design Programs* Teachpacks" > manual was for students and the "HtDP Languages as Libraries" manual was for > implementors. I clarified personally but for 'dev' in general. There should be three sets of docs: 1. HtDP teachpacks --- for students 2. How to Design HtDP Teachpack -- for teachers courageous enough to implement teachpacks 3. HtDP Languages --- for implementors of teaching languages _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Two minutes ago, Matthias Felleisen wrote: > > I clarified personally but for 'dev' in general. There should be > three sets of docs: > > 1. HtDP teachpacks --- for students > > 2. How to Design HtDP Teachpack -- for teachers courageous enough to >implement teachpacks I love the pun (and the resulting HtDHtDPT), but looks like a trap to confuse students... How about something more obvious, like "Implementing HtDP Teachpacks"? Also, a big warning at the top describing what it is for the occasional student that will stumble there after a random search? > 3. HtDP Languages --- for implementors of teaching languages Same here -- "Implementing HtDP Languages"? -- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life! _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
>>> I'm talking about the references to identifiers, and sections.
>>> Guillaume and I want pure, verbatim duplication of a piece of
>>> documentation.
>>
>> Is the issue is that you want the links in one copy of the docs to go
>> to one place and the links in another copy to go in another place and
>> Scribble's use of lexical scope to do linking is getting in your way?
>
> Yes.
Yes
Right now I am using macros that accept some identifiers as an
argument, instead of breaking hygiene.
(define-syntax-rule (define-form/explicit-lambda define lambda)
(make-splice
(list
@defform/none[#:literals (define lambda)
(... (define name (lambda (variable variable ...) expression)))]{
An alternate way on defining functions. The @racket[name] is the name of
the function, which cannot be the same as that of another function or
variable.
@defidform/inline[lambda] cannot be used outside of this alternate syntax.
}
)))
_
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Thu, Jul 7, 2011 at 11:49 AM, Guillaume Marceau wrote:
I'm talking about the references to identifiers, and sections.
Guillaume and I want pure, verbatim duplication of a piece of
documentation.
>>>
>>> Is the issue is that you want the links in one copy of the docs to go
>>> to one place and the links in another copy to go in another place and
>>> Scribble's use of lexical scope to do linking is getting in your way?
>>
>> Yes.
>
> Yes
>
>
> Right now I am using macros that accept some identifiers as an
> argument, instead of breaking hygiene.
>
>
> (define-syntax-rule (define-form/explicit-lambda define lambda)
>
> (make-splice
> (list
>
> @defform/none[#:literals (define lambda)
> (... (define name (lambda (variable variable ...) expression)))]{
>
> An alternate way on defining functions. The @racket[name] is the name of
> the function, which cannot be the same as that of another function or
> variable.
>
> @defidform/inline[lambda] cannot be used outside of this alternate syntax.
> }
> )))
>
... that macro works well enough.
If I could ask for something better, it would be something like
@duplicate-documentation[define-struct #:from htdp-beginner].
The big problem at the moment is that the layout engine doesn't know
what to do with the source information generated from the macro, so
the HTML comes out all wrong.
_
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
At Wed, 6 Jul 2011 05:59:30 -0400, Guillaume Marceau wrote: > [3]There is a layout problem in my new documentation I need help with. > I > tried to abstract the common text between the documentation of the > different levels. Possibly because I didn't do it correctly, the macro > I > am using confuses the layout engine, and it is now inserting lots of > spurious new lines whenever there is a @defform. Look at the > documentation for beginner's COND, you'll see what the problem is. Fix pushed. Some remaining issues: * ISL's "Syntax" section lists syntax that was already in B+SL. * ASL incorrectly specifies >= 1 arguments required for functions and function calls (i.e., functions and call are not common syntax at that point). * The order of some things is strange, such as `quote' instead of `define' to lead off the BSL syntax section. * All contracts for primitives print as lists. * Expanding `expr' to `expression' means that the grammar tables don't fit in the available width. (Is `expr' as an abbreviation confusing to students?) You were probably aware of many of those and waiting for the formatting problems to be fixed! _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
> Fix pushed. Thanks. > Some remaining issues: > > * ISL's "Syntax" section lists syntax that was already in B+SL. > > * ASL incorrectly specifies >= 1 arguments required for functions and > function calls (i.e., functions and call are not common syntax at > that point). > > * The order of some things is strange, such as `quote' instead of > `define' to lead off the BSL syntax section. Those are fixed in the commit I just pushed. > * All contracts for primitives print as lists. This is pending. I'll look into it next. > * Expanding `expr' to `expression' means that the grammar tables don't > fit in the available width. (Is `expr' as an abbreviation confusing > to students?) In general, yes, abbreviations are a big speed bump for students, enough that we put a 'no abbreviation' rule in the error message composition guidelines. It's somewhat important that the HTdP documentation be consistent with what we say in the guidelines. The grammar chart doesn't look too wide on my machine, except for the two lines for "case" in Advanced. Are you seeing something else? _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
At Sat, 9 Jul 2011 01:59:31 -0400, Guillaume Marceau wrote: > > * Expanding `expr' to `expression' means that the grammar tables don't > > fit in the available width. (Is `expr' as an abbreviation confusing > > to students?) > > In general, yes, abbreviations are a big speed bump for students, > enough that we put a 'no abbreviation' rule in the error message > composition guidelines. It's somewhat important that the HTdP > documentation be consistent with what we say in the guidelines. > > The grammar chart doesn't look too wide on my machine, except for the > two lines for "case" in Advanced. Are you seeing something else? I see that `case' is the only one in a blue box that doesn't fit, but I meant the grammar at the start of each language section. It doesn't fit for any of the languages on my machines (i.e., some line extends further than the beige bar at the top of the page). IE handles the overflow particularly badly on my Win7 machine: Sometimes it erases or doesn't draw text that extends beyond the column, which sometimes has the particularly unfortunate effect of omitting a closing parenthesis. That's probably an IE bug, but overflowing the column creates all sorts of problems. Maybe the solution is to add newlines. I see that the `case' production already has newlines (though the indentation is off). _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Thu, Jul 7, 2011 at 12:44 PM, Matthew Flatt wrote: > * ASL incorrectly specifies >= 1 arguments required for functions and > function calls (i.e., functions and call are not common syntax at > that point). > Stephen pointed out that function calls in BSL can invoke functions of zero arguments. You can't define such a function, but if you get it from a library, it works fine. Should I document the grammar for function calls as (name expression ...) thorough? _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
I'd much prefer eliminating such function calls. On Jul 11, 2011, at 6:28 PM, Guillaume Marceau wrote: > On Thu, Jul 7, 2011 at 12:44 PM, Matthew Flatt wrote: >> * ASL incorrectly specifies >= 1 arguments required for functions and >> function calls (i.e., functions and call are not common syntax at >> that point). >> > > Stephen pointed out that function calls in BSL can invoke functions of > zero arguments. You can't define such a function, but if you get it > from a library, it works fine. > > Should I document the grammar for function calls as (name expression > ...) thorough? > > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Mon, Jul 11, 2011 at 6:32 PM, Matthias Felleisen wrote: > I'd much prefer eliminating such function calls. Do you want them out in this release? _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Whoa, whoa there. They're there for a reason. I can't remember why, but I am pretty certain I have actually used such a function. Please don't go around chopping and changing the language a few days before the deadline. On Mon, Jul 11, 2011 at 7:21 PM, Guillaume Marceau wrote: > On Mon, Jul 11, 2011 at 6:32 PM, Matthias Felleisen > wrote: >> I'd much prefer eliminating such function calls. > > Do you want them out in this release? > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Yes, they're useful for 'teachpacks' like the Kiva teachpack... (https://github.com/nadeemabdulhamid/Kiva-Teachpack) On Mon, Jul 11, 2011 at 7:28 PM, Shriram Krishnamurthi wrote: > Whoa, whoa there. They're there for a reason. I can't remember why, > but I am pretty certain I have actually used such a function. Please > don't go around chopping and changing the language a few days before > the deadline. > > On Mon, Jul 11, 2011 at 7:21 PM, Guillaume Marceau wrote: >> On Mon, Jul 11, 2011 at 6:32 PM, Matthias Felleisen >> wrote: >>> I'd much prefer eliminating such function calls. >> >> Do you want them out in this release? _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
It's way too late for this release but I consider this a wart On Jul 11, 2011, at 7:21 PM, Guillaume Marceau wrote: > On Mon, Jul 11, 2011 at 6:32 PM, Matthias Felleisen > wrote: >> I'd much prefer eliminating such function calls. > > Do you want them out in this release? _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Jul 11, 2011, at 6:32 PM, Matthias Felleisen wrote: I'd much prefer eliminating such function calls. What harm do they do? You can't call any library function with the wrong number of arguments, and you can't define a zero-argument function. The only way this affects a BSL student is if the student is using a library that provides a zero-argument function, which it presumably does because the library author thinks BSL students NEED a zero-argument function. I wouldn't draw attention to the existence of zero-argument functions in the docs, but I don't see that we need to overrule the judgment of every library author who ever provides one. Stephen Bloch sbl...@adelphi.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Precisely. On Tue, Jul 12, 2011 at 6:10 AM, Stephen Bloch wrote: > > On Jul 11, 2011, at 6:32 PM, Matthias Felleisen wrote: > > I'd much prefer eliminating such function calls. > > What harm do they do? You can't call any library function with the wrong > number of arguments, and you can't define a zero-argument function. The > only way this affects a BSL student is if the student is using a library > that provides a zero-argument function, which it presumably does because the > library author thinks BSL students NEED a zero-argument function. > I wouldn't draw attention to the existence of zero-argument functions in the > docs, but I don't see that we need to overrule the judgment of every library > author who ever provides one. > Stephen Bloch > sbl...@adelphi.edu > > > > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
At Mon, 11 Jul 2011 18:28:56 -0400, Guillaume Marceau wrote: > On Thu, Jul 7, 2011 at 12:44 PM, Matthew Flatt wrote: > > * ASL incorrectly specifies >= 1 arguments required for functions and > > function calls (i.e., functions and call are not common syntax at > > that point). > > > > Stephen pointed out that function calls in BSL can invoke functions of > zero arguments. You can't define such a function, but if you get it > from a library, it works fine. > > Should I document the grammar for function calls as (name expression > ...) thorough? My initial reaction was that a 0-ary function call is a syntax error, but a teachpack might extend the grammar by introducing a binding that works without arguments. That is, the 0-ary extension is part of the teachpack, not the grammar. But it seems that 0-ary function calls are not syntax errors after all (in any Recent version of DrRacket). For example, BSL accepts (define (f x) (cons)) and complain only when `f' is called. I'm not sure whether it's better to try to fix that or leave it alone (maybe it's not causing any trouble) and adapt the grammar somehow. I write "somehow" because calling a (not pre-)defined function with 0 argument is a syntax error. For example, BSL rejects (define (f x) (f)) as a syntax error. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
I am with your initial thoughts. I find this inconsistency disturbing. I also wish to use BSL as a language that is isomorphic to the kind of mathematics that students see in middle school and high school. (I think of structs as generalized Cartesian points, i.e., something comprehensible in principle.) In this world, a zero-arity function doesn't exist. (Yes, I should introduce vectors right here and now.) If the author of a teachpack wishes to break this convention (to hell with Matthias's stupid ideas of helping kids with their math) that's fine. But such teachpacks should have to extend the grammar explicitly. -- Matthias On Jul 12, 2011, at 8:45 AM, Matthew Flatt wrote: > At Mon, 11 Jul 2011 18:28:56 -0400, Guillaume Marceau wrote: >> On Thu, Jul 7, 2011 at 12:44 PM, Matthew Flatt wrote: >>> * ASL incorrectly specifies >= 1 arguments required for functions and >>> function calls (i.e., functions and call are not common syntax at >>> that point). >>> >> >> Stephen pointed out that function calls in BSL can invoke functions of >> zero arguments. You can't define such a function, but if you get it >> from a library, it works fine. >> >> Should I document the grammar for function calls as (name expression >> ...) thorough? > > My initial reaction was that a 0-ary function call is a syntax error, > but a teachpack might extend the grammar by introducing a binding that > works without arguments. That is, the 0-ary extension is part of the > teachpack, not the grammar. > > But it seems that 0-ary function calls are not syntax errors after all > (in any Recent version of DrRacket). For example, BSL accepts > > (define (f x) > (cons)) > > and complain only when `f' is called. I'm not sure whether it's better > to try to fix that or leave it alone (maybe it's not causing any > trouble) and adapt the grammar somehow. > > I write "somehow" because calling a (not pre-)defined function with 0 > argument is a syntax error. For example, BSL rejects > > (define (f x) > (f)) > > as a syntax error. > > > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Thu, Jul 7, 2011 at 12:44 PM, Matthew Flatt wrote: > * All contracts for primitives print as lists. I traced this down to the change from (require scheme/pretty) to (require racket/pretty). I don't understand how that's causing the bug, but reverting to (require scheme/pretty) fixes things. Ryan, can you pull this fix into the release branch? It's commit 452f3a14fb7b25e6c54d08abdb8770fb20e68752 _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
In racket/pretty, pretty-print is like print and pretty-write is like write. In scheme/pretty, pretty-print is like write. So probably the better change is to stick with racket/pretty and use pretty-write instead of pretty-print. Robby On Wed, Jul 13, 2011 at 9:57 PM, Guillaume Marceau wrote: > On Thu, Jul 7, 2011 at 12:44 PM, Matthew Flatt wrote: >> * All contracts for primitives print as lists. > > > I traced this down to the change from (require scheme/pretty) to > (require racket/pretty). > > I don't understand how that's causing the bug, but reverting to > (require scheme/pretty) fixes things. > > Ryan, can you pull this fix into the release branch? It's commit > 452f3a14fb7b25e6c54d08abdb8770fb20e68752 > > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Thu, Jul 14, 2011 at 12:00 AM, Robby Findler wrote: > In racket/pretty, pretty-print is like print and pretty-write is like > write. In scheme/pretty, pretty-print is like write. > > So probably the better change is to stick with racket/pretty and use > pretty-write instead of pretty-print. Done. It is commit 793d7894, which should be pulled into the release. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
10 hours ago, Guillaume Marceau wrote: > On Thu, Jul 14, 2011 at 12:00 AM, Robby Findler > wrote: > > In racket/pretty, pretty-print is like print and pretty-write is > > like write. In scheme/pretty, pretty-print is like write. > > > > So probably the better change is to stick with racket/pretty and > > use pretty-write instead of pretty-print. > > Done. It is commit 793d7894, which should be pulled into the > release. I missed that -- so the only question I have for you is about da6e819. -- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life! _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Are the SIGNATURES in the beginner funs definitions and elsewhere fed to Mike's signature checker? If so, we need to roll back a commit I made for a small change to atan and that Eli just rolled over to the release. If not, it's okay. On Jul 13, 2011, at 11:57 PM, Guillaume Marceau wrote: > On Thu, Jul 7, 2011 at 12:44 PM, Matthew Flatt wrote: >> * All contracts for primitives print as lists. > > > I traced this down to the change from (require scheme/pretty) to > (require racket/pretty). > > I don't understand how that's causing the bug, but reverting to > (require scheme/pretty) fixes things. > > Ryan, can you pull this fix into the release branch? It's commit > 452f3a14fb7b25e6c54d08abdb8770fb20e68752 > > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
5 minutes ago, Matthias Felleisen wrote: > > Are the SIGNATURES in the beginner funs definitions and elsewhere > fed to Mike's signature checker? If so, we need to roll back a > commit I made for a small change to atan and that Eli just rolled > over to the release. > > If not, it's okay. The commit that I asked about changed only the documentation. In any case, I didn't merge it, just marked it to do in the next merging batch. Should I wait with that? -- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life! _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
Matthias Felleisen writes: > Are the SIGNATURES in the beginner funs definitions and elsewhere > fed to Mike's signature checker? If so, we need to roll back a commit > I made for a small change to atan and that Eli just rolled over to the > release. You mean those in the documentation? No. -- Cheers =8-} Mike Friede, Völkerverständigung und überhaupt blabla _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] New error messages for *SL
On Sat, Jul 9, 2011 at 10:17 AM, Matthew Flatt wrote: > I see that `case' is the only one in a blue box that doesn't fit, but I > meant the grammar at the start of each language section. It doesn't fit > for any of the languages on my machines (i.e., some line extends > further than the beige bar at the top of the page). > > IE handles the overflow particularly badly on my Win7 machine: > Sometimes it erases or doesn't draw text that extends beyond the > column, which sometimes has the particularly unfortunate effect of > omitting a closing parenthesis. That's probably an IE bug, but > overflowing the column creates all sorts of problems. > > Maybe the solution is to add newlines. I see that the `case' production > already has newlines (though the indentation is off). I don't have enough time to debug this before the release, so I rolled back the "expr -> expression" change. Hopefully that fixes the layout problem you see. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
