Btw shouldn’t we keep to consistent attributes like this? I remember that for blocks in general, the {} goes at the last line. Thus for your ascii cat example:
Also about your choice of @. Isn’t it already used by most commenter as a signifier for usernames? e.g. twitter uses it as username, discourse uses it for username as well.
Fenced code blocks in Pandoc, MarkdownExtra and Kramdown (and therefore the consistent attributes proposal) have the attributes on the first line. It’s kind of nice to see all the arguments/attributes before you start to read the code/directive content…
``` {.language-ruby}
x = 1
```
True, but shouldn’t be a problem with @@@name or when the [] in @name[] is mandatory.
It’s kind of nice to see all the arguments/attributes before you start to read the code/directive content…
Alright
@@@name is ugly, and people would hate to have to type that for usernames.
@name[] is ugly. What if people want to call directive without arguments. E.g. @TableOfContents or !cut etc…
Using ! is much safer, and is internally consistent, since is already used to embed images. So naturally !name[]() would imply special embedded content/declaration.
Btw I’ve been thinking about the issue of the !cut example. As in how do you distingush between a single line inline directive vs block directive. Here is an example of the issue.
!cut "this is settings for a block directive, but how do you know that `!cut` is not inline?"
!cut this is a normal paragraph with `!cut` as an inline directive in the first line.
I think the solution is to use : as the block directive switch. This is since anything after : in a block directive is purely arguments for the directive only. Thus
!cut: "much clearer that this is for the `!cut` directive"
!cut this is a normal paragraph with `!cut` as an inline directive in the first line.
Unfortunately, this does mean that the block directive for !cut without argument is
The issue with your leaf block proposal is if people for some reason type !!!!!! for some reason e.g.
!!!LeafBlock settings=value
some paragraph words etc....
!!!!!!!!!!!! WARNING !!!!!!!!!!!!!
Well.. its a warning message.
What did you expect?
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
now compare to this parser safer method:
!LeafBlock: settings=value
some paragraph words etc....
!!!!!!!!!!!! WARNING !!!!!!!!!!!!!
Well.. its a warning message.
What did you expect?
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Now it will leave the bit inbetween !LeafBlock and the last !!!! alone, and thus wont get confused.
No particular preference about the optional [](){}. As usual, if it’s optional then that’s good. I’m just covering @vitaly 's preference to keep the block param flexible.
Spaces between the @/! and the name should not be allowed: !!! warning is not valid while !!!warning is. Or should it be @@@warning to decrease the probability of clashes even further?
That warning block in example is not a directive btw. It’s just a style I see people randomly type in instruction manual, on things that people shouldn’t do if they want to not die. Basically its used in the wild as an enclosed box that is empathised for visibility.
(Wonder if we should make an ‘emphasis’ block where !!! <Important Block> !!! as the start header, and !!! for the end header. Edit: Content Block/Inline Syntax )
I don’t like idea to add [](){} into spec for blocks. Looks like attempt to invent something universal with inlines without real needs. If you go this way, you can get html-like result in the end - working, but overcomplicated and not relevant to initial goal.
May be, {} only, but also under question.
That can work, but require parser to know exactly if named block is leaf or container. Because blocks can be nested. If you change parser to another one, that don’t know some named block directives, nesting sequence will become broken.
I’m not sure I understand. The point of my proposal is exactly to avoid this. Therefore a leaf block is !!!name on one line, while a container block has an opening !!!name and a closing !!!. You agree that there should be a different syntax for leaf and container block directives, right?
The [inline content] (argument) {key-value pairs} serves simply as a common way to supply the directive with these three things, which I think is equally useful for inline and block directives. I’m thinking of what kind of AST a custom filter or module would like to receive after a markdown parser has parsed the document. An AST that contains something like:
@mofosyne I’ve looked at your updated first post in this topic. If I understand correctly, our two proposals are fairly close and there are mainly two things separating them:
Mine fails if we would allow the [](){} stuff to spread over multiple lines (as I proposed in the attributes thread…)
Yours doesn’t have a way to specify InlineContent, i.e. the [] in my proposal.
Mine fails if we would allow the {} stuff to spread over multiple lines (as I proposed in the attributes thread…)
Well, now that I’ve been practising typing the {} syntax (via examples above). I’m incline to agree with vitaly that param should be more flexible. Since the {} is not very friendly for touch typing, and is only used in inline typing as a necessity.
Plus mine is still in keeping with the consistent attribute syntax. Since I recognize that a block can be styled via {} at the end, or at the fence start. I intentionally allowed two formats, because for short settings, the compact block directive is more intuitive. While for larger directive with more complex params, it should really be in it’s own line for legibility.
I encourage you to type typing my two forms and your form. You’ll see the difference I noticed.
Yours doesn’t have a way to specify InlineContent, i.e. the in my proposal.
Well that’s because I don’t think it comes under the jurisdiction of generic block directives. I have no issue with your inlinecontent proposal, but’s not a generic directive. It’s more related to the family of [](){}, though I do not have a name for it.
(tl;dr: I support it, but think it needs to be in a different category. Not a directive.) (Oh and btw, this is a block directive thread. So limited scope of discussion here)
Actually, I’m out of ideas too. It may be that this feature is more advanced than is actually needed for practical purposes.
In programming, good libraries and frameworks often come out of real world projects, rather than being designed in isolation. A pattern might be repeated a few times in different projects before being moved into a library. I think we should use the same approach when deciding whether to just use HTML or to invent new Markdown syntax.
Well if anything I don’t commonmark to be a programming language. I rather it be more like CSS, which is more declarative.
There is one thing I am annoyed in CSS however. It’s a lack of constants support (e.g. #define in C).
And yea I agree, that’s why I would like to see it in action in something like @vitaly 's remarkable parser, his is a good candidate as it is designed to be pluggable from the ground up. Seeing it in action might help us iron out some real world issues in terms of the syntax. But of course, only one style could really be tested at a time, so he would need to choose one of our proposals (or make one up himself).
Generating output from a code snippet !eval( print "hello world")
Evaluating a maths input !calc[ 1+1= ]
Generating a table from remote source !table(data.csv)
Including external commonmark files (e.g. compiling a book or report) !include(intro.md)
Generating QR codes !QRcode[google](www.google.com)
Including the first generic clipart found: !clipart[ cat dancing ]( optional image url )
Image macro generator (Very useful for sight impaired readers): !imagemacro[Of all the front yards in all the world][The cat walks into mine](Noir Dog)