I’m with jericson on this.
I’m in favour of this syntax. It’s a lot more readable (for an English writer) than the HTML attribute syntax, and readability should be emphasised above similarity to HTML. Especially if the goal here is the eliminate the need to use/know HTML.
I’m with @jericson that a singular syntax is preferable.
2 Likes
Yea I’m convinced on the readability argument, but at the condition that , is optional (Since , is mostly redundant, used to resolve ambiguities that can be solved via using ".
No commas (more readable since each “block” in {} is one attribute:
{ title:"some audio ambiance" cycle:forever }
With Commas (is more conventional):
{ title: some audio ambiance, cycle: forever }Should the keys be allowed to contain spaces?
Compare:
{ fontcolor: "light green" fontsize: 14 }
to
{ font color: light green, font size: 14 }
Not the best example (CSS would be better here), however from a readability point of view the example with a space in the key is easier on the eyes. The seperation seems to require the use of a comma though. Otherwise you’d need to specify it as something like this:
{ "font color": "light green" "font size": 14 }
Non-programmers aren’t going to understand the need for quotes (at least not without explaining it), so I’m in favour of commas for that reason.
1 Like
Good point. Haven’t thought of it in that sense. It won’t look like HTML, and it’s not exactly json. But it does look like markdown in terms of visual simplicity.
I would say that "" would be included as an option, and this mode would allow for 'escaping characters. Without it, it would be read directly character by character (or as a number if numerical).
Inputs:
{ font color: light green}
{ string: string with \n new line }
{ string: "string with \n new line"}
{ number: 10 }
Outputs:
1. 'font color' =
'light green'
2. string =
'string with \n new line'
3. string =
"string with
new line"
4. number =
10I hope we all agree that the directives’ {} should have the same syntax as the generic attributes. Since both MarkdownExtra and Pandoc have used {key=val key2="val 2"} for ages, I’m strongly in favour of sticking to that.
2 Likes
Could we do this the same way that other characters are escaped in Markdown? I’m just thinking of what would be most consistent for the writer.
It makes sense to use the same syntax for both generic directives and attributes.
I’m in favour of making extension syntax as close the philosophy of the original Markdown as possible. That may mean improving syntax.
CommonMark is about formalising Markdown syntax, but should the use of syntax in other implementations (beyond the original) be the primary reason for choosing that syntax? You could always convert MultiMarkdown/MarkdownExtra/Pandoc files to a new CommonMark extension syntax if needed.
1 Like
This syntax would also help a lot while converting to non-html. My specific usecase is moving away from texinfo and be able to generate readable manpages.
Currently the best I found is kramdown-man (even if the man conversion lacks support for definition lists for now).
2 Likes
pandoc had been considered and had been rejected since it is too heavy dependencies wise.
Currently we are using a custom set of perl scripts based on texi2html e texi2pod.
Ideally for the man page only perl, python and ruby would be ok. Or at least more likely to be accepted.
Yes, if those implementations are already widely used (which both of those are) - the point is to achieve a pragmatic spec using what is more or less common practice already.
@@@ is a bit hard for eyes on everyday use, it takes too many attention. Also note, that not all users, who have to use markdown, are programmers. I’d sugggest this format for block-style markup:
!!:name <anything, used as params>
...
... content ...
...
!!
Example 1:
!!:spoiler Click me to expand
...content...
!!
Example 2:
!!:float left
...content...
!!
Block name is mandatory, params can have any format and processed by block code after name recognized.
In general, that have no principle differences with discussed above. Only a bit more eye-friendly look, and assumption, that params should not have strict form, only recommendations for complex cases.
If we use ! for block directives, then for consistency sake we would end up needing to treat generic directives as
!name[content](arg){#myId .myClass key=val key2="val 2"}
to maintain consistency with
!!!name[content](arg){#myId .myClass key=val key2="val 2"}
...
... content ...
...
!!!
With block directive shorthand
!!!spoiler "Click me to expand"
... content ...
!!!
is same as saying
!!!spoiler[Click me to expand]
... content ...
!!!
This is plausible, as long as we treat ![](){} as shorthand for !image[](){}. Which would invoke the handler for embedding images in html.
- I’ve suggested
!!:block start prefix as more readable - Not sure, that it’s good idea to search consistensy between blocks of different nature.
- blocks with preprocessor calls should be good for developpers and can have complex params
- blocks with message elements styles (spoiler, sidebar, notice), are for ordinary users and must be readable and natural. Things like this
name[content](arg){#myId .myClass key=val key2="val 2"}for ordinary user are total mess
1 Like
Don’t like !!: , potentially confusing. Plus is inconsistent with ‘code fencing’ syntax in CommonMark, which is visually similar.
Don’t see how that’s any harder to use. You don’t have to have all () [] {} elements since !nameOfExt is the base trigger word. You only need to add elements as you need, much like how english has core based words that are used often, and a person will learn many more vocabularies to handle edge cases. Thus for your examples it would be like:
!spoiler[ Click me to expand ]( Hidden text here )
!sidebarElement[ home ]( #home )
!notice[ This is an official notice to everyone ]{ .noticeclass }
If you need syntactic sugar, here is some extension to the above syntax for notice extension. Only supports strings however.
!notice:"This is an official notice to everyone" { .noticeclass }
alternatively without : (Omitting noticeclass class as well):
!notice "This is an official notice to everyone"
No recommended due to potential edge case, when wanting to use extensions without arguments.
e.g.
!randomQuote
vs
!randomQuote "this is not part of !randomQuote"
tl;dr: It is flexible enough for both block and inline. Can consider !name: " ... " or !name " ... " as an optional alternative to !name[] for natural message .
I hear you. But don’t underatand why block syntax should be consistent with fences. It should be readable first. And i don’t understand why “” should be used. Why not just pass the rest of string to block parser? If block needs ()[], it can split internally.
Also note, there is no practical need to make the same syntax between multiline blocks and inlines. In terms of html, i mean difference between display:block and display:inline. Blocks have to allow nesting. Inlines - not sure. Since cases do not intersect, each can have it’s own syntax, based on readability criteria. Everyting i suggested was only about multiline blocks.
To mb21
I had another though about if we really should use @ over ! for images. Well what if ![](){} is just shorthand for !image[](){} or more generally !default[](){} which would detect url type and redirect to approtate extention like !youtube[](){} . If that is the case, then we can just treat ! as just another generic directive that already includes some image embedding extensions by default.
!image[ img descrip ]( image url ){ .style }
This then allows for a visually compact block directive
!!!image [ Image description ] () { .blockStyle type=png encoding=base64 }
... Base 64 encoded png image Content ...
!!!
Or if we include vitaly’s recommendation for readability in block directives (via adding a : , and just passing the entire string after !!!:image) :
!!!:image png base64
... Base 64 encoded png image Content ...
!!!
{ .blockStyle }
Extra thoughts: to avoid polluting the directive namespace, uncommon extensions are place under extention. e.g. !extention.regexReplace as opposed to '!regexReplace`
Yeah using !name[] instead of @name[] could work as well. On the other hand, people might confuse it with images and !!!name has kind of a less horizontal vibe to it than @@@name.
I don’t find that adding a : makes it more readable, quite the opposite in fact. It is inspired by reStructuredText’s syntax and many people favour Markdown over reStructuredText exactly because of things like that.
1 Like
It’s inspired by looking at the display 
. I’m not familiar with reStructuredText’s syntax.
!!: has the same length as !!!, and don’t confuse with images. I did not suggested !!!: - that’s too long. Anyway, it’s a question of personal preferences. We could vote at the end.
1 Like
That’s fair enough vitaly. Though I suspect that laziness in typing !!!name will win out at the end lol.
mb21
I don’t think people is likely to confuse !name[](){} with ![](){} as the extension name quantifier will be pretty obvious enough.
On the vibe of !!! feeling less horizontal than @@@. This is only really an issue on non monospaced displays, and I don’t think it is worth the hassle of having a wider vibe at the cost of requiring the users to remember additional symbols (which was my issue with reStructuredText (I’m lazy, and so is the majority of markdown converts). I think it is more beneficial keeping the ‘core syntax language’ small by conceptual reuse of ! as an extention directive (and treating embedded videos, and images as extensions of it).