Documentation improvement suggestions

[bbatsov]

Hey there!

I just came across the project (which looks pretty cool, btw) and I have a couple of small suggestions to improve the docs:

• Might be a good idea to publish the docs folder to a service like ReadTheDocs. This requires almost no work from you, just adding a configuration file for the service. I didn't notice the doc files originally and I thought the README was a bit short on details.
• I think it'd be great if there's some rationale for rewriting cljfmt (which I've been using for a while), as it's not very clear what exactly are the advantages of cljstyle
• I think it's a good idea to indicate where are the defaults derived from. I'm hoping that's the community style guide, but I couldn't find any indication of this in the docs.

Thanks for the great project! 🙇

[greglook]

Hi bbatsov, thanks! Publishing would be neat - there are links from the relevant README sections, but maybe they're not discoverable enough.

I'll put the rationale in a doc, but there were a couple of things I wanted when I first forked cljfmt:

• A better way to specify configuration local to certain bits of code.
• Namespace-matched and pattern-matched indent rules.
• Enforced line-breaks for some function, var, and type forms.
• Canonical ns rewriting.
• A stand-alone binary tool.

The defaults are indeed mostly from the community style guide, with the main exception being the default two-space indent. That's configurable back to one space for those who want it, but it never really made sense to me.

[bbatsov]

Sounds good to me!

The defaults are indeed mostly from the community style guide, with the main exception being the default two-space indent. That's configurable back to one space for those who want it, but it never really made sense to me.

I know this is probably the most controversial topic when it comes to code layout, but I was doing Lisp(s) way before Clojure, so I got used to this a long time ago. :-) As a bonus - it makes it really easy to spot some macro that operates on a body of code and function calls with multi-line arguments. Anyways, I understand your point.