add Topiary to “Formatting Your Code”

[toastal]

Topiary is a viable code formatter for OCaml projects. My favorite feature compared to its competitor is that Topiary can be configured to use tab indentation for user accessibility (which affects me). While Topiary can be configured, it isn’t as intuitive to configure as many other code formatters that just look for a specific file in a specific location.

Additionally, I removed the implicit assumptions of OCamlFormat in the description & title since the sidebar & URL slug generically state “Formatting Your Code” without specifying a tool. This also required moving the file whose name implied OCamlFormat.

It would have been nice to use a callout/admonition for the “TIP:”, but Markdown does not support this feature.

¹

Footnotes

1. Please consider giving up MS GitHub or offering a non-proprietary, non-US-corporate-controlled mirror for this free software project. I wish to delete this Microsoft account in the future, but I need more projects like this to support alternative methods to send patches & contribute. ↩

[bbatsov]

You've changed the URL of the page, so you'll need to add some redirect from the old one.

[toastal]

You've changed the URL of the page, so you'll need to add some redirect from the old one.

I don’t think this is true. The Markdown YAML heading thing’s id value has not changed. However, the filename (& title) should change as it doesn’t reflect that id (& by proxy the URL slug) as well as the sidebar’s “Formatting your Code” — else you don’t want to give the wrong impression that there is just one formatter.

[bbatsov]

I don’t think this is true. The Markdown YAML heading thing’s id value
has not changed. However, the filename (& title) should change as it
doesn’t reflect that id (& by proxy the URL slug) as well as the
sidebar’s “Formatting your Code” — else you don’t want to give the wrong
impression that there is just one formatter.

My bad. I saw the filename change and at first I assume that the slug was changed to match it.

[yawaramin]

Imho, the OCaml website should document how to use the tools of the OCaml Platform. It's OK to provide a link to other resources like eg Topiary for formatting and Nix for package management, but as I understand it the goal of this site is not to provide documentation on those alternatives.

[toastal]

If that is the case, then how to get something listed as “Tools with a status of "active" or "sustain" are considered stable and mature”? This has been a stable project that does things other the other formatters do not.

[yawaramin]

I think that is a separate question for discussion in the forum.

[cuihtlauac]

Waiting input from discuss.ocaml.org on this.

[sabine]

Imho, the OCaml website should document how to use the tools of the OCaml Platform. It's OK to provide a link to other resources like eg Topiary for formatting and Nix for package management, but as I understand it the goal of this site is not to provide documentation on those alternatives.

I think the question of what exactly the OCaml.org website should present here is open for interpretation and a good topic for a community discussion on https://discuss.ocaml.org. I don't think we have a clear policy here yet. Do you want me to open a discussion?

Obviously, documenting the OCaml Platform Tools is a main goal, but I could see having every tooling-focused document have a section at the end listing alternatives (only projects that are production ready and stable).

If that is the case, then how to get something listed as “Tools with a status of "active" or "sustain" are considered stable and mature”?

We have a description of what it takes to become an OCaml Platform Tool here: https://ocaml.org/policies/governance#iv-ocaml-platform

[toastal]

@yannham

[yawaramin]

How about we mention Topiary as an alternative at the end of the formatting tutorial and link to a Cookbook Recipe for it? I want to avoid adding too much detail about alternatives to the tutorials as per

ocaml.org/DOCUMENTATION_WRITING.md

Line 42 in c75be9b

- **Avoid Overwhelming Choices**. Tutorials should guide learners on a straightforward path, avoiding multiple options. This makes the learning process smoother. Detailed choices can be included in additional references and guides.

Avoid Overwhelming Choices. Tutorials should guide learners on a straightforward path, avoiding multiple options. This makes the learning process smoother. Detailed choices can be included in additional references and guides.

[toastal]

The documentation could also be stripped down. While there are defaults (no need for a blank .topiary.cfg.ncl just to run formatter lol), I think the tricky parts of using Topiary is that there is (no longer) something akin to $PROJECT_ROOT/.topiary.cfg.ncl for users to easily/obviously set their settings in a project with teammates—which is why I ended up doing full documentation on how to set that part up since otherwise it seems almost like you can’t configure it.

[sabine]

I think the tricky parts of using Topiary is that there is (no longer) something akin to $PROJECT_ROOT/.topiary.cfg.ncl for users to easily/obviously set their settings in a project with teammates—which is why I ended up doing full documentation on how to set that part up

Is there a good place where we could put this so ocaml.org can link to it?

[yawaramin]

I recommend making it a Cookbook Recipe: https://ocaml.org/cookbook