This is a large commit that does the following:
* Removes backticks from messages and comments.
All references to backticks have been replaced with double quotes everywhere the
code is not interpreted as Markdown, (ie. anywhere outside documentation and
markdown files, such as in code comments, or error messages).
* Variables in Exception messages are printed using `inspect`
The way no-matching error message are printed, have changed because now we use inspect for printing
variables. The following file and their respective test have been changed:
- lib/elixir/lib/exception.ex
- lib/elixir/lib/inspect/algebra.ex
- lib/elixir/test/elixir/inspect_test.exs
- lib/ex_unit/test/ex_unit/formatter_test.exs
- lib/elixir/test/elixir/exception_test.exs
* Properly use Title Case for Mix, Git, Dializer
* Use backticks when citing a command
****************************************************
CONVENTION FOR RENAMING USING BACKTICKS AND QUOTES
https://github.com/elixir-lang/elixir/pull/3697#issuecomment-138811747
1. Backticks should never be printed in error messages, neither be included anywhere where Markdown code is not interpreted as such.
2. Do not use single quotes anywhere. We should favor double quotes everywhere, to avoid confusion
3. If you want to format something in error messages, use inspect. For example, if you want to show the dependency name and that is an atom, instead of the dependency "foo", let's show the dependency :foo. Less noise and may click better
4. Similarly, if you want to show something with double quotes, call inspect, as it handles escaping as well as the quotes
5. Things like "--all" just add verbosity, we can definitely read --all without ambiguity.
6. When using switches with a single hyphen (such as "-o"), we can make it explicit in the text: e.g. "... give the switch -o when choosing ..."
****************************************************
SHELL COMMANDS TO DETECT CODE BREAKING THE RULES
* Detect values surrounded by single-quotes where we want double-quotes.
# regular variables
ag "'#{"
# constants or ENV variables
ag "'[A-Z][A-Z0-9_-]+"
# switches
ag -i "(?<!(\[))'--?[a-z0-9][a-z0-9_-]+'"
# atoms
ag -i "(?<!(\[))':[a-z0-9][a-z0-9_-]+'"
# DETECT BACKTICKS OUTSIDE DOCS
ag "^\s+(?<!(#))#[^#\r\n]*\`" --ignore "*.md"
ag '^\s+["%].*`' --ignore "*.md"
ag -s '(raise|Error)\b(?!(`|/)).*\`'
* Spot mentions to running a command that is not using backticks:
commands="elixir|elixirc|mix|iex|ex_doc|git|make|rebar|dialyzer|erl|rm|cd|mkdir|rmdir|ln|ls|pwd"
actions="runs?|running|executes?|executing|types?|typing|enters?|entering|calls?|calling"
ag '(?i)('${actions}')(?-i)\b[^`\r\n/]+[\ \t]+(?!(`))('${commands}')'
ag '(?-i)\b(?!(`))('${commands}')[\ \t]+[^`\r\n/]+(?i)(commands?)'
* Spot where a command is mentioned:
#commands="erlang|elixir|eex|iex|ex_unit|ex_doc|logger|elixirc|git|make|rebar|dialyzer|erl|rm|cd|mkdir|rmdir|ln|ls|pwd"
commands="mix|elixirc|git|make|rebar|dialyzer|erl|rm|cd|mkdir|rmdir|ln|ls|pwd"
ag -s '(?<!(\`))(?<!(\.))(?<!(/))(?<!(:))(?<!(_))\b('${commands}')\b(?!(:))(?!(\?))(?!(_))(?!(-))(?!(\.))(?!(\`))(?!(/))(?!(>))' \
--ignore "*.erl" --ignore "*.yrl" --ignore "*.src"
For the ones in the documentation, a space will be added in after the hyphen.
Just for consistency and to ease detection, I have replaced the ones in
comments as well.
Command to detect these lines:
ag "\w+-\n"
It makes it consistent with the rest of the docs.
I have just looked for the first line in @doc, @moduledoc, so lines bellow it may still need
to be corrected.
@shortdoc all have been corrected.
Inspired by: https://github.com/elixir-lang/elixir/pull/2942
Command to list the first lines:
```sh
# first line in @moduledoc / @doc
ag '(@(module)?doc)\s+("{3})(\r|\n|.)\s*+[\w-]+(?<!s)\b'
# also @shortdoc
ag '(@shortdoc)\s+("{1,3})(\r|\n|.)\s*+[\w-]+(?<!s)\b'
```
If the `trim` option is used, trims around EEx tags:
- On left, up to the line break if all whitespace
- On right, up to and including the line break if all whitespace
Does not trim around quotations (`<%% %>`), but does trim around
any tags inside a quotation.
Closes#3154
Add column info for each token in elixir_tokenizer.
Change the format of location info from `Line` to `[Line, BeginColumn,
EndColumn]`. Pass the current column after the current line in
`elixir_tokenizer:tokenize`. Reflect the change in related modules.
The rules are similar to those for the unordered lists (see previous
commits). Subsequent lines and paragraphs should be aligned to the
beginning of the sentence on the first line, like this:
1. This is a list item,
it has a second line.
Also paragraph.
2. Second list item.
code fragment
Short, one-sentence items that can be read as part of the surrounding
paragraph can start with a non-capital letter
* Never use capital letters after `-`. Sentences start right after
the bullet and continue to the first period.
* When list elements are one or two sentences, use non-capitalized
format without terminators.
The two sentences are converted into one, separated by a semicolon.
This mainly applies to the cases with short sentences or when only
one of many list elements needs to have two sentences.
Example:
* `:opt_a` - basic description, no terminator
* `:opt_b` - also short description; this used to be second
sentence
* When at least one list element needs to have real sentences,
the whole list is formatted like that, with a period at the end
of each element:
* `:opt_a` - this is still short.
* `:opt_b` or `:opt_c` - but this is longer. May have multiple
sentences.
Or even paragraphs.
List items are marked with a star (*). Bullets marking list elements
must have a 2-space indent. The continuation lines should be indented
by 2 more spaces.
The second and subsequent paragraphs need to be indented 4 spaces
from the beginning of the line to be included in the list item.
The code fragments have to be indented 8 spaces from the beginning
of the line (or 4 spaces from the beginning of the preceding paragraph).
Sublists are marked with a hyphen (-). They follow the rules above
with the difference that their initial indent will be greater
(8 spaces from the beginning of the line).
eksperimental
José Valim
Louis Pilfold
Or Neeman
José Valim
Alexander Ivanov
Doug Yun
Shayan Pooya
Peter Ericson
Alexei Sholik
chyndman
Igor Kapkov
Eric Meadows-Jönsson