update engine reference docs with latest changes

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

_data/engine-cli/docker_build.yaml

@@ -905,7 +905,7 @@ examples: |-
     base image is still supported.
   - When using this option you may see significantly more space used due to
     storing two copies of the image, one for the build cache with all the cache
-    layers in tact, and one for the squashed version.
+    layers intact, and one for the squashed version.
   - While squashing layers may produce smaller images, it may have a negative
     impact on performance, as a single layer takes longer to extract, and
     downloading a single layer cannot be parallelized.

_data/engine-cli/docker_checkpoint.yaml

@@ -1,6 +1,99 @@
 command: docker checkpoint
 short: Manage checkpoints
-long: Manage checkpoints
+long: |-
+  Checkpoint and Restore is an experimental feature that allows you to freeze a running
+  container by checkpointing it, which turns its state into a collection of files
+  on disk. Later, the container can be restored from the point it was frozen.
+
+  This is accomplished using a tool called [CRIU](http://criu.org), which is an
+  external dependency of this feature. A good overview of the history of
+  checkpoint and restore in Docker is available in this
+  [Kubernetes blog post](https://kubernetes.io/blog/2015/07/how-did-quake-demo-from-dockercon-work/).
+
+  ### Installing CRIU
+
+  If you use a Debian system, you can add the CRIU PPA and install with `apt-get`
+  [from the criu launchpad](https://launchpad.net/~criu/+archive/ubuntu/ppa).
+
+  Alternatively, you can [build CRIU from source](https://criu.org/Installation).
+
+  You need at least version 2.0 of CRIU to run checkpoint and restore in Docker.
+
+  ### Use cases for checkpoint and restore
+
+  This feature is currently focused on single-host use cases for checkpoint and
+  restore. Here are a few:
+
+  - Restarting the host machine without stopping/starting containers
+  - Speeding up the start time of slow start applications
+  - "Rewinding" processes to an earlier point in time
+  - "Forensic debugging" of running processes
+
+  Another primary use case of checkpoint and restore outside of Docker is the live
+  migration of a server from one machine to another. This is possible with the
+  current implementation, but not currently a priority (and so the workflow is
+  not optimized for the task).
+
+  ### Using checkpoint and restore
+
+  A new top level command `docker checkpoint` is introduced, with three subcommands:
+
+  - `docker checkpoint create` (creates a new checkpoint)
+  - `docker checkpoint ls` (lists existing checkpoints)
+  - `docker checkpoint rm` (deletes an existing checkpoint)
+
+  Additionally, a `--checkpoint` flag is added to the `docker container start` command.
+
+  The options for `docker checkpoint create`:
+
+  ```console
+  Usage:  docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT
+
+  Create a checkpoint from a running container
+
+    --leave-running=false    Leave the container running after checkpoint
+    --checkpoint-dir         Use a custom checkpoint storage directory
+  ```
+
+  And to restore a container:
+
+  ```console
+  Usage:  docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] CONTAINER
+  ```
+
+  Example of using checkpoint and restore on a container:
+
+  ```console
+  $ docker run --security-opt=seccomp:unconfined --name cr -d busybox /bin/sh -c 'i=0; while true; do echo $i; i=$(expr $i + 1); sleep 1; done'
+  abc0123
+
+  $ docker checkpoint create cr checkpoint1
+
+  # <later>
+  $ docker start --checkpoint checkpoint1 cr
+  abc0123
+  ```
+
+  This process just logs an incrementing counter to stdout. If you run `docker logs`
+  in between running/checkpoint/restoring you should see that the counter
+  increases while the process is running, stops while it's checkpointed, and
+  resumes from the point it left off once you restore.
+
+  ### Known limitations
+
+  seccomp is only supported by CRIU in very up to date kernels.
+
+  External terminal (i.e. `docker run -t ..`) is not supported at the moment.
+  If you try to create a checkpoint for a container with an external terminal,
+  it would fail:
+
+  ```console
+  $ docker checkpoint create cr checkpoint1
+  Error response from daemon: Cannot checkpoint container c1: rpc error: code = 2 desc = exit status 1: "criu failed: type NOTIFY errno 0\nlog file: /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log\n"
+
+  $ cat /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log
+  Error (mount.c:740): mnt: 126:./dev/console doesn't have a proper root mount
+  ```
 usage: docker checkpoint
 pname: docker
 plink: docker.yaml

_data/engine-cli/docker_create.yaml

@@ -990,7 +990,7 @@ examples: |-
   created into the container once it is run. This poses a problem when
   a new device needs to be added to running container.
 
-  One of the solution is to add a more permissive rule to a container
+  One of the solutions is to add a more permissive rule to a container
   allowing it access to a wider range of devices. For example, supposing
   our container needs access to a character device with major `42` and
   any number of minor number (added as new devices appear), the

_data/engine-cli/docker_search.yaml

@@ -141,9 +141,8 @@ examples: |-
   ```console
   $ docker search --filter is-official=true --filter stars=3 busybox
 
-  NAME                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
-  progrium/busybox                                                     50                   [OK]
-  radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
+  NAME      DESCRIPTION           STARS     OFFICIAL   AUTOMATED
+  busybox   Busybox base image.   325       [OK]
   ```
 
   ### Format the output