Skip to content

Commit

Permalink
Medias: add documentation
Browse files Browse the repository at this point in the history
Signed-off-by: Paul-Elliot <[email protected]>
  • Loading branch information
panglesd committed Sep 28, 2023
1 parent 6ae32ef commit 75d5830
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 0 deletions.
1 change: 1 addition & 0 deletions doc/ocamldoc_differences.mld
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
27 changes: 27 additions & 0 deletions doc/odoc_for_authors.mld
Original file line number Diff line number Diff line change
Expand Up @@ -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 [{<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}

Expand Down

0 comments on commit 75d5830

Please sign in to comment.