scomma / aksornklang

Official style guide
https://aksorn.org/
MIT License
5 stars 7 forks source link

Official Style Guide for Aksorn

This is the official reference that is applied by the Aksorn engine. Like a secret sauce minus the secrecy.

For more information please refer to About Aksorn.

Syntax

Ruleset

In the context of the style guide, a ruleset is a group of rules aimed at catching a particular class of stylistic errors. It is defined by a text file comprising of zero or more rules separated by a blank line.

Rule

A rule is composed of up to two parts: at least one or more match patterns, and the optional suggest text. It is defined by consecutive non-blank lines in the ruleset file. If there are two or more lines, the final line is understood to be the suggestion. For example, this is how rules are interpreted:

match1
match1
suggest
match1
match2
match3
suggest

The pattern is a regular expression. It usually employes lookbehinds heavily to prevent false positives, because the text is not tokenized before being processed. The suggest part is just plain text.

Regular Expression

Regular expression is a standard programming language for describing patterns. If you are not familiar with it, read this introduction to regular expression in Thai, then test your patterns in Rubular. Even if you are familiar with it, Rubular can be tremendously helpful.

Sometimes it is necessary to use lookbehind assertions in our patterns, but many major browser engines do not support it, with an exception of Google Chrome. The Aksorn engine will ignore those patterns. There is no way around this problem except petitioning browser vendors.

Contributing

  1. If you are not fluent in regular expression, feel free to open an issue so that someone fluent may step in.
  2. Create a pull request. You may work on an existing ruleset, or start a new ruleset.
  3. It is entirely valid to have a rule with no reference, but where appropriate, the commit message should cite one.
  4. Fierce debates are welcome and encouraged.
  5. The maintainers consider themselves curators of this particular style guide and reserve the final say in accepting or rejecting any contribution.