Odoc 3.0 Planning: Assets and medias in odoc

This discussion builds on https://github.com/ocaml/odoc/discussions/1097, focusing on assets and media elements.

Referencing assets

Recall from https://github.com/ocaml/odoc/discussions/1097:

A 'unit of documentation' consists of a set of documents and assets in a hierarchical directory structure. Documentation files are mld files, and assets are jpegs, pngs, svgs, etc., that are referenced by the docs.

Assets are part of the hierarchy. They are referenced in a similar way to pages. The new asset keyword can be used to disambiguate. Here are some examples of reference to assets: "data.json", asset-"data.json", data/"example.json", or data/asset-"example.json".

Asset path

When references are used in places where we know they should link to assets (see here), some of the syntax for general references is not needed, but tedious to escape. In particular, dots (.) and dashes (-) are often seen in filenames but interpreted by odoc, leading to additional ", as in {!directory/"file.img"}.

In order to make it easier to write, we define asset path as normal references where the part after the last / is considered verbatim. So an asset path dirname/file-name.extension is parsed as the normal reference dirname/"file-name.extension".

Resolving assets within a page

When resolving asset references/paths in a page within the hierarchy, assets can be resolved relatively or absolutely, up to the root of the documentation tree. For example, given the hierarchy (omitting index.mld files: all directories must contain an index.mld, even if they do not contain a page but only assets!):

/data.json
/a/result.dat
/a/b/baz.mld
/a/b/image.jpg
/a/b/d/windows.exe
/a/c/template.ml

when resolving in baz.mld, the following are valid paths (assuming our package name is pkgname):

{!../result.dat}
{!../c/template.ml}
{!../../data.json}
{!d/windows.exe}
{!image.jpg}
{!/pkgname/data.json}
{!/otherpackage/something_in_another_package.txt}

For completeness, here are the same path but written as references (instead of asset paths):

{!../asset-"result.dat"} or {!../"result.dat"}
{!../c/asset-"template.ml"} or {!../c/"template.ml"}
{!../../asset-"data.json"}
{!d/"windows.exe"}
{!dir-d/"windows.exe"}
{!"image.jpg"}
{!/pkgname/asset-"data.json"} or {!/pkgname/"data.json"}
{!/otherpackage/asset-something_in_another_package}

Resolving assets within a module

The same mechanism that adds a package's documentation pages to the scope also adds the corresponding assets. The asset path /packagename/a/b/c/d.txt would refer to the asset that usually ends up installed at <opam dir>/doc/<packagename>/odoc-pages/a/b/c/d.txt

Including media

The syntax for including media builds on the syntax for reference links. A media is inserted by {<media><kind><target>} where:

• <media> can be either figure for figures, image for images, audio for audio, and video for video, or asset for asset links
• <sep> is either ! if <target> is an asset path, or : if <target> is a link.

{asset:<link>} renders the same as {:<link>}.

An additional "replacement", "caption" or "alternative" text can be added with the following syntax: {{<media><kind><target>}<replacement text>}. The replacement text can only contain inline elements.

Here is the meaning of each media:

Here are some examples:

{image!../figure.jpg}
{image!../figure.jpg}
{{image!ellen.jpg}Astronaut Ellen Ochoa}
{image:https://picsum.photos/200/300}
{{image:https://picsum.photos/200/300}Randomly chosen image}

{video!dirname/output.mpg}
{video!/pkgname/output.mpg}
{video:https://example.com/output.mpg}
{{video!/pkgname/output.mpg}The output from pkgname is very cool!}
{{video:https://example.com/output.mpg}Introductory video}

{audio!dirname/output.ogg}
{audio!/pkgname/output.ogg}
{audio:https://example.com/output.ogg}
{{audio!/pkgname/output.ogg}The output from pkgname is very cool!}
{{audio:https://example.com/output.ogg}Introductory video}

{asset!dirname/output.ogg}
{asset!/pkgname/output.ogg}
{{asset!/pkgname/output.ogg}The output from pkgname is very cool!}

Figures

Medias can be included in (captioned) figures. This allows to reference them.

The syntax is as follows: {figure<?:id> <media>} or {{figure<?:id> <media>}<caption>} where:

• <?:id> is either empty or a : followed by an id. If no id is given, one is autogenerated from the caption (if existant).
• <media> is either an image, audio or video element,
• <caption> consists of the inline elements that will be rendered as the caption for the figure.

Figures are nestable block elements. They can be referenced by id (using the label prefix for disambiguation).

Examples:

{figure {image!kangaroo.svg}}

{figure {image!kangaroo.svg}
  Kangaroo numbers in Victoria from 1880 to 1980}

Refer to {!"kangaroo-numbers-in-victoria-from-1880-to-1980"} for more details.

{figure:kang {image!kangaroo.svg}
  Kangaroo numbers in Victoria from 1880 to 1980}

Refer to {!kang} for more details.

{figure:kang
  {{image!kangaroo.svg}
    Line graph showing a doubling of kangaroo numbers from 1880 to 1980}
  Kangaroo numbers in Victoria from 1880 to 1980}

The last example, taken from here, shows that alternative text and caption are different.

Audio and video are also allowed in figures:

{figure 
  {{video!flowers.mpg}Video of flower growing in rocky ground}
  These beautiful flowers (Hoary sunray) decorate the Snowy Mountains in summer}

{figure 
  {{audio!birds.mp3}Sounds of birds}
  The audio landscape in this country is very nice}

Rendering medias

HTML

Rendering media in html is easy thanks to HTML5 features.

The size for rendered images and figures depend on the size of the asset. Audio and video have controls embedded.

Latex

How medias are inserted in latex is made on a best-effort basis. Here are some ideas:

• Links to assets could be made using attachfile2.
• Image assets could be made using \includegraphics.
• Images with absolute links could be made using this trick
• Figures are made using the figure environment.
• Video and audio could be made using the media9 package.

Medias are rendered without size specification: they use the original size of the media. They are block elements.

Assets for installed packages

Assets should be installed in the hierarchy that starts at <pkgname>/odoc-pages/. Additionally, any file installed in <pkgname>/odoc-assets/ will be equivalent to the file installed in <pkgname>/odoc-pages/_assets/. This allows compatibility with the odig convention.