search

tweag / ormolu

A formatter for Haskell source code
https://ormolu-live.tweag.io
Other
958 stars 83 forks source link

Document in README how code is formatted #861

Closed andreasabel closed 2 years ago

andreasabel commented 2 years ago

Add an example how code is formatted to your README, like in https://github.com/haskell/stylish-haskell#example. Atm, there is no quick way to find out what ormolu is doing. (The live page is just a blank page.)

amesgen commented 2 years ago

Atm, there is no quick way to find out what ormolu is doing. (The live page is just a blank page.)

I heard this from several persons now, and I can't reproduce it, I opened https://github.com/tweag/ormolu/issues/862 for it. If you see something in the Javascript console, can you maybe create a comment there?

In any case, coming up with a nice example of Ormolu output in the README seems like a good idea. We could just reuse the stylish-haskell snippet for example.

andreasabel commented 2 years ago

We could just reuse the stylish-haskell snippet for example.

Yes, this would be a good start.

mrkkrp commented 2 years ago

Ormolu live is now working. I think it is the best way to let people know how Ormolu formats the code. I'm not super sure what we could include as a demo snippet in the readme, because no matter what we pick (unless we include a fairly long snippet) it cannot be comprehensive. Closing.

mrkkrp commented 2 years ago

(I don't think the snippet from stylish-haskell would reveal enough in Ormolu's case, because IIRC stylish-haskell only touches some very specific elements of a module, while Ormolu formats everything.)

andreasabel commented 2 years ago

Yes, but demonstrating a fraction of the functionality is better than demonstrating nothing.

mrkkrp commented 2 years ago

Demonstrating everything (which is what Ormolu live does) is better still than demonstrating a fraction of functionality.

Another advantage of Ormolu live versus a fixed snippet is that we don't need to worry about it going out of date.

That said, if you open a PR adding an example snippet to the readme I will merge it. However, I don't think this is worth having an issue about it.

andreasabel commented 2 years ago

The small flaw in the ointment is that https://ormolu-live.tweag.io/ presents me with a blank slate.

Maybe the live demo could be filled with an example code, or you could have a menu where several examples can be tried.

You can shorten the path to obtain information about the formatting style. Currently it is:

  1. ormulo home: https://github.com/tweag/ormolu : no information.
  2. Navigate to live demo page: no information yet.
  3. Look for some code and paste it there: finally, some information.

(What I originally suggested would give some information already at step 1.)

mrkkrp commented 2 years ago

This would be important if source code formatters were like clothes in a shop. You look and compare A and B and choose the one you like. In reality, though

  1. There are not so many options.
  2. They all have different philosophies and scopes.
  3. They have different levels of robustness.

So chances are, you are

  1. Going to spend much more time anyway making a choice (in not 5 seconds, and not by looking at a snippet)
  2. That choice is going to depend on the level of maturity and design of the tool
  3. It is not going to be due to purely cosmetic reasons.