GUI (get-directory)

[pow bam]

Hello, I am very new to programming and up until this point I had only seriously messed with the AutoIt language - it was easy to search and find out how to do things as their forums were quite active and already possessed a wealth of data that any determined person could get by on with just search alone and never needing to actively post. I built myself an entire program in this fashion, learning as I went. I decided I wanted to learn how to do this in a "real" full-blown language (tho you could easily argue that AutoIt is a full language now). I've decided that I love the idea of Lisp and Racket in particular but I am hitting roadblocks to that goal as the search functionality and community just isn't near the level of AutoIt. So here I am, actually posting in the only place it appears I can..

I am trying to make use of (get-directory) which pops up a GUI prompt asking a user to select a directory..

https://docs.racket-lang.org/gui/Windowing_Functions.html#%28def._%28%28lib._mred%2Fmain..rkt%29._get-directory%29%29

Here is my code which works..

#lang racket/gui
(require racket/class)
(define gds-main
  (new frame%
       [label "GD Switcher"]
       [width 250]
       [height 300]
       [style '(no-resize-border)]))
(define panel-1
  (new vertical-panel%
       [parent gds-main]
       [style '(border)]
       [alignment '(center center)]))
(new choice%
     [parent panel-1]
     [label #f]
     [choices '("Forgotten Gods"
                "Ashes of Malmouth"
                "Vanilla Ice Cream")])
(get-directory)
(send gds-main center 'both)
(send gds-main show #t)

..if I just use get directory as-is but if I try

(get-directory [message "Select a folder.."])

in any combination, and I've tried so many, it only ever gives me back the error..

message: unbound identifier in: message

What am I missing, how do I make this work?

Thank you in advance for any insight.

[Hadi Moshayedi]

On Tue, Nov 19, 2019 at 9:49 AM pow bam <darr...@gmail.com> wrote:

 

(get-directory [message "Select a folder.."])

You should just use (get-directory "Select a folder.."). The docs says the syntax is

(get-directory	[	message
		parent
		directory
		style
		#:dialog-mixin dialog-mixin])		→		(or/c path #f)

Here the "[...]" means that message, parent, etc. are all optional and not named args. The #:dialog-mixin syntax means that it is a named arg.

-- Hadi

[pow bam]

Ah thank you very much Hadi.. that indeed worked out nicely and now makes alot more sense to me. The documentation structure can be a bit confusing/misleading on points like this and I rather wish that they would display "real world" usage examples more in-depth in the docs for clarity. Again thank you.

[George Neuner]

You might want to have a look at this page that describes the
conventions used in the manul:
    "Notation for Documentation" -
https://docs.racket-lang.org/reference/notation.html


Probably there should be a link to this on the main documentation page -
or an intro section on "how to read the manual" right up front.   We
can't reasonably expect novices to know the notation conventions.

George

[pow bam]

Indeed I would have likely never even known that section existed - and looking at it now I see that it is very dense reading material. I turns my mind to mush trying to interpret what's being said there. I also happen to be, by and large, a self-learning lone wolf type. I am a complete novice to programming but when it came to AutoIt I managed to figure out how to piece together a fairly complicated and large-ish program only using Google, typing in Autoit + whateverineededtoknowabout and it invariably led me to not only just the documentation but a community forum FULL of questions and answers from years of community involvement. Sadly, Racket has no such structure in place except this very secluded, small Google group and smattering of tuts about the web - hardly any of which actually focus in any depth upon GUI app creation to any real extent, seemingly more concerned with various game making and animation activities.

As an example take a look at what happens if I type this into Google for an AutoIt function:

https://www.google.com/search?q=autoit+get+window+size

I wind up with a list of forum entries that I can read for clues on what to do OR I can read the documentation along with all that and if you look at the documentation..

https://www.autoitscript.com/autoit3/docs/functions/WinGetClientSize.htm

..it not only gives me a more traditional breakdown of the function it then goes on to show me it in real world use/action. That's a powerful thing to getting new people and beginners in the door and using your language. I would actually be much happier with a true official forum. Nothing against Google, I guess, but it feels so spartan and limited compared to what it could be.

[Jack Firth]

Would it have helped if the get-directory documentation had included examples? Many parts of Racket's documentation are lacking in example code, especially the less-commonly-encountered parts.

[pow bam]

I can't speak for others but for me I feel it would have helped a great deal in enabling me to quickly figure out how it was supposed to actually be used. What was tripping me up the most I guess was 1) it appeared to me I needed to use the brackets like shown in the documentation, and 2) that it was wanting some keyword (like "message") there.

Except for that I rather do feel so far that it is a great language for beginners to learn and it even appears that it is in part aimed at beginners in spite of the fact it is a language that professional scientist types developed. It's a bit of a shame there are few serious, well done video (YouTube) tutorials covering vital aspects like how to get a simple GUI for an app put together - which for the most part is surprisingly simple to do compared to other languages I've experimented with up until this point. I had been fiddling with Python prior - which, as you'd expect, has a massive amount of community material out there in the void - but I wandered onto Racket and, except for the documentation snafu I experienced, I find it to be an incredibly appealing language.

[James Platt]

On Nov 20, 2019, at 3:31 AM, Jack Firth wrote:

> Would it have helped if the get-directory documentation had included examples? Many parts of Racket's documentation are lacking in example code, especially the less-commonly-encountered parts.

Indeed, I have previously mentioned the lack of examples as a general problem. However, many potential examples may already be written in the form of test code. There is a way to add a sandbox to Scribble which allows you to write test code and documentation at the same time. It would be great if this could be made easier to set up and then promoted for wider use. One place where it has been used is the struct++ package.

See:
https://docs.racket-lang.org/struct-plus-plus/index.html
https://github.com/dstorrs/struct-plus-plus/blob/master/scribblings/struct-plus-plus.scrbl

Also, as David Storrs has mentioned, it would be good if we can find a way to make it easier for more people to contribute to the documentation. See, for example, the thread "Wanted: Easier way to contribute docs" on this forum from June of 2017.

If we can direct more of the energy of this community into, not just improving the documentation, but the way we do documentation, it would be a major improvement. Requiring lots of parentheses doesn't bother me. Lack of infix notation doesn't bother me. Lack of documentation does.

James

[Alexis King]

On Nov 21, 2019, at 11:21, James Platt <j...@biomantica.com> wrote:

If we can direct more of the energy of this community into, not just improving the documentation, but the way we do documentation, it would be a major improvement.  Requiring lots of parentheses doesn't bother me.  Lack of infix notation doesn't bother me.  Lack of documentation does.

Every so often I see this sentiment expressed, and I’ll be entirely honest: I find it very surprising! I don’t at all want to suggest your experiences are untrue, or that they’re somehow your fault or not worth fixing, but they’re so contrary to my own that I must be missing something. I would go so far as to say that my experience with Racket’s documentation is far and away the best of every programming language I have ever used, even without adjusting for its comparatively small community.

I will concede that racket/draw and racket/gui are particularly sparse in the way of inline examples—perhaps something about the amount of context setup often necessary—but as the main distribution goes, that feels more like an exception than the norm! If you pick any section in the Datatypes chapter of the Racket Reference, for example, virtually every binding has typeset examples (using the scribble/example library you mention). Sections with fewer inline examples usually at least have links to example-heavy companion sections in the Guide. Even a library like pict, which is visual in the same way racket/draw and racket/gui are, has typeset examples for nearly every documented export.

I agree that it would be nice to make contributing small documentation improvements more accessible, but your wording seems to suggest you feel there is a deeper, systemic problem with the existing documentation. Could you say more on what that is? Or, maybe better yet, could you point to some other language’s documentation that you feel does things better that we might take inspiration from? I, at least, would find that extremely helpful to understand what steps Racket could take to do better.

[Martin DeMello]

One helpful thing to do is expand the GUI section of awesome-racket https://github.com/avelino/awesome-racket

I just sent them a PR for GUI-helpers.

martin

--
You received this message because you are subscribed to the Google Groups "Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to racket-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/934E0BEE-5840-4596-975F-410C3770DBA6%40biomantica.com.

[Laurent]

There may be some examples on Rosetta code, or at least Racket snippets could be added:

https://rosettacode.org/wiki/Category:GUI

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CAFrFfuEd7b3Y_aQ5rHq32tDE_iR06nrJp2J1RRaDsWaYKBhpkg%40mail.gmail.com.

[Stephen De Gabrielle]

Many packages contain an /examples folder, and adding examples is an easy way to contribute.

There is also https://github.com/racket/racket/wiki/Artifacts

> This page captures useful code snippets that are too small to be a package.
>
> Please contribute your own!

Though these might be better places in documentation, or in /examples

S.

[James Platt]

On Nov 21, 2019, at 6:27 PM, Alexis King wrote:

>> On Nov 21, 2019, at 11:21, James Platt <j...@biomantica.com> wrote:
>>
>> If we can direct more of the energy of this community into, not just improving the documentation, but the way we do documentation, it would be a major improvement. Requiring lots of parentheses doesn't bother me. Lack of infix notation doesn't bother me. Lack of documentation does.
>
> Every so often I see this sentiment expressed, and I’ll be entirely honest: I find it very surprising! I don’t at all want to suggest your experiences are untrue, or that they’re somehow your fault or not worth fixing, but they’re so contrary to my own that I must be missing something. I would go so far as to say that my experience with Racket’s documentation is far and away the best of every programming language I have ever used, even without adjusting for its comparatively small community.

It is definitely true that poor documentation is a general problem with programming languages and the Racket Guide and Racket Reference are, indeed, among the best that I have seen. I really like the fact that the Racket community explicitly recognizes the need to have both a guide and a reference. Documentation actually is a big problem almost everywhere these days.

>
> I will concede that racket/draw and racket/gui are particularly sparse in the way of inline examples—perhaps something about the amount of context setup often necessary—but as the main distribution goes, that feels more like an exception than the norm! If you pick any section in the Datatypes chapter of the Racket Reference, for example, virtually every binding has typeset examples (using the scribble/example library you mention). Sections with fewer inline examples usually at least have links to example-heavy companion sections in the Guide. Even a library like pict, which is visual in the same way racket/draw and racket/gui are, has typeset examples for nearly every documented export.

A lot of what I have been working on in Racket is GUI related. That might be part of the reason my experience has been so different than yours. I have almost entirely been using the Racket Guide rather than the Racket Reference. I suppose I should start collecting examples of lack of examples. As it happens, my next project is about creating stand-alone executables. Look at the Racket Guide about raco distribute and there are no examples at all. I'm looking here: https://docs.racket-lang.org/raco/exe.html?q=raco%20distribute

I also have not been able to find Racket examples very easily with a web search. I did some example searches just now to make sure I'm right about that and it looks like my default search engine, DuckDuckGo, has a particular problem with Racket. DuckDuckGo, usually gets just as good, and sometimes better, results than Google, in my general experience. However, I got better results with Startpage for a few Racket related searches. For example, I recently needed to use a PBKDF in my Racket code. Search for "racket pbkdf" (without the quotes) in DuckDuckGo and you don't get much of use but Google or Startpage get you straight to the most relevant material. So I'll have to make sure to try Startpage for my Racket work from now on. Maybe this part is not so bad as I thought.

Something else which I am not able to find easily about creating standalone executables is an overall description of how to do this. If I understand correctly, there are at least three methods. There are command line tools, there is the "Create Executable" command in DrRacket or you can create and run a makefile. Are there limitations to any of these compared to the others?

The documentation probably belongs here:
https://docs.racket-lang.org/guide/exe.html

I do expect that this blog post will be helpful:
https://www.greghendershott.com/2017/04/racket-makefiles.html

I'm sure that I can also find lots of examples of makefiles around which I can look through but it is nicer to have some official documentation. I probably will create some documentation about this myself but I would want to run it by someone with more knowledge on the topic before contributing it to the official documentation. It's easier to create a blog post and give the information on a this-worked-for-me basis. What I would go ahead and add to the official documentation is a link to the DrRacket Create Executable documentation, which is missing at first link above.

> I agree that it would be nice to make contributing small documentation improvements more accessible, but your wording seems to suggest you feel there is a deeper, systemic problem with the existing documentation. Could you say more on what that is? Or, maybe better yet, could you point to some other language’s documentation that you feel does things better that we might take inspiration from? I, at least, would find that extremely helpful to understand what steps Racket could take to do better.

The part about making contributions is one thing. The other is that it definitely has been my impression that I have frequently gone through pages in The Guide and still not known where to start. That leads me to think that there needs to be more of a culture of creating examples directly in The Guide. Perhaps, like my example about creating executables, there are other cases where the documentation about all the individual functions are there but something al level up, about the overall process, is missing.

The only other two languages which I have used much are Perl and R. Perl, at first, I learned mostly from books (mostly O'Reilly) and they have lots of good examples. Later on, I ended up mostly using Stack Overflow for figuring out how to do new things in Perl. R has especially bad official documentation, in my opinion, but some really good unofficial documentation. The official, manual page style, documentation is usually too terse to be useful. The other form of documentation, which they call "vignettes," are not written as reference material nor do they typically cover all functions of the library they are about. I learned R mostly through a combination of blog posts, kind of like the one from Greg Hendershott referenced above, and through attending seminars. After that, Stack Overflow became the primary reference material. I have found some useful stuff about Racket on Stack Overflow from some of the same people on this forum but not to the level there is with R and Perl. I suppose that goes with the popularity of the language.

One thing I have learned from creating documentation myself is that it is best to do it in stages. Just get something out there first and get comments on it. I always miss things but what people miss is often not what I would have anticipated. So, I have to keep going back to the documentation and fixing it. It can be a lot of work. To rephrase what I said earlier, if there are people in the Racket community with time available, I think documentation should be a priority even though things may be worse with other languages.

[James Platt]

On Nov 25, 2019, at 1:29 PM, Stephen De Gabrielle wrote:

> Many packages contain an /examples folder, and adding examples is an easy way to contribute.

I did not know that. So, I guess the strategy is to find the git repository for the package and look there? In any case, I haven't been finding these examples with a general web search.

>
> There is also https://github.com/racket/racket/wiki/Artifacts
>
>> This page captures useful code snippets that are too small to be a package.
>>
>> Please contribute your own!
>
> Though these might be better places in documentation, or in /examples

That artifacts wiki a good thing to know about. Most of these are a little more complex than I am thinking are good for documentation but I may well contribute some small but useful code. I sometimes create my own examples as I go because I often look back through my own code to refresh my memory on how to do something.

[David Storrs]

For the record, my big concern with the documentation is that it's extremely hard to contribute to.  I would be delighted to contribute documentation if the process was easy, but it's just not.  For a language as amazing as Racket and a documentation set as high-quality as Racket's, the difficulty of helping with it is surprising.

tl;dr :  Using literate programming techniques(*) for documentation is a bad idea.  So is having random tiny files scattered around instead of one single .scrbl file in a location that maps to the URL of the page.

(*) (i.e., having random tiny files with documentation on one particular thing and then automating the process of assembling them)

My understanding is that the sequence goes like this:

1) Notice a thing you would like to change (a typo fix, add an example, etc)

1a) Ask on the mailing list how to contribute changes since the Guide / Reference / package does not have clear directions built in

2) Go to Github

3) Find which racket-related repository is the one that matters for this documentation.  The Racket project itself has half a dozen repositories and it's not obvious (to me, at least) which one is which.  Things on the package server will have a direct link, which helps a lot.

4) git fork the appropriate repository, git clone it to your local machine

5) grep -r through the clone to find the document that you want to modify.  It will not be in a location apparent from the URL of the page you were looking at, nor will it be named what that page was named, nor will it contain all of the content from that page.  Also, it will be in Scribble, which is a DSL that requires non-trivial effort to learn and is non-trivial to read.  Still, it produces amazing output so that's probably worth it.  It's intimidating when you're just getting started, though.

6a) make your change

6b) google for how to rebuild scribble documentation

6c) rebuild (by default this will rebuild all documentation), verify you made the change correctly

7) git commit, git push

8) go back to github and submit a pull request

9) (when (eq? (sync pr-msg-ch) 'Accepted) (exit))

10) make requested changes

11) git commit, git push, goto 9

