Merge pull request #2182 from iterative/jorge

Misc. updates

content/docs/command-reference/cache/dir.md

@@ -29,10 +29,10 @@ cache directory.
 
 ## Options
 
-- `--global` - modify a global config file (e.g. `~/.config/dvc/config`) instead
-  of the project's `.dvc/config`.
+- `--global` - modify the global config file (e.g. `~/.config/dvc/config`)
+  instead of the project's `.dvc/config`.
 
-- `--system` - modify a system config file (e.g. `/etc/dvc/config`) instead of
+- `--system` - modify the system config file (e.g. `/etc/dvc/config`) instead of
   `.dvc/config`.
 
 - `--local` - modify a local [config file](/doc/command-reference/config)

content/docs/command-reference/config.md

@@ -64,11 +64,11 @@ multiple projects and users, respectively:
   need to specify private config option values that you don't want to track and
   share with Git (credentials, private locations, etc).
 
-- `--global` - modify a global config file (e.g. `~/.config/dvc/config`) instead
-  of the project's `.dvc/config`. Useful to apply config options to all your
-  projects.
+- `--global` - modify the global config file (e.g. `~/.config/dvc/config`)
+  instead of the project's `.dvc/config`. Useful to apply config options to all
+  your projects.
 
-- `--system` - modify a system config file (e.g. `/etc/dvc/config`) instead of
+- `--system` - modify the system config file (e.g. `/etc/dvc/config`) instead of
   `.dvc/config`. Useful to apply config options to all the projects (all users)
   in the machine. May require superuser access e.g.
   `sudo dvc config --system ...` (Linux).

content/docs/command-reference/pull.md

@@ -233,9 +233,9 @@ 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 -d r1 ssh://_username_@_host_/path/to/dvc/remote/storage
+$ dvc remote add -d r1 ssh://[email protected]/path/to/dvc/remote/storage
 $ dvc remote list
-r1	ssh://_username_@_host_/path/to/dvc/remote/storage
+r1	ssh://[email protected]/path/to/dvc/remote/storage
 ```
 
 > DVC supports several

content/docs/command-reference/push.md

@@ -116,15 +116,15 @@ To use `dvc push` (without options), a default
 
 ```dvc
 $ dvc remote add --default r1 \
-                 ssh://_username_@_host_/path/to/dvc/cache/directory
+                 ssh://[email protected]/path/to/dvc/cache/directory
 ```
 
 > For existing <abbr>projects</abbr>, remotes are usually already set up. You
 > can use `dvc remote list` to check them:
 >
 > ```dvc
 > $ dvc remote list
-> r1	ssh://_username_@_host_/path/to/dvc/cache/directory
+> r1	ssh://[email protected]/path/to/dvc/cache/directory
 > ```
 
 Push entire data <abbr>cache</abbr> from the current <abbr>workspace</abbr> to

content/docs/command-reference/remote/modify.md

@@ -134,14 +134,19 @@ these parameters, you could use the following options.
   $ dvc remote modify myremote credentialpath /path/to/creds
   ```
 
