Avoid producing `NoDelim` values in `MacArgs::delim()`.

[rust.git] / README.md

diff --git a/README.md b/README.md
index 381dc73209e5b4b5ee3de3a21f1b3b9d5caf4e6e..b3a968f0c043e30f10badc3853a3b5652e082eee 100644 (file)
--- a/README.md
+++ b/README.md
@@ -47,13 +47,12 @@ cargo +nightly fmt
 
 ## Limitations
 
-Rustfmt tries to work on as much Rust code as possible, sometimes, the code
-doesn't even need to compile! As we approach a 1.0 release we are also looking
-to limit areas of instability; in particular, post-1.0, the formatting of most
-code should not change as Rustfmt improves. However, there are some things that
-Rustfmt can't do or can't do well (and thus where formatting might change
-significantly, even post-1.0). We would like to reduce the list of limitations
-over time.
+Rustfmt tries to work on as much Rust code as possible. Sometimes, the code
+doesn't even need to compile! In general, we are looking to limit areas of
+instability; in particular, post-1.0, the formatting of most code should not
+change as Rustfmt improves. However, there are some things that Rustfmt can't
+do or can't do well (and thus where formatting might change significantly,
+even post-1.0). We would like to reduce the list of limitations over time.
 
 The following list enumerates areas where Rustfmt does not work or where the
 stability guarantees do not apply (we don't make a distinction between the two
@@ -102,6 +101,25 @@ read data from stdin. Alternatively, you can use `cargo fmt` to format all
 binary and library targets of your crate.
 
 You can run `rustfmt --help` for information about available arguments.
+The easiest way to run rustfmt against a project is with `cargo fmt`. `cargo fmt` works on both
+single-crate projects and [cargo workspaces](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html).
+Please see `cargo fmt --help` for usage information.
+
+You can specify the path to your own `rustfmt` binary for cargo to use by setting the`RUSTFMT` 
+environment variable. This was added in v1.4.22, so you must have this version or newer to leverage this feature (`cargo fmt --version`)
+
+### Running `rustfmt` directly
+
+To format individual files or arbitrary codes from stdin, the `rustfmt` binary should be used. Some
+examples follow:
+
+- `rustfmt lib.rs main.rs` will format "lib.rs" and "main.rs" in place
+- `rustfmt` will read a code from stdin and write formatting to stdout
+  - `echo "fn     main() {}" | rustfmt` would emit "fn main() {}".
+
+For more information, including arguments and emit options, see `rustfmt --help`.
+
+### Verifying code is formatted
 
 When running with `--check`, Rustfmt will exit with `0` if Rustfmt would not
 make any formatting changes to the input, and `1` if Rustfmt would make changes.
@@ -129,16 +147,16 @@ rustfmt to exit with an error code if the input is not formatted correctly.
 It will also print any found differences. (Older versions of Rustfmt don't
 support `--check`, use `--write-mode diff`).
 
-A minimal Travis setup could look like this (requires Rust 1.24.0 or greater):
+A minimal Travis setup could look like this (requires Rust 1.31.0 or greater):
 
 ```yaml
 language: rust
 before_script:
 - rustup component add rustfmt
 script:
-- cargo fmt --all -- --check
 - cargo build
 - cargo test
+- cargo fmt --all -- --check
 ```
 
 See [this blog post](https://medium.com/@ag_dubs/enforcing-style-in-ci-for-rust-projects-18f6b09ec69d)
@@ -179,12 +197,16 @@ needs to be specified in `rustfmt.toml`, e.g., with `edition = "2018"`.
 ## Tips
 
 * For things you do not want rustfmt to mangle, use `#[rustfmt::skip]`
-* To prevent rustfmt from formatting a macro,
-  use `#[rustfmt::skip::macros(target_macro_name)]`
+* To prevent rustfmt from formatting a macro or an attribute,
+  use `#[rustfmt::skip::macros(target_macro_name)]` or
+  `#[rustfmt::skip::attributes(target_attribute_name)]`
 
   Example:
 
     ```rust
+    #![rustfmt::skip::attributes(custom_attribute)]
+
+    #[custom_attribute(formatting , here , should , be , Skipped)]
     #[rustfmt::skip::macros(html)]
     fn main() {
         let macro_result1 = html! { <div>
@@ -216,6 +238,7 @@ needs to be specified in `rustfmt.toml`, e.g., with `edition = "2018"`.
   | stdout | writes output to stdout | No |
   | coverage | displays how much of the input file was processed | Yes |
   | checkstyle | emits in a checkstyle format | Yes |
+  | json | emits diffs in a json format | Yes |
 
 ## License
 
@@ -225,5 +248,5 @@ Apache License (Version 2.0).
 See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.
 
 [rust]: https://github.com/rust-lang/rust
-[fmt rfcs]: https://github.com/rust-lang-nursery/fmt-rfcs
-[style guide]: https://github.com/rust-lang-nursery/fmt-rfcs/blob/master/guide/guide.md
+[fmt rfcs]: https://github.com/rust-dev-tools/fmt-rfcs
+[style guide]: https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md