Auto merge of #8855 - salewski:ads/issue-8854-doc-essential-terms, r=…

…alexcrichton

doc (book): add "Getting Started" subsection: "Essential Terminology"

# Reworked PR (2020-11-21)

Fixes #8854

In The Cargo Book, beef-up the glossary, and provide hyperlinks to the definitions of key terms through both the "Getting Started" and "Cargo Guide" chapters.

In addition to the links, some transitional text (two sentences) has been added to the beginning of "First Steps with Cargo", and somewhat more to "Why Cargo Exists" in the guide. The intent is cater to readers jumping into this book cold, or perhaps coming from the "Hello, Cargo!" section at the beginning of The Book. The changes assume a knowledgeable but skeptical user, so take pains to justify the reader's attention. A developer that knows very little about Rust and nothing about Cargo and can follow the text and map Cargo-specific concepts to analogues in other language ecosystems.

Within the glossary many terms are touched-up, as described in the commit message for the first patch in the series. Intra-glossary links are added between all terms.

In the "Getting Started" and "Cargo Guide" chapters, terms are linked to their glossary entries throughout, for the first mention of a term within a given *section*. The first time a term is seen in the *chapter*, the markdown syntax for italics is used. In "First Steps with Cargo", both italics and bold markdown are used, in keeping with the existing styling.

# Orig PR (2020-11-12) -- obsolete

~~Insert short terminology cheatsheet page to explain these terms:~~

   * ~~package~~
   * ~~crate~~
      - ~~library crate~~
      - ~~binary crate~~
   * ~~module~~
   * ~~workspace~~

~~Important in these definitions is the fact that a single package is defined by
a single 'Cargo.toml' file, and that a non-workspace Cargo.toml package
contains one or more crates.~~

~~The last two terms in the list are just glossed over, as it is more important
that the user know that the terms exist, and that there are both lower-level
(module) and higher-level (workspace) concepts than the organizational units
(a package and its crates) that feature most prominently in basic cargo
builds.~~

~~With the addition of this new "Essential Terminology" page, the structure at
the beginning of The Cargo Book is:~~

    Introduction
    1. Getting Started
        1.1. Essential Terminology      <= new
        1.2. Installation
        1.3. First Steps with Cargo
    2. Cargo Guide
    ...

~~The terms in the above list are all well defined elsewhere in the Rust and
Cargo documentation, but a new user encountering them for the first time
should not need to hunt them down.~~

~~Since the opening sections of the Cargo book are among the first documents a
new user is likely to encounter, we are providing a little cheatsheet of the
essentials at this stage. Defining the above terms gives the reader a good
foothold to map concepts they may be familiar with from other languages onto
their Rust counterparts (roughly speaking).~~

~~Closes #8854~~

src/doc/src/appendix/glossary.md

@@ -3,30 +3,50 @@
 ### Artifact
 
 An *artifact* is the file or set of files created as a result of the
