Add Syntax page #200

feihong · 2024-10-18T02:02:56Z

Addresses #38

feihong · 2024-10-18T02:03:48Z

docs/.vitepress/config.mts

@@ -103,6 +103,7 @@ export default defineConfig({
        items: [
          { text: "What is Melange", link: "/what-is-melange" },
          { text: "Rationale", link: "/rationale" },
+          { text: "Syntaxes", link: "/syntaxes" },


It's in its own page, but maybe it should be merged into Getting Started instead?

For some reason "Syntaxes" doesn't sound good to me (?), maybe it's just an impression but would "Supported syntaxes" make more sense or I'm tripping?

Renamed to "Supported syntaxes" in 5bacbf3

feihong · 2024-10-18T02:05:57Z

docs/syntaxes.md

+  "opam-check-npm-deps" {with-test}
+  "ocaml-lsp-server" {with-test}
+  "dot-merlin-reader" {with-test}


Should with-test be replaced by dev? I copied this directly from melange-opam-template.

Yes, I'd replace it as 2.2 is released now. It is with-dev-setup though.

@jchavarri I created PR to update melange-opam-template: melange-re/melange-opam-template#38

Changed to with-dev-setup in 5bacbf3

docs/syntaxes.md

feihong · 2024-10-23T00:46:43Z

cc @psb

jchavarri

Looking good, it'd be great if @davesnx could also check as he suggested the idea of new "Syntaxes" section.

cc @anmonteiro

docs/syntaxes.md

jchavarri · 2024-10-23T06:53:18Z

docs/syntaxes.md

+  "opam-check-npm-deps" {with-test}
+  "ocaml-lsp-server" {with-test}
+  "dot-merlin-reader" {with-test}


Yes, I'd replace it as 2.2 is released now. It is with-dev-setup though.

jchavarri · 2024-10-23T06:53:45Z

docs/syntaxes.md

+opam install -y . --deps-only
+```
+
+Note that reason support is already set up for you in


Suggested change

Note that reason support is already set up for you in

Note that Reason support is already set up for you in

Fixed in 5bacbf3

jchavarri · 2024-10-23T06:55:50Z

docs/syntaxes.md

+Note that reason support is already set up for you in
+[melange-opam-template](https://github.com/melange-re/melange-opam-template).
+
+## Editor configuration


I would mention that this is the "Editor configuration for Reason syntax" and somehow reference the previously existing Editor conf section.

Alternatively, move this editor conf section to /getting-started.html to consolidate all editor config under a single section, and maybe specify the part that is Reason specific with a link to /syntaxes page.

I added link to "Editor integration" section of getting-started. Also added a link from "Editor integration" back to this page. It seems a bit circular, but I figure that explaining how to set up format-on-save for Reason syntax doesn't necessarily make sense if it hasn't been explained what Reason syntax is.

ac4e7d6

docs/syntaxes.md

davesnx

I would add a section on "Formatters" explaining refmt for Reason and ocamlformat for OCaml

davesnx · 2024-10-23T08:28:57Z

docs/syntaxes.md

+To install Reason syntax support add `reason` to the `depends` section of the
+`<project-name>.opam` file in your project:


I would expect a link to reasonml docs somewhere here

Added links to both OCaml syntax and Reason syntax in the opening paragraph: 5bacbf3

davesnx · 2024-10-23T08:31:38Z

docs/syntaxes.md

@@ -0,0 +1,64 @@
+# Syntaxes
+
+Melange supports two syntaxes: OCaml syntax (the default) and Reason syntax.


I would add a paragraph on what we mean by syntaxes, before we say melange supports both

I would mention that the syntax for the melange website can be toggled.

I explain how to toggle syntaxes in 5bacbf3

I would add a paragraph on what we mean by syntaxes, before we say melange supports both

I added an example snippet before explaining the difference in 5bacbf3. Is that good enough?

davesnx · 2024-10-23T08:33:04Z

docs/syntaxes.md

+
+## Editor configuration
+
+To enable format-on-save in VS Code:


Probably link to reasonml editor for more info? and same for OCaml?

What page do you want to link to?

Probably https://reasonml.github.io/docs/en/editor-plugins

Added link in c36a87e

feihong

I would add a section on "Formatters" explaining refmt for Reason and ocamlformat for OCaml

Added a Formatters section in 5bacbf3

feihong · 2024-10-25T01:23:03Z

docs/syntaxes.md

+  "opam-check-npm-deps" {with-test}
+  "ocaml-lsp-server" {with-test}
+  "dot-merlin-reader" {with-test}


@jchavarri I created PR to update melange-opam-template: melange-re/melange-opam-template#38

feihong · 2024-10-29T04:19:33Z

docs/.vitepress/config.mts

@@ -103,6 +103,7 @@ export default defineConfig({
        items: [
          { text: "What is Melange", link: "/what-is-melange" },
          { text: "Rationale", link: "/rationale" },
+          { text: "Syntaxes", link: "/syntaxes" },


Renamed to "Supported syntaxes" in 5bacbf3

feihong · 2024-10-29T04:22:16Z

docs/syntaxes.md

@@ -0,0 +1,64 @@
+# Syntaxes
+
+Melange supports two syntaxes: OCaml syntax (the default) and Reason syntax.


I explain how to toggle syntaxes in 5bacbf3

I would add a paragraph on what we mean by syntaxes, before we say melange supports both

I added an example snippet before explaining the difference in 5bacbf3. Is that good enough?

feihong · 2024-10-29T04:23:37Z

docs/syntaxes.md

+To install Reason syntax support add `reason` to the `depends` section of the
+`<project-name>.opam` file in your project:


Added links to both OCaml syntax and Reason syntax in the opening paragraph: 5bacbf3

feihong · 2024-10-29T04:24:20Z

docs/syntaxes.md

+  "opam-check-npm-deps" {with-test}
+  "ocaml-lsp-server" {with-test}
+  "dot-merlin-reader" {with-test}


Changed to with-dev-setup in 5bacbf3

feihong · 2024-10-29T04:24:34Z

docs/syntaxes.md

+opam install -y . --deps-only
+```
+
+Note that reason support is already set up for you in


Fixed in 5bacbf3

docs/syntaxes.md

feihong · 2024-10-29T04:27:47Z

docs/syntaxes.md

+
+## Editor configuration
+
+To enable format-on-save in VS Code:


What page do you want to link to?

feihong · 2024-10-29T04:38:30Z

docs/syntaxes.md

+Note that reason support is already set up for you in
+[melange-opam-template](https://github.com/melange-re/melange-opam-template).
+
+## Editor configuration


I added link to "Editor integration" section of getting-started. Also added a link from "Editor integration" back to this page. It seems a bit circular, but I figure that explaining how to set up format-on-save for Reason syntax doesn't necessarily make sense if it hasn't been explained what Reason syntax is.

ac4e7d6

davesnx · 2024-10-30T09:52:57Z

docs/syntaxes.md

+the [OCaml Platform VS Code
+extension](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform),
+works well with Reason, but some tools aren't completely aware of it—for
+example, error messages from the compiler still use OCaml syntax.


I would either link the issue here or not even mention this, since it's not always the case. Sometimes the error gets in reason and sometimes it doesn't

Deleted that line in 55b49d4

davesnx

Looks awesome, good job @feihong

jchavarri

Thanks!

jchavarri · 2024-10-30T10:09:23Z

docs/syntaxes.md

+On the command line, run
+
+```bash
+opam install -y . --deps-only


Should we mention that alternatively, users can just run opam install reason -y?

Added alternate command in 55b49d4

docs/syntaxes.md

feihong requested review from davesnx and jchavarri October 18, 2024 02:03

Add Syntax page

ae2f577

feihong force-pushed the syntax-page branch from 657a195 to ae2f577 Compare October 18, 2024 02:07

feihong commented Oct 18, 2024

View reviewed changes

feihong marked this pull request as ready for review October 18, 2024 02:09

jchavarri approved these changes Oct 23, 2024

View reviewed changes

davesnx reviewed Oct 23, 2024

View reviewed changes

feihong added 2 commits October 28, 2024 21:55

Edits in response to feedback

5bacbf3

Link to and from getting-started in syntaxes

ac4e7d6

feihong commented Oct 29, 2024

View reviewed changes

feihong requested review from davesnx, jchavarri and psb October 29, 2024 04:38

feihong force-pushed the syntax-page branch 2 times, most recently from 7e12f37 to 030b370 Compare October 30, 2024 02:47

Add links for setup of other editors

390113c

feihong force-pushed the syntax-page branch from 030b370 to 390113c Compare October 30, 2024 03:01

davesnx reviewed Oct 30, 2024

View reviewed changes

davesnx approved these changes Oct 30, 2024

View reviewed changes

jchavarri approved these changes Oct 30, 2024

View reviewed changes

psb approved these changes Oct 30, 2024

View reviewed changes

Delete line about error messages not being aware of Reason syntax

55b49d4

feihong merged commit 0d54e6c into master Oct 31, 2024

feihong deleted the syntax-page branch October 31, 2024 02:02

	Note that reason support is already set up for you in
	Note that Reason support is already set up for you in

		To install Reason syntax support add `reason` to the `depends` section of the
		`<project-name>.opam` file in your project:

		@@ -0,0 +1,64 @@
		# Syntaxes

		Melange supports two syntaxes: OCaml syntax (the default) and Reason syntax.

Add Syntax page #200

Add Syntax page #200

Conversation

feihong commented Oct 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

feihong commented Oct 23, 2024

jchavarri left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davesnx left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

feihong left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davesnx Oct 30, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davesnx left a comment

Choose a reason for hiding this comment

jchavarri left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

feihong commented Oct 18, 2024 •

edited

Loading

davesnx Oct 30, 2024 •

edited

Loading