-- `configpath` - path to the AWS config file. The location defaults to
-  `~/.aws/config`. It supports S3-specific
-  [configuration values](https://docs.aws.amazon.com/cli/latest/topic/s3-config.html#configuration-values):
+- `configpath` - path to the
+  [AWS CLI config file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
+  The default AWS CLI config file path (e.g. `~/.aws/config`) is used if this
+  parameter isn't set.
 
   ```dvc
   $ dvc remote modify myremote --local configpath /path/to/config
   ```
 
+  > Note that only the S3-specific
+  > [configuration values](https://docs.aws.amazon.com/cli/latest/topic/s3-config.html#configuration-values)
+  > are used.
+
 - `endpointurl` - endpoint URL to access S3:
 
   ```dvc
@@ -500,7 +505,9 @@ more information.
 ### Click for SSH
 
 - `url` - remote location, in a regular
-  [SSH format](https://tools.ietf.org/id/draft-salowey-secsh-uri-00.html#sshsyntax):
+  [SSH format](https://tools.ietf.org/id/draft-salowey-secsh-uri-00.html#sshsyntax).
+  Note that this can already include the `user` parameter, embedded into the
+  URL:
 
   ```dvc
   $ dvc remote modify myremote url \
@@ -513,7 +520,7 @@ more information.
 
   > Note that your server's SFTP root might differ from its physical root (`/`).
 
-- `user` - username to access the remote.
+- `user` - username to access the remote:
 
   ```dvc
   $ dvc remote modify --local myremote user myuser
@@ -523,8 +530,9 @@ more information.
 
   1. `user` parameter set with this command (found in `.dvc/config`);
   2. User defined in the URL (e.g. `ssh://[email protected]/path`);
-  3. User defined in `~/.ssh/config` for this host (URL);
-  4. Current user
+  3. User defined in the SSH config file (e.g. `~/.ssh/config`) for this host
+     (URL);
+  4. Current system user
 
 - `port` - port to access the remote.
 
@@ -536,7 +544,8 @@ more information.
 
   1. `port` parameter set with this command (found in `.dvc/config`);
   2. Port defined in the URL (e.g. `ssh://example.com:1234/path`);
-  3. Port defined in `~/.ssh/config` for this host (URL);
+  3. Port defined in the SSH config file (e.g. `~/.ssh/config`) for this host
+     (URL);
   4. Default SSH port 22
 
 - `keyfile` - path to private key to access the remote.
@@ -641,8 +650,8 @@ by HDFS. Read more about by expanding the WebHDFS section in
 
 - `hdfscli_config` - path to a `HdfsCLI` cfg file. WebHDFS access depends on
   `HdfsCLI`, which allows the usage of a configuration file by default located
-  in `~/.hdfscli.cfg`. In the file, multiple aliases can be set with their own
-  connection parameters, like `url` or `user`. If using a cfg file,
+  in `~/.hdfscli.cfg` (Linux). In the file, multiple aliases can be set with
+  their own connection parameters, like `url` or `user`. If using a cfg file,
   `webhdfs_alias` can be set to specify which alias to use.
 
   ```dvc

content/docs/start/data-pipelines.md

@@ -222,7 +222,7 @@ This should be a good point to commit the changes with Git. These include
 
 ## Reproduce
 
-The whole point of creating this `dvc.yaml` pipeline file is an ability to
+The whole point of creating this `dvc.yaml` pipelines file is an ability to
 reproduce the pipeline:
 
 ```dvc

content/docs/user-guide/external-dependencies.md

@@ -37,6 +37,9 @@ certain `dvc remote` types. Currently, the following protocols are supported:
 Let's take a look at defining and running a `download_file` stage that simply
 downloads a file from an external location, on all the supported location types.
 
+> See the [Remote alias example](#example-using-dvc-remote-aliases) for info. on
+> using remote locations that require manual authentication setup.
+
 <details>
 
 ### Click for Amazon S3
@@ -144,10 +147,9 @@ $ dvc run -n download_file \
 ## Example: Using DVC remote aliases
 
 You may want to encapsulate external locations as configurable entities that can
-be managed independently. This is useful if multiple dependencies (or stages)
-reuse the same location, or if its likely to change in the future. And if the
-location requires authentication, you need a way to configure it in order to
-connect.
+be managed independently. This is useful if the connection requires
+authentication, if multiple dependencies (or stages) reuse the same location, or
+if the URL is likely to change in the future.
 
 [DVC remotes](/doc/command-reference/remote) can do just this. You may use
 `dvc remote add` to define them, and then use a special URL with format
@@ -157,12 +159,11 @@ dependency.
 Let's see an example using SSH. First, register and configure the remote:
 
 ```dvc
-$ dvc remote add myssh ssh://myserver.com
-$ dvc remote modify --local myssh user myuser
-$ dvc remote modify --local myssh password mypassword
+$ dvc remote add myssh ssh://[email protected]
+$ dvc remote modify --local myssh password 'mypassword'
 ```
 
-> Please refer to `dvc remote add` for more details like setting up access
+> Please refer to `dvc remote modify` for more details like setting up access
 > credentials for the different remote types.
 
 Now, use an alias to this remote when defining the stage: