Lack of context in README.md example

[kachkaev]

I installed an alternative markdown grammar and ended up struggling with applying removeTrailingWhitespace: false for it (see my issue). The reason was that I did not completely get the selectors in config.cson and thought that your example lines from README.md should be a part of * or even * → whitespace. Now I completely understand how these hierarchies of settings work and the selectors make a complete sense. However, other people are likely to end up in the same situation.

Adding a bit of context to the example might help. Even something like this:

'*'
  core:
    # ...
  "some-plugin":
    # ...

'.slim.text':
  whitespace:
    removeTrailingWhitespace: false
'.anothergrammar.text':
  whitespace:
    removeTrailingWhitespace: false

It can also be noted that ".slim" and ".text" are just like CSS classes, which means that the order does not matter and a leading period is needed despite that it is not added to your grammar's scope. I wish I could understand all this a couple of hours earlier and not waste so much time making things work :–)

[philip]

Related to this, how about turning the following into a wiki entry:

#10 (comment)

And referring to that final image and description in the README.

[kachkaev]

The problem with wiki is that it suggests a different workflow for dealing with content. You can't easily clone the docs or propose a change by submitting a pull request. I prefer seeing both the docs and the source under one roof unless the docs are way too large, which makes the repo unreasonably heavy.

[philip]

How about a mix: expand the README by mentioning the 'Remove Trailing Whitespace' configuration option, and include two grammar examples as you propose, but also create a more detailed entry elsewhere (such as the wiki) that can include, for example, the screenshot.