Media: add documentation

Author: panglesd

doc/ocamldoc_differences.mld

@@ -30,6 +30,7 @@ The following describes the changes between what [odoc] understands and what’s
 
 {3 Improvements}
 - [odoc] supports writing mathematics and tables with a specific syntax.
+- [odoc] supports the inclusion of medias such as audio, video and image.
 - [odoc] has a better mechanism for disambiguating references in comments. See 'reference syntax' later in this document.
 - Built-in support for standalone [.mld] files. These are documents using the OCamldoc markup, but they’re rendered as distinct pages.
 - Structured output: [odoc] can produce output in a structured directory tree rather a set of files.

doc/odoc_for_authors.mld

@@ -628,6 +628,33 @@ would render as
 The light syntax has the advantages of being arguably more readable for small tables, when viewing the source file directly. However, its content is restricted (for instance, no new line is allowed).
 The heavy syntax is easier to write, can be more readable for big tables, and supports having any kind of content inside. It does not support alignment (yet).
 
+{2 Medias}
+
+Odoc 3.0 introduced new markup for medias. Medias are nestable blocks,
+so they can be put inside lists and tables, but they cannot be
+inlined, for instance in a link..
+
+There are currently three kinds of medias: image, audio, and
+video. Each of them can refer to the file either using an asset
+reference, or a direct link.
+
+The markup is [{<media>:link}], [{<media>!ref}],
+[{{<media>:link}Replacement text}] and [{{<media>:ref}Replacement text}],
+where [<media>] is either [image], [video] or [audio].
+
+The replacement text is used for backends that do not support medias
+(latex and man), and for when a reference is unresolved. In the case
+of an image, it is also used to generate an alternative text.
+
+Images are clickable and links to the image file.
+
+The following source:
+
+{[
+  renders as: {image:https://picsum.photos/200/300}
+]}
+
+renders as: {image:https://picsum.photos/200/300}
 
 {2 Stop Comments}