From 75d583031e9069acaf3205613892e4590522d521 Mon Sep 17 00:00:00 2001 From: Paul-Elliot Date: Thu, 28 Sep 2023 14:53:28 +0200 Subject: [PATCH] Medias: add documentation Signed-off-by: Paul-Elliot --- doc/ocamldoc_differences.mld | 1 + doc/odoc_for_authors.mld | 27 +++++++++++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/doc/ocamldoc_differences.mld b/doc/ocamldoc_differences.mld index 6a9131f43a..01f896c615 100644 --- a/doc/ocamldoc_differences.mld +++ b/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. diff --git a/doc/odoc_for_authors.mld b/doc/odoc_for_authors.mld index 5f69660673..2aa1eb0c18 100644 --- a/doc/odoc_for_authors.mld +++ b/doc/odoc_for_authors.mld @@ -610,6 +610,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 2.4 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 [{:link}], [{!ref}], +[{{:link}Replacement text}] and [{{:ref}Replacement text}], +where [] 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}