docs: more Markdown touch-ups

- replace the "none" code-hint with "console"
- some changes in the "experimental" instructions
- reformat some notes
- reformat / re-indent JSON output to use 2 spaces (for consistency)
- split JSON outputs to separate code-block so that it can be highlighted

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/reference/commandline/build.md

@@ -384,14 +384,15 @@ contents of the `debug` file instead of looking for a `Dockerfile` and will use
 directory structure of the build context, regardless of how you refer to it on
 the command line.
 
-> **Note:**
+> **Note**
-> `docker build` will return a `no such file or directory` error if the
+>
+> `docker build` returns a `no such file or directory` error if the
 > file or directory does not exist in the uploaded context. This may
 > happen if there is no context, or if you specify a file that is
 > elsewhere on the Host system. The context is limited to the current
 > directory (and its children) for security reasons, and to ensure
 > repeatable builds on remote Docker hosts. This is also the reason why
-> `ADD ../file` will not work.
+> `ADD ../file` does not work.
 
 ### Use a custom parent cgroup (--cgroup-parent)
 
@@ -672,30 +673,47 @@ The `--squash` option has a number of known limitations:
 
 #### Prerequisites
 
-The example on this page is using experimental mode in Docker 1.13.
+The example on this page is using experimental mode in Docker 19.03.
 
-Experimental mode can be enabled by using the `--experimental` flag when starting the Docker daemon or setting `experimental: true` in the `daemon.json` configuration file.
+Experimental mode can be enabled by using the `--experimental` flag when starting
+the Docker daemon or setting `experimental: true` in the `daemon.json` configuration
+file.
 
-By default, experimental mode is disabled. To see the current configuration, use the `docker version` command.
+By default, experimental mode is disabled. To see the current configuration of
+the docker daemon, use the `docker version` command and check the `Experimental`
+line in the `Engine` section:
 
-```none
+```console
-Server:
+Client: Docker Engine - Community
- Version:      1.13.1
+ Version:           19.03.8
- API version:  1.26 (minimum version 1.12)
+ API version:       1.40
- Go version:   go1.7.5
+ Go version:        go1.12.17
- Git commit:   092cba3
+ Git commit:        afacb8b
- Built:        Wed Feb  8 06:35:24 2017
+ Built:             Wed Mar 11 01:21:11 2020
- OS/Arch:      linux/amd64
+ OS/Arch:           darwin/amd64
  Experimental:      false
 