Compare that to what it looks like in, e.g., Perl

1) Notice a thing you would like to change (a typo fix, add an example, etc)

2) got to CPAN and search for the package / tutorial / etc.  clicking on the name of the package gets you a listing of all files in the package (cf https://metacpan.org/release/ETHER/Moose-2.2012)

3) click on the 'Package::Name::Contributing' file and do what it says.  This will probably be similar to the Racket workflow except that:

a) The complete details are spelled out.

b) There is a link directly to the repository

c) The location of the file you need to edit is obvious from the URL of the documentation page that you're changing

d) The file contains the complete text of the page so it's easier to find and easier to verify that your edits were correct

e) The file is in POD, which is so simple that you can generally learn what you need just from glancing at the file, and it's easier to read than Scribble.  It's simple enough that you generally don't need to rebuild it to HTML, but if you choose to then you can easily rebuild just that page.

Example of a Contributing file:  https://metacpan.org/pod/release/ETHER/Moose-2.2012/lib/Moose/Manual/Contributing.pod

  (NB:  All major Perl packages have a Contributing file and the 'create a package' tool for generating Perl modules creates a stub version for you so it's hard to forget.  If the author somehow *does* forget and the package doesn't have its own Contributing file then CPAN will show you a default version that contains all critical information.  Also, it's easy to find the Contributing file:  Go to the package listing that's available directly on CPAN and Ctrl+F for "Contributing")

