doc: regular updates (mid Jan)

pages/doc.js

@@ -129,7 +129,7 @@ export default function Documentation({ item, headings, markdown, errorCode }) {
 }
 
 Documentation.getInitialProps = async ({ asPath, req }) => {
-  const item = getItemByPath(asPath.split('#')[0].split('?')[0])
+  const item = getItemByPath(asPath.split(/[?#]/)[0])
 
   if (!item) {
     return {

public/static/docs/command-reference/add.md

@@ -87,10 +87,10 @@ reproducible.
 
 ## Options
 
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to add by searching
-  each target directory and its subdirectories for data files. For each file
-  found, a new DVC-file is created using the process described in this command's
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to add by searching each
+  target directory and its subdirectories for data files. For each file found, a
+  new DVC-file is created using the process described in this command's
   description.
 
 - `--no-commit` - do not save outputs to cache. A DVC-file is created, and an
@@ -197,8 +197,8 @@ Saving information to 'pics.dvc'.
 
 There are no [DVC-files](/doc/user-guide/dvc-file-format) generated within this
 directory structure, but the images are all added to the <abbr>cache</abbr>. DVC
-prints a message to that effect, mentioning that `md5` values are computed for
-each directory. A single `pics.dvc` DVC-file is generated for the top-level
+prints a message about this, mentioning that `md5` values are computed for each
+directory. A single `pics.dvc` DVC-file is generated for the top-level
 directory, and it contains:
 
 ```yaml

public/static/docs/command-reference/checkout.md

@@ -67,16 +67,16 @@ be pulled from remote storage using `dvc pull`.
 
 ## Options
 
-- `-d`, `--with-deps` - determine files to update by tracking dependencies to
-  the target DVC-files (stages). This option only has effect when one or more
-  `targets` are specified. By traversing all stage dependencies, DVC searches
-  backward from the target stages in the corresponding pipelines. This means DVC
-  will not checkout files referenced in later stages than the `targets`.
-
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to checkout by
-  searching each target directory and its subdirectories for DVC-files to
-  inspect.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to update by tracking dependencies to
+  the target DVC-files (stages). By traversing all stage dependencies, DVC
+  searches backward from the target stages in the corresponding pipelines. This
+  means DVC will not checkout files referenced in later stages than the
+  `targets`.
+
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to checkout by searching
+  each target directory and its subdirectories for DVC-files to inspect.
 
 - `-f`, `--force` - does not prompt when removing workspace files. Changing the
   current set of DVC-files with `git checkout` can result in the need for DVC to

public/static/docs/command-reference/commit.md

@@ -68,16 +68,15 @@ reproducibility in those cases.
 
 ## Options
 
-- `-d`, `--with-deps` - determine files to commit by tracking dependencies to
-  the target DVC-files (stages). This option only has effect when one or more
-  `targets` are specified. By traversing all stage dependencies, DVC searches
-  backward from the target stages in the corresponding pipelines. This means DVC
-  will not commit files referenced in later stages than the `targets`.
-
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to commit by
-  searching each target directory and its subdirectories for DVC-files to
-  inspect.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to commit by tracking dependencies to
+  the target DVC-files (stages). By traversing all stage dependencies, DVC
+  searches backward from the target stages in the corresponding pipelines. This
+  means DVC will not commit files referenced in later stages than the `targets`.
+
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to commit by searching
+  each target directory and its subdirectories for DVC-files to inspect.
 
 - `-f`, `--force` - commit data even if checksums for dependencies or outputs
   did not change.

public/static/docs/command-reference/config.md

@@ -110,8 +110,8 @@ for more details.) This section contains the following options:
   > directory into paths relative to the config file location.
 
 - `cache.protected` - make files under DVC control read-only. Possible values
-  are `true` or `false` (default). Run `dvc checkout` for the change to go into
-  effect.
+  are `true` or `false` (default). Run `dvc checkout` after changing the value
+  of this option for the change to go into effect.
 
   Due to the way DVC handles linking between the data files in the cache and
   their counterparts in the <abbr>workspace</abbr>, it's easy to accidentally
@@ -200,18 +200,19 @@ learn more about the state file (database) that is used for optimization.
 $ dvc config core.loglevel debug
 ```
 
-## Example: Add an S3 remote
+## Example: Add an S3 remote, and set it as default
 
 > 💡 Before adding an S3 remote, be sure to
 > [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html).
 
-This also sets the remote as the <abbr>project</abbr> default:
-
 ```dvc
 $ dvc remote add myremote s3://bucket/path
 $ dvc config core.remote myremote
 ```
 
+> Note that this is equivalent to using `dvc remote add` with the
+> `-d`/`--default` option.
+
 ## Example: Default remotes
 
 Use remote `myremote` by default:

public/static/docs/command-reference/fetch.md

@@ -78,16 +78,15 @@ specified in DVC-files currently in the project are considered by `dvc fetch`
   `dvc config core.remote`). The argument `REMOTE` is a remote name defined
   using the `dvc remote` command.
 
-- `-d`, `--with-deps` - determine files to download by tracking dependencies to
-  the target DVC-files (stages). This option only has effect when one or more
-  `targets` are specified. By traversing all stage dependencies, DVC searches
-  backward from the target stages in the corresponding pipelines. This means DVC
-  will not fetch files referenced in later stages than the `targets`.
-
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to fetch by
-  searching each target directory and its subdirectories for DVC-files to
-  inspect.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to download by tracking dependencies
+  to the target DVC-files (stages). By traversing all stage dependencies, DVC
+  searches backward from the target stages in the corresponding pipelines. This
+  means DVC will not fetch files referenced in later stages than the `targets`.
+
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to fetch by searching
+  each target directory and its subdirectories for DVC-files to inspect.
 
 - `-j JOBS`, `--jobs JOBS` - number of threads to run simultaneously to handle
   the downloading of files from the remote. Using more jobs may improve the

public/static/docs/command-reference/get.md

@@ -19,10 +19,10 @@ positional arguments:
 ## Description
 
 Provides an easy way to download files or directories tracked in any <abbr>DVC
-project</abbr> (e.g. datasets, ML models), or Git repository (e.g. source code,
-small images or data files). The file or directory in path is copied to the
-current working directory. (For remote URLs, it works like downloading with
-wget, but supporting DVC <abbr>data artifacts</abbr> and files tracked by Git.)
+project</abbr> (e.g. datasets, intermediate results, ML models), or Git
+repository (e.g. source code, small image/other files). `dvc get` copies the
+target file or directory (`url`/`path`) to the current working directory. (For
+<abbr>DVC repositories</abbr>, it's analogous to `wget`.)
 
 Note that this command doesn't require an existing DVC project to run in. It's a
 single-purpose command that can be used out of the box after installing DVC.
@@ -35,11 +35,11 @@ doesn't have a default remote set up, instead of downloading, DVC will try to
 copy the target data from the external source project or its
 <abbr>cache</abbr>).
 
-The `path` argument of this command is used to specify the location, within the
-source project or repository at `url`, of the target(s) to be downloaded. It can
-point to any file or directory in the source project, including <abbr>outputs
-</abbr> tracked by DVC as well as files tracked by Git. Note that for the
-former, data should be specified in one of the
+The `path` argument of this command is used to specify the location of the
+target(s) to be downloaded within the source project or repository at `url`. It
+can point to any file or directory in the source project, including
+<abbr>outputs </abbr> tracked by DVC as well as files tracked by Git. Note that
+for the former, data should be specified in one of the
 [DVC-files](/doc/user-guide/dvc-file-format) of the source repository. (In this
 case, a default [DVC remote](/doc/command-reference/remote) needs to be
 configured in the project, containing the actual data.)
@@ -58,11 +58,12 @@ name.
   an existing directory is specified, then the output will be placed inside of
   it.
 
-- `--rev` - specific
+- `--rev` - `url` is expected to represent a Git repository for this option to
+  have an effect. Specific
   [Git revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
-  (such as a branch name, a tag, or a commit hash) of the Git repository to
-  download the file or directory from. The tip of the default branch is used by
-  default when this option is not specified.
+  (such as a branch name, a tag, or a commit hash) of the repository to download
+  the file or directory from. The tip of the default branch is used by default
+  when this option is not specified.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
@@ -107,9 +108,9 @@ The same example applies to raw or intermediate <abbr>data artifacts</abbr> as
 well, of course, for cases where we want to download those files or directories
 and perform some analysis on them.
 
-## Examples: Get a Git-tracked model file
+## Examples: Get a misc. Git-tracked file
 
-We can also use `dvc get` to retrieve any file or directory that exists in a git
+We can also use `dvc get` to retrieve any file or directory that exists in a Git
 repository.
 
 ```dvc

public/static/docs/command-reference/import.md

@@ -23,10 +23,10 @@ positional arguments:
 
 Provides an easy way to reuse files or directories tracked in any <abbr>DVC
 project</abbr> (e.g. datasets, intermediate results, ML models) or Git
-repository (e.g. other files and directories), into the workspace. The
-`dvc import` command downloads such a <abbr>data artifact</abbr> in a way that
-it is tracked with DVC, so it can be updated when the data source changes. (See
-`dvc update`.)
+repository (e.g. source code, small image/other files). `dvc import` downloads
+the target file or directory (`url`/`path`) in a way so that it's tracked with
+DVC, becoming a local <abbr>data artifact</abbr>. This also permits updating the
+import later, if it has changed in its data source. (See `dvc update`.)
 
 The `url` argument specifies the address of the <abbr>DVC project</abbr> or Git
 repository containing the data source. Both HTTP and SSH protocols are supported
@@ -36,11 +36,11 @@ doesn't have a default remote set up, instead of downloading, DVC will try to
 copy the target data from the external source project or its
 <abbr>cache</abbr>).
 
-The `path` argument of this command is used to specify the location, within the
-source project or repository at `url`, of the target(s) to be downloaded. It can
-point to any file or directory in the source project, including <abbr>outputs
-</abbr> tracked by DVC as well as files tracked by Git. Note that for the
-former, data should be specified in one of the
+The `path` argument of this command is used to specify the location of the
+target(s) to be downloaded within the source project or repository at `url`. It
+can point to any file or directory in the source project, including
+<abbr>outputs </abbr> tracked by DVC as well as files tracked by Git. Note that
+for the former, data should be specified in one of the
 [DVC-files](/doc/user-guide/dvc-file-format) of the source repository. (In this
 case, a default [DVC remote](/doc/command-reference/remote) needs to be
 configured in the project, containing the actual data.)
@@ -75,13 +75,16 @@ data artifact from the source project.
   an existing directory is specified, then the output will be placed inside of
   it.
 
-- `--rev` - specific
+- `--rev` - `url` is expected to represent a Git repository for this option to
+  have an effect. Specific
   [Git revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
-  (such as a branch name, a tag, or a commit hash) of the Git repository to
-  import the data from. The tip of the repository's default branch is used by
-  default when this option is not specified. Note that this adds a `rev` field
-  in the import stage that fixes it to this revision. This can impact the
-  behavior of `dvc update`. (See **re-importing** example below.)
+  (such as a branch name, a tag, or a commit hash) of the repository to download
+  the file or directory from. The tip of the default branch is used by default
+  when this option is not specified.
+
+  > Note that this adds a `rev` field in the import stage that fixes it to this
+  > revision. This can impact the behavior of `dvc update`. (See
+  > **re-importing** example below.)
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
@@ -130,7 +133,7 @@ Several of the values above are pulled from the original stage file
 subfields under `repo` are used to save the origin and version of the
 dependency.
 
-## Example: fixed revisions & re-importing
+## Example: Fixed revisions & re-importing
 
 To import a specific revision of a <abbr>data artifact</abbr>, we may use the
 `--rev` option:

public/static/docs/command-reference/metrics/show.md

@@ -89,9 +89,10 @@ extension.)
   Similar to `-a` above. Note that both options can be combined, for example
   using the `-aT` flag.
 
-- `-R`, `--recursive` - `path` is expected to be a directory for this option to
-  have effect. Determines the metric files to show by searching each target
-  directory and its subdirectories for DVC-files to inspect.
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the metric files to show by
+  searching each target directory and its subdirectories for DVC-files to
+  inspect.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 

public/static/docs/command-reference/pull.md

@@ -72,15 +72,15 @@ reflinks or hardlinks to put it in the workspace without copying. See
   to save different experiments or project checkpoints. Note that both options
   can be combined, for example using the `-aT` flag.
 
-- `-d`, `--with-deps` - determines files to download by tracking dependencies to
-  the target DVC-files (stages). This option only has effect when one or more
-  `targets` are specified. By traversing all stage dependencies, DVC searches
-  backward from the target stages in the corresponding pipelines. This means DVC
-  will not pull files referenced in later stages than the `targets`.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to download by tracking dependencies
+  to the target DVC-files (stages). By traversing all stage dependencies, DVC
+  searches backward from the target stages in the corresponding pipelines. This
+  means DVC will not pull files referenced in later stages than the `targets`.
 
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to pull by searching
-  each target directory and its subdirectories for DVC-files to inspect.
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to pull by searching each
+  target directory and its subdirectories for DVC-files to inspect.
 
 - `-f`, `--force` - does not prompt when removing workspace files, which occurs
   when these file no longer match the current DVC-file references. This option
@@ -103,19 +103,18 @@ reflinks or hardlinks to put it in the workspace without copying. See
 ## Examples
 
 For using the `dvc pull` command, a remote storage must be defined. (See
-`dvc remote`.) For an existing <abbr>project</abbr>, remotes are usually already
-set up and you can use `dvc remote list` to check them. Just to remind how it is
-done and set a context for the example, let's define an SSH remote with the
-`dvc remote add` command:
+`dvc remote add`.) For an existing <abbr>project</abbr>, remotes are usually
+already set up and you can use `dvc remote list` to check them. To remember how
+it's done, and set a context for the example, let's define a default SSH remote:
 
 ```dvc
-$ dvc remote add r1 ssh://_username_@_host_/path/to/dvc/remote/storage
+$ dvc remote add -d r1 ssh://_username_@_host_/path/to/dvc/remote/storage
 $ dvc remote list
 r1	ssh://_username_@_host_/path/to/dvc/remote/storage
 ```
 
-> DVC supports several remote types. For details, see the
-> [`remote add`](/doc/command-reference/remote/add) documentation.
+> DVC supports several
+> [remote types](/doc/command-reference/remote/add#supported-storage-types).
 
 Having some images and other files in remote storage, we can pull all changed
 files from the current Git branch: