doc: misc. updates (#1673)

* cmd: remove unnecessary commas in get and import

* cmd: fix typo in add

* cmd: remote copy edits
per #1617 (comment)

* guide: .dvcignore copy edit

* cmd: init copy edits

* clarify about dirs in import -o

* cmd: review get -o desc

* dvcignore: updates to guide and check-ignore ref.
per #1629 (review)
et al.

* cmd: update check-ignore -n
per iterative/dvc#4323 (comment)

* cmd: fix get.import -o descriptions
per #1673 (review)
and #1673 (review)

* cmd: copy edits to remote add/modify

Author: jorgeorpinel

content/docs/command-reference/check-ignore.md

@@ -10,7 +10,7 @@ usage: usage: dvc check-ignore [-h] [-q | -v] [-d] [-n]
                                targets [targets ...]
 
 positional arguments:
-  targets        File or directory paths to check (wildcards supported)
+  targets        File or directory paths to check
 ```
 
 ## Description
@@ -19,16 +19,15 @@ This helper command checks whether the given `targets` are ignored by DVC
 according to the [`.dvcignore` file](/doc/user-guide/dvcignore) (if any). The
 ones that are ignored indeed are printed back.
 
-> Note that your shell may support path wildcards such as `dir/file*` and these
-> can be fed as `targets` to `dvc check-ignore`, as shown in the
-> [examples](#examples).
-
 ## Options
 
-- `-d`, `--details` - show the exclude pattern together with each target path.
+- `-d`, `--details` - show the exclude patterns along with each target path. A
+  series of lines are printed in this format:
+  `<path/to/.dvcignore>:<line_num>:<pattern> <target_path>`
 
-- `-n`, `--non-matching` - show the target paths which don’t match any pattern.
-  Only usable when `--details` is also employed
+- `-n`, `--non-matching` - include the target paths which don’t match any
+  pattern in the `--details` list. All fields in each line, except for
+  `<target_path>`, will be empty. Has no effect without `--details`.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
@@ -40,13 +39,14 @@ ones that are ignored indeed are printed back.
 ## Examples
 
 First, let's create a `.dvcignore` file with some patterns in it, and some files
-to check against it.
+to check against it:
 
 ```dvc
 $ echo "file*\n\!file2" >> .dvcignore
 $ cat .dvcignore
 file*
 !file2
+
 $ touch file1 file2 other
 $ ls
 file1  file2 other
@@ -58,31 +58,33 @@ given our `.dvcignore` file:
 ```dvc
 $ dvc check-ignore file1
 file1
+
 $ dvc check-ignore file1 file2
 file1
 file2
+
 $ dvc check-ignore other
   # There's no command output, meaning `other` is not excluded.
+
 $ dvc check-ignore file*
 file1
 file2
 ```
 
-If the `--details` option is used, a series of lines are printed using this
-format: `<path/to/.dvcignore>:<line_num>:<pattern> | <target_path>`
+With `--details` (`-d`), we get a detailed report of all the matches:
 
 ```dvc
 $ dvc check-ignore -d file1 file2
 .dvcignore:1:file*	file1
 .dvcignore:2:!file2	file2
-$ dvc check-ignore -d other
+
 $ dvc check-ignore -d file*
 .dvcignore:1:file*	file1
 .dvcignore:2:!file2	file2
 ```
 
-With the `--non-matching` option, non-matching `targets` will also be included
-in the list. All fields in each line, except for `<target path>`, will be empty.
+With the `--non-matching` (`-n`) option, non-matching `targets` will also be
+included in the details list:
 
 ```dvc
 $ dvc check-ignore -d -n other

content/docs/command-reference/get.md

@@ -55,11 +55,10 @@ name.
 
 ## Options
 
-- `-o <path>`, `--out <path>` - specify a path (directory and/or file name) to
-  the desired location to place the download file in. The default value (when
-  this option isn't used) is the current working directory (`.`) and original
-  file name. If an existing directory is specified, then the target data will be
-  placed inside.
+- `-o <path>`, `--out <path>` - specify a path to the desired location in the
+  workspace to place the downloaded file or directory (instead of using the
+  current working directory). Directories specified in the path will be created
+  by this command.
 
 - `--rev <commit>` - commit hash, branch or tag name, etc. (any
   [Git revision](https://git-scm.com/docs/revisions)) of the repository to

content/docs/command-reference/import.md

@@ -75,11 +75,10 @@ from the source repo.
 
 ## Options
 
-- `-o <path>`, `--out <path>` - specify a path (directory and/or file name) to
-  the desired location to place the imported file in (instead of using the
-  current working directory). If an existing directory is specified, the target
-  data will be placed inside. If `path` contains a parent directory which does
-  not exist, this command will fail.
+- `-o <path>`, `--out <path>` - specify a path to the desired location in the
+  workspace to place the downloaded file or directory (instead of using the
+  current working directory). Directories specified in the path should already
+  exist, otherwise this command will fail.
 
 - `--rev <commit>` - commit hash, branch or tag name, etc. (any
   [Git revision](https://git-scm.com/docs/revisions)) of the repository to

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

@@ -155,23 +155,22 @@ For more information about the variables DVC supports, please visit
 ### Click for Microsoft Azure Blob Storage
 
 ```dvc
-$ dvc remote add --local myremote azure://my-container-name/path
+$ dvc remote add -d myremote azure://my-container-name/path
 $ dvc remote modify --local myremote connection_string \
-                            "my-connection-string"
+                            'my-connection-string'
 ```
 
-> The connection string contains access to data and is inserted into the
-> `.dvc/config` file. Therefore, it is safer to add the remote with the
-> `--local` option, enforcing it to be written to a Git-ignored config file. See
-> `dvc remote modify` for a full list of Azure storage parameters.
+> The connection string contains sensitive user info. Therefore, it's safer to
+> add it with the `--local` option, so it's written to a Git-ignored config
+> file. See `dvc remote modify` for a full list of Azure storage parameters.
 
 The Azure Blob Storage remote can also be configured globally via environment
 variables:
 
 ```dvc
-$ export AZURE_STORAGE_CONNECTION_STRING="<my-connection-string>"
-$ export AZURE_STORAGE_CONTAINER_NAME="my-container-name"
-$ dvc remote add -d myremote "azure://"
+$ export AZURE_STORAGE_CONNECTION_STRING='<my-connection-string>'
+$ export AZURE_STORAGE_CONTAINER_NAME='my-container-name'
+$ dvc remote add -d myremote 'azure://'
 ```
 
 > For more information on configuring Azure Storage connection strings, visit
@@ -181,7 +180,7 @@ $ dvc remote add -d myremote "azure://"
   Storage Account. If you don't already have a storage account, you can create
   one following
   [these instructions](https://docs.microsoft.com/en-us/azure/storage/common/storage-create-storage-account).
-  The connection string can be found in the "Access Keys" pane of your Storage
+  The connection string can be found in the **Access Keys** pane of your Storage
   Account resource in the Azure portal.
 
   > 💡 Make sure the value is quoted so its processed correctly by the console.
@@ -198,13 +197,12 @@ $ dvc remote add -d myremote "azure://"
 
 To start using a GDrive remote, first add it with a
 [valid URL format](/doc/user-guide/setup-google-drive-remote#url-format). Then
-simply use any DVC command that needs it (e.g. `dvc pull`, `dvc fetch`,
-`dvc push`), and follow the instructions to connect your Google Drive with DVC.
-For example:
+use any DVC command that needs to connect to it (e.g. `dvc pull` or `dvc push`
+once there's tracked data to synchronize). For example:
 
 ```dvc
 $ dvc remote add -d myremote gdrive://0AIac4JZqHhKmUk9PDA/dvcstore
-$ dvc push
+$ dvc push  # Assuming there's data to push
 
 Go to the following link in your browser:
 
@@ -262,18 +260,18 @@ To set key id, key secret and endpoint (or any other OSS parameter), use
 option to avoid committing your secrets with Git:
 
 ```dvc
+$ dvc remote modify myremote oss_endpoint <endpoint>
 $ dvc remote modify myremote --local oss_key_id my-key-id
 $ dvc remote modify myremote --local oss_key_secret my-key-secret
-$ dvc remote modify myremote oss_endpoint endpoint
 ```
 
 You can also set environment variables and use them later, to set environment
 variables use following environment variables:
 
 ```dvc
-$ export OSS_ACCESS_KEY_ID="my-key-id"
-$ export OSS_ACCESS_KEY_SECRET="my-key-secret"
-$ export OSS_ENDPOINT="endpoint"
+$ export OSS_ACCESS_KEY_ID='my-key-id'
+$ export OSS_ACCESS_KEY_SECRET='my-key-secret'
+$ export OSS_ENDPOINT='endpoint'
 ```
 
 **Testing your OSS storage using docker**
@@ -353,16 +351,14 @@ $ dvc remote add -d myremote webdavs://example.com/public.php/webdav
 
 > See also `dvc remote modify` for a full list of WebDAV parameters.
 
-> Note that the location of the WebDAV API endpoint `/public.php/webdav` might
-> be different for your server.
-
 </details>
 
 <details>
 
 ### Click for local remote
 
-A "local remote" is a directory in the machine's file system.
+A "local remote" is a directory in the machine's file system. Not to be confused
+with the `--local` option of `dvc remote` commands!
 
 > While the term may seem contradictory, it doesn't have to be. The "local" part
 > refers to the type of location where the storage is: another directory in the
@@ -385,7 +381,7 @@ $ cat .dvc/config
 Using a relative path:
 
 ```dvc
-$ dvc remote add myremote ../my-dvc-storage
+$ dvc remote add -d myremote ../my-dvc-storage
 $ cat .dvc/config
   ...
   ['remote "myremote"']

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

@@ -224,17 +224,17 @@ must explicitly set the `endpointurl` in the configuration:
 For example:
 
 ```dvc
-$ dvc remote add myremote s3://path/to/dir
+$ dvc remote add -d myremote s3://path/to/dir
 $ dvc remote modify myremote endpointurl \
                     https://object-storage.example.com
 ```
 
 S3 remotes can also be configured entirely via environment variables:
 
 ```dvc
-$ export AWS_ACCESS_KEY_ID="<my-access-key>"
-$ export AWS_SECRET_ACCESS_KEY="<my-secret-key>"
-$ dvc remote add myremote "s3://bucket/myremote"
+$ export AWS_ACCESS_KEY_ID='<my-access-key>'
+$ export AWS_SECRET_ACCESS_KEY='<my-secret-key>'
+$ dvc remote add -d myremote 's3://bucket/myremote'
 ```
 
 For more information about the variables DVC supports, please visit
@@ -249,14 +249,14 @@ For more information about the variables DVC supports, please visit
 - `url` - remote location URL.
 
   ```dvc
-  $ dvc remote modify myremote url "azure://my-container-name/path"
+  $ dvc remote modify myremote url 'azure://my-container-name/path'
   ```
 
 - `connection_string` - connection string.
 
   ```dvc
   $ dvc remote modify --local myremote connection_string \
-                              "my-connection-string"
+                              'my-connection-string'
   ```
 
 > The connection string contains sensitive user info. Therefore, it's safer to
@@ -399,13 +399,13 @@ more information.
 
   ```dvc
   $ dvc remote modify \
-        myremote credentialpath "/home/.../project-XXXXXXX.json"
+        myremote credentialpath '/home/.../project-XXXXXXX.json'
   ```
 
   Alternatively, the `GOOGLE_APPLICATION_CREDENTIALS` env var can be set:
 
   ```dvc
-  $ export GOOGLE_APPLICATION_CREDENTIALS=".../project-XXXXXXX.json"
+  $ export GOOGLE_APPLICATION_CREDENTIALS='.../project-XXXXXXX.json'
   ```
 
 </details>

content/docs/user-guide/dvcignore.md

@@ -33,7 +33,7 @@ DVC-handled directories.
 they are not produced by a pipeline [stage](/doc/command-reference/run), they
 can be lost permanently.
 
-Keep in mind, that when you add `.dvcignore` patterns that affect an existing
+Keep in mind that when you add `.dvcignore` patterns that affect an existing
 <abbr>output</abbr>, its status will change and DVC will behave as if that
 affected files were deleted.