Re: [racket] Documentation enhancement suggestions
On Wed, Jan 4, 2012 at 11:22 AM, Vincent St-Amour wrote: > When the cursor is inside a function call and the operator is > recognized by eldoc (both standard library functions and user-defined > functions defined in the same file), the function's header and (if > known) return type is displayed in the minibuffer. > Geiser gives some info based on cursor position. Racket Users list: http://lists.racket-lang.org/users
Re: [racket] Documentation enhancement suggestions
At Mon, 2 Jan 2012 14:49:34 +, Erich Rast wrote: > But here is another suggestion that I would find > tremendously helpful: an auto-hover live help that pops up information > about function definitions plus a short explanation of what the function > does directly in the IDE, Similar to that, I really like Emacs's eldoc. When the cursor is inside a function call and the operator is recognized by eldoc (both standard library functions and user-defined functions defined in the same file), the function's header and (if known) return type is displayed in the minibuffer. For example if the cursor is here (<= |2 3) eldoc displays (<= x1 x2 ...) => bool in the minibuffer. Often, that gives me all the information I need, and I don't need to search the docs (or my source file). Something similar for DrRacket would be great. Vincent Racket Users list: http://lists.racket-lang.org/users
Re: [racket] Documentation enhancement suggestions
Hello, On Mon, Jan 2, 2012 at 15:35, Juan Fatas Huang wrote: > How about Sphinx? > I think that Sphinx collides with having Scribble -- the documentation toolset for Racket (and not only). Back to the Python department, I was reading some documentation today, and I found specifically helpful to have this FAQ => http://docs.python.org/faq/programming.html I think I haven't used it before. I was reading about how to distribute standalone binaries, and the FAQ came as one of Google's results. For Racket, a FAQ could cover commons questions that show up in the mailing-list or IRC. Example: 1. Why do I get an error ...? Make sure to set "detect language from source" 2. How to distribute binaries? ... 3. Where is the documentation for slideshows? ... 4. Can I do this ... in Racket? ... etc... It would be helpful if the FAQ would concentrate more links and short explanations to things that are better documented or exemplified somewhere else. Additionally, by reading the list I've heard about many contributions spread in Github or personal pages, for example one Github page with a list of pet projects. I think there could be a section somehow in the Racket website to link to those contributions, or else it gets more difficult to remember that they exist, and where they are. Maybe something in the already existent community page? []'s Rodolfo Carvalho Racket Users list: http://lists.racket-lang.org/users
Re: [racket] Documentation enhancement suggestions
How about Sphinx? Sphinx is a tool that makes it easy to create intelligent and beautiful > documentation, written by Georg Brandl and licensed under the BSD license. Benefits: -- host on github (for everyone who love to contribute) -- the website can run on http://readthedocs.org/ e.g. http://racket-doc.readthedocs.org/ -- a lot of features already there! What do you think? -- Juanito On 3 January 2012 00:33, Robby Findler wrote: > Well, there is more to be done. It would be nice to get completion, > etc. Someday. :) > > Robby > > On Mon, Jan 2, 2012 at 10:23 AM, Erich Rast wrote: > > Oops...I didn't know that. Please disregard my last mail. > > > > Thanks a lot! > > > >> FWIW, in DrRacket, you can type f1 to search for the text that's at > >> the current insertion point and you can right click on a word to do a > >> similar search. > > > > Racket Users list: > > http://lists.racket-lang.org/users > > > Racket Users list: > http://lists.racket-lang.org/users > Racket Users list: http://lists.racket-lang.org/users
Re: [racket] Documentation enhancement suggestions
Well, there is more to be done. It would be nice to get completion, etc. Someday. :) Robby On Mon, Jan 2, 2012 at 10:23 AM, Erich Rast wrote: > Oops...I didn't know that. Please disregard my last mail. > > Thanks a lot! > >> FWIW, in DrRacket, you can type f1 to search for the text that's at >> the current insertion point and you can right click on a word to do a >> similar search. > > Racket Users list: > http://lists.racket-lang.org/users Racket Users list: http://lists.racket-lang.org/users
Re: [racket] Documentation enhancement suggestions
Oops...I didn't know that. Please disregard my last mail. Thanks a lot! > FWIW, in DrRacket, you can type f1 to search for the text that's at > the current insertion point and you can right click on a word to do a > similar search. Racket Users list: http://lists.racket-lang.org/users
Re: [racket] Documentation enhancement suggestions
FWIW, in DrRacket, you can type f1 to search for the text that's at the current insertion point and you can right click on a word to do a similar search. The online check syntax makes it possible to jump right to the docs for a given imported variable. Robby On Mon, Jan 2, 2012 at 8:49 AM, Erich Rast wrote: > > I personally have no quirks with the existing documentation, I think > it's excellent. But here is another suggestion that I would find > tremendously helpful: an auto-hover live help that pops up information > about function definitions plus a short explanation of what the function > does directly in the IDE, or at least allows you to perform a search > for the function in the help pages with a simple mouse click. > > For an example of what I mean, take a look at GNAT Programming Studio; > it gives "online" help to produdures and functions while you type them. > > Any volunteers? ;-) > > Best, > > Erich > > Racket Users list: > http://lists.racket-lang.org/users Racket Users list: http://lists.racket-lang.org/users
Re: [racket] Documentation enhancement suggestions
I personally have no quirks with the existing documentation, I think it's excellent. But here is another suggestion that I would find tremendously helpful: an auto-hover live help that pops up information about function definitions plus a short explanation of what the function does directly in the IDE, or at least allows you to perform a search for the function in the help pages with a simple mouse click. For an example of what I mean, take a look at GNAT Programming Studio; it gives "online" help to produdures and functions while you type them. Any volunteers? ;-) Best, Erich Racket Users list: http://lists.racket-lang.org/users
Re: [racket] Documentation enhancement suggestions
I don't like the idea of people solving "real world" problems copy/paste'ing code from docs, which I'm not sure it's even possible (e.g. what would be the example of call/cc?). However, couple of times I've been in a position to write some general usage examples of a function that we looked up in a class with students, where I was also demonstrating an example usage of the docs itself. For example, for 'delay' and 'force' to generate streams, we look up the language reference where the lang was advanced student[*]. Then I felt I need to write > (define x (delay (+ 1 2))) > x promise.. > (force x) 3 on the board. I think if there were some kind of automation where we can provide some examples for any 'non-exampled' constructs that we see in docs, it would increase the enhancement of the docs. However, it would somehow require moderation, which of course in some cases would be a real pain. To generalize this, it would be great to have something like "The Hitchhikers Guide to Racket!", like [**], but I don't really have a single clue how to do that :) -- caner [*] http://docs.racket-lang.org/htdp-langs/advanced.html?q=delay&q=reference [**] http://docs.python-guide.org/en/latest/index.html On 01/02/2012 09:26 AM, Gerry Weaver wrote: > Hello All, > > It seems we are not seeing many/any actual suggestions for ways to > improve the Racket documentation. I have been thinking about this > quite a bit. Writing good documentation is hard and very time > consuming. It is also a task which most developers absolutely hate > (myself included). I've been trying figure out what could be done that > would hopefully minimize the pain and shorten the timeline to > enhancing the docs. I think the area that could most use the attention > would be the library reference. If each library function were to > include a practical (not contrived) real world usage example, it would > help a lot. The Nokia Qt library would be a good example of what I'm > talking about. In most cases the docs contain usage examples that are > further augmented by nice collection of working code examples. I am > not suggesting that Racket should do a knock off of Qt's docs or > anything like that. I use Qt as an example, because the Qt docs are > generally regarded as some of the best out there. When I say "real > world" examples, I mean that they are written with the idea that the > developer can copy and paste them into his/her code as a good starting > point. Since the web docs were the original issue, I would suggest > something similar. A few example web applications that represent > typical use. For example, a restful web service with ajax, an xmlrpc > service, and template based pages would be a good start. These example > apps should include sessions, cookies, SSL, and be backed by a > database of some sort. They should also include a text that provides a > line by line walk-thru of the code. Most of the popular web frameworks > out there have these types of examples. > > http://doc.qt.nokia.com/4.7/classes.html > http://developer.qt.nokia.com/doc/qt-4.8/all-examples.html > > > Disclaimer: I'm not trying to be critical or ruffle any feathers. My > intention is only to put a stake in the ground as a starting point. > > Thanks, > Gerry > > > > > > Racket Users list: > http://lists.racket-lang.org/users signature.asc Description: OpenPGP digital signature Racket Users list: http://lists.racket-lang.org/users
