Clarify when original styling is significant (#1620)
* Clarify when original styling is significant * add superscript "1" as footnote link * use "*" instead of "1" to denote a caveatmaster
parent
4e9cdc413c
commit
2fd7199c11
13
README.md
13
README.md
|
@ -33,7 +33,7 @@
|
|||
Prettier is an opinionated JavaScript formatter inspired by
|
||||
[refmt](https://facebook.github.io/reason/tools.html) with advanced
|
||||
support for language features from [ES2017](https://github.com/tc39/proposals/blob/master/finished-proposals.md), [JSX](https://facebook.github.io/jsx/), and [Flow](https://flow.org/). It removes
|
||||
all original styling and ensures that all outputted JavaScript
|
||||
all original styling[\*](#styling-footnote) and ensures that all outputted JavaScript
|
||||
conforms to a consistent style. (See this [blog post](http://jlongster.com/A-Prettier-Formatter))
|
||||
|
||||
If you are interested in the details, you can watch those two conference talks:
|
||||
|
@ -49,7 +49,7 @@ formatted JavaScript as output.
|
|||
|
||||
In technical terms: Prettier parses your JavaScript into an AST (Abstract Syntax Tree) and
|
||||
pretty-prints the AST, completely ignoring any of the original
|
||||
formatting. Say hello to completely consistent syntax!
|
||||
formatting[\*](#styling-footnote). Say hello to completely consistent syntax!
|
||||
|
||||
There's an extremely important piece missing from existing styling
|
||||
tools: **the maximum line length**. Sure, you can tell ESLint to warn
|
||||
|
@ -108,10 +108,17 @@ foo(
|
|||
)
|
||||
```
|
||||
|
||||
Prettier bans all custom styling by parsing it away and re-printing
|
||||
Prettier bans all custom styling[\*](#styling-footnote) by parsing it away and re-printing
|
||||
the parsed AST with its own rules that take the maximum line width
|
||||
into account, wrapping code when necessary.
|
||||
|
||||
<a href="#styling-footnote" name="styling-footnote">\*</a>_Well actually, some
|
||||
original styling is preserved when practical—see [empty lines] and [multi-line
|
||||
objects]._
|
||||
|
||||
[empty lines]:Rationale.md#empty-lines
|
||||
[multi-line objects]:Rationale.md#multi-line-objects
|
||||
|
||||
## Usage
|
||||
|
||||
Install:
|
||||
|
|
10
Rationale.md
10
Rationale.md
|
@ -44,6 +44,16 @@ Prettier outputs the minimum number of parentheses required to ensure that the b
|
|||
It turns out that empty lines are very hard to automatically generate. The approach that prettier takes is to preserve empty lines the way they were in the original source code. The only constraint is that prettier disallows several empty lines in a row. They are collapsed to a single one.
|
||||
|
||||
|
||||
### Multi-line objects
|
||||
|
||||
It is tempting to collapse an object to a single line if it fits, but there are times when it is better for sibling/cousin keys to stay vertically aligned—see [object lists], [nested configs], [stylesheets], and [keyed methods]. To avoid unfavorable collapsing, prettier simply formats any object as multi-line if it appears as such in the original source code. This is the same strategy used by [elm-format] for multi-line records.
|
||||
|
||||
[object lists]:https://github.com/prettier/prettier/issues/74#issue-199965534
|
||||
[nested configs]:https://github.com/prettier/prettier/issues/88#issuecomment-275448346
|
||||
[stylesheets]:https://github.com/prettier/prettier/issues/74#issuecomment-275262094
|
||||
[keyed methods]:https://github.com/prettier/prettier/pull/495#issuecomment-275745434
|
||||
[elm-format]:https://github.com/prettier/prettier/issues/74#issuecomment-275621526
|
||||
|
||||
## What prettier is _not_ concerned about
|
||||
|
||||
Here are a few examples of things that are out of scope for prettier:
|
||||
|
|
Loading…
Reference in New Issue