3.6.5 grammar pickles

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index 205163f3e158d92cdd6be653fda388980a18c0d2..cef3283efbb03d3b9fd3217de86a4606d3a0936d 100644 (file)
--- a/README.md
+++ b/README.md
@@ -53,13 +53,18 @@ black [OPTIONS] [SRC]...
 
 Options:
   -l, --line-length INTEGER   Where to wrap around.  [default: 88]
-  --check                     Don't write back the files, just return the
+  --check                     Don't write the files back, just return the
                               status.  Return code 0 means nothing would
                               change.  Return code 1 means some files would be
                               reformatted.  Return code 123 means there was an
                               internal error.
+  --diff                      Don't write the files back, just output a diff
+                              for each file on stdout.
   --fast / --safe             If --fast given, skip temporary sanity checks.
                               [default: --safe]
+  -q, --quiet                 Don't emit non-error messages to stderr. Errors
+                              are still emitted, silence those with
+                              2>/dev/null.
   --version                   Show the version and exit.
   --help                      Show this message and exit.
 ```
@@ -262,12 +267,27 @@ keep it.
 
 ### Strings
 
-*Black* prefers double quotes (`"` and `"""`), but only if this does not
-result in more escaping. It will remove escape sequences as necessary as
-part of moving to the other type of quote. This applies to all kinds of
-prefixed strings, including *raw-strings* (`r""`), *byte literals* (`b""`),
-and *formatted strings* (`f""`). The approach above strikes a good balance
-between consistency and legibility.
+*Black* prefers double quotes (`"` and `"""`) over single quotes (`'`
+and `'''`).  It will replace the latter with the former as long as it
+does not result in more backslash escapes than before.
+
+The main reason to standardize on a single form of quotes is aesthetics.
+Having one kind of quotes everywhere reduces reader distraction.
+It will also enable a future version of *Black* to merge consecutive
+string literals that ended up on the same line (see
+[#26](https://github.com/ambv/black/issues/26) for details).
+
+Why settle on double quotes?  They anticipate apostrophes in English
+text.  They match the docstring standard described in PEP 257.  An
+empty string in double quotes (`""`) is impossible to confuse with
+a one double-quote regardless of fonts and syntax highlighting used.
+On top of this, double quotes for strings are consistent with C which
+Python interacts a lot with.
+
+On certain keyboard layouts like US English, typing single quotes is
+a bit easier than double quotes.  The latter requires use of the Shift
+key.  My recommendation here is to keep using whatever is faster to type
+and let *Black* handle the transformation.
 
 
 ## Editor integration
@@ -392,10 +412,19 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
-### 18.3a5 (unreleased)
+### 18.4a1
+
+* added `--quiet` (#78)
 
-* add line breaks before all delimiters, except in cases like commas, to better
-  comply with PEP8 (#73)
+### 18.4a0
+
+* added `--diff` (#87)
+
+* add line breaks before all delimiters, except in cases like commas, to
+  better comply with PEP 8 (#73)
+
+* standardize string literals to use double quotes (almost) everywhere
+  (#75)
 
 * fixed handling of standalone comments within nested bracketed
   expressions; Black will no longer produce super long lines or put all
@@ -404,6 +433,9 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 * fixed 18.3a4 regression: don't crash and burn on empty lines with
   trailing whitespace (#80)
 
+* fixed 18.3a4 regression: `# yapf: disable` usage as trailing comment
+  would cause Black to not emit the rest of the file (#95)
+
 * when CTRL+C is pressed while formatting many files, Black no longer
   freaks out with a flurry of asyncio-related exceptions
 
@@ -518,3 +550,4 @@ Multiple contributions by:
 * Hugo van Kemenade
 * [Mika Naylor](mailto:mail@autophagy.io)
 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
+* [Zsolt Dollenstein](mailto:zsol.zsol@gmail.com)