Right but the rest could be changed as well—and that does not take too much time. (Addressing minor issues does not mean other ones are not worked upon.)
ocamlmktop , utop, Toploop, etc. ?
Frankly I doubt this a real issue in practice you may be over reacting to the impressions of a single individual.
1 Like
I feel like it’s more like a quirk than a pain point.
– So this is the toplevel…
– The what?
– The toplevel. It means REPL.
– Okay, why not.
1 Like
Top level is a terrible name, REPL is also a pretty bad name but much more common. I’m partial to “interactive prompt” myself.
3 Likes
OK — made only minor changes, mostly adding links to the tutorial basic.html which explains that toplevel = REPL. Hopefully, that should be enough to clear any misunderstanding.
3 Likes
@boxed The above changes include replacing most “toplevel” with “interactive toplevel”. (We also speak of “top-level phrases” which may make matters more confusing to some… 
)
I did think, “What is utop? It’s a better toplevel? What’s that? What’s a toplevel? Never heard of that. A REPL??” There was nothing intuitive about calling it a top level, for me. I’ve never seen “toplevel” used in any other language. (I learned lisps a long time ago, and I have no idea how well-known “REPL” is outside of functional languages.)
It’s a small hurdle to get over, but if there are many small hurdles, they can have an impact. None of us has time to try out all of the technologies that are interesting and potentially useful. Many would turn out to be … not worth the trouble. So we make judgements as we learn about whether something is worth learning. I don’t think one should disdain attempts to make potential users take that the next little step to learn more about what began, perhaps, as only a casual curiosity.
Adding a toplevel = REPL note may be enough in this case. “Interactive prompt” gets the idea across, too.
2 Likes
There is no disdain. You should consider that the community, surrounding documentation and tooling has been using that word for more than twenty years. You won’t be able to change this by just not using the word on ocaml.org. There’s no point in trying to make newcomers believe we use another word when everyone else is not using it, that wouldn’t be helpful at all.
I think the disconnect here is that you’re looking at it from the perspective of someone who’s already been convinced to use OCaml and isn’t going to be deterred by a few unfamiliar terms. A newcomer is coming to OCaml with the perspective of ‘should I put in a time and effort investment to learn this?’, and will factor in familiarity of concepts, perhaps to a large extent. People learn by relating new concepts to the familiar ones they already know. Too much unfamiliarity though can act as a barrier to entry.
That seems reasonable to me. Sounds like a case where friendly and possibly repetitive (i.e. on different, relevant pages) notes about standard terminology–as in @Chris00’s change to basics.html–would smooth potential new users’ paths toward learning more. Maybe there are other pages where this sort of thing could be helpful; I don’t know.
Note that @octachron merged yesterday @Chris00’s pull request to use “toplevel or REPL” instead of “toplevel” in a few key places of the official manual.
Note that @octachron merged yesterday @Chris00’s pull request
I did agree that adding the information toplevel ≡ repl in a visible way was an acceptable compromise, but it was @mshinwell that merged the pull request.
I don’t know where you read that exactly, please do not try to extrapolate what I may be thinking beyond what I write; the case I’m making has absolutely nothing to do with this.
That’s why I said ‘I think the disconnect here is…’, not ‘this is what you’re thinking’. My point is that newcomers need reference points to help understand unfamiliar terminology–as you can see in this thread, ‘toplevel’ is a perfect example of this–and that a lack of familiar reference points builds up an unfamiliarity debt which helps to drive away learners. I think the case you’re making doesn’t take that into account.
Please, do you really think I don’t understand this ? I never said we should not explain what a toplevel is, I said it would be both unproductive and unhelpful to try to “hide” the fact that it’s being called that way in the OCaml world.
1 Like
The last couple messages here have been a bit too defensive for my taste – while I believe there is a consensus on the underlying issues, and differences in phrasing or emphasis. Maybe we could agree to move on.
9 Likes
- Calling their REPL “toplevel” is a bit confusing
That’s one of the worst “private jokes” of the OCaml community/environment.
It confuses anyone who’s not aware. Most people who call the REPL “toplevel” don’t even know why. Sometimes they don’t even know what “top-level” means, and when they do, they rarely make the connection between “top-level” and “REPL”.
It’s a very small issue but it causes a lot of confusion, which is not welcome at all for freshmen.
Please, call it “top-loop” if you have to give it a name that starts with “top”. Please, please, please, try not to use “top-level” for REPL.
1 Like
I started learning Ocaml for a few days now (1 week) and Honesly
utop is better than the python REPL and actually, i think that it’s the best REPL i ever seen and the completion works really well, the user has to know the key bindings and that’s it.
The manual saved me time and energy for mentioning it, since i declared a function and just after it i called printf, i remembered that the manual mentioned ;; to separate the declaration from the direct call to a function. the let () = expression () is a best practice as i saw but it’s worth to mention ;;
What i found a little difficult is the documentation for some extra libraries, like Core for example, since i am reading Real Worl Ocaml and i want some time to check the documentation. There is no words, just function signatures. Maybe i didn’t understand the philosophy of Ocaml yet.
that’s a first feedback for a beginner (1 week).
6 Likes
Thanks for your feedback!
The documentation for many libraries needs to be improved. Having a centralised repository for all OPAM packages will help promoting this as a standard. Function signatures are very useful of course, but they can’t replace written documentation and examples.
Most of the libraries expose well-defined documented public interfaces in mli files. Even if the project doesn’t have a rendered API reference, reading the interface files might help you a lot.
Finally there’s an excellent tool to navigate through libraries and docs called ocp-browser, which I highly recommend.
Let us know if you find any other issues with your experience learning OCaml!
3 Likes