Introduce new syntax for explicit block type #385
Conversation
| @@ -0,0 +1 @@ | |||
| [mdx] Fatal error: File "test-case.md", line 6: invalid code block: Label `block-type` requires a value. | |||
There was a problem hiding this comment.
The error for block-type=invalid should probably have its own test case, since we exit on the first.
There was a problem hiding this comment.
Yes hence me working on multiple error reporting before undrafting this!
There was a problem hiding this comment.
Also I should rewrite the tests to use the new labels syntax!
|
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 |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
The idea for this new "syntax" here is to make the label more easily readable and understandable to anyone. I agree 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! |
|
I'll undraft once #389 is merged! |
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. Signed-off-by: Nathan Rebours <[email protected]>
NathanReb
force-pushed
the
better-kind-label
branch
from
6b12f66
to
d855426
Compare
|
Just rebased! |
Signed-off-by: Nathan Rebours <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
NathanReb
force-pushed
the
better-kind-label
branch
from
d855426
to
64cd796
Compare
There was a problem hiding this comment.
The code is good, my suggestions are mostly just from the renaming of block-type to type. Just overlooked details.
What I would however like to see would be some free-text documentation (e.g. in the README) about this, maybe with some advice whether and when to use ocaml, type=ocaml or inference, to make this a bit more discoverable for users as well as clearer which of the various choices make the most sense in their particular situation.
test/bin/mdx-test/failure/include-without-file-label/test-case.md
Outdated
Show resolved
Hide resolved
|
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 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 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. |
Signed-off-by: Nathan Rebours <[email protected]>
|
I just rebased and hopefully fixed the issues you pointed out. The CI failure on alpine seems unrelated! |
This introduce a new, more explicit labels
block-type=...which is meant to replace the four separate labelscram,ocaml,toplevelandincludein 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!