[racket-dev] Documentation Update for 6.1
Hi, In trying to look up the documentation for some of the new features in the release it looks like the documentation on http://docs.racket-lang.org is still for 6.0.1 I was able to just use the local documentation, so it’s not a big deal. I just wanted to make sure it didn’t fall through the cracks of the release. Thanks for 6.1, by the way, it seems very solid. -Chris signature.asc Description: Message signed with OpenPGP using GPGMail _ Racket Developers list: http://lists.racket-lang.org/dev
[racket-dev] Documentation
In cases where the semantics of constructs are changed, should the documentation have a margin note stating the version number of the change? I am in particular thinking of case: http://docs.racket-lang.org/reference/case.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._case%29%29 /Jens Axel _ Racket Developers list: http://lists.racket-lang.org/dev
Re: [racket-dev] Documentation
At Sun, 8 Dec 2013 11:09:39 +0100, Jens Axel Søgaard wrote: In cases where the semantics of constructs are changed, should the documentation have a margin note stating the version number of the change? Yes, it really should. Details like this get listed in HISTORY.txt (the `case` form apparently changed in v5.3.2), but no one ever reads HISTORY.txt, and we frequently forget to update it. Putting change information in the documentation is clearly better. Unless someone has an even better idea, I'll add a suitable form to `scribble/manual` and start trying to record changes this way. Matthew _ Racket Developers list: http://lists.racket-lang.org/dev
Re: [racket-dev] Documentation
Should the history.txt files get stuck into the end of the manuals for the time being? Robby On Sun, Dec 8, 2013 at 8:37 AM, Matthew Flatt mfl...@cs.utah.edu wrote: At Sun, 8 Dec 2013 11:09:39 +0100, Jens Axel Søgaard wrote: In cases where the semantics of constructs are changed, should the documentation have a margin note stating the version number of the change? Yes, it really should. Details like this get listed in HISTORY.txt (the `case` form apparently changed in v5.3.2), but no one ever reads HISTORY.txt, and we frequently forget to update it. Putting change information in the documentation is clearly better. Unless someone has an even better idea, I'll add a suitable form to `scribble/manual` and start trying to record changes this way. Matthew _ Racket Developers list: http://lists.racket-lang.org/dev _ Racket Developers list: http://lists.racket-lang.org/dev
[racket-dev] documentation dependencies indirect hyperlinks
Documentation hyperlinks are now covered by the package-dependency
checking of `raco setup'.
Dependencies that take the form of `for-label' imports were found by
normal module-dependency checking, already. The new checks cover cases
where a document refers to another document via `other-doc' or
`@secref[#:doc ...]' and where documentation refers to a module with
`racketmodname'.
Sometimes, you don't want a documentation link to force installation of
another document (and its dependencies). For example, the DrRacket
manual refers to the Algol 60 manual, but I don't want to force the
installation of Algol 60 and its documentation just to get the DrRacket
documentation; the hyperlink to Algol 60 should in the DrRacket manual,
but it should be a remote link if Algol 60 is not installed.
A few Scribble forms can make such indirect links:
* Add `#:indirect' to the end of a `racketmodname' link to make it
indirect:
@racketmodname[htdp/image #:indirect]
This works because `racketmodname' can build a suitable link tag
without consulting any other modules or documents.
* To make a section reference indirect, change `secref' to `seclink',
and include `#:indirect?':
@secref[#:other-doc '(lib scribblings/htdp-langs/beginner.scbl)
beginner-syntax]
=
@seclink[#:other-doc '(lib scribblings/htdp-langs/beginner.scbl)
#:indirect? #t
beginner-syntax]{the BSL grammar}
The reason `secref' changes to to `seclink' is that the former
depends on the target document to extract the section title, while
the latter uses the link text that you provide without having to
consult the target document.
* As a convenience, the `other-doc' function accepts an `#:indirect'
argument that is content to describe a document. The content is
combined with the and documentation to form the link text:
@other-doc['(lib scribblings/htdp-langs/beginner.scbl)]
=
@other-doc['(lib scribblings/htdp-langs/beginner.scbl)
#:indirect @elem{BSL}]
; which is the same as
@seclink[#:other-doc '(lib scribblings/htdp-langs/beginner.scbl)
#:indirect? #t
top]{the @elem{BSL} documentation}
Use indirect links sparingly, because they are not checked by either
the documentation-build part of `raco setup' or the package-dependency
part. A bad indirect link shows up only as broken link when you try to
follow it in the rendered documentation.
Dependency checking does not cover dynamic dependencies from
`scribble/eval' uses in a document. That's an area for future
improvement, but those dependencies are normally paired with checked
`for-label' imports, anyway, to hyperlink examples.
_
Racket Developers list:
http://lists.racket-lang.org/dev
Re: [racket-dev] Documentation lacuna?
I've pushed this change: http://git.racket-lang.org/plt/commitdiff/d071dc43873b7e84a59e3c9df47a6c8b3f7c6b1d?hp=7b33298b6654bcd55105e24e99545b98db3206ba Jay On Mon, Jan 21, 2013 at 9:57 AM, Norman Gray nor...@astro.gla.ac.uk wrote: Jay, hello. On 2013 Jan 21, at 16:12, Jay McCarthy jay.mccar...@gmail.com wrote: I don't understand your concern. The response structure, which is the only actual structure (everything else is an interface on it)... a) Allows #f as the mime type ...but the documentation doesn't say what #f means here. Does it mean 'dunno, you work it out', or 'there is no content', or 'use some default'? In fact it means I promise there isn't any output, so so I don't have to tell you a MIME type, but that can only be discovered from experiment or inspecting the source. b) Has you provide an 'output' function that does the output. If you don't want there to be any output, then don't write any: (response 304 #304 (current-seconds) #f empty void) When I read the documentation for RESPONSE, I thought 'oh dear, it doesn't know about no-content responses', because it reads as if it assumes (and implements) that every HTTP response has a message-body. Reading output produces the body suggests that there's always supposed to be a body, especially because it seems to suggest that it _always_ produces a Content-Type header. I don't think this is an outrageously wrong reading of the paragraph. So, what exactly is it that you want, if not what is already provided? How about a second paragraph after An HTTP response... which reads: Certain HTTP responses (with status 1xx, 204 and 304) have no content. These are correctly generated with a response structure which has #f for 'mime' and 'void' for 'output'. Such responses have no message-body, and no content-length or content-type headers. An alternative interface would be to have the response structure let output be (or/c false/c (- output-port? void?)), and indicate that output:#f produces no output, ignores any MIME type and produces no Content-Type header. That's potentially clearer (easier to guess the effect of) in the no-output case. (response 304 #Not Modified (current-seconds) #IGNORED (list (make-header #Location #http://racket-lang.org/download;)) #f) Finally: Re-reading what I first wrote, I suspect I was becoming slightly fixated on response/full over response, which meant I was a good bit less clear than I should have been. Sorry about that. Best wishes, Norman -- Norman Gray : http://nxg.me.uk SUPA School of Physics and Astronomy, University of Glasgow, UK -- Jay McCarthy j...@cs.byu.edu Assistant Professor / Brigham Young University http://faculty.cs.byu.edu/~jay The glory of God is Intelligence - DC 93 _ Racket Developers list: http://lists.racket-lang.org/dev
[racket-dev] Documentation lacuna?
Greetings. In the web server, the documentation for RESPONSE and, by implication, RESPONSE/FULL does not explain how to avoid including a message-body in the response, as is required for 1xx, 204, 304 statuses (and those alone). By experiment, giving RESPONSE/FULL a 'body' argument of # produces the right effect, but: (a) it would be reassuring if this case was mentioned in the documentation; (b) this still produces a content-length:0 header. A problem is that without reassurance in (a), giving an empty 'body' feels slightly like a hack. It might be that allowing an 'output' or 'body'' argument of #f would communicate the intent more clearly. Regarding (b), RFC 2616 Sect. 4.4 doesn't say that a Content-Length header is invalid in one of these responses, but it does imply (point 1 in that section) that the Content-Length header should be ignored in that case. This means that it's slightly unsightly (no more) that the header appears in a RESPONSE/FULL response. So, suggestion: either support an 'output' (for RESPONSE) or 'body' (for RESPONSE/FULL) argument of #f, which is documented to be appropriate only for certain statuses, and which suppresses the content-length; or document that giving a 'body' of # is indeed the approved way of giving a no-body response for these statuses, and that the content-length is generated but redundant. Best wishes, Norman -- Norman Gray : http://nxg.me.uk SUPA School of Physics and Astronomy, University of Glasgow, UK _ Racket Developers list: http://lists.racket-lang.org/dev
Re: [racket-dev] Documentation lacuna?
Sorry, an addendum... On 2013 Jan 21, at 12:23, Norman Gray nor...@astro.gla.ac.uk wrote: In the web server, the documentation for RESPONSE and, by implication, RESPONSE/FULL does not explain how to avoid including a message-body in the response, as is required for 1xx, 204, 304 statuses (and those alone). By experiment, giving RESPONSE/FULL a 'body' argument of # produces the right effect, but: (a) it would be reassuring if this case was mentioned in the documentation; (b) this still produces a content-length:0 header. The other thing (ahem...) is that without such an explanation, it's not clear what to put as the MIME type. Since there's no content, it's tempting to conclude that the 'mime' argument is ignored. If, however, one gives this argument as # (on the grounds that it doesn't matter what it is), this is faithfully send down the wire as a Content-Type: header, which is invalid. Giving 'mime' as #f (which is allowed in the contract of RESPONSE but not otherwise documented) _does_ suppress the content-type header, even though the documentation for RESPONSE states that the server will automatically add a Content-Type header if one is not present. That is, one can produce the correct behaviour here, even though the documentation seems to suggest that no-body responses will be problematic. Best wishes, Norman -- Norman Gray : http://nxg.me.uk SUPA School of Physics and Astronomy, University of Glasgow, UK _ Racket Developers list: http://lists.racket-lang.org/dev
Re: [racket-dev] Documentation lacuna?
Jay, hello. On 2013 Jan 21, at 16:12, Jay McCarthy jay.mccar...@gmail.com wrote: I don't understand your concern. The response structure, which is the only actual structure (everything else is an interface on it)... a) Allows #f as the mime type ...but the documentation doesn't say what #f means here. Does it mean 'dunno, you work it out', or 'there is no content', or 'use some default'? In fact it means I promise there isn't any output, so so I don't have to tell you a MIME type, but that can only be discovered from experiment or inspecting the source. b) Has you provide an 'output' function that does the output. If you don't want there to be any output, then don't write any: (response 304 #304 (current-seconds) #f empty void) When I read the documentation for RESPONSE, I thought 'oh dear, it doesn't know about no-content responses', because it reads as if it assumes (and implements) that every HTTP response has a message-body. Reading output produces the body suggests that there's always supposed to be a body, especially because it seems to suggest that it _always_ produces a Content-Type header. I don't think this is an outrageously wrong reading of the paragraph. So, what exactly is it that you want, if not what is already provided? How about a second paragraph after An HTTP response... which reads: Certain HTTP responses (with status 1xx, 204 and 304) have no content. These are correctly generated with a response structure which has #f for 'mime' and 'void' for 'output'. Such responses have no message-body, and no content-length or content-type headers. An alternative interface would be to have the response structure let output be (or/c false/c (- output-port? void?)), and indicate that output:#f produces no output, ignores any MIME type and produces no Content-Type header. That's potentially clearer (easier to guess the effect of) in the no-output case. (response 304 #Not Modified (current-seconds) #IGNORED (list (make-header #Location #http://racket-lang.org/download;)) #f) Finally: Re-reading what I first wrote, I suspect I was becoming slightly fixated on response/full over response, which meant I was a good bit less clear than I should have been. Sorry about that. Best wishes, Norman -- Norman Gray : http://nxg.me.uk SUPA School of Physics and Astronomy, University of Glasgow, UK _ Racket Developers list: http://lists.racket-lang.org/dev
Re: [racket-dev] Documentation for dynamic-require and related terms is confusing.
I will second the idea behind this request. (I thought I had to use dynamic-require's second argument in the summer, and after studying it for quite a while, i was happy to figure out a way around it.) On Sep 14, 2012, at 3:17 PM, Carl Eastlund wrote: I just tried to figure out what the second argument of dynamic-require does when it's not a symbol, for the nth time. First of all, the current interface -- 0, #false, and (void) as tokens for three rather arbitrary modes of operation -- leaves much to be desired. These other modes should probably be other functions, or one other function with flags that are more mnemonic. Second, the documentation of these modes is based on the technical terms instantiate, visit, and available, which I find incredibly arcane. Even now that I have looked them up and know what they mean (I _think_), I don't know why these particular words were chosen for the concepts they represent. To the best of my understanding, instantiate means allocate space for, and run, the relative-phase 0 content of a module; visit means the same thing at relative-phase 1. Neither the terms nor their documented definitions actually indicate this close relationship; I had to puzzle it out to realize they are almost the same thing, essentially differing only by add1. I would much prefer related terms, or even just one term used with a phase number. Otherwise I'm running around with two words for what seems to be just one concept. I'm also confused that there is no term for running module contents at higher phases. The term available appears to mean queued up for on-demand instantiation. Could we perhaps just say lazily instantiated here or something? Again, the word available here doesn't really suggest what's going on to me. Especially because to a user, the module doesn't actually become any more available than it was; it's only to the runtime implementation that the module suddenly becomes available. And I don't think Matthew's C code reads the documentation very often. (Though that would be impressive!) Of course, if I've interpreted these terms incorrectly, there's a further problem with either the explanation or my reading comprehension. I can certainly understand how the documentation got to this state. The module system is incredibly complicated, and at the outset I wouldn't know what to name anything, either. And I would imagine dynamic-require's interface has evolved over time. Now that we've had it a while, though, I think we can do a lot to improve the clarity of these features. I hope someone who understands them better than I do can take a stab at it. Carl Eastlund _ Racket Developers list: http://lists.racket-lang.org/dev _ Racket Developers list: http://lists.racket-lang.org/dev
Re: [racket-dev] Documentation problem
Did you use `raco docs' to open the documentation page? No. All I did was to access the Help Desk from DrRacket's Help menu. BTW, this is a fresh install, after uninstalling the previous version. I can see the wrong links in the file index.html, in AppData/Roaming/Racket/5.3.0.11/doc/ Best, António. _ Racket Developers list: http://lists.racket-lang.org/dev
[racket-dev] Documentation problem
Hi, Recent nightly builds (e.g., for 5.3.0.10 or 5.3.0.11) install documentation files that incorrectly point to 5.3.0.4 files. This is visible after accessing the Help Desk: the page says it's for version 5.3.0.4 and clicking on any of the links will show the problem. Best, António. _ Racket Developers list: http://lists.racket-lang.org/dev
Re: [racket-dev] documentation reorganization
I think the 'guide' and 'reference' links could use a description of
what they are similar to the tutorial links.
On 07/01/2011 06:45 PM, Ryan Culpepper wrote:
I just pushed a commit intended to improve the usability of the main
documentation page, especially for newcomers to Racket. You can also
see the new version here:
http://www.cs.utah.edu/~ryan/tmp/doc/
If you have a manual in the trunk, I probably changed it
slightly. Take a look at the changes. The rest of this message is
about the rationale behind the reorganization.
--
Back in May, we heard from a newcomer to Racket who had gotten lost in
the documentation and ended up going down the wrong path. His report
sparked a discussion about, among other things, changing the
documentation to make it more accessible to newcomers and
visitors. While there are some gaps in the content of the
documentation we have available, the primary problem seemed to be the
organization; the newcomer didn't find the right manuals to read.
The new documentation has four conceptual parts: Orientation, Racket,
Teaching, and Everything Else.
Orientation: The Getting Started link now stands alone; previously it
was too easy to miss. The tutorials are now labeled as such in a
separate section.
Racket: The previous organization was too egalitarian. The Racket
Reference was bare centimeters above the R6RS manual; R6RS is the
standard, right?---guess I should start there! Core libraries were
scattered throughout the documentation; you have to scroll to find the
GUI manual.
The new Racket Language and Core Libraries section makes it clear
where the serious, comprehensive material about Racket starts. The
core libraries are part reassurance (good, there's a standard GUI
toolkit) and part advertisement (oh, there's a standard way of
producing documentation).
Teaching: The teaching materials are important enough to the Racket
mission that they come next.
Everything Else: There are a couple lesser improvements to the rest of
the manuals.
First, the old Languages section (again, overly egalitarian) is now
much smaller, and its role is clarified. Racket is The Language; these
are others... what does that mean? The link explains it.
Second, I've done away with the @bold{X}: Y manual naming
convention. In some cases this convention works, but in most cases it
was a poor fit. @bold{Guide}: Racket is a bit inscrutable compared
to The Racket Guide, and @bold{Version}: Racket Version Checking
is grandiose for a manual that documents eight exports. The convention
was confining, and it led to an arms race of bolding. If your manual
didn't start with a bold keyword, it looked pitiful. I've changed
major manuals to have names such as The Racket Guide, The Racket
Drawing Toolkit, etc. I've renamed a few other manuals in that style,
such as Web Applications in Racket (used to be Web: ...) and
Extending DrRacket (used to be Plugins: ...). Use the unbolded
X: Y pattern for manuals that are just the documentation for some
collection; otherwise consider giving the manual a more descriptive
name.
--
This is intended as a first step. In particular, I wanted to get the
first three parts (Orientation, Racket, Teaching) in better shape in
time for the upcoming release.
Ryan
_
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] documentation reorganization
This looks great to me.
Minor thing: Low-Level APIs = Low-Level API and the last section
actually can have a name other than misc I think.
Robby
On Sat, Jul 2, 2011 at 8:45 AM, Ryan Culpepper r...@cs.utah.edu wrote:
I just pushed a commit intended to improve the usability of the main
documentation page, especially for newcomers to Racket. You can also
see the new version here:
http://www.cs.utah.edu/~ryan/tmp/doc/
If you have a manual in the trunk, I probably changed it
slightly. Take a look at the changes. The rest of this message is
about the rationale behind the reorganization.
--
Back in May, we heard from a newcomer to Racket who had gotten lost in
the documentation and ended up going down the wrong path. His report
sparked a discussion about, among other things, changing the
documentation to make it more accessible to newcomers and
visitors. While there are some gaps in the content of the
documentation we have available, the primary problem seemed to be the
organization; the newcomer didn't find the right manuals to read.
The new documentation has four conceptual parts: Orientation, Racket,
Teaching, and Everything Else.
Orientation: The Getting Started link now stands alone; previously it
was too easy to miss. The tutorials are now labeled as such in a
separate section.
Racket: The previous organization was too egalitarian. The Racket
Reference was bare centimeters above the R6RS manual; R6RS is the
standard, right?---guess I should start there! Core libraries were
scattered throughout the documentation; you have to scroll to find the
GUI manual.
The new Racket Language and Core Libraries section makes it clear
where the serious, comprehensive material about Racket starts. The
core libraries are part reassurance (good, there's a standard GUI
toolkit) and part advertisement (oh, there's a standard way of
producing documentation).
Teaching: The teaching materials are important enough to the Racket
mission that they come next.
Everything Else: There are a couple lesser improvements to the rest of
the manuals.
First, the old Languages section (again, overly egalitarian) is now
much smaller, and its role is clarified. Racket is The Language; these
are others... what does that mean? The link explains it.
Second, I've done away with the @bold{X}: Y manual naming
convention. In some cases this convention works, but in most cases it
was a poor fit. @bold{Guide}: Racket is a bit inscrutable compared
to The Racket Guide, and @bold{Version}: Racket Version Checking
is grandiose for a manual that documents eight exports. The convention
was confining, and it led to an arms race of bolding. If your manual
didn't start with a bold keyword, it looked pitiful. I've changed
major manuals to have names such as The Racket Guide, The Racket
Drawing Toolkit, etc. I've renamed a few other manuals in that style,
such as Web Applications in Racket (used to be Web: ...) and
Extending DrRacket (used to be Plugins: ...). Use the unbolded
X: Y pattern for manuals that are just the documentation for some
collection; otherwise consider giving the manual a more descriptive
name.
--
This is intended as a first step. In particular, I wanted to get the
first three parts (Orientation, Racket, Teaching) in better shape in
time for the upcoming release.
Ryan
_
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] documentation reorganization
Great stuff. This is a big improvement.
Carl Eastlund
On Fri, Jul 1, 2011 at 8:45 PM, Ryan Culpepper r...@cs.utah.edu wrote:
I just pushed a commit intended to improve the usability of the main
documentation page, especially for newcomers to Racket. You can also
see the new version here:
http://www.cs.utah.edu/~ryan/tmp/doc/
If you have a manual in the trunk, I probably changed it
slightly. Take a look at the changes. The rest of this message is
about the rationale behind the reorganization.
--
Back in May, we heard from a newcomer to Racket who had gotten lost in
the documentation and ended up going down the wrong path. His report
sparked a discussion about, among other things, changing the
documentation to make it more accessible to newcomers and
visitors. While there are some gaps in the content of the
documentation we have available, the primary problem seemed to be the
organization; the newcomer didn't find the right manuals to read.
The new documentation has four conceptual parts: Orientation, Racket,
Teaching, and Everything Else.
Orientation: The Getting Started link now stands alone; previously it
was too easy to miss. The tutorials are now labeled as such in a
separate section.
Racket: The previous organization was too egalitarian. The Racket
Reference was bare centimeters above the R6RS manual; R6RS is the
standard, right?---guess I should start there! Core libraries were
scattered throughout the documentation; you have to scroll to find the
GUI manual.
The new Racket Language and Core Libraries section makes it clear
where the serious, comprehensive material about Racket starts. The
core libraries are part reassurance (good, there's a standard GUI
toolkit) and part advertisement (oh, there's a standard way of
producing documentation).
Teaching: The teaching materials are important enough to the Racket
mission that they come next.
Everything Else: There are a couple lesser improvements to the rest of
the manuals.
First, the old Languages section (again, overly egalitarian) is now
much smaller, and its role is clarified. Racket is The Language; these
are others... what does that mean? The link explains it.
Second, I've done away with the @bold{X}: Y manual naming
convention. In some cases this convention works, but in most cases it
was a poor fit. @bold{Guide}: Racket is a bit inscrutable compared
to The Racket Guide, and @bold{Version}: Racket Version Checking
is grandiose for a manual that documents eight exports. The convention
was confining, and it led to an arms race of bolding. If your manual
didn't start with a bold keyword, it looked pitiful. I've changed
major manuals to have names such as The Racket Guide, The Racket
Drawing Toolkit, etc. I've renamed a few other manuals in that style,
such as Web Applications in Racket (used to be Web: ...) and
Extending DrRacket (used to be Plugins: ...). Use the unbolded
X: Y pattern for manuals that are just the documentation for some
collection; otherwise consider giving the manual a more descriptive
name.
--
This is intended as a first step. In particular, I wanted to get the
first three parts (Orientation, Racket, Teaching) in better shape in
time for the upcoming release.
Ryan
_
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] documentation reorganization
On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper r...@cs.utah.edu wrote:
re Low-Level API: the other category labels are generally plural, and
other manuals might get inserted into this category (eg by planet packages)
The page is regenerated when new manuals are added, no? Just make it
plural then.
re misc: Do you mean Other? Would you prefer Other Languages and
Libraries or Other Manuals?
At the moment it contains two experimental languages so other
seems like a bad title.
Robby
Ryan
On 07/01/2011 06:51 PM, Robby Findler wrote:
This looks great to me.
Minor thing: Low-Level APIs = Low-Level API and the last section
actually can have a name other than misc I think.
Robby
On Sat, Jul 2, 2011 at 8:45 AM, Ryan Culpepperr...@cs.utah.edu wrote:
I just pushed a commit intended to improve the usability of the main
documentation page, especially for newcomers to Racket. You can also
see the new version here:
http://www.cs.utah.edu/~ryan/tmp/doc/
If you have a manual in the trunk, I probably changed it
slightly. Take a look at the changes. The rest of this message is
about the rationale behind the reorganization.
--
Back in May, we heard from a newcomer to Racket who had gotten lost in
the documentation and ended up going down the wrong path. His report
sparked a discussion about, among other things, changing the
documentation to make it more accessible to newcomers and
visitors. While there are some gaps in the content of the
documentation we have available, the primary problem seemed to be the
organization; the newcomer didn't find the right manuals to read.
The new documentation has four conceptual parts: Orientation, Racket,
Teaching, and Everything Else.
Orientation: The Getting Started link now stands alone; previously it
was too easy to miss. The tutorials are now labeled as such in a
separate section.
Racket: The previous organization was too egalitarian. The Racket
Reference was bare centimeters above the R6RS manual; R6RS is the
standard, right?---guess I should start there! Core libraries were
scattered throughout the documentation; you have to scroll to find the
GUI manual.
The new Racket Language and Core Libraries section makes it clear
where the serious, comprehensive material about Racket starts. The
core libraries are part reassurance (good, there's a standard GUI
toolkit) and part advertisement (oh, there's a standard way of
producing documentation).
Teaching: The teaching materials are important enough to the Racket
mission that they come next.
Everything Else: There are a couple lesser improvements to the rest of
the manuals.
First, the old Languages section (again, overly egalitarian) is now
much smaller, and its role is clarified. Racket is The Language; these
are others... what does that mean? The link explains it.
Second, I've done away with the @bold{X}: Y manual naming
convention. In some cases this convention works, but in most cases it
was a poor fit. @bold{Guide}: Racket is a bit inscrutable compared
to The Racket Guide, and @bold{Version}: Racket Version Checking
is grandiose for a manual that documents eight exports. The convention
was confining, and it led to an arms race of bolding. If your manual
didn't start with a bold keyword, it looked pitiful. I've changed
major manuals to have names such as The Racket Guide, The Racket
Drawing Toolkit, etc. I've renamed a few other manuals in that style,
such as Web Applications in Racket (used to be Web: ...) and
Extending DrRacket (used to be Plugins: ...). Use the unbolded
X: Y pattern for manuals that are just the documentation for some
collection; otherwise consider giving the manual a more descriptive
name.
--
This is intended as a first step. In particular, I wanted to get the
first three parts (Orientation, Racket, Teaching) in better shape in
time for the upcoming release.
Ryan
_
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] documentation reorganization
Four minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper r...@cs.utah.edu wrote: re Low-Level API: the other category labels are generally plural, and other manuals might get inserted into this category (eg by planet packages) The page is regenerated when new manuals are added, no? Just make it plural then. I also prefer the plural title, as a signal that more might be here rather than singular, which begs a question of why bother with a category for it. -- ((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] documentation reorganization
On Fri, Jul 1, 2011 at 9:41 PM, Ryan Culpepper r...@cs.utah.edu wrote: re misc: Do you mean Other? Would you prefer Other Languages and Libraries or Other Manuals? I think those should just go under Experimental Languages, since they're both languages, and at least one is experimental. -- sam th sa...@ccs.neu.edu _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] documentation reorganization
On Sat, Jul 2, 2011 at 9:53 AM, Eli Barzilay e...@barzilay.org wrote: Four minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper r...@cs.utah.edu wrote: re Low-Level API: the other category labels are generally plural, and other manuals might get inserted into this category (eg by planet packages) The page is regenerated when new manuals are added, no? Just make it plural then. I also prefer the plural title, as a signal that more might be here rather than singular, which begs a question of why bother with a category for it. That's not what begs the question means and that's not what plural means, either. (But perhaps I'm old fashioned.) Robby _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] documentation reorganization
Three minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:53 AM, Eli Barzilay e...@barzilay.org wrote: Four minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper r...@cs.utah.edu wrote: re Low-Level API: the other category labels are generally plural, and other manuals might get inserted into this category (eg by planet packages) The page is regenerated when new manuals are added, no? Just make it plural then. I also prefer the plural title, as a signal that more might be here rather than singular, which begs a question of why bother with a category for it. That's not what begs the question means and that's not what plural means, either. By signal and begs I meant that that's what it leads me to think. In other words (and IMO) low-level APIS makes sense as a container for more than a single entry so the fact that there is one looks like more will be there. On the other side, having just one entry with a singular title raises the same kind of question I'd have if I read a book with Chapter 1 but no other chapters. -- ((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] documentation reorganization
Yes, I understood you. I'm observing that making it plural is not helping. On Fri, Jul 1, 2011 at 9:06 PM, Eli Barzilay e...@barzilay.org wrote: Three minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:53 AM, Eli Barzilay e...@barzilay.org wrote: Four minutes ago, Robby Findler wrote: On Sat, Jul 2, 2011 at 9:41 AM, Ryan Culpepper r...@cs.utah.edu wrote: re Low-Level API: the other category labels are generally plural, and other manuals might get inserted into this category (eg by planet packages) The page is regenerated when new manuals are added, no? Just make it plural then. I also prefer the plural title, as a signal that more might be here rather than singular, which begs a question of why bother with a category for it. That's not what begs the question means and that's not what plural means, either. By signal and begs I meant that that's what it leads me to think. In other words (and IMO) low-level APIS makes sense as a container for more than a single entry so the fact that there is one looks like more will be there. On the other side, having just one entry with a singular title raises the same kind of question I'd have if I read a book with Chapter 1 but no other chapters. -- ((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] documentation reorganization
On Fri, Jul 1, 2011 at 8:45 PM, Ryan Culpepper r...@cs.utah.edu wrote: I just pushed a commit intended to improve the usability of the main documentation page, especially for newcomers to Racket. You can also see the new version here: This is great. Heres a few comments that come to mind: Underneath the Teaching header, the first item is How to Design Programs, it should probably read How to Design Programs, the Book. RackLog should be under Languages or under Experimental Languages, not under Tools. I am nominating RackUnit for promotion to the Racket Language and Core Libraries section. I would demote drawing toolkit if you don't want the section to get any larger. As it is, there are two items that make the sales pitch we can draw things in windows, but none that say we take testing seriously. The racket/gui manual should have a duplicate entry under GUI and graphics libraries. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
[racket-dev] Documentation bug - 12.6.3: Reading numbrs
At the end of part 12.6.3 of the docs in http://docs.racket-lang.org/reference/reader.html, it gives some examples Examples: -1 reads equal to -1 1/2 reads equal to (/ 1 2) 1.0 reads equal to (inexact-exact 1) 1+2i reads equal to (make-complex 1 2) 1/2+3/4i reads equal to (make-complex (/ 1 2) (/ 3 4)) 1.0+3.0e7i reads equal to (inexact-exact (make-complex 1 3000)) 2e5 reads equal to (inexact-exact 20) #i5 reads equal to (inexact-exact 5) #e2e5 reads equal to 20 #x2e5 reads equal to 741 #b101 reads equal to 5 Shouldn't all the usages of inexact-exact here actually be exact-inexact ? (I think this is the right place to ask this sort of question - if I'm wrong, please steer me in the right direction ;) _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Documentation bug - 12.6.3: Reading numbrs
On Jul 27, The Configurator wrote: Shouldn't all the usages of inexact-exact here actually be exact-inexact ? Yes, thanks -- fixed in git. -- ((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
