Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

BSB / Reason with existing OCaml setup / Merlin is underdocumented #404

Closed
4 tasks
ELLIOTTCABLE opened this issue Jul 11, 2018 · 1 comment · Fixed by #765
Closed
4 tasks

BSB / Reason with existing OCaml setup / Merlin is underdocumented #404

ELLIOTTCABLE opened this issue Jul 11, 2018 · 1 comment · Fixed by #765

Comments

@ELLIOTTCABLE
Copy link

ELLIOTTCABLE commented Jul 11, 2018

So, on global-installation, it's really not clear what to do if you already have a global / functioning OCaml setup on the machine in question (specifically, I mean an OPAM switch with ocamlmerlin installed).

(I'm a special-case; I'm trying to contribute back to Merlin's support for Vim; my installation is global to the machine, from my source clone of the project, but same question basically applies.)

In fact, in general, the onboarding is much clearer / smoother coming ‘from the JS direction.’ I totally understand this — more devs in your target-market are coming from Node / JS / our community; but I'd wager that Reason has matured enough that it's time to start fleshing out the docs for these cases a little more? “Definitely not an edge-case, but also not the single largest class of users”-type documentation?

Anyway: tl;dr, I suggest sections on the following pages, documenting the steps specifically for users who already have some sort of functioning OCaml setup, to bring OCaml up to ‘welcomeness-parity’ with JavaScript:

  • reasonml/quickstart — I'd say a bullet-point about OCaml users belongs on this page, the very first one linked from the homepage
  • reasonml/global-installation — I can deduce from this page that the reason-cli npm module installs a special version of Merlin, and that it's specifically an old version. This should be made explicit: “Here's how to install the correct versions of Merlin et al. in an OPAM switch …”
  • reasonml/convert-from-ocaml — although I'm new, I have been writing OCaml for a bit over a year now, and I've never once invoked ocamlbuild directly. This page desperately needs a section on existing build-systems, that mentions Dune and Oasis! (=

… not this project, but as far as I'm aware, these projects are tightly integrated, so I figured I'd keep the Issue centralized:

  • bucklescript/installation — needs a non-‘Install From Source’ section under ‘advanced users’ focused on OPAM as an alternative to npm

I hope this feedback was helpful! I'm a member of both communities (Node contributor since 2009; newer to OCaml, but came separately from Reason), and I'm coming to Reason as a complete newbie … so I hope I have a useful / unique perspective on what's missing from y'all's documentation!

@ELLIOTTCABLE
Copy link
Author

One thing in particular — forgive me if I end up using this Issue as a sort of running-log of my experiments and the documentation problems I run into while getting started — is that I can't figure out how to install BuckleScript, in a way that I can follow along with any of the documentation, without going through npm — specifically, npm install bs-platform. There's 4.02.3+buckle-master, but that seems undocumented?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant