Use human readable key value pairs for configuration.

[cirosantilli]

Instead of the MDXXX ids, why don't we use human readable key value pairs like:

unordered_list_marker: '*'

Advantages:

• human readable: people can just read the config file directly to determine the style. Currently, you would have to look up what every rule means, or use comments, which generates a lot of explanation. Same reason why we use nice var names in the code.
• pairs: deal nicely with mutually exclusive options like choosing one header or list style, in which enforcing multiple rules should never be done. Would solve: Warn when conflicting rules enabled #38

Disadvantage: longer to type. But this is not serious, since projects will write a config file and seldom modify it, and for interactive use according to personal preferences one can just alias it or we can add a global config. Being able to read quickly is more important in this case.

This is what the popular Rubocop does: https://github.com/bbatsov/rubocop/blob/master/config/default.yml.

This could be implemented in either Ruby or YAML: I'd rather have YAML since it allows us not to write rule directives all the time and since the config is mostly static, but this is no big deal.

Also once we fix those things we should document it. I had to Google and grep a bit to figure it out =) #41

[mivok]

I'm not sure how I feel about not having a numeric ID for rules, but the two arguments I have in favor of them (easier to type and refer to in chat/IM/issues, and no need to change the ID later if the name doesn't make sense any more, such as if I'd named MD007 'multimarkdown_list_indent' before discovering another reason for wanting 4 space indents) aren't that strong. The inspiration for this way of doing things btw is Foodcritic rather than rubocop. It's interesting to see the different choices made between the two.

I do really like the idea of having rules be able to take parameters in style files, and it does neatly solve the issue of multiple rules that do essentially the same thing as well as conflicts.

[mivok]

Parameters are done and in a branch. They'll be merged once I clean up the rules to use them.

However, regarding rule names, I think I'm still going to come down on the side of
having a short, mostly numeric, identifier for all rules. I've thought about
it quite a bit and there are two other issues I came across while trying out
named rules:

• Some of the later rules will end up with rule names almost as long as the
  descriptions in order to fully specify what they do (e.g. multiple spaces
  inside hash on atx_closed headers), and while parameters have helped with some
  of those (the header style rule description is much more concise), it won't
  help everywhere.
• Remembering the name of the rule without looking it up is more difficult than
  remembering a shorter number (e.g. was the rule name
  header_trailing_blank_line, header_surround_blank_lines or something else).

Both of these could be solved with aliases, but that sacrifices
recognizability of a given rule, especially if more terse forms are used, and
you're right back to the original issue that prompted having.

Ultimately, the tradeoff is reading and recognizing (in style files or other
places where it won't have the description printed next to the ID) vs writing
and remembering.

[cirosantilli]

I understand the difficulty, and of course the final decision is up to you.

I believe:

1. When writing the config file: both numbers and meaningful names are hard enough to remember that people writing the config file will have to look up the docs in both cases for a very long time before they are confident enough with them to write the config without checking.
2. When reading:
   • for readable IDs, you might have to look a few times at the docs, but it is likely that you will soon be able to guess correctly what they mean.
   • for numbers, readers will have to look at the docs for way longer before they memorize what they mean. They could always add comments to the config file, but then why not use the comment strings as data instead of the IDs?

People will read the files much more than they write them, since every contributor has to read it to know what style to use, but only a few owners will modify the file occasionally.

[mivok]

The rule parameters option has been merged. As part of this, I updated the style files to not have to exclude the rules that have now been removed. As part of this, I simplified the cirosantilli style file significantly. Let me know if the changes make sense or not.

For now I'm closing this issue. Docs on creating style files/rules/parameters I'll add as a separate issue.