-compilation process. This includes linkable libraries and executable binaries.
+compilation process. This includes linkable libraries, executable binaries,
+and generated documentation.
+
+### Cargo
+
+*Cargo* is the Rust [*package manager*](#package-manager), and the primary
+topic of this book.
+
+### Cargo.lock
+
+See [*lock file*](#lock-file).
+
+### Cargo.toml
+
+See [*manifest*](#manifest).
 
 ### Crate
 
-Every target in a package is a *crate*. Crates are either libraries or
-executable binaries. It may loosely refer to either the source code of the
-target, or the compiled artifact that the target produces. A crate may also
-refer to a compressed package fetched from a registry.
+A Rust *crate* is either a library or an executable program, referred to as
+either a *library crate* or a *binary crate*, respectively.
+
+Every [target](#target) defined for a Cargo [package](#package) is a *crate*.
+
+Loosely, the term *crate* may refer to either the source code of the target or
+to the compiled artifact that the target produces. It may also refer to a
+compressed package fetched from a [registry](#registry).
+
+The source code for a given crate may be subdivided into [*modules*](#module).
 
 ### Edition
 
 A *Rust edition* is a developmental landmark of the Rust language. The
 [edition of a package][edition-field] is specified in the `Cargo.toml`
-manifest, and individual targets can specify which edition they use. See the
-[Edition Guide] for more information.
+[manifest](#manifest), and individual targets can specify which edition they
+use. See the [Edition Guide] for more information.
 
 ### Feature
 
 The meaning of *feature* depends on the context:
 
 - A [*feature*][feature] is a named flag which allows for conditional
   compilation. A feature can refer to an optional dependency, or an arbitrary
-  name defined in a `Cargo.toml` manifest that can be checked within source
-  code.
+  name defined in a `Cargo.toml` [manifest](#manifest) that can be checked
+  within source code.
 
 - Cargo has [*unstable feature flags*][cargo-unstable] which can be used to
   enable experimental behavior of Cargo itself.
@@ -40,55 +60,107 @@ The meaning of *feature* depends on the context:
 
 ### Index
 
-The index is the searchable list of crates in a registry.
+The *index* is the searchable list of [*crates*](#crate) in a
+[*registry*](#registry).
 
 ### Lock file
 
 The `Cargo.lock` *lock file* is a file that captures the exact version of
-every dependency used in a workspace or package. It is automatically generated
-by Cargo. See [Cargo.toml vs Cargo.lock].
+every dependency used in a [*workspace*](#workspace) or
+[*package*](#package). It is automatically generated by Cargo. See
+[Cargo.toml vs Cargo.lock].
 
 ### Manifest
 
-A [*manifest*][manifest] is a description of a package or a workspace in a
-file named `Cargo.toml`.
+A [*manifest*][manifest] is a description of a [package](#package) or a
+[workspace](#workspace) in a file named `Cargo.toml`.
 
 A [*virtual manifest*][virtual] is a `Cargo.toml` file that only describes a
 workspace, and does not include a package.
 
 ### Member
 
-A *member* is a package that belongs to a workspace.
+A *member* is a [*package*](#package) that belongs to a
+[*workspace*](#workspace).
+
+### Module
+
+Rust's module system is used to organize code into logical units called
+*modules*, which provide isolated namespaces within the code.
+
+The source code for a given [crate](#crate) may be subdivided into one or more
+separate modules. This is usually done to organize the code into areas of
+related functionality or to control the visible scope (public/private) of
+symbols within the source (structs, functions, and so on).
+
+A [`Cargo.toml`](#manifest) file is primarily concerned with the
+[package](#package) it defines, its crates, and the packages of the crates on
+which they depend. Nevertheless, you will see the term "module" often when
+working with Rust, so you should understand its relationship to a given crate.
 
 ### Package
 
-A *package* is a collection of source files and a `Cargo.toml` manifest which
-describes the package. A package has a name and version which is used for
-specifying dependencies between packages. A package contains multiple targets,
-which are either libraries or executable binaries.
+A *package* is a collection of source files and a `Cargo.toml`
+[*manifest*](#manifest) file which describes the package. A package has a name
+and version which is used for specifying dependencies between packages.
+
+A package contains multiple [*targets*](#target), each of which is a
+[*crate*](#crate). The `Cargo.toml` file describes the type of the crates
+(binary or library) within the package, along with some metadata about each
+one -- how each is to be built, what their direct dependencies are, etc., as
+described throughout this book.
 
 The *package root* is the directory where the package's `Cargo.toml` manifest
-is located.
+is located. (Compare with [*workspace root*](#workspace).)
 
 The [*package ID specification*][pkgid-spec], or *SPEC*, is a string used to
 uniquely reference a specific version of a package from a specific source.
 
+Small to medium sized Rust projects will only need a single package, though it
+is common for them to have multiple crates.
+
+Larger projects may involve multiple packages, in which case Cargo
+[*workspaces*](#workspace) can be used to manage common dependencies and other
+related metadata between the packages.
+
+### Package manager
+
+Broadly speaking, a *package manager* is a program (or collection of related
+programs) in a software ecosystem that automates the process of obtaining,
+installing, and upgrading artifacts. Within a programming language ecosystem,
+a package manager is a developer-focused tool whose primary functionality is
+to download library artifacts and their dependencies from some central
+repository; this capability is often combined with the ability to perform
+software builds (by invoking the language-specific compiler).
+
+[*Cargo*](#cargo) is the package manager within the Rust ecosystem. Cargo
+downloads your Rust [package](#package)’s dependencies
+([*artifacts*](#artifact) known as [*crates*](#crate)), compiles your
+packages, makes distributable packages, and (optionally) uploads them to
+[crates.io][], the Rust community’s [*package registry*](#registry).
+
+### Package registry
+
+See [*registry*](#registry).
+
 ### Project
 
 Another name for a [package](#package).
 
 ### Registry
 
-A *registry* is a service that contains a collection of downloadable crates
-that can be installed or used as dependencies for a package. The default
-registry is [crates.io](https://crates.io). The registry has an *index* which
+A *registry* is a service that contains a collection of downloadable
+[*crates*](#crate) that can be installed or used as dependencies for a
+[*package*](#package). The default registry in the Rust ecosystem is
+[crates.io](https://crates.io). The registry has an [*index*](#index) which
 contains a list of all crates, and tells Cargo how to download the crates that
 are needed.
 
 ### Source
 
-A *source* is a provider that contains crates that may be included as
-dependencies for a package. There are several kinds of sources:
+A *source* is a provider that contains [*crates*](#crate) that may be included
+as dependencies for a [*package*](#package). There are several kinds of
+sources:
 
 - **Registry source** — See [registry](#registry).
 - **Local registry source** — A set of crates stored as compressed files on
@@ -110,16 +182,17 @@ See [package ID specification](#package).
 
 The meaning of the term *target* depends on the context:
 
-- **Cargo Target** — Cargo packages consist of *targets* which correspond to
-  artifacts that will be produced. Packages can have library, binary, example,
-  test, and benchmark targets. The [list of targets][targets] are configured
-  in the `Cargo.toml` manifest, often inferred automatically by the [directory
+- **Cargo Target** — Cargo [*packages*](#package) consist of *targets* which
+  correspond to [*artifacts*](#artifact) that will be produced. Packages can
+  have library, binary, example, test, and benchmark targets. The
+  [list of targets][targets] are configured in the `Cargo.toml`
+  [*manifest*](#manifest), often inferred automatically by the [directory
   layout] of the source files.
 - **Target Directory** — Cargo places all built artifacts and intermediate
   files in the *target* directory. By default this is a directory named
-  `target` at the workspace root, or the package root if not using a
-  workspace. The directory may be changed with the `--target-dir` command-line
-  option, the `CARGO_TARGET_DIR` [environment variable], or the
+  `target` at the [*workspace*](#workspace) root, or the package root if not
+  using a workspace. The directory may be changed with the `--target-dir`
+  command-line option, the `CARGO_TARGET_DIR` [environment variable], or the
   `build.target-dir` [config option].
 - **Target Architecture** — The OS and machine architecture for the built
   artifacts are typically referred to as a *target*.
@@ -154,22 +227,24 @@ correctness of code. There are two types of test artifacts:
   individual units of code.
 * **Integration test target** — An [*integration test
   target*][integration-tests] is an executable binary compiled from a *test
-  target* which is a distinct crate whose source is located in the `tests`
-  directory or specified by the [`[[test]]` table][targets] in the
-  `Cargo.toml` manifest. It is intended to only test the public API of a
-  library, or execute a binary to verify its operation.
+  target* which is a distinct [*crate*](#crate) whose source is located in the
+  `tests` directory or specified by the [`[[test]]` table][targets] in the
+  `Cargo.toml` [*manifest*](#manifest). It is intended to only test the public
+  API of a library, or execute a binary to verify its operation.
 
 ### Workspace
 
-A [*workspace*][workspace] is a collection of one or more packages that share
-common dependency resolution (with a shared `Cargo.lock`), output directory,
-and various settings such as profiles.
+A [*workspace*][workspace] is a collection of one or more
+[*packages*](#package) that share common dependency resolution (with a shared
+`Cargo.lock` [*lock file*](#lock-file)), output directory, and various
+settings such as profiles.
 
 A [*virtual workspace*][virtual] is a workspace where the root `Cargo.toml`
-manifest does not define a package, and only lists the workspace members.
+[*manifest*](#manifest) does not define a package, and only lists the
+workspace [*members*](#member).
 
 The *workspace root* is the directory where the workspace's `Cargo.toml`
-manifest is located.
+manifest is located. (Compare with [*package root*](#package).)
 
 
 [Cargo.toml vs Cargo.lock]: ../guide/cargo-toml-vs-cargo-lock.md
@@ -178,6 +253,7 @@ manifest is located.
 [Source Replacement]: ../reference/source-replacement.md
 [cargo-unstable]: ../reference/unstable.md
 [config option]: ../reference/config.md
+[crates.io]: https://crates.io/
 [directory layout]: ../guide/project-layout.md
 [edition guide]: ../../edition-guide/index.html
 [edition-field]: ../reference/manifest.md#the-edition-field

src/doc/src/getting-started/first-steps.md

@@ -1,13 +1,18 @@
 ## First Steps with Cargo
 
+This section provides a quick sense for the `cargo` command line tool. We
+demonstrate its ability to generate a new [***package***][def-package] for us,
+its ability to compile the [***crate***][def-crate] within the package, and
+its ability to run the resulting program.
+
 To start a new package with Cargo, use `cargo new`:
 
 ```console
 $ cargo new hello_world
 ```
 
-Cargo defaults to `--bin` to make a binary program. To make a library, we'd
-pass `--lib`.
+Cargo defaults to `--bin` to make a binary program. To make a library, we
+would pass `--lib`, instead.
 
 Let’s check out what Cargo has generated for us:
 
@@ -34,8 +39,8 @@ edition = "2018"
 [dependencies]
 ```
 
-This is called a **manifest**, and it contains all of the metadata that Cargo
-needs to compile your package.
+This is called a [***manifest***][def-manifest], and it contains all of the
+metadata that Cargo needs to compile your package.
 
 Here’s what’s in `src/main.rs`:
 
@@ -45,7 +50,8 @@ fn main() {
 }
 ```
 
-Cargo generated a “hello world” for us. Let’s compile it:
+Cargo generated a “hello world” program for us, otherwise known as a
+[***binary crate***][def-crate]. Let’s compile it:
 
 ```console
 $ cargo build
@@ -71,3 +77,7 @@ Hello, world!
 ### Going further
 
 For more details on using Cargo, check out the [Cargo Guide](../guide/index.md)
+
+[def-crate]:     ../appendix/glossary.md#crate     '"crate" (glossary entry)'
+[def-manifest]:  ../appendix/glossary.md#manifest  '"manifest" (glossary entry)'
+[def-package]:   ../appendix/glossary.md#package   '"package" (glossary entry)'

src/doc/src/getting-started/index.md

@@ -1,6 +1,9 @@
 ## Getting Started
 
-To get started with Cargo, install Cargo (and Rust) and set up your first crate.
+To get started with Cargo, install Cargo (and Rust) and set up your first
+[*crate*][def-crate].
 
 * [Installation](installation.md)
 * [First steps with Cargo](first-steps.md)
+
+[def-crate]:  ../appendix/glossary.md#crate  '"crate" (glossary entry)'

src/doc/src/guide/build-cache.md

@@ -1,9 +1,10 @@
 ## Build cache
 
 Cargo stores the output of a build into the "target" directory. By default,
-this is the directory named `target` in the root of your workspace. To change
-the location, you can set the `CARGO_TARGET_DIR` [environment variable], the
-[`build.target-dir`] config value, or the `--target-dir` command-line flag.
+this is the directory named `target` in the root of your
+[*workspace*][def-worksapce]. To change the location, you can set the
+`CARGO_TARGET_DIR` [environment variable], the [`build.target-dir`] config
+value, or the `--target-dir` command-line flag.
 
 The directory layout depends on whether or not you are using the `--target`
 flag to build for a specific platform. If `--target` is not specified, Cargo
@@ -90,6 +91,7 @@ configuration][config]. Refer to sccache documentation for more details.
 [`cargo publish`]: ../commands/cargo-publish.md
 [build scripts]: ../reference/build-scripts.md
 [config]: ../reference/config.md
+[def-workspace]:  ../appendix/glossary.md#workspace  '"workspace" (glossary entry)'
 [environment variable]: ../reference/environment-variables.md
 [incremental output]: ../reference/profiles.md#incremental
 [sccache]: https://github.com/mozilla/sccache

src/doc/src/guide/cargo-home.md

@@ -1,7 +1,7 @@
 ## Cargo Home
 
 The "Cargo home" functions as a download and source cache.
-When building a crate, Cargo stores downloaded build dependencies in the Cargo home.
+When building a [crate][def-crate], Cargo stores downloaded build dependencies in the Cargo home.
 You can alter the location of the Cargo home by setting the `CARGO_HOME` [environmental variable][env].
 The [home](https://crates.io/crates/home) crate provides an API for getting this location if you need this information inside your Rust crate.
 By default, the Cargo home is located in `$HOME/.cargo/`.
@@ -16,10 +16,10 @@ The Cargo home consists of following components:
 	Cargo's global configuration file, see the [config entry in the reference][config].
 
 * `credentials.toml`
- 	Private login credentials from [`cargo login`] in order to log in to a registry.
+ 	Private login credentials from [`cargo login`] in order to log in to a [registry][def-registry].
 
 * `.crates.toml`
-	This hidden file contains package information of crates installed via [`cargo install`]. Do NOT edit by hand!
+	This hidden file contains [package][def-package] information of crates installed via [`cargo install`]. Do NOT edit by hand!
 
 ## Directories:
 
@@ -83,4 +83,7 @@ Alternatively, the [cargo-cache](https://crates.io/crates/cargo-cache) crate pro
 [`cargo login`]: ../commands/cargo-login.md
 [`cargo vendor`]: ../commands/cargo-vendor.md
 [config]: ../reference/config.md
+[def-crate]:     ../appendix/glossary.md#crate     '"crate" (glossary entry)'
+[def-package]:   ../appendix/glossary.md#package   '"package" (glossary entry)'
+[def-registry]:  ../appendix/glossary.md#registry  '"registry" (glossary entry)'
 [env]: ../reference/environment-variables.md

src/doc/src/guide/cargo-toml-vs-cargo-lock.md

@@ -8,18 +8,20 @@ about them, here’s a summary:
 * `Cargo.lock` contains exact information about your dependencies. It is
   maintained by Cargo and should not be manually edited.
 
-If you’re building a non-end product, such as a rust library that other rust packages will depend on, put
-`Cargo.lock` in your `.gitignore`. If you’re building an end product, which are executable
-like command-line tool or an application, or a system library with crate-type of `staticlib` or `cdylib`,
-check `Cargo.lock` into `git`. If you're curious about why that is, see
+If you’re building a non-end product, such as a rust library that other rust
+[packages][def-package] will depend on, put `Cargo.lock` in your
+`.gitignore`. If you’re building an end product, which are executable like
+command-line tool or an application, or a system library with crate-type of
+`staticlib` or `cdylib`, check `Cargo.lock` into `git`. If you're curious
+about why that is, see
 ["Why do binaries have `Cargo.lock` in version control, but not libraries?" in the
 FAQ](../faq.md#why-do-binaries-have-cargolock-in-version-control-but-not-libraries).
 
 Let’s dig in a little bit more.
 
-`Cargo.toml` is a **manifest** file in which we can specify a bunch of
-different metadata about our package. For example, we can say that we depend
-on another package:
+`Cargo.toml` is a [**manifest**][def-manifest] file in which we can specify a
+bunch of different metadata about our package. For example, we can say that we
+depend on another package:
 
 ```toml
 [package]
@@ -101,3 +103,6 @@ This will write out a new `Cargo.lock` with the new version information. Note
 that the argument to `cargo update` is actually a
 [Package ID Specification](../reference/pkgid-spec.md) and `rand` is just a short
 specification.
+
+[def-manifest]:  ../appendix/glossary.md#manifest  '"manifest" (glossary entry)'
+[def-package]:   ../appendix/glossary.md#package   '"package" (glossary entry)'