Odoc 3.0 planning

Ecosystem
1

Hi everyone,

For many years we’ve had a team here at Tarides working away on Odoc, quietly adding new features, fixing bugs, speeding things up and generally enabling OCaml package mantainers to write good documentation. Up until recently, those improvements have mostly been incremental, but with the recent addition of some larger new features like search and source rendering we’ve found we need to think a bit more broadly and consider how these changes will fit into the larger ecosystem. We’re also thinking of how to extend the abilities of Odoc to handle more structure in the documentation, with better support for images, an improved sidebar, and a better ability to link to the docs of other packages.

We’ve therefore started the process that’s going to lead to Odoc 3.0, which will involve not only work on odoc itself, but also on ocaml.org, the documentation pipeline that produces the docs for ocaml.org, dune, and odig. It’s being done incrementally, so we’ve started with the core issues of how to structure your docs, how to do references both within the docs and across packages, what the output file structure will look like and how the breadcrumbs will reflect that. What we’ve posted so far is by no means the final version, and we’d love to get feedback on the suggestions we’ve got so far. Getting this right is surprisingly complicated, so the more people we have thinking about it, the better our chances of success!

So if you’re interested in writing or reading docs, I encourage you to head on over to the discussion we’ve just started on ocaml/odoc and join in the conversation!

16 Likes
2

Following the github discussion posted in this thread, we have published a new one that continues the previous one and focuses on assets and medias for Odoc 3.0.

Please tell us what you think!

2 Likes
3

Not sure how much this has been commented on: the success of Markdown is owed to its light syntax and what I see here looks closer to LaTeX in comparison:

{{video!/pkgname/output.mpg}The output from pkgname is very cool!}

Why can’t ODoc figure out at least by default that the file is a video but requires an annotation? Why not make this optional as an override and rely on mime types or extensions? Requiring proper nesting is another burden on the author - I understand where the requirement comes from but I believe we need to think about authors more than machines if we want to have better documentation.

1 Like
4

Thanks for starting the discussion!

Let’s compare with markdown:

![alternative text](link/to/image.jpg)

versus

{{image!link/to/image.jpg}Alternative text}

We have I think two main differences:

  • In markdown, alternative text and links are not nested, but “one after the other” (and in reverse order compared to ocamldoc). In ocamldoc, they are nested. I don’t think we can really change that in the syntax we introduce: it would make it a bit too different from the rest of the syntax…

    According to you, would:

     {image!link/to/image.jpg Alternative text}

    be better? To me yes, it looks a bit better, but not sufficiently to justify the difference in syntax with links.

  • Markdown only uses ! to tell its a media (and not a link). Additionally markdown does not differentiate between images and other medias (video, audio).

    Here, we propose to use a more “guessable” but heavier syntax. We could definitely replace image, audio and video by a single media and guess from the extension/mime:

    {{media!link/to/image.jpg} Alternative text}

    Do you think that would be better? To me that does not really change. What would change is to have, in addition of this “guess the kind of media from extension”, a lighter way to tell that it is a media.
    Something along the lines of:

    {{#link/to/image.jpg} Alternative text}

    Such “short syntax” might make sense in my opinion.

1 Like
5

That syntax is confusing, # is for URL fragments.

I didn’t look closely but the proposal looks fine. Being explicit is more obvious and not providing different ways of doing thing avoids style discussions.

Besides you may not be able to infer a proper type from multimedia containers files like .mp4 without decoding them, as they could contain audio or video or both .

I think if we want to have better documentation we need programmers to think more about humans than about machines – that is educate programmers entirely differently than how they are now.

6

I think it would be better. I understand that this creates problems with paths that include spaces but I think it is better to deal with the rare cases using an escape mechanism or demand URL encoding. It would also work better without alternative text compared to Markdown.