@sorawee Let me try to answer your questions:
> For 1), are you saying that there are things that are not documented in brag/support? Ah, no, brag/support does document that it re-exports from br-parser-tools/lex, but if I wanted to find where an identifier comes from, I’d have to manually click through to figure this out. This problem would be compounded if br-parser-tools/lex then re-exported a bunch of modules.
Ideally there would be a programmatically-generated list of all the identifiers exported from each module, but I can’t seem to find anything like this (aside from inspecting bindings exported from modules programatically in the repl).
> For 2), you can just go through the documentation. Hmm, this is basically what I have been doing up till now, but it feels somewhat ad-hoc.
Maybe I’m misunderstanding, but the documentation is not fully generated programatically, correct? There is no where in the documentation where all the available modules are listed together in one place?
I feel like what I am used to in other languages is “here is a list of all modules, click on the one you want to get more documentation about”. But in Racket, everything is often in one long page, and I rarely feel like I have a good overview of everything that the package provides. I often feel like I am swimming through disorganized documentation, rather than navigating a hierarchy of functionality.
Try:
> (require brag/support)
> (module->exports 'brag/support)
I don’t think it’s gonna be useful much, because you will want to see the doc of each of these symbols anyway.
@cdep.illabout_slack It just turns out that your example was particular involved. Normally things are more straightforward. Also, I misremembered how Brag works.
The question “where is token defined” is only asked by someone, who wants to look in the code. The question is best answered with the help of DrRacket / racket-mode. Write a small program that contains the identifier token. Then click analyze syntax. Then right-click the identifier - you can now choose to go to the source file where it is defined.
Second, Brag is a layer on top of parser-tools. Brag takes the description of your grammar and the produces something that parser-tools understands. One of the things that Brag produces is a define-tokens form, which in turn produces the token struct. And I think the define-tokens form is affected by the actual grammar, you enter in your own code.
So - token just happen to a special case.
> I feel like what I am used to in other languages is “here is a list of all modules, click on the one you want to get more documentation about”. But in Racket, everything is often in one long page, and I rarely feel like I have a good overview of everything that the package provides. I often feel like I am swimming through disorganized documentation, rather than navigating a hierarchy of functionality. Need to go now - but hold that thought :slightly_smiling_face:
I have been using module->exports, as well as the various functionalities in drracket for exploring libraries.
However, whenever I am trying to understand a library, I feel like I am constantly flipping between my browser, drracket, and the repl.
@sorawee made this comment initially:
> Users usually just read documentation for these information. The documentation should be accurate, and if it’s not, that’s a doc bug. I guess I just don’t feel like this. I can’t remember ever recently using a programming language where I don’t constantly read the source code for the libraries I’m using. Maybe this is just me!
(Another unrelated problem I have is that it seems like the documentation is often not in the same file as the source code, so I need at least two windows open when reading through the source code.)
Maybe my underlying problem is that I feel like there is this weird gap between how good Racket’s documentation is, and how much trouble I have actually using it.
Racket’s documentation is very obviously written by people who are skilled technical writers. It is much better than documentation for other programming languages, especially if you consider the size of Racket’s community.
Despite that, I feel like navigating the documentation (and library source code) and actually using the documentation for writing my own code is pretty painful.
@wanpeebaw Check the packages of @alexknauth. He has a package that can do that, but I have forgotten the name.
@soegaard2 This one? https://docs.racket-lang.org/multi-file-lang/index.html
Yes.
Very close!
What I thought was something like following… #lang racket
(lang brag
nested-word-list: WORD
\| LEFT-PAREN nested-word-list* RIGHT-PAREN)
(lang 2d racket
(define (fizzbuzz n)
#2dmatch
╔═════════════════════╦══════════════╦════════════════════╗
║ (fizz? n) (buzz? n) ║ #t ║ #f ║
╠═════════════════════╬══════════════╬════════════════════╣
║ #t ║ "FizzBuzz" ║ "Buzz" ║
╠═════════════════════╬══════════════╬════════════════════╣
║ #f ║ "Fizz" ║ (number->string n) ║
╚═════════════════════╩══════════════╩════════════════════╝)
)
(lang sql
SELECT id, name, score FROM student)
...normal racket code using above definition...
@wanpeebaw The 2d language behaves like at-exp so #lang 2d racket ought to work:
Unless … brag is uncooperative. Guess you need to try it.
@cdep.illabout_slack I had the same reaction - in racket-mode you can jump from a symbol to it’s docs to it’s def really nicely.
But you are correct - the docs are really good. I’ve been trying to point other people in my programming community towards the Racket docs for inspiration.
@cdep.illabout_slack I wonder what you’re trying to do with the list of exports. I agree that the Racket docs don’t usually have a list of all the exports in one place, but I’m not sure I’ve ever wanted that.
Incidentally, in many cases the left sidebar will serve as that list
@yilin.wei10 Yeah, I’ve been using racket-mode, and it is really nice. I guess my main problem is that you can’t do that in the docs on the website.
@samth > I wonder what you’re trying to do with the list of exports. Mostly just look at what is available. It does seem like the left sidebar works nicely a lot of the time, but it doesn’t seem to always be the case (from my example above).
@cdep.illabout_slack Documentation is hard.
In my opinion the ideal for documentation makes it possible for the user to write programs without consulting the underlying code. To make this possible the documentation needs to very precise and document everything exported. This makes it possible to use the documentation as a reference.
However, when systems grow large, it can be difficult to see the big picture. This is especially apparent as a new Racket user (us old timers can just read the material “new” to us, and often know how this new piece belongs in the larger puzzle).
Ideally, documentation should contain introductory prose each time a new sub topic is presented. This is difficult to do in reference documentation, so for Racket the language, the Reference often links to the Guide, where the big picture (with examples) is presented.
Now, there are lots of libraries available that extends Racket. Most authors attempt to write some documentation. If there is a lack of time, they tend to write reference style documentation. Others have a very terse style. This can be a bit of hit-and-miss.
There are other approaches. Some languages have “in source documentation”. The advantage is that the documentation is right next to the code. The disadvantage is that the generated documentation follows whatever order is in the source - not one that makes logically sense.
Now, the Reference and Guide are very well-written. For newer users, I think, that it would be great in addition to have a series of Tutorials that presents a topic with lots of examples, but skips some of the finer details. Writing such tutorials take a lot of time.
At a more practical note, I always keep a browser open with the documentation my side screen and code on the center screen. If I am on a single screen, I often divide the screen in two. (Note: When doing this it is more practical to use the horizontal division between definition window and interaction window (the repl).)
Again, the documentation problem becomes more difficult for larger systems. At times it can be advantageous to begin understanding the core of a system. In the case of Racket, one option is to start with R5RS and then read up on structs, modules and for-loops in the Reference and in the Guide.
IIRC, @samth is also working on linking the documentation to source code.
Well, I did the linking to the documentation source
Linking to the actual source is a bit more work
Btw - when reading the Guide I often click at something and end up in the Reference without noticing. Would it makes sense to “color code” the Reference and the Guide, to make it more obvious. Exactly how I don’t know, perhaps different background colors?
you mean the background of the doc, or the background of a link?
The doc itself. Perhaps vertical stripes with different colors. Something that looks better than I can design :wink:
FWIW, this is already a thing, via query string
But I think passing the information via query string is awful
Huh? I don’t think I have seen that before.
Let’s say I am here (in the reference) and then click the link “Pairs and Lists”: https://docs.racket-lang.org/reference/pairs.html?q=list#%28def._%28%28quote._~23~25kernel%29._list%29%29
Oh, when I said “already a thing”, I didn’t mean it already works the way you described. I meant the infrastructure is already there.
Ah!