Odoc 3.0 Planning: Assets and medias in odoc

[panglesd]

Odoc 3.0 Planning: Assets and medias in odoc

This discussion builds on #1097, focusing on assets and media elements.

Referencing assets

Recall from #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 the "medias" section), 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
• <kind> 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:

Media	Rendered as	Type	Text used as	Text can contain
asset	link	Inline	Displayed text	Inlines but no links
image	image	Nestable block	alternative	Text
video	video	Nestable block	alternative	Inlines
audio	audio	Nestable block	alternative	Inlines

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

Similarly to pages, assets for <pkgname> should be installed in the <pkgname>/odoc-pages/ hierarchy.

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.

[dbuenzli]

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

Why do you provide this syntax ? It can only lead to absurdities like {video:https://picsum.photos/200/300}.

[panglesd]

Do you mean {asset:https://picsum.photos/200/300}?
This was added I think only for "consistency of the syntax: whenever there can be a !, there can be a :.
But that is not very important, I don't mind removing it.

[dbuenzli]

Ah no sorry I read {<meta>:<link} renders the same as {:<link>}.

Also there's a typo. {<media><kind><target>} should be {<media><sep><target>} or <sep> should be <kind>.

[dbuenzli]

I don't think I'm happy about the asset resolution scheme. It replicates all the problems you get with link references in HTML which are extremely brittle to structural changes. These problems can perfectly be avoided here and I think we should take the steps to do so.

Two basic requirements to start from:

1. If the basename of an asset or .mld page is unique in the hierarchy rooted at the package root I do not want to have to specify its path. Only if the name is ambiguous, should a warning tell you to disambiguate with a path. (Said differently: I want the basename of assets or .mld pages be treated like the module name of compilation units).

2. I want to be able to access the root of my package hierarchy without having to name it.

The reason for 1. is that this allows to move either assets or entities referring to them without having all references breaking.

The reason for 2. is that packages do get renamed or split etc. and in this case you don't want to have to redo all you references. To give an example suppose I decide to simply have all my assets in a toplevel assets directory. If I use relative references in my page then if I move the page in the hierarchy all the references break, not happy. If I hardcode absolute references /pkgname/assets, the page breaks the day my package name changes, not happy.

Regarding 1. I think that all <target> which do not have a path separator should be "logical" (looked up anywhere in the hierarchy). If you really want the one in your directory you should write ./<target>.

Regarding 2. I'd propose perhaps to simply use a starting // to resolve to "/mypackageroot/". That way if I want to refer to my package landing page I can write: {!page-//index} or {!//page-index} I'm not sure I understood where you put the reference <kind> qualifier (I would rather be in favor of always starting with the qualifier rather these odd looking and hard to parse references: {!../../asset-"data.json"}).

[dbuenzli]

Regarding 1: I think that the resolving mechanism for pages/assets should have a simple mental model: people writing docs seem to want to spend as little time as possible learning odoc. Yet, it has to be expressive enough to disambiguate duplicates. That is why I think the familiar "relative/absolute" path with no exceptions is a good candidate.

Precisely: why make a different mental model for resolving modules and assets/pages ?

Here are a few points:

1. In general from a documentation maintenance point of view you will want to avoid as much as possible path based references since those are brittle.
2. From a user perpective being familiar with broken stuff is not a very good argument to enshrine it.
3. A documentation system like LaTeX use logical (name based) references.

and it will be confusing not to be able to write {!index.mld} (which are currently working references!)...

Currently it's possible to have only one. So there's no ambiguity. I don't necessarily see the need for tons of index.mld pages in packages, these days you can already be happy if you can find one…

We could just add a special case in mechanism as you propose, for pages/assets within the same directory:

I don't think this is a good solution.

1. I think it's clearer for users if you say all references without a / are logical and all those that have one are path based.

2. It doesn't work in face of documentation evolution. File additions in a directory can silently turn logical references into path based one. For example:

   Suppose I have a bunch of .mld pages in a subdirectory that use {!index.mld} to refer to the root of the package page. Suddenly I add an index.mld file in that subdirectory. Now all of my references silently point to something I didn't want them to point to. The problem is of course
   not specific to index.mld but with any kind of asset.

Also, do I understand correctly that this is equally about assets AND pages?

Yes I don't think there's the need to make a difference.

[panglesd]

Precisely: why make a different mental model for resolving modules and assets/pages ?

In my opinion, they are already quite different: assets/pages are in a file system hierarchy, the module hierarchy is defined in files that are in a flat namespace, which in my opinion already "breaks" the symmetry. But more importantly, when we tried to have the same resolution for pages and modules, we had many problems with disambiguation (modules may use alias to solve this, I don't want to have to introduce page aliases!)

I don't necessarily see the need for tons of index.mld pages in packages, these days you can already be happy if you can find one…

Each directory "should" have an index.mld page, see #1097. Yes, maybe few people will do that, but that does not mean we should not try to make it a good experience for those that have multiple directories each with an index.mld file.

[dbuenzli]

In my opinion, they are already quite different: assets/pages are in a file system hierarchy, the module hierarchy is defined in files that are in a flat namespace, which in my opinion already "breaks" the symmetry.

Well it seems (I didn't have the time to go over #1097 yet) the system your are currently designing breaks it.

But more importantly, when we tried to have the same resolution for pages and modules, we had many problems with disambiguation (modules may use alias to solve this, I don't want to have to introduce page aliases!)

Let's not get overboard here. Most package won't have any problem in simply having pages with different names in their namespace. More generally most packages will simply have unique file names for pages and assets, even more so if that makes everything more convenient; being able to make references by name regardless of where your file located is utterly convenient.

Yes, maybe few people will do that, but that does not mean we should not try to make it a good experience for those that have multiple directories each with an index.mld file.

Not sure exactly what the bad experience is here but one thing I know for sure is that the problem I highlight in the second point 2. of my last message is bad user experience.

[panglesd]

I though about this a bit more, discussed with @Julow and @EmileTrotignon , and I am still slightly more convinced by the "logical resolving biased toward the current directory" than the "unbiased logical resolving (that requires ./)".

For instance, if you have a directory A where you have an example.mld page and you refer to this page (as a "global" reference).
Then, you create a directory B and add an example.mld in it. Suddenly all your references to example in A break. (At least, you get a warning with the opportunity to suggest how to solve the issue!)

The fact that adding a file somewhere makes reference break can be problematic especially if the driver adds some file: for instance, it is explained in the other document on structured documentation, that every folder need an index.mld. So, the driver is likely to add the missing index.mld. Suppose you create a directory containing the assets (but no index.mld), the driver will create one and your {!index} references will be ambiguous, which can be a bit confusing.

I can still be convinced, in particular I'd wait for @jonludlam's opinion. (But at least, if we keep the unbiased global resolving, we need to have a warning that explicitly mention the ./ syntax on ambiguous references that could be solved by taking the file in the same directory.

(I am also not going to be very reactive this week).

[dbuenzli]

(At least, you get a warning with the opportunity to suggest how to solve the issue!)

Precisely, whereas with "logical resolving biased towards the current directory"¹ adding files may silently change your references to things they were not meant to point to !

So, the driver is likely to add the missing index.mld. Suppose you create a directory containing the assets (but no index.mld), the driver will create one and your {!index} references will be ambiguous, which can be a bit confusing.

I'm not so concerned by that. If it's a convention and all drivers work the same it will be immediately reported as ambiguous when you devise and build your docs.

Basically {!index} will only be ever available if your docs are flat enough but that will likely be 95% of the cases out there.

Footnotes

1. Which is in fact, not logical resolution, you conflate path resolution and logical resolution into a single ambiguous syntax. ↩

[dbuenzli]

Btw. since all this will likely happen in the reference parsing code please solve #865 along the way :-)