Syntax for including images

[panglesd]

This issue is for discussing the syntax for including images in odoc. Since the parser has been remerged into this repo, I open it here!

External and internal images

I would like to support "external" and "internal" images, just as for links. The "src attribute" for external images would be given as a link, and as a reference (to an asset) for internal images.

Alternative text

I think that we should encourage the use of an alternative text, for accessibility. The recommanded rules for alternative text are:

• A replacement for the image when the image is "informative"
• An empty alt text when the image is "decorative"
• No alt text when providing an alt text is not really possible (for instance, a user-uploaded image.)

In the case of odoc, I guess we can always provide an alt text (case 1 and 2), so the syntax should hopefully incentivize people to add one.

Compatibility with metadata extension

At some point, during the dev meetings and private discussions, the need to add metadata to the odoc language was mentioned (it first came when discussing how to specify alignments in table columns, in "heavy syntax").

Some things were mentioned:

• {tag[key1=value1 key2=value2] content}. For instance {table[align="LCR"]...}.
• {{tag key1=value1 key2=value2} content}. For instance {{table align="LCR"}...}. This looks a bit similar to {{!ref}content} and {{:link}content}.

While this was only informal discussions, I think the new syntax for image should be designed not to prevent the addition of metadata!

The syntax

With these three requirements in mind, here is one proposition (option A) {{img!ref}alt text}:

Using a reference:
Home town: {{img!carouge.png}Carouge}.

Using a link:
Home town: {{img:http://carouge.com/carouge.png}Carouge}.

With an empty alternative text:
I lived in {{img!carouge.png}} Carouge.
I lived in {{img:http://carouge.com/carouge.png}} Carouge.

I think it is nice for the following reason:

• The syntax for external and internal images is quite consistent with links and references
• It incentivize people to write alternative text, as {{img!ref}} feels wrong ({img!ref} could arguably be added).
• It is compatible with at least one option for adding metadata: {{img!carouge.png title="A photo of Carouge"}Carouge}

Other possibilities

• Option B: {img{!ref}alt text}

Using a reference:
Home town: {img{!carouge.png}Carouge}.

Using a link:
Home town: {img{:http://carouge.com/carouge.png}Carouge}.

With an empty alternative text:
I lived in {img{!carouge.png}} Carouge.
I lived in {img{:http://carouge.com/carouge.png}} Carouge.

But that’s not great to add metadata

• Option C: {img[!ref]alt text}

Using a reference:
Home town: {img[!carouge.png]Carouge}.

Using a link:
Home town: {img[:http://carouge.com/carouge.png]Carouge}.

With an empty alternative text:
I lived in {img[!carouge.png]} Carouge.
I lived in {img[:http://carouge.com/carouge.png]} Carouge.

With metadata
Home town: {img[!carouge.png title="A photo of Carouge"]Carouge}

Satisfy all criteria as well, but feels slightly more different from the rest of the syntax, since it introduces the brackets in tags. But, a serious candidate in my opinion :)

Conclusion

What do you think?

[dbuenzli]

Thanks for getting the ball rolling on this. Very much appreciated!

I'd prefer proposition A.

In my opinion it's the simplest w.r.t. to learning and remembering the documentation language. Basically this makes images exactly like links except the generated tag moves from a to img (you could even explain the (regexp) syntax as being {[a|img|video|audio]!ref} with a default to a). As such I would definitively add the bare {img!ref} to make it more consistent with the link syntax.

Here a few comments:

1. I think it would be nice not to limit ourselves to images but also allow for audio and video tags. Two approaches here. Either we overload proposition A {{(img|video|audio)!ref}alt text} or we move to {{asset!ref}alt text} and infer a tag based on the extension of ref. The latter is of course more brittle w.r.t. introduction of new formats. The former is likely a better idea.

2. We still need to be able to refer to assets in the normal link reference syntax, e.g. you may want to make a link on a PDF file that is part of the assets. I guess that following page-* reference we should have asset-* references that must resolve to the link on the asset. With this in mind we should be careful to mention (and implement) the fact that {img!ref} and {img!asset-ref} have the same effects.

3. Something needs to be said about nesting link and images. Is {{!Module}{img!my.img}} allowed ?

xref #59

P.S. When you need to make URL examples RFC 2606 is your friend.

[panglesd]

I'd prefer proposition A.

Me too :)

I think it would be nice not to limit ourselves to images but also allow for audio and video tags.

Yes, definitely a good idea. I also prefer the explicit tag, instead of inferring the tag based on the extension of ref. Moreover, if we allow links to image/audio/..., it can be hard to guess the extension: {img:https://picsum.photos/200/300} is an url to an image, but it’s not evident from the URL.

We still need to be able to refer to assets in the normal link reference syntax

Also agree (I have already some branch implementing this somewhere)

Something needs to be said about nesting link and images. Is {{!Module}{img!my.img}} allowed ?

Currently, only text, code span, math span, raw markup and styled content (bold, italic, ...) is allowed inside links.
I think we can allow images, but not audio and video, since those will have buttons to trigger them.

(For some reason, odoc’s AST for comments is different from odoc-parser’s AST. The restriction for content of links is in odoc, not in odoc-parser. See the non_link_inline_element type.)

[yawaramin]

I just want to double-check something: do we have a critical argument for why the current way of including images is not good enough? Ie, {%html: <img src="..." style="width:...; height:..."> %}. Of course, I agree that it's nice to have a dedicated syntax for images, but is there something about embedding HTML that breaks for the image use case?

[dbuenzli]

It works but, then theoretically raw html needs to be sanitized if you want to publish things on a community website like docs.ocaml.org and avoid XSS by rogue package publishers. IIRC sanitizing HTML is actually a difficult thing. One simple way of doing that is to simply forbid raw html :–)

Also in that src attribute you have to hardcode a path that depends on how odoc generate stuff which is not a good idea. First you need to define a convention (see e.g. odig's convention about the odoc-assets directory) and then compute yourself how to get to that directory depending on how your doc is generated. That link depends at which submodule level you are so it will happily break if you reorganize your module structure or if odoc changes its output generation structure.

Inclusion of assets via machine-checked logical cross references avoids all these problems.