Should similarity to HTML be the goal here? Markdown was designed to be easy to read, in direct contrast to HTML which isn’t particular easy for a non-developer to understand. The use of HTML seems like a fallback in the original spec. For other parts of the Markdown syntax, the syntax choice appears to be in opposition to HTML.
It’s worth asking why colons were chosen for some languages instead of equals signs. In particular YAML. As with Markdown, YAML was designed to be human readable first and foremost. Have a look at part of this example YAML document from Wikipedia:
The syntax is quite readable to a human, spaced out with key/value pairs seperated as you might expect a list to be written down. Also, the colon is used in English to express “this is what I mean” whereas an equals sign is typically used to express something mathematical. E.g. John Gruber created a language: Markdown.
In YAML’s (JSON like) stream context, the advantage of using comma as item separators is that it allows omission of quotation marks in many cases, even when a value contains spaces. But YAML would require a space after the colons, unless the values were quoted.
It’s not the computer parser that concerns me, but the human parser. Whenever you add a second way to say something, readers are going to wonder what the distinction means. Remember, this is already a slightly esoteric region for non-programmers and not all Markdown flavors support it. So there will be some situations where folks will see a bit of line noise{id: “line-noise”, title = ‘$#@^(’ .extreme_example_to_prove_a_point} in their documents. If sometimes authors use = and other times : with optional commas and quotations and so on, it will make the problem exponentially worse.
Note: I’m a Perl programmer, so I’m used to reading cartoon character swearing. As a programmer, I like the flexibility. As someone who needs to explain Markdown to non-technical people sometimes, I dread it. So let’s pick one syntax and stick to it.
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.
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:
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.
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 =
10
I 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.
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.
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).
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.
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
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.
