New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Syntax for including images #985
Comments
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 Here a few comments:
xref #59 P.S. When you need to make URL examples RFC 2606 is your friend. |
Me too :)
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:
Also agree (I have already some branch implementing this somewhere)
Currently, only text, code span, math span, raw markup and styled content (bold, italic, ...) is allowed inside links. (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 |
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:
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}
:I think it is nice for the following reason:
{{img!ref}}
feels wrong ({img!ref}
could arguably be added).{{img!carouge.png title="A photo of Carouge"}Carouge}
Other possibilities
{img{!ref}alt text}
But that’s not great to add metadata
{img[!ref]alt text}
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?
The text was updated successfully, but these errors were encountered: