docs: Add installation.md, lots of tweaks

Assorted edits and wording tweaks, as well as including bash as type on
most of the fenced code blocks. Also relocated assets into docs/assets
from docs/img in order to accommodate docusaurus' expected layout.

Author: sdboyer

README.md

@@ -1,4 +1,4 @@
-<p align="center"><img src="docs/img/DigbyShadows.png" width="360"></p>
+<p align="center"><img src="docs/assets/DigbyShadows.png" width="360"></p>
 <p align="center">
   <a href="https://travis-ci.org/golang/dep"><img src="https://travis-ci.org/golang/dep.svg?branch=master" alt="Build Status"></img></a>
   <a href="https://ci.appveyor.com/project/golang/dep"><img src="https://ci.appveyor.com/api/projects/status/github/golang/dep?svg=true&branch=master&passingText=Windows%20-%20OK&failingText=Windows%20-%20failed&pendingText=Windows%20-%20pending" alt="Windows Build Status"></a>
@@ -15,9 +15,9 @@ For guides and reference materials about `dep`, see [the documentation](https://
 
 ## Installation
 
-Unless you are hacking on dep, it is strongly recommended that you use a released version. You can grab the latest binary from the [releases](https://github.com/golang/dep/releases) page.
+It is strongly recommended that you use a released version. Release binaries are available on the [releases](https://github.com/golang/dep/releases) page.
 
-On macOS you can install or upgrade to the latest released version with Homebrew:
+On MacOS you can install or upgrade to the latest released version with Homebrew:
 
 ```sh
 $ brew install dep

docs/FAQ.md

@@ -1,19 +1,8 @@
 ---
-id: faq.md
----
-
-
-
 title: FAQ
---
-
-# FAQ
-
-_The first rule of FAQ is don't bikeshed the FAQ, leave that for
-[Create structure for managing docs](https://github.com/golang/dep/issues/331)._
+---
 
-Please contribute to the FAQ! Found an explanation in an issue or pull request helpful?
-Summarize the question and quote the reply, linking back to the original comment.
+The FAQ predated the introduction of the rest of the documentation. If something in here conflicts with other guides or reference documents, it's probably here that it's wrong - please file a PR!
 
 ## Concepts
 * [Does `dep` replace `go get`?](#does-dep-replace-go-get)

docs/Gopkg.lock.md

@@ -41,22 +41,22 @@ Let's explore each of moments. To play along, you'll need to `cd` into a project
 
 Let's say that we want to introduce a new dependency on  `github.com/pkg/errors`. This can be accomplished with one command:
 
-```
+```bash
 $ dep ensure -add github.com/pkg/errors
 ```
 
 > Much like git, `dep status` and `dep ensure` can also be run from any subdirectory of your project root, which is determined by the presence of a `Gopkg.toml` file.
 
 This should succeed, resulting in an updated `Gopkg.lock` and `vendor/` directory, as well as injecting a best-guess version constraint for `github.com/pkg/errors` into our `Gopkg.toml`. But, it will also report a warning:
 
-```
+```bash
 "github.com/pkg/errors" is not imported by your project, and has been temporarily added to Gopkg.lock and vendor/.
 If you run "dep ensure" again before actually importing it, it will disappear from Gopkg.lock and vendor/.
 ```
 
 As the warning suggests, you should introduce an `import "github.com/pkg/errors"` in your code, the sooner the better. If you don't, a later `dep ensure` run will interpret your newly-added dependency as unused, and automatically remove it from `Gopkg.lock` and `vendor/`. This also means that if you want to add multiple dependencies at once, you'll need to do it in a single command, rather than one after the other:
 
-```
+```bash
 $ dep ensure -add github.com/pkg/errors github.com/foo/bar
 ```
 
@@ -70,13 +70,13 @@ The [ensure mechanics section on `-add`](ensure-mechanics.md#add) has a more tho
 
 Ideally, updating a dependency project to a newer version is a single command:
 
-```
+```bash
 $ dep ensure -update github.com/foo/bar
 ```
 
 This also works without arguments to try to update all dependencies, though it's generally not recommended:
 
-```
+```bash
 $ dep ensure -update
 ```
 

docs/assets

@@ -1,5 +1,5 @@
 ---
-title: Import path deduction
+title: Import Path Deduction
 ---
 
 Deduction is dep's algorithm for looking at an import path and determining the portion of the path that corresponds to the source root. The algorithm has a static component, by which a small set of known, popular hosts like GitHub and Bitbucket have their roots deduced:

docs/img/DigbyFlat.png renamed to docs/assets/DigbyFlat.png

@@ -1,8 +1,8 @@
 ---
-title: Models and Mechanics
+title: Models and Mechanisms
 ---
 
-While dep has many discrete components and moving parts, all of these parts revolve around a central model. This document explains that model, then explores the major mechanisms of dep as they relate to it.
+While dep has many discrete components and moving parts, all of these parts revolve around a central model. This document explains that model, then explores the dep's primary mechanisms in the context of that model.
 
 ## States and flows
 
@@ -17,7 +17,7 @@ Briefly, the four states are:
 
 We can visually represent these four states as follows:
 
-![dep's four states](img/four-states.png)
+![dep's four states](assets/four-states.png)
 
 ### Functional flow
 
@@ -28,7 +28,7 @@ It's useful to think of dep as a system that imposes a unidirectional, functiona
 
 We can represent these two functions visually:
 
-![dep's two main functions](img/annotated-func-arrows.png)
+![dep's two main functions](assets/annotated-func-arrows.png)
 
 This is `dep ensure` - the typical flow, used when a `Gopkg.toml` already exists. When a project does not yet have a `Gopkg.toml`, `dep init` can generate one. The essential flow remains the same, but with changed inputs: instead of reading from an existing `Gopkg.toml` file, `dep init` constructs one out of data inferred from the user's GOPATH, and/or [a metadata file from another tool](). (In other words, `dep init` automatically migrates a project from other approaches to organizing dependencies.)
 
@@ -65,7 +65,7 @@ Each of `dep ensure`'s various flags affects the behavior of the solving and ven
 
 These two flags are mutually exclusive, and determine which of `dep ensure`'s two functions are actually performed. Passing `-no-vendor` will cause only the solving function to be run, resulting in the creation of a new `Gopkg.lock`;  `-vendor-only` will skip solving and run only the vendoring function, causing `vendor/` to be repopulated from the pre-existing `Gopkg.lock`.
 
-![Flags to run only one or the other of dep's functions](img/func-toggles.png)
+![Flags to run only one or the other of dep's functions](assets/func-toggles.png)
 
 Passing `-no-vendor` has the additional effect of causing the solving function to run unconditionally,  bypassing the pre-check ordinarily made against `Gopkg.lock` to see if it already satisfies all inputs.
 
@@ -86,13 +86,13 @@ This implies two preconditions for `dep ensure -add`, at least one of which must
 
 It is also possible to explicitly specify a version constraint:
 
-```
+```bash
 $ dep ensure -add github.com/foo/[email protected]
 ```
 
-When no version constraint is included in the argument, the solving function will select the latest version that works (generally, the newest semver release, or the default branch if there are no semver releases). Either this inferred version, or the specified version, will be appended into `Gopkg.toml`.
+When no version constraint is included in the argument, the solving function will select the latest version that works (generally, the newest semver release, or the default branch if there are no semver releases). If solving succeeds, then either the argument-specified version, or if none then the version selected by the solver, will be appended into `Gopkg.toml`.
 
-The behavioral variations that arise from the assorted differences in input and current project state are best expressed as a matrix: 
+The behavioral variations that arise from the assorted differences in input and current project state are best expressed as a matrix:
 
 | Argument to `dep ensure -add` | Has `[[constraint]]` stanza in `Gopkg.toml` | In imports or `required` | Result                                   |
 | ----------------------------- | ---------------------------------------- | ------------------------ | ---------------------------------------- |
@@ -105,15 +105,15 @@ The behavioral variations that arise from the assorted differences in input and
 
 For any of the paths where `dep ensure -add` needs to run the solving function in order to generate an updated `Gopkg.lock`, the relevant information from CLI arguments is applied to the in-memory representation of `Gopkg.toml`:
 
-![Model modifications made by -add](img/required-arrows.png)
+![Model modifications made by -add](assets/required-arrows.png)
 
 Import path arguments that need to be added are injected via the `required` list, and if an explicit version requirement was specified, the equivalent of a `[[constraint]]` is created.
 
 Though these rules may ultimately be persisted if solving succeeds, they are ephemeral at least until solving succeeds. And, from the solver's perspective, the ephemeral rules are indistinguishable from rules sourced directly from disk. Thus, to the solver, `dep ensure -add [email protected]` is identical to modifying `Gopkg.toml` by adding `"foo"` to the `required` list, plus a `[[constraint]]` stanza with `version = "v1.0.0"`, then running `dep ensure`.
 
 However, because these modifications are ephemeral, a successful `dep ensure -add` may actually push the project out of sync. Constraint modifications generally do not, but if the `required` list is modified, then the project will desync. The user is warned accordingly:
 
-```
+```bash
 $ dep ensure -add github.com/foo/bar
 "github.com/foo/bar" is not imported by your project, and has been temporarily added to Gopkg.lock and vendor/.
 If you run "dep ensure" again before actually importing it, it will disappear from Gopkg.lock and vendor/.
@@ -125,7 +125,7 @@ The behavior of `dep ensure -update` is intimately linked to the behavior of the
 
 First, to solidify an implication in the discussion of [functional optimizations](#staying-in-sync), the solving function actually takes into account the pre-existing `Gopkg.lock` when it runs:
 
-![Pre-existing lock feeds back into solving function](img/lock-back.png)
+![Pre-existing lock feeds back into solving function](assets/lock-back.png)
 
 Injecting `Gopkg.lock` into the solver is a necessity. If we want the solver to preserve previously-selected versions by default, then the solver has to learn about the existing `Gopkg.lock` from somewhere. Otherwise, it wouldn't know what to preserve!
 
@@ -151,19 +151,19 @@ When a version hint from `Gopkg.lock` is not placed at the head of the version q
 
 For example, say there is a project, `github.com/foo/bar`, with the following versions:
 
-```
+```bash
 v1.2.0, v1.1.1, v1.1.0, v1.0.0, master
 ```
 
 If we depend on that project with `^1.1.0`, and have `v1.1.0` in our `Gopkg.lock` , then it means there are three versions that match our constraint, and two of them are newer than the one currently selected. (There's also an older version, `v1.0.0`, and a `master` branch, but these aren't allowed by a `^1.1.0` constraint.) An ordinary `dep ensure` run will duplicate and push `v1.1.0` ahead of all the others in the queue:
 
-```
+```bash
 [v1.1.0, v1.2.0, v1.1.1, v1.1.0, v1.0.0, master]
 ```
 
 And `v1.1.0` will be selected again, unless some other condition is presented that forces the solver to discard it. When running `dep ensure -update github.com/foo/bar`, however, the locked version is not prepended:
 
-```
+```bash
 [v1.2.0, v1.1.1, v1.1.0, v1.0.0, master]
 ```
 
@@ -175,15 +175,15 @@ Continuing with our example, it's important to note that updates with `-update`
 
 It does work with branch constraints, which we can observe by including the underlying revision. If the user has constrained on `branch = "master"`, and `Gopkg.lock` points at a topologically older revision (say, `aabbccd`) than the tip of the canonical source's `master` branch (say, `bbccdde`), then `dep ensure` will end up contructing a queue that looks like this:
 
-```
+```bash
 [master@aabbccd, v1.1.0, v1.2.0, v1.1.1, v1.1.0, v1.0.0, master@bbccdde]
 ```
 
 With `-update`, the hint at the head will be omitted; `branch = "master"` will cause the solver to reject all of the semantic versions, and finally settle on `master@bbccdde`.
 
 All versions in the version queue keep track of an underlying revision, which means the same is true if, for example, some upstream project force-pushes a git tag:
 
-```
+```bash
 [v1.1.0@aabbccd, v1.1.0, v1.2.0, v1.1.1, v1.1.0@bbccdde, v1.0.0, master]
 ```
 

docs/img/DigbyFlat.svg renamed to docs/assets/DigbyFlat.svg

@@ -2,7 +2,7 @@
 title: Failure Modes
 ---
 
-Like all complex, network-oriented software, dep has known failure modes. These generally fall into two categories: I/O and logical. I/O errors arise from unexpected responses to system calls when dep is interacting with the network or local disk. Logical failures occur when dep encounters issues within the package management problem domain.
+Like all complex, network-oriented software, dep has known failure modes. These generally fall into two categories: I/O and logical. I/O errors arise from unexpected responses to system calls that interact with the network or local disk. Logical failures occur when dep encounters issues within the package management problem domain.
 
 ## I/O errors
 
@@ -31,7 +31,7 @@ Network failures that you actually may observe are biased towards the earlier it
 
 #### Persistent network failures
 
-Although most network failures are ephemeral, there are three well-defined cases where that's not true. These are those cases, and their respective remediations:
+Although most network failures are ephemeral, there are three well-defined cases where they're more permanent:
 
 * **The network on which the source resides is permanently unreachable from the user's location:** in practice, this generally means one of two things: you've forgotten to log into your company VPN, or you're behind [the GFW](https://en.wikipedia.org/wiki/Great_Firewall). In the latter case, setting the *de facto* standard HTTP proxy environment variables that [`http.ProxyFromEnvironment()`](https://golang.org/pkg/net/http/#ProxyFromEnvironment) respects will cause dep's `go-get` HTTP metadata requests, as well as git, bzr, and hg subcommands, to utilize the proxy.
 
@@ -102,7 +102,7 @@ Some of these failures can be as straightforward as typos, and are just as easil
 
 Import path deduction, as detailed in the [deduction reference](deduction.md), has both static and dynamic phases. When neither of these phases is able to determine the source root for a given import path, it is considered to be a deduction failure. Deduction failures all have this key error text:
 
-```
+```bash
 unable to deduce repository and source type for "<bad path>"...
 ```
 
@@ -168,7 +168,7 @@ For the most part, static ("is it one of the handful of hosts we know?") and dyn
 
 When `dep ensure` or `dep init` exit with an error message looking something like this:
 
-```
+```bash
 $ dep init
 init failed: unable to solve the dependency graph: Solving failure: No versions of github.com/foo/bar met constraints:
 	v1.0.1: Could not introduce github.com/foo/[email protected], as its subpackage github.com/foo/bar/foo is missing. (Package is required by (root).)
@@ -181,7 +181,7 @@ _Note: all three of the other hard failure types can sometimes be reported as th
 
 It means that the solver was unable to find a combination of versions for all dependencies that satisfy all the rules enforced by the solver. It is crucial to note that, just because dep provides a big list of reasons why each version failed _doesn't mean_ you have to address each one! That's just dep telling you why it ultimately couldn't use each of those versions in a solution.
 
-These rules, and specific remediations for failing to meet them, are described in detail in the section on [solver invariants](the-solver.md#solving-invariants). This section is about the steps to take when solving failures occur in general. But, to set context, here's a quick summary:
+These rules, and specific remediations for failing to meet them, are described in detail in the section on [solver invariants](the-solver.md#solving-invariants). This section is about the steps to take when solving failures occur in general. But, to set context, here's a summary:
 
 * **`[[constraint]]` conflicts:** when projects in the dependency graph disagree on what [versions](gopkg.toml.md#version-rules) are acceptable for a project, or where to [source](gopkg.toml.md#source) it from.
   * Remediation will usually be either changing a `[[constraint]]` or adding an `[[override]]`, but genuine conflicts may require forking and hacking code.