--
You received this message because you are subscribed to the Google Groups "Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to racket-users...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/D5A56D93-963F-412D-9CA6-7DE3A17F6148%40biomantica.com.

[Jens Axel Søgaard]

FWIW I just found an introduction to Racket GUIs by Andres Ramos:

https://www.youtube.com/watch?v=yo6wVXS6dkU

/soegaard

--

You received this message because you are subscribed to the Google Groups "Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to racket-users...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/67dff8ff-cbd2-4d26-8901-34fc2be43928%40googlegroups.com.

--

--
Jens Axel Søgaard

[wanderley...@gmail.com]

I think your point is totally valid, and I feel that I already saw such discussion in the mail list.

You can simplify the process by searching a piece of the documentation in github.  For example, I search for a piece of the docs from rackjure (1) which is the second result in my search.

(1) https://github.com/search?l=&q=macro+automatically+adds+the+parentheses+language%3ARacket&type=Code

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CAE8gKodBn9oA_FHsbAbpMcvEUu37YoX7KpqStM9ZXsaAYKfyMw%40mail.gmail.com.

--

Abraço,
Wanderley Guimarães

[Matt Jadud]

It feels like much of the information needed to make some of the sign posts for easy contribution are available either 1) automatically available at time of documentation build, or 2) could be added to the info file.