+Server: Docker Engine - Community
+ Engine:
+  Version:          19.03.8
+  API version:      1.40 (minimum version 1.12)
+  Go version:       go1.12.17
+  Git commit:       afacb8b
+  Built:            Wed Mar 11 01:29:16 2020
+  OS/Arch:          linux/amd64
+  Experimental:     true
  [...]
 ```
 
-To enable experimental mode, users need to restart the docker daemon with the experimental flag enabled.
+To enable experimental mode, users need to restart the docker daemon with the
+experimental flag enabled.
 
 #### Enable Docker experimental
 
-Experimental features are now included in the standard Docker binaries as of version 1.13.0. For enabling experimental features, you need to start the Docker daemon with `--experimental` flag. You can also enable the daemon flag via /etc/docker/daemon.json. e.g.
+Experimental features are now included in the standard Docker binaries as of
+version 1.13.0. For enabling experimental features, you need to start the
+Docker daemon with `--experimental` flag. You can also enable the daemon flag
+via `/etc/docker/daemon.json`. e.g.
 
 ```json
 {
@@ -731,7 +749,7 @@ $ docker build --squash -t test .
 [...]
 ```
 
-If everything is right, the history will look like this:
+If everything is right, the history looks like this:
 
 ```bash
 $ docker history test
@@ -747,6 +765,8 @@ IMAGE               CREATED             CREATED BY
 <missing>           7 weeks ago         /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff   1.113 MB
 ```
 
-We could find that all layer's name is `<missing>`, and there is a new layer with COMMENT `merge`.
+We could find that a layer's name is `<missing>`, and there is a new layer with
+COMMENT `merge`.
 
-Test the image, check for `/remove_me` being gone, make sure `hello\nworld` is in `/hello`, make sure the `HELLO` envvar's value is `world`.
+Test the image, check for `/remove_me` being gone, make sure `hello\nworld` is
+in `/hello`, make sure the `HELLO` environment variable's value is `world`.

docs/reference/commandline/dockerd.md

@@ -676,7 +676,7 @@ thin pool device deletion is synchronous. Before a container is deleted,
 the Docker daemon removes any associated devices. If the storage driver
 can not remove a device, the container deletion fails and daemon returns.
 
-```none
+```console
 Error deleting container: Error response from daemon: Cannot destroy container
 ```
 
@@ -1264,9 +1264,9 @@ to avoid collisions with other prometheus exporters and services.
 
 If you are running a prometheus server you can add this address to your scrape configs
 to have prometheus collect metrics on Docker.  For more information
-on prometheus you can view the website [here](https://prometheus.io/).
+on prometheus refer to the [prometheus website](https://prometheus.io/).
 
-```none
+```yaml
 scrape_configs:
   - job_name: 'docker'
     static_configs:
@@ -1414,7 +1414,9 @@ This is a full example of the allowed configuration options on Linux:
 }
 ```
 
-> **Note:** You cannot set options in `daemon.json` that have already been set on
+> **Note:**
+>
+> You cannot set options in `daemon.json` that have already been set on
 > daemon startup as a flag.
 > On systems that use `systemd` to start the Docker daemon, `-H` is already set, so
 > you cannot use the `hosts` key in `daemon.json` to add listening addresses.
@@ -1534,7 +1536,7 @@ by providing them as flags, or by using a [daemon configuration file](#daemon-co
 
 The following daemon options must be configured for each daemon:
 
-```none
+```console
 -b, --bridge=                          Attach containers to a network bridge
 --exec-root=/var/run/docker            Root of the Docker execdriver
 --data-root=/var/lib/docker            Root of persisted Docker data

docs/reference/commandline/events.md

@@ -222,7 +222,7 @@ $ docker stop test
 
 **Shell 1: (Again .. now showing events):**
 
-```none
+```console
 2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test)
 2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge)
 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)

docs/reference/commandline/info.md

@@ -204,7 +204,7 @@ $ docker info --format '{{json .}}'
 
 Here is a sample output for a daemon running on Windows Server 2016:
 
-```none
+```console
 E:\docker>docker info
 Client:
  Context:    default

docs/reference/commandline/network_inspect.md

@@ -47,9 +47,13 @@ template for each result. Go's
 [text/template](http://golang.org/pkg/text/template/) package describes all the
 details of the format.
 
-```none
+```bash
 $ sudo docker network inspect bridge
+```
 
+The output is in JSON format, for example:
+
+```json
 [
   {
     "Name": "bridge",
@@ -106,9 +110,13 @@ $ docker network create simple-network
 69568e6336d8c96bbf57869030919f7c69524f71183b44d80948bd3927c87f6a
 ```
 
-```none
+```bash
 $ docker network inspect simple-network
+```
 
+The output is in JSON format, for example:
+
+```json
 [
   {
     "Name": "simple-network",
@@ -138,9 +146,13 @@ For swarm mode overlay networks `network inspect` also shows the IP address and
 of the peers. Peers are the nodes in the swarm cluster which have at least one task attached
 to the network. Node name is of the format `<hostname>-<unique ID>`.
 
-```none
+```bash
 $ docker network inspect ingress
+```
 
+The output is in JSON format, for example:
+
+```json
 [
   {
     "Name": "ingress",
@@ -203,6 +215,11 @@ attached to. service `s1` in this case has three replicas.
 
 ```bash
 $ docker network inspect --verbose ov1
+```
+
+The output is in JSON format, for example:
+
+```json
 [
   {
     "Name": "ov1",

docs/reference/commandline/network_prune.md

@@ -64,7 +64,7 @@ networks without the specified labels.
 The following removes networks created more than 5 minutes ago. Note that
 system networks such as `bridge`, `host`, and `none` will never be pruned:
 
-```none
+```bash
 $ docker network ls
 
 NETWORK ID          NAME                DRIVER              SCOPE

docs/reference/commandline/ps.md

@@ -174,7 +174,7 @@ ea09c3c82f6e        registry:latest   /srv/run.sh            2 weeks ago
 You can use a filter to locate containers that exited with status of `137`
 meaning a `SIGKILL(9)` killed them.
 
-```none
+```bash
 $ docker ps -a --filter 'exited=137'
 
 CONTAINER ID        IMAGE               COMMAND                CREATED             STATUS                       PORTS               NAMES

docs/reference/commandline/run.md

@@ -437,7 +437,7 @@ variables. (Unlike environment variables, labels are not visible to processes
 running inside a container.) The following example illustrates a label-file
 format:
 
-```none
+```console
 com.example.label1="a label"
 
 # this is a comment

docs/reference/commandline/search.md

@@ -32,7 +32,7 @@ Search [Docker Hub](https://hub.docker.com) for images
 
 This example displays images with a name containing 'busybox':
 
-```none
+```bash
 $ docker search busybox
 
 NAME                             DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED

docs/reference/commandline/secret_create.md

@@ -67,7 +67,7 @@ $ docker secret create --label env=dev \
 eo7jnzguqgtpdah3cm5srfb97
 ```
 
-```none
+```bash
 $ docker secret inspect my_secret
 
 [

docs/reference/commandline/secret_inspect.md

@@ -50,9 +50,13 @@ ID                          NAME                CREATED             UPDATED
 eo7jnzguqgtpdah3cm5srfb97   my_secret           3 minutes ago       3 minutes ago
 ```
 
-```none
+```bash
 $ docker secret inspect secret.json
+```
 
+The output is in JSON format, for example:
+
+```json
 [
   {
     "ID": "eo7jnzguqgtpdah3cm5srfb97",

docs/reference/commandline/service_inspect.md

@@ -53,7 +53,11 @@ produce the same result:
 
 ```bash
 $ docker service inspect redis
+```
 
+The output is in JSON format, for example:
+
+```json
 [
   {
     "ID": "dmu1ept4cxcfe8k8lhtux3ro3",

docs/reference/commandline/trust_inspect.md

@@ -31,6 +31,11 @@ following example prints trust information for the `alpine:latest` image:
 
 ```bash
 $ docker trust inspect alpine:latest
+```
+
+The output is in JSON format, for example:
+
+```json
 [
   {
     "Name": "alpine:latest",
@@ -76,6 +81,11 @@ commands, `docker trust inspect` includes a `Signers` key:
 
 ```bash
 $ docker trust inspect my-image:purple
+```
+
+The output is in JSON format, for example:
+
+```json
 [
   {
     "Name": "my-image:purple",
@@ -158,7 +168,11 @@ However, if other tags are signed in the same image repository,
 
 ```bash
 $ docker trust inspect alpine:unsigned
+```
 
+The output is in JSON format, for example:
+
+```json
 [
   {
     "Name": "alpine:unsigned",
@@ -192,7 +206,11 @@ signed tags in the repository:
 
 ```bash
 $ docker trust inspect alpine
+```
 
+The output is in JSON format, for example:
+
+```json
 [
   {
     "Name": "alpine",
@@ -257,7 +275,11 @@ and reports the results in an ordered list:
 
 ```bash
 $ docker trust inspect alpine notary
+```
 
+The output is in JSON format, for example:
+
+```json
 [
   {
     "Name": "alpine",

docs/reference/commandline/volume_create.md

@@ -46,7 +46,7 @@ Volume names must be unique among drivers. This means you cannot use the same
 volume name with two different drivers. If you attempt this `docker` returns an
 error:
 
-```none
+```console
 A volume named  "hello"  already exists with the "some-other" driver. Choose a different volume name.
 ```
 

docs/reference/commandline/volume_inspect.md

@@ -27,27 +27,39 @@ details of the format.
 ## Examples
 
 ```bash
-$ docker volume create
+$ docker volume create myvolume
 
-8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5
+myvolume
+```
 
-$ docker volume inspect 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d
+Use the `docker volume inspect` comment to inspect the configuration of the volume:
 
+```bash
+$ docker volume inspect myvolume
+```
+
+The output is in JSON format, for example:
+
+```json
 [
   {
     "CreatedAt": "2020-04-19T11:00:21Z",
     "Driver": "local",
     "Labels": {},
     "Mountpoint": "/var/lib/docker/volumes/8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5/_data",
-    "Name": "8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5",
+    "Name": "myvolume",
     "Options": {},
     "Scope": "local"
   }
 ]
+```
+Use the `--format` flag to format the output using a Go template, for example,
+to print the `Mountpoint` property:
 
-$ docker volume inspect --format '{{ .Mountpoint }}' 8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5
+```bash
+$ docker volume inspect --format '{{ .Mountpoint }}' myvolume
 
-/var/lib/docker/volumes/8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5/_data
+/var/lib/docker/volumes/myvolume/_data
 ```
 
 ## Related commands