Minor doc changes suggested on #914

Author: jonludlam

CHANGES.md

@@ -1,5 +1,8 @@
+2.2.0
+-----
+
 Additions
-- New (experimental!) option `--as-json` for the HTML renderer that emits HTML
+- New unstable option `--as-json` for the HTML renderer that emits HTML
   fragments (preamble, content) together with metadata (table of contents,
   breadcrumbs, whether katex is used) in JSON format. (@sabine, #908)
 - New maths support via `{m ... }` and `{math ... }` tags. (@giltho, @gpetiot, #886)

doc/driver.md

@@ -6,7 +6,7 @@ The document built here includes not only the documentation of `odoc` itself, bu
 docs for a subset of `odoc`'s dependent libraries to show how this may be done. For a much more
 complete and comprehensive use of `odoc`, see the [Voodoo project](https://github.com/ocaml-doc/voodoo), the tool that is being used to build
 the package docs for
-[v3.ocaml.org](https://v3.ocaml.org/).
+[www.ocaml.org/packages](https://www.ocaml.org/packages).
 
 First we need to initialise MDX with some libraries and helpful values.
 

doc/odoc_for_authors.mld

@@ -30,7 +30,7 @@ v}
 - {{!page-driver}The reference driver} is the simplest driver, useful if you
   want to see how to integrate it with your own projects.
 - {{:https://github.com/ocaml-doc/voodoo}Voodoo} is the driver used to create
-  the docs for {{:https://v3.ocaml.org/packages}the new OCaml website}.
+  the docs for {{:https://www.ocaml.org/packages}the OCaml website}.
 
 {1:interfaces Documenting your interfaces}
 
@@ -296,22 +296,10 @@ v}
 
 {4:language_headers Language Headers}
 
-As of [odoc.2.1] it is possible to write blocks with explicit language headers,
-similar to markdown code blocks:
-
-{@markdown[
-Here is some python code:
-```python
-def f():
-  return 0
-```
-]}
-
-These blocks can be written using the enclosing tags [ {@<language>[ ... ]} ].
-The content of those block should be properly styled if odoc supports the
-styling for the given language. It is encouraged to use them even before proper
-support is available so that you benefit from it as soon as it is released.
-The above markdown example would be written as:
+As of [odoc.2.2] it is possible to write blocks with explicit language headers.
+These blocks can be written using the enclosing tags [{@<language>[ ... ]}].
+The content of those block should be properly styled if highlightjs supports the
+styling for the given language.
 
 {v
 (** Here is some python code:
@@ -333,7 +321,7 @@ Here is some python code:
 {4:verbatim_blocks Verbatim Blocks}
 
 It is possible to write language agnostic code blocks, also called verbatim
-blocks using the enclosing tags [ {v ... v} ]. The content of these blocks will be
+blocks using the enclosing tags [{v ... v}]. The content of these blocks will be
 formatted as code but with no particular style applied.
 
 {[
@@ -346,7 +334,7 @@ formatted as code but with no particular style applied.
 
 {3:escaping Escaping}
 
-In most contexts, the characters [ { [ ] } @ ] all need to be escaped with a backslash.
+In most contexts, the characters [{ [ ] } @] all need to be escaped with a backslash.
 In inline source code style, only square brackets need to be escaped. However, as a
 convenience, {e matched} square brackets need not be escaped to aid in typesetting
 code. For example, the following would be acceptable in a documentation comment:

src/odoc/bin/main.ml

@@ -563,7 +563,9 @@ module Odoc_html_args = struct
     let doc =
       "EXPERIMENTAL: Output HTML files in 'embeddable json' mode, where HTML \
        fragments (preamble, content) together with metadata (uses_katex, \
-       breadcrumbs, table of contents) are emitted in JSON format."
+       breadcrumbs, table of contents) are emitted in JSON format. The \
+       structure of the output should be considered unstable and no \
+       guarantees are made about backward compatibility."
     in
     Arg.(value & flag & info ~doc [ "as-json" ])