Merge pull request #765 from davesnx/source

docs/compiling-to-js-with-jsoo.md

@@ -0,0 +1,18 @@
+---
+title: Js_of_ocaml
+---
+
+[Js_of_ocaml](https://ocsigen.org/js_of_ocaml/3.7.0/manual/overview)
+
+## Template
+
+To get started check out this [`hello-jsoo-esy`](https://github.com/jchavarri/hello-jsoo-esy) template:
+
+```
+git clone https://github.com/jchavarri/hello-jsoo-esy.git
+cd hello-jsoo-esy
+esy
+
+npm install
+npm run webpack
+```

docs/compiling-to-js-with-melange.md

@@ -0,0 +1,103 @@
+---
+title: Melange
+---
+
+One of the best usages of Reason is to compile it to JavaScript an run it in the browser or any JavaScript platform such as [Node.js](https://nodejs.org), [Deno](https://deno.com), [Cloudflare Workers](https://workers.cloudflare.com).
+
+Reason compiles to JavaScript thanks to our partner project, [Melange](https://melange.re).
+
+## What's Melange?
+
+[Melange](https://melange.re) is a backend for the OCaml compiler that emits readable, modular and highly performant JavaScript code.
+
+> Melange strives to provide the best integration with both the OCaml and JavaScript ecosystems
+
+If you have experience with JavaScript and the ecosystem we recommend Melange, over other alternatives such as [Js_of_ocaml](compiling-to-js-with-jsoo.md).
+
+## Getting started
+
+The install guide on the Melange website shares a lot of common steps with [our installation](installation.md), check it out: [melange.re/v2.0.0/getting-started](https://melange.re/v2.0.0/getting-started).
+
+Since [Melange v1](https://buttondown.email/anmonteiro/archive/melange-hits-v10/), Melange integrates with dune. This means that you can use dune to compile your Reason code to JavaScript and also to bytecode or native.
+
+## Template
+
+To get started with Reason and Melange, there's an official template:
+
+```bash
+git clone https://github.com/melange-re/melange-opam-template
+cd melange-opam-template
+
+# Create opam switch and install dependencies
+make init
+
+# In separate terminals:
+
+make watch # Watch for reason file changes and recompile
+make serve # Run the development server
+```
+
+## Manual
+
+If you prefer to do all the steps manually, here is a step by step. Assuming you have an opam switch with OCaml 5.1.0. If not, check the [installation](installation.md#setup-a-new-environment-manually) guide.
+
+#### Install melange
+
+```bash
+opam install melange
+```
+
+#### Create dune-project
+
+If you don't have a `dune-project` file, create one with the following content:
+
+```lisp
+; dune-project
+(dune lang 3.8)
+(use melange 0.1) ; Here we enable melange to work with dune
+```
+
+#### Emit JavaScript
+
+In your `dune` file, add a `melange.emit` stanza to emit JavaScript.
+
+The `melange.emit` stanza tells dune to generate JavaScript files from a set of libraries and modules. In-depth documentation about this stanza can be found in the [build-system on the Melange documentation](https://melange.re/v2.0.0/build-system/#entry-points-with-melangeemit).
+
+```lisp
+; dune
+(melange.emit
+ (target app))
+```
+
+#### Libraries
+
+dune allows to define libraries by creating a dune file inside a folder and adding a library stanza: https://dune.readthedocs.io/en/stable/concepts/package-spec.html#libraries
+
+To compile a library with melange, add the `(modes melange)` stanza to the library dune file.
+
+```diff
+(library
+  (name ui_library)
++ (modes melange)
+)
+```
+
+Once you have a melange library, you can add it to the `melange.emit` stanza:
+```lisp
+; dune
+(melange.emit
+ (target app)
+ (libraries ui_library))
+```
+
+#### Compile
+
+Each time you compile the project, dune will emit JavaScript files under `_build/default/app/` (`app` comes from the `(target app)` defined under `melange.emit`).
+
+To compile the project, run:
+
+```bash
+dune build # Compile the entire project
+# or compile the melange alias (only melange.emit stanzas)
+dune build @melange
+```

docs/converting-from-js.md

@@ -2,4 +2,6 @@
 title: Converting from JS
 ---
 
-This section has been moved to the new ReScript project: https://rescript-lang.org/docs/manual/v8.0.0/converting-from-js. More info on the transition [here](https://rescript-lang.org/blog/bucklescript-is-rebranding).
+This section has been moved to ReScript project: https://rescript-lang.org/docs/manual/v8.0.0/converting-from-js. More info on the transition [here](https://rescript-lang.org/blog/bucklescript-is-rebranding).
+
+Some parts aren't relevant anymore, but the general idea is still the same. The process of introducing a new language to your project applies for Reason also.

docs/editor-plugins.md

@@ -15,7 +15,7 @@ And other features.
 
 ## Editor Plugins & Language Server
 
-Since Reason is just an alternative syntax for OCaml, we integrate seamlessly into the official OCaml editor toolchain as well.
+The OCaml Platform provides support for Reason and integrates with editors such as VSCode, Vim, or Emacs.
 
 - For VSCode, we recommend using the [vscode-ocaml-platform](https://github.com/ocamllabs/vscode-ocaml-platform) plugin, which offers OCaml & Reason support out of the box.
 - For other editors, we recommend using a language server client plugin of your choice, and pairing it with the [`ocaml-lsp`](https://github.com/ocaml/ocaml-lsp). Check out the respective README's to get started.
@@ -24,3 +24,5 @@ Since Reason is just an alternative syntax for OCaml, we integrate seamlessly in
 
 - [Vim/Neovim](https://github.com/reasonml-editor/vim-reason-plus): Make sure to use [ocaml-language-server](https://www.npmjs.com/package/ocaml-language-server) for native development as suggested. (Mac, Linux): `npm install -g ocaml-language-server`
 - [vim-reasonml](https://github.com/jordwalke/vim-reasonml): For use with [esy](https://esy.sh/), Reason, and Merlin (not LSP based). (Mac, Linux, Windows).
+- [Sublime Text](https://github.com/reasonml-editor/sublime-reason)
+- [IDEA](https://github.com/reasonml-editor/reasonml-idea-plugin)

docs/events.md

@@ -8,13 +8,14 @@ There are a Reason meetups all around the world, among others:
 - [Chicago](https://www.meetup.com/Chicago-ReasonML/)
 - [Copenhagen](https://www.meetup.com/ReasonML-CPH) ([Twitter](https://twitter.com/ReasonMLCPH))
 - [Göteborg](https://www.meetup.com/got-lambda/)
-- [Lisbon](https://www.meetup.com/ReasonML-Lisbon)
 - [Montreal](https://www.meetup.com/ReasonMTL/)
+- [New York](https://twitter.com/nycreasonml)
 - [Paris](https://www.meetup.com/ReasonML-Paris/)
-- [Phoenix](https://www.meetup.com/Phoenix-Reason)
+- [Portland](https://twitter.com/ReasonPDX)
 - [Prague](https://www.meetup.com/Reason-Prague/) ([Twitter](https://twitter.com/ReasonPrague))
 - [San Francisco](https://www.meetup.com/sv-ocaml/)
 - [Seattle](https://www.meetup.com/Seattle-ReasonML-OCaml-Meetup/)
 - [Stockholm](https://www.meetup.com/ReasonSTHLM/)
+- [Vienna](https://www.meetup.com/Reason-Vienna/) ([Twitter](https://twitter.com/reasonvienna))
 
 If you don't find your local area's Reason meetup, search on https://meetup.com or start one!

docs/faq.md

@@ -4,14 +4,39 @@ title: Frequently Asked Questions
 
 ### I'm not sure what to do with Reason
 
-You can do all the things you'd usually do with OCaml! OCaml is an incredible useful language for systems programming, while still being able to compile to pretty type safe JS with the aid of the `js_of_ocaml` compiler.
+You can do all the things you'd usually do with JavaScript or OCaml! OCaml is an incredible useful language for general programming, while still being able to compile to pretty type safe JS with the aid of the [`Melange`](https://melange.re/v2.0.0/) compiler.
 
-Natively compiled CLI's are also known to be really fast (like... C-like fast), and since the language is garbage collected, you will find yourself in a very nice spot of not having to worry about borrow-checking like in Rust and you don't have to deal with verbose non-ML languages like Go. 
+Natively compiled CLI's are also known to be really fast (like... C-like fast), and since the language is garbage collected, you will find yourself in a very nice spot of not having to worry about borrow-checking like in Rust and you don't have to deal with verbose non-ML languages like Go.
 
 Reason also gives access to the declarative UI framework [revery-ui](https://github.com/revery-ui/revery) to build native applications with a ReactJS like paradigm (+ JSX).
 
 ### What is BuckleScript and ReScript, and why is it mentioned in so many Reason related resources?
 
-Reason was originally bundled with BuckleScript (JS compiler) to provide a single toolchain for JS / ReactJS development.
+Reason was originally integrated with BuckleScript to provide a single toolchain for JavaScript and React.js development.
 
 In July 2020, BuckleScript released its own syntax and rebranded to ReScript to be its own language. More infos can be found in their [official rebranding announcement](https://rescript-lang.org/blog/bucklescript-is-rebranding).
+
+### Where do all these `print_endline`, `string_of_int` functions come from?
+They're from the standard library, pre-`open`ed during the compilation of your file. This is why you see them in scope.
+
+You can read more about the Pervasives library in the api documentation:
+
+https://reasonml.github.io/api/Pervasives.html
+
+### Why is there a + for adding ints and +. for adding floats, etc.?
+See [here](integer-and-float.md#design-decisions).
+
+### What's the `.merlin` file at the root of my project?
+That's the metadata file for [editor support](editor-plugins.md). This is usually generated for you; You don't need to check that into your version control and don't have to manually modify it.
+
+### I don't see any `import` or `require` in my file; how does module resolution work?
+Reason/OCaml doesn't require you to write any import; modules being referred to in the file are automatically searched in the project. Specifically, a module `Hello` asks the compiler to look for the file `hello.re` or `hello.ml` (and their corresponding [interface file](module.md#signatures), `hello.rei` or `hello.mli`, if available).
+
+### Is `Some | None`, `contents`, `Array`, `List` and all of these special? Where do they come from?
+They're ordinary variants/records/module definitions that come with the [standard library](/api/index.html), `open`ed by default during compilation out of convenience.
+
+### What's this `MyModule.t` I keep seeing?
+Assuming `MyModule` is a module's name, `t` is a community convention that indicates "the type that represents that module, whatever that means". For example, for the [`Js.String`](http://bucklescript.github.io/bucklescript/api/Js.String.html) module, [`String.t`](http://bucklescript.github.io/bucklescript/api/Js.String.html#TYPEt) is the type carried around and representing "a string".
+
+### What does an argument with a prepended underscore (e.g. `_` or `_foo`) mean?
+Say you have `List.map(item => 1, myList);`. The argument `item` isn't used and will generate a compiler warning. Using `_ => 1` instead indicates that you're intentionally receiving and ignoring the argument, therefore bypassing the warning. Alternatively, `_item => 1` has the same effect, but indicates more descriptively what you're ignoring.

docs/getting-started.md

@@ -0,0 +1,42 @@
+---
+title: Getting started
+---
+
+This section of the docs is all about quickly setting up a Reason development enviromanet up and running.
+
+## Get an overview of Reason
+
+```reason
+type schoolPerson =
+  | Teacher
+  | Director
+  | Student(string);
+
+let greeting = person =>
+  switch (person) {
+  | Teacher => "Hey Professor!"
+  | Director => "Hello Director."
+  | Student("Richard") => "Still here Ricky?"
+  | Student(anyOtherName) => "Hey, " ++ anyOtherName ++ "."
+  };
+
+module Intro = {
+  [@react.component]
+  let make = (~person) => {
+    <p> {React.string(greeting(person))} </p>
+  }
+};
+```
+> This snippet includes [@react.component] which comes from [reason-react](https://reasonml.github.io/reason-react/)
+
+For an introduction to most language features check out the [overview](overview.md)
+
+## Try Reason in your browser
+
+To start immediately an online REPL is available at [Sketch.sh](https://sketch.sh)
+or open the [playground](playground)
+
+## Install Reason
+
+Install Reason on your computer to start writing Reason applications.
+Check the [installation](installation.md) for a more detailed guide.

docs/installation-esy.md

@@ -0,0 +1,62 @@
+---
+title: Installation via esy
+---
+
+This page is a detailed explanation on how to install Reason with [esy](https://esy.sh/) Easy package management for native Reason, OCaml and more, both manually and using a template.
+
+Reason can be installed with a package manager like [opam](https://opam.ocaml.org/) also, check the [installation page](installation.md) for more details.
+
+### Requirements
+
+System Requirements:
+
+- Node.js 16.14 or later.
+- macOS, Windows (including WSL), and Linux are supported.
+
+Esy is distributed via npm, install it using the following command:
+
+```
+npm install -g esy
+```
+> It's recommended to install esy globally
+
+### Automatic
+Using the [`hello-reason`](https://github.com/esy-ocaml/hello-reason) template
+
+### Manual installation
+
+To add packages that happen to be hosted on npm, run `esy add npm-package-name`.
+
+To add packages from opam's registry, prefix the package name with `@opam`. `esy` treats the npm scope `@opam` specially. In this case, `esy` will install any package name with the `@opam` scope directly from [opam](https://opam.ocaml.org/packages/).
+
+```bash
+esy add @opam/bos
+```
+
+<!-- Add a warning about being crazy slow the first time -->
+
+We install reason from opam using the following command:
+
+```
+esy add @opam/reason
+```
+
+Link to getting started with esy https://esy.sh/docs/en/getting-started.html
+See the [configuration](https://esy.sh/docs/en/configuration.html) section from the complete `esy` docs.
+
+To create your first Reason native CLI program, run the following commands:
+
+```
+git clone https://github.com/esy-ocaml/hello-reason.git
+cd hello-reason
+
+# Install all dependencies (might take a while in the first run)
+esy
+
+# Compile and run Hello.exe
+esy x Hello
+```
+
+## What's Next?
+
+After you have successfully compiled your first example, it's time to [set up your editor](editor-plugins.md) to get access to all the nice features such as auto-completion. Later on you can check out the [language basics](overview.md) to get a basic understanding of all the Reason language constructs.