Re: Patch to provide special form documentation online (doc, find-doc)
On Sep 19, 12:05 am, "Stephen C. Gilardi" <[EMAIL PROTECTED]> wrote: > On Sep 18, 2008, at 12:34 PM, Rich Hickey wrote: > > > Done, except catch and finally, which are sub-syntax of try, like & > > is for fn. > > Thanks. I've uploaded specialdocs-2.patch. Patch applied (rev 1034) - thanks! Rich --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: Patch to provide special form documentation online (doc, find-doc)
On Sep 18, 2008, at 12:34 PM, Rich Hickey wrote: > Done, except catch and finally, which are sub-syntax of try, like & > is for fn. Thanks. I've uploaded specialdocs-2.patch. Clojure user=> (doc doc) - clojure/doc ([name]) Macro Prints documentation for a var or special form given its name nil user=> (doc def) - def Special Form Please see http://clojure.org/special_forms#def nil user=> (doc catch) - catch Syntax Symbol Please see http://clojure.org/special_forms#try nil user=> (doc fn*) java.lang.Exception: Unable to resolve var: fn* in this context (NO_SOURCE_FILE:6) user=> - The patched code includes support for &, catch, and finally, pointing the user to fn or try on the special forms page. That support is easy to remove if you don't like it. - fn*, let*, and loop* get no special treatment as we discussed: they're unbound vars - fn, let, and loop are now treated as special forms rather than macros. Doc will point the user to the complete docs on the special_forms page rather than the abbreviated docs in the code. That's easy to change if you don't like it. Find-doc will still search through the old docs, so if you like fn, let, and loop pointing to the special_forms page, I recommend removing the abbreviated docs from their macro definitions. --Steve --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: Patch to provide special form documentation online (doc, find-doc)
On Sep 18, 2008, at 12:36 PM, Allen Rohner wrote: > I completely agree that users should read the site, but can we make > the special form doc just include a reminder of the syntax and then > link to the site? i.e. > > user=> (doc if) > - > (if test then) > (if test then else) > > Special Form. Please see http://clojure.org/special_forms/if for more > information. I like that and I'll be happy to implement it if it's acceptable to Rich. --Steve --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: Patch to provide special form documentation online (doc, find-doc)
> > > There's simply no substitute for reading the special forms page on the > > site, and everyone who intends to use Clojure should do so in its > > entirety. > > > If we want to make it so (doc def) et al do something, they should > > return the simple message: > > > Please see:http://clojure.org/special_forms > I think it's very cool that this works at all. I've gotten annoyed at the equivalent to doc in other languages because it didn't work on special forms. I completely agree that users should read the site, but can we make the special form doc just include a reminder of the syntax and then link to the site? i.e. user=> (doc if) - (if test then) (if test then else) Special Form. Please see http://clojure.org/special_forms/if for more information. Allen --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: Patch to provide special form documentation online (doc, find-doc)
On Sep 18, 11:47 am, "Stephen C. Gilardi" <[EMAIL PROTECTED]> wrote: > On Sep 18, 2008, at 7:52 AM, Rich Hickey wrote: > > > > > I'm not in favor of doing it this way, for several reasons. First, > > there needs to be one place for canonic docs for each thing. For > > functions and macros, that's the inline docs, from which the API page > > on the site is generated. For special forms, it's: > > >http://clojure.org/special_forms > > > I'm not going to start maintaining the special forms docs in source > > code. These docs inherently involve lots of prose, example code, > > highlighting and mutual reference. They are not a good fit for doc, > > doc is not man. > > > There's simply no substitute for reading the special forms page on the > > site, and everyone who intends to use Clojure should do so in its > > entirety. > > > If we want to make it so (doc def) et al do something, they should > > return the simple message: > > > Please see:http://clojure.org/special_forms > > > I'll add anchors within that if it helps. > > > Also, fn*, let* and loop* are not part of the public interface, I > > don't want them exposed - they are subject to change/disappearance at > > any time. > > > & isn't really a special form, it's just part of the syntax for fn. It > > doesn't need docs. > > OK, given that, I have some thoughts and questions: > > [1] We have 4 symbols for which special-symbol? returns true, but > which shouldn't be documented because they are private to Clojure's > (current) implementation: > > & fn* let* loop* > > [1a] Would it be acceptable for doc to acknowledge the fact that they > are not ordinary symbols, but give no further info as in: I don't understand the use case. Isn't doc either for getting help for something you've seen others do that you don't understand, or finding new things to call? Right now it does: user=> (doc fn*) java.lang.Exception: Unable to resolve var: fn* in this context same as user=> (doc foobar) java.lang.Exception: Unable to resolve var: foobar in this context I'm fine with that. > [2] There are 15 other symbols for which special-symbol? returns true > that we could document by referring to an anchor: > > . catch def do finally if monitor-enter monitor-exit new quote recur > set! throw try var > > [2a] Would you please provide anchors for those on the special_forms > page? > Done, except catch and finally, which are sub-syntax of try, like & is for fn. > [2b] Is this acceptable for the documentation?: > > user=> (doc if) > - > if > Special Form > Please see:http://clojure.org/special_forms#if > nil > user=> > Yes. > [2c] Am I correct that strictly speaking, a "special form" is a form > with one of these special symbols in its first position? Should doc > refer to these symbols as "Special Symbols" of "Special Operators" > instead? > No. > [3] Would it be a worthwhile change for "def" to reject definition of > vars with names for which special-symbol? returns true? > That's a separate conversation/feature. Thanks, Rich --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: Patch to provide special form documentation online (doc, find-doc)
On Sep 18, 2008, at 7:52 AM, Rich Hickey wrote: > I'm not in favor of doing it this way, for several reasons. First, > there needs to be one place for canonic docs for each thing. For > functions and macros, that's the inline docs, from which the API page > on the site is generated. For special forms, it's: > > http://clojure.org/special_forms > > I'm not going to start maintaining the special forms docs in source > code. These docs inherently involve lots of prose, example code, > highlighting and mutual reference. They are not a good fit for doc, > doc is not man. > > There's simply no substitute for reading the special forms page on the > site, and everyone who intends to use Clojure should do so in its > entirety. > > If we want to make it so (doc def) et al do something, they should > return the simple message: > > Please see: http://clojure.org/special_forms > > I'll add anchors within that if it helps. > > > Also, fn*, let* and loop* are not part of the public interface, I > don't want them exposed - they are subject to change/disappearance at > any time. > > & isn't really a special form, it's just part of the syntax for fn. It > doesn't need docs. OK, given that, I have some thoughts and questions: [1] We have 4 symbols for which special-symbol? returns true, but which shouldn't be documented because they are private to Clojure's (current) implementation: & fn* let* loop* [1a] Would it be acceptable for doc to acknowledge the fact that they are not ordinary symbols, but give no further info as in: user=> (doc fn*) - fn* Reserved Symbol fn* is used internally by Clojure and should be avoided in user code nil user=> or would you prefer user=> (doc fn*) no doc available for fn* user=> [1b] The docs for monitor-enter and monitor-exit essentially put them in this same group of symbols intended for internal use. Should they be moved into this class of "Reserved Symbols" or left where they are as special forms that are documented as "don't use". (One advantage of their current status is the pointer the docs provide to the locking macro.) [2] There are 15 other symbols for which special-symbol? returns true that we could document by referring to an anchor: . catch def do finally if monitor-enter monitor-exit new quote recur set! throw try var [2a] Would you please provide anchors for those on the special_forms page? [2b] Is this acceptable for the documentation?: user=> (doc if) - if Special Form Please see: http://clojure.org/special_forms#if nil user=> [2c] Am I correct that strictly speaking, a "special form" is a form with one of these special symbols in its first position? Should doc refer to these symbols as "Special Symbols" of "Special Operators" instead? [3] Would it be a worthwhile change for "def" to reject definition of vars with names for which special-symbol? returns true? Here are a couple of interactions that one might find confusing in the absence of "def" rejecting them with a clear message: user=> (defn fn* [x] (+ x 3)) #'user/fn* user=> (fn* 4) java.lang.ClassCastException: java.lang.Integer cannot be cast to clojure.lang.ISeq [...] user=> (defn monitor-enter [x] (+ x 3)) #'user/monitor-enter user=> (monitor-enter 4) java.lang.IllegalMonitorStateException [...] Thanks, --Steve --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Re: Patch to provide special form documentation online (doc, find-doc)
On Sep 18, 2:58 am, "Stephen C. Gilardi" <[EMAIL PROTECTED]> wrote: > This patch makes clojure/doc and clojure/find-doc operate on special > forms as well as vars. I'm enclosing it with this message, but if that > doesn't work I'll upload it to the group's file section as > "specialdocs.tgz". The .tgz file contains a patch file that patches > boot.clj and a new file: src/clj/clojure/specialdocs.clj. The .tgz > file is meant to be expanded from within the clojure home directory. > > Changes: > - add new file src/clj/clojure/specialdocs.clj containing a private > map from symbol to doc string for each of the 19 special forms and a > public function that prints the doc string given the symbol. > - change boot.clj to load specialdocs.clj > - move definition of special-symbol? earlier in boot.clj > - change find-doc to consider special form docs as well as var docs > - change doc to provide doc for special forms as well as vars and to > explain when doc is not available without throwing an exception > - a style correction to clojure/load: (.loadResourceScript > clojure.lang.RT ...) -> (clojure.lang.RT/loadResourceScript ...) > > > The reason is that not all special forms argument lists can be > expressed as if the special form were a function. The notation used on > the website has more flexibility to express the variants of the > special forms clearly. > - The special form docs are nearly identical to the docs on the > website. In cases where an item could be elided or repeated, I used > the singular form followed by *. For example (do expr*) rather than > (do exprs*). I also mentioned the ' reader macro in the doc for quote. > I suggest the same changes for the website. > - I guessed at the doc for the "&" special form, please check it. > - The new print-special-form-doc has to be public because it's called > from the "doc" macro expansion > - The website lists fn, let, and loop as special forms, but that's no > longer true. They are now macros--the corresponding special forms are > fn*, let*, and loop* which don't do destructuring. I adapted the > special form docs to reflect that. I suggest an update to the docs on > the website to correct this. > I'm not in favor of doing it this way, for several reasons. First, there needs to be one place for canonic docs for each thing. For functions and macros, that's the inline docs, from which the API page on the site is generated. For special forms, it's: http://clojure.org/special_forms I'm not going to start maintaining the special forms docs in source code. These docs inherently involve lots of prose, example code, highlighting and mutual reference. They are not a good fit for doc, doc is not man. There's simply no substitute for reading the special forms page on the site, and everyone who intends to use Clojure should do so in its entirety. If we want to make it so (doc def) et al do something, they should return the simple message: Please see: http://clojure.org/special_forms I'll add anchors within that if it helps. Also, fn*, let* and loop* are not part of the public interface, I don't want them exposed - they are subject to change/disappearance at any time. & isn't really a special form, it's just part of the syntax for fn. It doesn't need docs. Thanks, Rich --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~--~~~~--~~--~--~---
Patch to provide special form documentation online (doc, find-doc)
This patch makes clojure/doc and clojure/find-doc operate on special forms as well as vars. I'm enclosing it with this message, but if that doesn't work I'll upload it to the group's file section as "specialdocs.tgz". The .tgz file contains a patch file that patches boot.clj and a new file: src/clj/clojure/specialdocs.clj. The .tgz file is meant to be expanded from within the clojure home directory.Here is an example of applying the patch and using it:$ cd $ tar xzvf specialdocs.tgz specialdocs.patchsrc/clj/clojure/specialdocs.clj$ patch -p0 < specialdocs.patchpatching file src/clj/clojure/boot.clj$ ant[...]BUILD SUCCESSFULTotal time: 0 seconds$ cljClojureuser=> (doc doc)-clojure/doc([name])Macro Prints documentation for a var or special form given its nameniluser=> (doc if)-(if test then)(if test then else)Special Form Evaluates test. If not nil or false, evaluates and yields then otherwise, evaluates and yields else. If else is not supplied it defaults to nil. All of the other conditionals in Clojure are based upon the same logic, that is, nil and false constitute logical falsity, and everything else constitutes logical truth, and those meaning apply throughout. if performs conditional test of boolean Java method returns without conversion to Boolean.niluser=> (doc foo)no doc available for fooniluser=> Changes:- add new file src/clj/clojure/specialdocs.clj containing a private map from symbol to doc string for each of the 19 special forms and a public function that prints the doc string given the symbol.- change boot.clj to load specialdocs.clj- move definition of special-symbol? earlier in boot.clj- change find-doc to consider special form docs as well as var docs- change doc to provide doc for special forms as well as vars and to explain when doc is not available without throwing an exception- a style correction to clojure/load: (.loadResourceScript clojure.lang.RT ...) -> (clojure.lang.RT/loadResourceScript ...)Notes:- I made the docs a separate file because they're large and they currently confuse the emacs clojure mode I'm using. It's nice if that confusion is isolated to a file I'll rarely visit.- Rather than synthetic "arg lists" in Special Form docs, I used the notation from the website. For example what could have been: - def ([symbol] [symbol init]) Special Form ...is instead - (def symbol init?) Special Form ...The reason is that not all special forms argument lists can be expressed as if the special form were a function. The notation used on the website has more flexibility to express the variants of the special forms clearly.- The special form docs are nearly identical to the docs on the website. In cases where an item could be elided or repeated, I used the singular form followed by *. For example (do expr*) rather than (do exprs*). I also mentioned the ' reader macro in the doc for quote. I suggest the same changes for the website.- I guessed at the doc for the "&" special form, please check it.- The new print-special-form-doc has to be public because it's called from the "doc" macro expansion- The website lists fn, let, and loop as special forms, but that's no longer true. They are now macros--the corresponding special forms are fn*, let*, and loop* which don't do destructuring. I adapted the special form docs to reflect that. I suggest an update to the docs on the website to correct this.--Steve specialdocs.tgz Description: Binary data
