Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 14 commits into from
Nov 25, 2020
Merged

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

merged 14 commits into from
Nov 25, 2020

Commits on Nov 21, 2020

  1. doc (book)[01/14]: glossary beef-up 

    Add a handful of entries to the glossary of The Cargo Book, and add
intra-glossary hyperlinks for terms. A full catalog of the specific
changes follows.

Glossary entries added:

    + 'Cargo.lock' -- just points to the 'lock file' entry

    + 'Cargo.toml' -- just points to the 'manifest' entry

    + 'Module' -- explained in relation to 'crate'

    + 'Package manager' -- first term in the Introduction

    + 'Package registry' -- Another term from the Introduction. This
       entry just points to the 'registry' entry

Glossary entries modified:

    + 'Artifact'
        - Extend def. to include generated docs.

    + 'Crate'
        - Refer to a "Rust crate" as a hint that it is a term that
          exists outside of Cargo.

        - Refer to a "Cargo package" (rather than just "package") to
          reflect the fact that the term is a concept introduced by
          Cargo (as opposed to being inherent to Rust).

        - Link to related terms: 'module', 'package', 'registry',
          and 'target'.

    + 'Edition'
        - Link to related term: 'manifest'.

    + 'Feature'
        - Link to related term: 'manifest'.

    + 'Index'
        - Markdown: add emphasis to first mention of term "index".
        - Link to related terms: 'crate', 'registry'.

    + 'Lock file'
        - Link to related terms: 'package', 'workspace'.

    + 'Manifest'
        - Link to related terms: 'package', 'workspace'.

    + 'Member'
        - Link to related terms: 'package', 'workspace'.

    + 'Package'
        - Note that every target is a crate, and that the type
          (library or binary) is determined by the Cargo.toml file.

        - Note relationship to workspaces.

        - For "package root", add "compare to" note referencing
          "workspace root".

        - Link to related terms: 'crate', 'manifest', 'target',
          'workspace'.

    + 'Registry'
        - Link to related terms: 'crate', 'index', 'package'.

    + 'Source'
        - Link to related terms: 'crate', 'package'.

    + 'Target'
        - Link to related terms: 'artifact', 'manifest', 'package',
          'workspace'.

    + 'Test Targets'
        - Link to related terms: 'crate', 'manifest'.

    + 'Workspace'
        - For "workspace root", add "compare to" note referencing
          "package root".

        - Link to related terms: 'lock file', 'manifest', 'member',
          'package'.
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    37a6c8d View commit details
    Browse the repository at this point in the history

  2. doc (book)[02/14]: "Introduction": add links to glossary for key terms 

    No language changes; just make these existing terms link to their
corresponding entries in the glossary:
   - crate
   - package
   - package manager
   - package registry
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    c9a658a View commit details
    Browse the repository at this point in the history

  3. doc (book)[03/14]: "Getting Started" index: link "crate" to glossary … 

    …entry
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    4da7c38 View commit details
    Browse the repository at this point in the history

  4. doc (book)[04/14]: "Getting Started"/"First Steps...": add intro blurb 

    In the "First Steps with Cargo" section, add a short introductory
paragraph informing the reader what to expect from the page.

This provides a transition for the reader who may not yet know what
a package is. Rather than jump right into "To start a new package
with Cargo, ...", we now set the context for the purpose of the
page, and also provide hyperlinks into our Glossary for the terms
'package', 'manifest', and 'crate'.
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    759b60c View commit details
    Browse the repository at this point in the history

  5. doc (book)[05/14]: "Cargo Guide"/"Why Cargo Exists": add "Preliminaries" 

    The "Why Cargo Exists" section of the "Cargo Guide" is here split
into two subsections:

    "Preliminaries"
    "Enter: Cargo"

The content in "Preliminaries" is new, and provides a transition
that motivates the need for a package manager rather than using
'rustc' directly. It provides footing for the reader that knows very
little about Rust and nothing about Cargo.

The "Enter: Cargo" subsection contains the previous content,
augmented with a new paragraph explaining how the conventional list
of build targets simplifies working with Cargo packages: "...once
you know how to build one Cargo-based project, you know how to build
/all/ of them."

The following terms are linked to their Glossary entries:
    - artifact
    - crate
    - package
    - package manager
    - registry
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    c4c03c4 View commit details
    Browse the repository at this point in the history

  6. doc (book)[06/14]: "Cargo Guide"/"Creating a New...": link terms to g… 

    …lossary

The following terms are linked to their Glossary entries:
    - crate
    - manifest
    - package

Also note that the generated "hello world" program is known as a
"binary crate".
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    f862022 View commit details
    Browse the repository at this point in the history

  7. doc (book)[07/14]: "Cargo Guide"/"Working on an...": link terms to gl… 

    …ossary

The following term(s) are linked to their Glossary entries:
    - package
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    d2c181f View commit details
    Browse the repository at this point in the history

  8. doc (book)[08/14]: "Cargo Guide"/"Dependencies": link terms to glossary 

    The following term(s) are linked to their Glossary entries:
    - crate
    - package
    - package registry
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    d500dc8 View commit details
    Browse the repository at this point in the history

  9. doc (book)[09/14]: "Cargo Guide"/"Package Layout": link terms to glos… 

    …sary

The following term(s) are linked to their Glossary entries:
    - module
    - package
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    1fbc992 View commit details
    Browse the repository at this point in the history

  10. doc (book)[10/14]: "Cargo Guide"/"Cargo.toml vs...": link terms to gl… 

    …ossary

The following term(s) are linked to their Glossary entries:
    - manifest
    - package
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    05ee4c6 View commit details
    Browse the repository at this point in the history

  11. doc (book)[11/14]: "Cargo Guide"/"Tests": link terms to glossary 

    The following term(s) are linked to their Glossary entries:
    - package
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    c0b09f1 View commit details
    Browse the repository at this point in the history

  12. doc (book)[12/14]: "Cargo Guide"/"Continuous Integration": link terms… 

    … to glossary

The following term(s) are linked to their Glossary entries:
    - package
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    aeb517b View commit details
    Browse the repository at this point in the history

  13. doc (book)[13/14]: "Cargo Guide"/"Cargo Home": link terms to glossary 

    The following term(s) are linked to their Glossary entries:
    - crate
    - package
    - registry
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    365b738 View commit details
    Browse the repository at this point in the history

  14. doc (book)[14/14]: "Cargo Guide"/"Build Cache": link terms to glossary 

    The following term(s) are linked to their Glossary entries:
    - workspace
    @salewski
    salewski committed Nov 21, 2020
    Configuration menu
    Copy the full SHA
    ab78221 View commit details
    Browse the repository at this point in the history