search

realworldocaml / mdx

Execute code blocks inside your documentation
ISC License
265 stars 45 forks source link

Introduce new syntax for explicit block type #385

Open NathanReb opened 2 years ago

NathanReb commented 2 years ago

This introduce a new, more explicit labels block-type=... which is meant to replace the four separate labels cram, ocaml, toplevel and include in the future.

It is added for a transition period at the end of which the four labels of the apocalypse should be removed in favor of this new one.

I'm opening this as a draft as one of the test relies on MDX reporting multiple errors at once which I thought we had but turns out we still haven't so I'll work on this next to unblock this PR.

Other than that it is ready for review!

NathanReb commented 2 years ago

The label will never be mandatory and I think we should probably keep the inference. It just provides a way to be explicit about things, providing better error messages. The label must not be confused with the language header. We can switch the label to type if the length really is a problem.

NathanReb commented 2 years ago

for example a single character: $ocaml, $toplevel. $ is used in the extended label syntax.

The idea for this new "syntax" here is to make the label more easily readable and understandable to anyone. I agree block- was redundant and removed it but I believe having a regular label syntax that state what this value is about helps understanding what it does, looking up the label in documentation (which I'm currently writing and is part of why I worked on this feature), etc...

I think the 4 extra characters don't do a lot of harm but they do simplify things for the newcomers to projects using MDX quite a lot!

NathanReb commented 2 years ago

I'll undraft once #389 is merged!

NathanReb commented 2 years ago

Just rebased!

NathanReb commented 2 years ago

Indeed, it seems to be good to clarify why we added explicit block types in the first place:

The main motivation was that people were sometime confused at error messages or behaviour. For instance they want to write a toplevel block but forget the leading # and can't figure out why it doesn't behave the way they want it to because MDX just treated it as an OCaml block. By adding the explicit type=toplevel, they would get an error about the misisng the #. There are a few other such examples but I can list them from the top of my head.

The other reason is clarity of the semantic. Using explicit labels, which are easy to look up (especially once we finish the manual), makes it clear what the intent of the block is and easier for newcomers to understand how MDX will behave.

The straight ocaml, toplevel, etc. form should be gradually removed as it doesn't help much with clarity. The explicit label name can be looked up in the documentation and will inevitably lead to describe what the four types of block are.

My personal recommendation would be to always use the explicit type label as when writing an MDX block, one usually knows what they want to do with it. I understand some people will prefer conciseness to clarity hence why we'll keep block inference.

NathanReb commented 2 years ago

I just rebased and hopefully fixed the issues you pointed out. The CI failure on alpine seems unrelated!