From bc489e255d6a7cee5531da4992512a9e281000bb Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Mon, 8 Jan 2018 14:42:48 -0800 Subject: [PATCH] doc: Replace 'shell' language labels (generally with 'console') GitHub uses Linguist for syntax highlighting [1]. Linguist's 'shell' language is for the *language* [2] (e.g. the contents of a `.sh` file). The proper language for a shell session is ShellSession [3], although in this commit I've used the alias 'console' [4]. The Cargo book uses mdBook (src/doc/README.md), mdBook uses Highlight.js [5], and Highlight.js also supports 'console' as an alias for shell sessions [6]. A handful of places where we had been using 'shell' were just command output, not shell sessions (e.g. they lacked a prompt and command). In this commit, I've left those without a language label. [1]: https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting [2]: https://github.com/github/linguist/blob/v5.3.3/lib/linguist/languages.yml#L4208 [3]: https://github.com/github/linguist/blob/v5.3.3/lib/linguist/languages.yml#L4249 [4]: https://github.com/github/linguist/blob/v5.3.3/lib/linguist/languages.yml#L4255 [5]: https://rust-lang-nursery.github.io/mdBook/format/theme/syntax-highlighting.html#syntax-highlighting [6]: https://github.com/isagalaev/highlight.js/blob/9.12.0/src/languages/shell.js#L10 --- src/doc/README.md | 8 ++++---- src/doc/src/getting-started/first-steps.md | 10 +++++----- src/doc/src/getting-started/installation.md | 2 +- src/doc/src/guide/cargo-toml-vs-cargo-lock.md | 2 +- src/doc/src/guide/creating-a-new-project.md | 12 ++++++------ src/doc/src/guide/dependencies.md | 4 ++-- src/doc/src/guide/project-layout.md | 2 +- src/doc/src/guide/tests.md | 4 ++-- src/doc/src/guide/working-on-an-existing-project.md | 4 ++-- src/doc/src/reference/build-scripts.md | 6 +++--- src/doc/src/reference/manifest.md | 4 ++-- src/doc/src/reference/publishing.md | 10 +++++----- src/doc/src/reference/specifying-dependencies.md | 6 +++--- 13 files changed, 37 insertions(+), 37 deletions(-) diff --git a/src/doc/README.md b/src/doc/README.md index b24da689e..983c96693 100644 --- a/src/doc/README.md +++ b/src/doc/README.md @@ -7,7 +7,7 @@ Building the book requires [mdBook]. To get it: [mdBook]: https://github.com/azerupi/mdBook -```shell +```console $ cargo install mdbook ``` @@ -15,7 +15,7 @@ $ cargo install mdbook To build the book: -```shell +```console $ mdbook build ``` @@ -23,7 +23,7 @@ The output will be in the `book` subdirectory. To check it out, open it in your web browser. _Firefox:_ -```shell +```console $ firefox book/index.html # Linux $ open -a "Firefox" book/index.html # OS X $ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell) @@ -31,7 +31,7 @@ $ start firefox.exe .\book\index.html # Windows (Cmd) ``` _Chrome:_ -```shell +```console $ google-chrome book/index.html # Linux $ open -a "Google Chrome" book/index.html # OS X $ Start-Process "chrome.exe" .\book\index.html # Windows (PowerShell) diff --git a/src/doc/src/getting-started/first-steps.md b/src/doc/src/getting-started/first-steps.md index 190f69f55..6b31d8d0c 100644 --- a/src/doc/src/getting-started/first-steps.md +++ b/src/doc/src/getting-started/first-steps.md @@ -2,7 +2,7 @@ To start a new project with Cargo, use `cargo new`: -```shell +```console $ cargo new hello_world --bin ``` @@ -11,7 +11,7 @@ were making a library, we’d leave it off. Let’s check out what Cargo has generated for us: -```shell +```console $ cd hello_world $ tree . . @@ -44,21 +44,21 @@ fn main() { Cargo generated a “hello world” for us. Let’s compile it: -```shell +```console $ cargo build Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) ``` And then run it: -```shell +```console $ ./target/debug/hello_world Hello, world! ``` We can also use `cargo run` to compile and then run it, all in one step: -```shell +```console $ cargo run Fresh hello_world v0.1.0 (file:///path/to/project/hello_world) Running `target/hello_world` diff --git a/src/doc/src/getting-started/installation.md b/src/doc/src/getting-started/installation.md index 8428a9063..98b84780b 100644 --- a/src/doc/src/getting-started/installation.md +++ b/src/doc/src/getting-started/installation.md @@ -5,7 +5,7 @@ The easiest way to get Cargo is to get the current stable release of [Rust] by using the `rustup` script: -```shell +```console $ curl -sSf https://static.rust-lang.org/rustup.sh | sh ``` diff --git a/src/doc/src/guide/cargo-toml-vs-cargo-lock.md b/src/doc/src/guide/cargo-toml-vs-cargo-lock.md index 574a6677f..66d52459c 100644 --- a/src/doc/src/guide/cargo-toml-vs-cargo-lock.md +++ b/src/doc/src/guide/cargo-toml-vs-cargo-lock.md @@ -92,7 +92,7 @@ they’ll use the exact same SHA, even though we didn’t specify it in our When we’re ready to opt in to a new version of the library, Cargo can re-calculate the dependencies and update things for us: -```shell +```console $ cargo update # updates all dependencies $ cargo update -p rand # updates just “rand” ``` diff --git a/src/doc/src/guide/creating-a-new-project.md b/src/doc/src/guide/creating-a-new-project.md index 3f0c90e3c..3566e02a3 100644 --- a/src/doc/src/guide/creating-a-new-project.md +++ b/src/doc/src/guide/creating-a-new-project.md @@ -2,7 +2,7 @@ To start a new project with Cargo, use `cargo new`: -```shell +```console $ cargo new hello_world --bin ``` @@ -12,7 +12,7 @@ repository by default. If you don't want it to do that, pass `--vcs none`. Let’s check out what Cargo has generated for us: -```shell +```console $ cd hello_world $ tree . . @@ -47,14 +47,14 @@ fn main() { Cargo generated a “hello world” for us. Let’s compile it: -```shell +```console $ cargo build Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) ``` And then run it: -```shell +```console $ ./target/debug/hello_world Hello, world! ``` @@ -63,7 +63,7 @@ We can also use `cargo run` to compile and then run it, all in one step (You won't see the `Compiling` line if you have not made any changes since you last compiled): -```shell +```console $ cargo run Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) Running `target/debug/hello_world` @@ -76,7 +76,7 @@ dependencies. Since we don’t have any yet, it’s not very interesting. Once you’re ready for release, you can use `cargo build --release` to compile your files with optimizations turned on: -```shell +```console $ cargo build --release Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) ``` diff --git a/src/doc/src/guide/dependencies.md b/src/doc/src/guide/dependencies.md index e199487f2..b5d1eb92e 100644 --- a/src/doc/src/guide/dependencies.md +++ b/src/doc/src/guide/dependencies.md @@ -44,7 +44,7 @@ regex = "0.1.41" Re-run `cargo build`, and Cargo will fetch the new dependencies and all of their dependencies, compile them all, and update the `Cargo.lock`: -```shell +```console $ cargo build Updating registry `https://github.com/rust-lang/crates.io-index` Downloading memchr v0.1.5 @@ -83,7 +83,7 @@ fn main() { Running it will show: -```shell +```console $ cargo run Running `target/hello_world` Did our date match? true diff --git a/src/doc/src/guide/project-layout.md b/src/doc/src/guide/project-layout.md index f9eb7d331..300c6e5c9 100644 --- a/src/doc/src/guide/project-layout.md +++ b/src/doc/src/guide/project-layout.md @@ -3,7 +3,7 @@ Cargo uses conventions for file placement to make it easy to dive into a new Cargo project: -```shell +``` . ├── Cargo.lock ├── Cargo.toml diff --git a/src/doc/src/guide/tests.md b/src/doc/src/guide/tests.md index 743a83f85..95d1c2d3a 100644 --- a/src/doc/src/guide/tests.md +++ b/src/doc/src/guide/tests.md @@ -9,7 +9,7 @@ the files in `tests`. Here's an example of running `cargo test` in our project, which currently has no tests: -```shell +```console $ cargo test Compiling rand v0.1.0 (https://github.com/rust-lang-nursery/rand.git#9f35b8e) Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) @@ -25,7 +25,7 @@ tests. You can also run a specific test by passing a filter: -```shell +```console $ cargo test foo ``` diff --git a/src/doc/src/guide/working-on-an-existing-project.md b/src/doc/src/guide/working-on-an-existing-project.md index 97c032005..34ee6c5a8 100644 --- a/src/doc/src/guide/working-on-an-existing-project.md +++ b/src/doc/src/guide/working-on-an-existing-project.md @@ -6,14 +6,14 @@ to get going. First, get the project from somewhere. In this example, we’ll use `rand` cloned from its repository on GitHub: -```shell +```console $ git clone https://github.com/rust-lang-nursery/rand.git $ cd rand ``` To build, use `cargo build`: -```shell +```console $ cargo build Compiling rand v0.1.0 (file:///path/to/project/rand) ``` diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md index 53074238c..35a6d9ea7 100644 --- a/src/doc/src/reference/build-scripts.md +++ b/src/doc/src/reference/build-scripts.md @@ -56,7 +56,7 @@ if you want to ensure that output is always displayed on your terminal. Any line that starts with `cargo:` is interpreted directly by Cargo. This line must be of the form `cargo:key=value`, like the examples below: -```shell +``` # specially recognized by Cargo cargo:rustc-link-lib=static=foo cargo:rustc-link-search=native=/path/to/foo @@ -219,7 +219,7 @@ library call as part of the build script. First, let’s take a look at the directory structure of this package: -```shell +``` . ├── Cargo.toml ├── build.rs @@ -305,7 +305,7 @@ a Rust library which calls into C to print “Hello, World!”. Like above, let’s first take a look at the project layout: -```shell +``` . ├── Cargo.toml ├── build.rs diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 6b32e1a06..9794f161e 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -440,7 +440,7 @@ features that people can enable or disable when they build it. In that case, Servo will describe features in its `Cargo.toml` and they can be enabled using command-line flags: -```shell +```console $ cargo build --release --features "shumway pdf" ``` @@ -575,7 +575,7 @@ Your project can optionally contain folders named `examples`, `tests`, and integration tests, and benchmarks respectively. Analogous to `bin` targets, they may be composed of single files or directories with a `main.rs` file. -```shell +``` ▾ src/ # directory containing source files lib.rs # the main entry point for libraries and packages main.rs # the main entry point for projects producing executables diff --git a/src/doc/src/reference/publishing.md b/src/doc/src/reference/publishing.md index 4f574fe6e..05439354c 100644 --- a/src/doc/src/reference/publishing.md +++ b/src/doc/src/reference/publishing.md @@ -16,7 +16,7 @@ account (required for now). After this, visit your [Account Settings](https://crates.io/me) page and run the `cargo login` command specified. -```shell +```console $ cargo login abcdefghijklmnopqrstuvwxyz012345 ``` @@ -37,7 +37,7 @@ The next step is to package up your crate into a format that can be uploaded to our entire crate and package it all up into a `*.crate` file in the `target/package` directory. -```shell +```console $ cargo package ``` @@ -87,7 +87,7 @@ Now that we’ve got a `*.crate` file ready to go, it can be uploaded to [crates.io] with the `cargo publish` command. And that’s it, you’ve now published your first crate! -```shell +```console $ cargo publish ``` @@ -119,7 +119,7 @@ being broken for one reason or another (syntax error, forgot to include a file, etc.). For situations such as this, Cargo supports a “yank” of a version of a crate. -```shell +```console $ cargo yank --vers 1.0.1 $ cargo yank --vers 1.0.1 --undo ``` @@ -142,7 +142,7 @@ A crate is often developed by more than one person, or the primary maintainer may change over time! The owner of a crate is the only person allowed to publish new versions of the crate, but an owner may designate additional owners. -```shell +```console $ cargo owner --add my-buddy $ cargo owner --remove my-buddy $ cargo owner --add github:rust-lang:owners diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index e58fa915c..ae9746f90 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -132,7 +132,7 @@ split out a separate crate for others to use. To do this Cargo supports **path dependencies** which are typically sub-crates that live within one repository. Let’s start off by making a new crate inside of our `hello_world` project: -```shell +```console # inside of hello_world/ $ cargo new hello_utils ``` @@ -216,7 +216,7 @@ uuid = "1.0" First thing we'll do is to clone the [`uuid` repository][uuid-repository] locally via: -```shell +```console $ git clone https://github.com/rust-lang-nursery/uuid ``` @@ -247,7 +247,7 @@ important to keep this in mind! In any case, typically all you need to do now is: -```shell +```console $ cargo build Compiling uuid v1.0.0 (file://.../uuid) Compiling my-library v0.1.0 (file://.../my-library) -- 2.30.2