Would someone in the Racket team be able to recommend or suggest some concrete ways the community might approach work that begins addressing the task of making it easier to contribute to docs? 

Or, really, anyone with some insight into the tools. Some pointers would help make it easier to contribute productively.

Cheers,

Matt

To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CAAmHZoe73tMi%3Deh61O14qhfHAcpGu7%3DXkB6gcx5Fuk0FWApq%3Dw%40mail.gmail.com.

[Sam Tobin-Hochstadt]

First, one thing I would suggest is that you can create pull requests
for anything right from the GitHub UI, although that doesn't let you
test them. Especially for small documentation changes where there's no
chance you're breaking something, I find that to be very effective and
lightweight.

Second, here's how I would go about making a documentation change to
something in the "main" documentation
- I go to the relevant directory (such as
racket/pkgs/racket-doc/scribblings/reference).
- I look at the file name of the HTML page I want to change, such as
https://docs.racket-lang.org/reference/envvars.html
- Edit envvars.scrbl. Sometimes the file name is less easy to find,
such as https://docs.racket-lang.org/reference/Manipulating_Paths.html
Then I use grep (it's in "paths.scrbl", which would be easy to see
from the larger section).
- Create pull request.

For most other packages, I'd do the following:
- `raco pkg update --clone the-pkg`
- cd the-pkg # and then look around for the documentation
- Other steps as above.

Sam

> To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/CAAGM456FbM%2Bfbsnw-Fy6%2BWLtxDYkxD7ALNVbNCyhdvYudv4wDg%40mail.gmail.com.