X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/e5f8251704c22b143b79474905c6c4b7e10ddb47..a42aef780630bce97c01dbf33a1947ea108e6e29:/README.md

diff --git a/README.md b/README.md
index 182e264..205163f 100644
--- a/README.md
+++ b/README.md
@@ -159,7 +159,7 @@ def very_important_function(
     debug: bool = False,
 ):
     """Applies `variables` to the `template` and writes to `file`."""
-    with open(file, 'w') as f:
+    with open(file, "w") as f:
         ...
 ```
 
@@ -260,11 +260,73 @@ if you'd like a trailing comma in this situation and *Black* didn't
 recognize it was safe to do so, put it there manually and *Black* will
 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.
+
 
 ## Editor integration
 
-* Visual Studio Code: [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode)
-* Emacs: [proofit404/blacken](https://github.com/proofit404/blacken)
+### Emacs
+
+Use [proofit404/blacken](https://github.com/proofit404/blacken).
+
+
+### Vim
+
+Commands and shortcuts:
+
+* `,=` or `:Black` to format the entire file (ranges not supported);
+* `:BlackUpgrade` to upgrade *Black* inside the virtualenv;
+* `:BlackVersion` to get the current version of *Black* inside the
+  virtualenv.
+
+Configuration:
+* `g:black_fast` (defaults to `0`)
+* `g:black_linelength` (defaults to `88`)
+* `g:black_virtualenv` (defaults to `~/.vim/black`)
+
+To install, copy the plugin from [vim/plugin/black.vim](https://github.com/ambv/black/tree/master/vim/plugin/black.vim).
+Let me know if this requires any changes to work with Vim 8's builtin
+`packadd`, or Pathogen, or Vundle, and so on.
+
+This plugin **requires Vim 7.0+ built with Python 3.6+ support**.  It
+needs Python 3.6 to be able to run *Black* inside the Vim process which
+is much faster than calling an external command.
+
+On first run, the plugin creates its own virtualenv using the right
+Python version and automatically installs *Black*. You can upgrade it later
+by calling `:BlackUpgrade` and restarting Vim.
+
+If you need to do anything special to make your virtualenv work and
+install *Black* (for example you want to run a version from master), just
+create a virtualenv manually and point `g:black_virtualenv` to it.
+The plugin will use it.
+
+**How to get Vim with Python 3.6?**
+On Ubuntu 17.10 Vim comes with Python 3.6 by default.
+On macOS with HomeBrew run: `brew install vim --with-python3`.
+When building Vim from source, use:
+`./configure --enable-python3interp=yes`. There's many guides online how
+to do this.
+
+
+### Visual Studio Code
+
+Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
+
+
+### Other editors
+
+Atom/Nuclide integration is planned by the author, others will
+require external contributions.
+
+Patches welcome! ✨ 🍰 ✨
 
 Any tool that can pipe code through *Black* using its stdio mode (just
 [use `-` as the file name](http://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
@@ -272,10 +334,7 @@ The formatted code will be returned on stdout (unless `--check` was
 passed).  *Black* will still emit messages on stderr but that shouldn't
 affect your use case.
 
-Vim and Atom/Nuclide integration is planned by the author, others will
-require external contributions.
-
-Patches welcome! ✨ 🍰 ✨
+This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
 
 
 ## Testimonials
@@ -335,9 +394,19 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ### 18.3a5 (unreleased)
 
+* add line breaks before all delimiters, except in cases like commas, to better
+  comply with PEP8 (#73)
+
+* fixed handling of standalone comments within nested bracketed
+  expressions; Black will no longer produce super long lines or put all
+  standalone comments at the end of the expression (#22)
+
 * fixed 18.3a4 regression: don't crash and burn on empty lines with
   trailing whitespace (#80)
 
+* when CTRL+C is pressed while formatting many files, Black no longer
+  freaks out with a flurry of asyncio-related exceptions
+
 * only allow up to two empty lines on module level and only single empty
   lines within functions (#74)
 
@@ -447,5 +516,5 @@ Multiple contributions by:
 * [Daniel M. Capella](mailto:polycitizen@gmail.com)
 * [Eli Treuherz](mailto:eli.treuherz@cgi.com)
 * Hugo van Kemenade
-* [Mika⠙](mailto:mail@autophagy.io)
+* [Mika Naylor](mailto:mail@autophagy.io)
 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)