tools/docker: Update README.org

- Proofread a bit
- Add #+SINCE: v2.0.9
- Change some formatting to proper Org syntax

modules/tools/docker/README.org

@@ -1,6 +1,6 @@
 #+TITLE:   tools/docker
 #+DATE:    April 30, 2019
-#+SINCE:   {replace with next tagged release version}
+#+SINCE:   v2.0.9
 #+STARTUP: inlineimages
 
 * Table of Contents :TOC_3:noexport:
@@ -8,25 +8,25 @@
   - [[#module-flags][Module Flags]]
   - [[#plugins][Plugins]]
 - [[#prerequisites][Prerequisites]]
-- [[#todo-features][TODO: Features]]
+- [[#features][Features]]
   - [[#docker-control][Docker control]]
     - [[#supported-commands][Supported commands]]
   - [[#tramp][TRAMP]]
 - [[#configuration][Configuration]]
   - [[#popups][Popups]]
-  - [[#dockerfile-mode][dockerfile-mode]]
+    - [[#other-useful-variables][Other useful variables]]
+  - [[#completion-in-dockerfiles][Completion in Dockerfiles]]
 - [[#troubleshooting][Troubleshooting]]
   - [[#tramp-hangs-on-alpine-container][Tramp hangs on Alpine container]]
 
 * Description
+This module allows you to manipulate Docker images, containers & more from
+Emacs.
 
-This package allows you to manipulate docker images, containers & more from Emacs.
+Provides a major =dockerfile-mode= to edit =Dockerfiles=. Additional
+convenience functions allow images to be built easily.
 
-Provides a major mode `dockerfile-mode' for use with the standard
+=docker-tramp.el= offers a [[https://www.gnu.org/software/tramp/][TRAMP]] method for Docker containers.
-`Dockerfile' file format.  Additional convenience functions allow
-images to be built easily.
-
-docker-tramp.el offers a TRAMP method for Docker containers.
 
 ** Module Flags
 This module provides no flags.
@@ -37,14 +37,14 @@ This module provides no flags.
  + [[https://github.com/spotify/dockerfile-mode][dockerfile-mode]]
 
 * Prerequisites
-This modules assumes `docker`, `docker-compose` and `docker-machine` binaries are
+This module assumes =docker=, =docker-compose= and =docker-machine= binaries
-installed and accessible from your PATH.
+are installed and accessible from your PATH.
 
-* TODO: Features
+* Features
 ** Docker control
-
+Use =M-x docker=, select a resource, and then mark or unmark items using the
-Use =M-x docker=, select a resource then then mark or unmark items using the following keybindings (for more
+following keybindings (for more marking possibilities, check out
-marking possibilities, check out https://github.com/politza/tablist):
+https://github.com/politza/tablist):
 
 | Binding   | Description          |
 |-----------+----------------------|
@@ -61,41 +61,40 @@ marking possibilities, check out https://github.com/politza/tablist):
 | =C-c C-e= | Export to csv        |
 
 *** Supported commands
-- docker container: attach, cp, diff, inspect, kill, logs, pause, rename, restart, rm, start, stop, unpause
+- =docker container=: =attach=, =cp=, =diff=, =inspect=, =kill=, =logs=,
-- docker image: inspect, pull, push, rm, run, tag
+  =pause=, =rename=, =restart=, =rm=, =start=, =stop=, =unpause=
-- docker network: rm
+- =docker image=: =inspect=, =pull=, =push=, =rm=, =run=, =tag=
-- docker volume: rm
+- =docker network=: =rm=
-- docker-machine: create, env, restart, rm, start, stop
+- =docker volume=: =rm=
-- docker-compose: build, config, create, down, exec, logs, pull, push, remove,
+- =docker-machine=: =create=, =env=, =restart=, =rm=, =start=, =stop=
-  restart, run, start, stop, up
+- =docker-compose=: =build=, =config=, =create=, =down=, =exec=, =logs=,
+  =pull=, =push=, =remove=, =restart=, =run=, =start=, =stop=, =up=
 
-  You can also enter `dired` or open a file inside a container or volume.
+  You can also enter =dired= or open a file inside a container or volume.
 
 ** TRAMP
+Offers the [[https://www.gnu.org/software/tramp/][TRAMP]] method =docker= to access running containers.
 
-Offers the TRAMP method `docker` to access running containers
+#+BEGIN_EXAMPLE
-
+C-x C-f /docker:user@container:/path/to/file
-    C-x C-f /docker:user@container:/path/to/file
+#+END_EXAMPLE
-
-    where
-      user           is the user that you want to use (optional)
-      container      is the id or name of the container
 
+| =user=      | the user that you want to use (optional) |
+| =container= | the id or name of the container          |
 
 * Configuration
 ** Popups
-
+Thanks to [[https://github.com/magit/magit-popup][magit-popup]], all the popups default arguments can be customized. For
-Thanks to [magit-popup](https://github.com/magit/magit-popup), all the popups default arguments can be customized. For
+example, here is how to customize the arguments for =docker-image-run-popup=:
-example, here is how to customize the arguments for `docker-image-run-popup`:
 
 #+BEGIN_SRC emacs-lisp
 (setq docker-image-run-arguments '("-i" "-t" "--rm"))
 #+END_SRC
 
-or inside a use-package declaration:
+or inside a =use-package= declaration:
 
 #+BEGIN_SRC emacs-lisp
-(use-package docker
+(use-package! docker
   :ensure t
   :bind ("C-c d" . docker)
   :custom (docker-image-run-arguments '("-i" "-t" "--rm")))
@@ -103,39 +102,35 @@ or inside a use-package declaration:
 
 You can also customize these using =M-x customize-variable=.
 
-### Others
+*** Other useful variables
+| Variable                            | Description                           | Default          |
+|-------------------------------------+---------------------------------------+------------------|
+| =docker-command=                    | The docker binary to use              | =docker=         |
+| =docker-container-default-sort-key= | Sort key for docker containers        | =("Image")=      |
+| =docker-container-shell-file-name=  | Shell to use when entering containers | =/bin/bash=      |
+| =docker-image-default-sort-key=     | Sort key for docker images            | =("Repository")= |
+| =docker-machine-default-sort-key=   | Sort key for docker machines          | =("Name")=       |
+| =docker-network-default-sort-key=   | Sort key for docker networks          | =("Name")=       |
+| =docker-run-as-root=                | Run docker as root                    | =nil=            |
+| =docker-volume-default-sort-key=    | Sort key for docker volumes           | =("Driver")=     |
 
-| Variable                          | Description                           | Default          |
+** Completion in Dockerfiles
-|-----------------------------------+---------------------------------------+------------------|
+By default, the keyword completion function detects the =docker-compose=
-| docker-command                    | The docker binary to use              | `docker`         |
+version of the current buffer and suggests the appropriate keywords.
-| docker-container-default-sort-key | Sort key for docker containers        | `("Image")`      |
-| docker-container-shell-file-name  | Shell to use when entering containers | `/bin/bash`      |
-| docker-image-default-sort-key     | Sort key for docker images            | `("Repository")` |
-| docker-machine-default-sort-key   | Sort key for docker machines          | `("Name")`       |
-| docker-network-default-sort-key   | Sort key for docker networks          | `("Name")`       |
-| docker-run-as-root                | Run docker as root                    | `nil`            |
-| docker-volume-default-sort-key    | Sort key for docker volumes           | `("Driver")`     |
 
-** dockerfile-mode
+You can change the candidates offered by the backend by customizing
-
+=docker-compose-keywords=.
-By default, the keyword completion function detects the docker-compose version of the current buffer and suggests the appropriate keywords.
-
-You can change the candidates offered by the backend by customizing docker-compose-keywords
 
 * Troubleshooting
-
 ** Tramp hangs on Alpine container
+Busyboxes built with the =ENABLE_FEATURE_EDITING_ASK_TERMINAL= config option
+also send escape sequences, which =tramp-wait-for-output= doesn't ignore
+correctly. This was [[http://git.savannah.gnu.org/cgit/tramp.git/commit/?id=98a511248a9405848ed44de48a565b0b725af82c][fixed in TRAMP upstream]] and is available since TRAMP 2.3.
 
-Busyboxes built with the `ENABLE_FEATURE_EDITING_ASK_TERMINAL' config option
+For older versions of TRAMP you can dump [[https://github.com/emacs-pe/docker-tramp.el/blob/master/docker-tramp-compat.el][docker-tramp-compat.el]] in your
-send also escape sequences, which `tramp-wait-for-output' doesn't ignores
+=load-path= somewhere and add the following to your =init.el= to overwrite
-correctly.  Tramp upstream fixed in [98a5112][] and is available since
+=tramp-wait-for-output= with the patch applied:
-Tramp>=2.3.
 
-For older versions of Tramp you can dump [docker-tramp-compat.el][] in your
+#+BEGIN_SRC emacs-lisp
-`load-path' somewhere and add the following to your `init.el', which
+(require 'docker-tramp-compat)
-overwrites `tramp-wait-for-output' with the patch applied:
+#+END_SRC
-
-    (require 'docker-tramp-compat)
-
-[98a5112]: http://git.savannah.gnu.org/cgit/tramp.git/commit/?id=98a511248a9405848ed44de48a565b0b725af82c
-[docker-tramp-compat.el]: https://github.com/emacs-pe/docker-tramp.el/raw/master/docker-tramp-compat.el