diff --git a/CHANGES.md b/CHANGES.md
index 190edd4292c5..0a52d014fe34 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -24,6 +24,9 @@ next
 - Add `(staged_pps ...)` to support staged ppx rewriters such as ones
   using the OCaml typer like `ppx_import` (#1080, fix #193, @diml)
 
+- Fix placeholders in `dune subst` documentation (#1090, @emillon, thanks
+  @trefis for the bug report)
+
 1.0.1 (19/07/2018)
 ------------------
 
diff --git a/bin/main.ml b/bin/main.ml
index baf23d224748..6f9e6009e75e 100644
--- a/bin/main.ml
+++ b/bin/main.ml
@@ -1279,6 +1279,10 @@ let exec =
   in
   (term, Term.info "exec" ~doc ~man)
 
+(** A string that is "%%VERSION%%" but not expanded by [dune subst] *)
+let literal_version =
+  "%%" ^ "VERSION%%"
+
 let subst =
   let doc =
     "Substitute watermarks in source files."
@@ -1294,17 +1298,17 @@ let subst =
     [ `S "DESCRIPTION"
     ; `P {|Substitute $(b,%%ID%%) strings in source files, in a similar fashion to
            what topkg does in the default configuration.|}
-    ; `P {|This command is only meant to be called when a user pins a package to
-           its development version. Especially it replaces $(b,%%VERSION%%) strings
-           by the version obtained from the vcs. Currently only git is supported and
-           the version is obtained from the output of:|}
+    ; `P ({|This command is only meant to be called when a user pins a package to
+            its development version. Especially it replaces $(b,|} ^ literal_version
+          ^{|) strings by the version obtained from the vcs. Currently only git is
+             supported and the version is obtained from the output of:|})
     ; `Pre {|  \$ git describe --always --dirty|}
     ; `P {|$(b,dune subst) substitutes the variables that topkg substitutes with
            the defatult configuration:|}
     ; var "NAME" "the name of the project (from the dune-project file)"
     ; var "VERSION" "output of $(b,git describe --always --dirty)"
-    ; var "VERSION_NUM" "same as $(b,%%VERSION%%) but with a potential leading \
-                         'v' or 'V' dropped"
+    ; var "VERSION_NUM" ("same as $(b," ^ literal_version ^
+                         ") but with a potential leading 'v' or 'V' dropped")
     ; var "VCS_COMMIT_ID" "commit hash from the vcs"
     ; opam "maintainer"
     ; opam "authors"