cmd ref: review language around term "effect" (conditional applicabil…

…ity of options)

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 setting changing the
+  value for 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

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

@@ -58,7 +58,8 @@ 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 DVC repository to
   download the file or directory from. The tip of the default branch is used by

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

@@ -74,13 +74,16 @@ data artifact from the source project.
   an existing directory is specified, then the output will be placed inside of
   it.
 
-- `--rev` - specific
-  [Git revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
+- `--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 DVC 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.)
+  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.
 

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`.
-
-- `-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.
+- `-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 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

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

@@ -81,15 +81,15 @@ to push.
   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 upload 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 push 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 push 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 upload 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 push 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 push by searching each
+  target directory and its subdirectories for DVC-files to inspect.
 
 - `-j JOBS`, `--jobs JOBS` - specifies number of jobs to run simultaneously
   while uploading files to the remote. The effect is to control the number of

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

@@ -95,8 +95,8 @@ and only execute the final stage.
   reproduced as part of the pipeline in the parent directory, or as an
   independent unit.
 
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the stages to reproduce by
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the stages to reproduce by
   searching each target directory and its subdirectories for DVC-files to
   inspect.
 

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

@@ -143,8 +143,8 @@ data pipeline (e.g. random numbers, time functions, hardware dependency, etc.)
   confirmation.
 
 - `--ignore-build-cache` - This options has an effect if an equivalent stage
-  file exists (same dependencies, outputs, and `command` to execute) which has
-  been already executed and is up to date. In this case, `dvc run` won't
+  file exists (same dependencies, outputs, and `command` to execute), that has
+  been already executed, and is up to date. In this case, `dvc run` won't
   normally execute the `command` again. The exception is when the existing stage
   is considered always changed (see `--always-changed` option). This option
   gives a way to forcefully execute the `command` anyway. Useful if the

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

@@ -98,12 +98,12 @@ workspace) is different from remote storage. Bringing the two into sync requires
 
 ## Options
 
-- `-d`, `--with-deps` - determines files to check 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 show changes occurring in later stages than the `targets`. Applies
-  whether or not `--cloud` is specified.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to check 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 show changes occurring in later stages than the `targets`.
+  Applies whether or not `--cloud` is specified.
 
 - `-c`, `--cloud` - enables comparison against a remote. (See `dvc remote`.). If
   no `--remote` option has been given, DVC will compare against the default