Generic directives/plugins syntax


#59

agreed lu_zero. Btw, would this make sense to you? That !extentionName is in root level, and @extention.extentionName is the same as !extentionName?

Thus:

  • !coreExtention would be for officially included extensions ( like the default ![](){} --> !default[](){} --> !image[](){} ). Which can be reasonably expected to work consistently.
  • Plus the input is defined for the name as well in a community page (e.g. just as how IP ports have a general standard)

while

  • @uncommonExtention would be for site specific extensions. Stuff that is not commonly used enough to be included in root namespace.

Would help keep namespaces bit cleaner.


#60

I think this is a very good reason for going with !. The less syntax that the writer has to remember, the better.

Earlier I raised an issue with using @ within Markdown. @ is commonly used to represent usernames. I do not think it should be used in Markdown for this reason.


#61

Actually @name is an extension so it fits perfectly the idea. The markup user would just hook to the AST and consume all Extension nodes without attributes to match users.

On the other hand !action[] could be good as well for it.


#62

Interesting. How would this work if usernames clashed with extension names though? Say you had an extension called “spoiler” and a user with the same name. What would @spoiler refer to?


#63

The possibility is non-existent if the parser provides enough information to discriminate from an inline item with or without {}.

extensions then would be parsed if they contain the {} otherwise they are names.


#64

This thread is getting out of control :smile: How about being a little pragmatic here. Let’s put the special structured syntax aside for a moment.

What do all languages have in common? Methods/Functions, possibly types, classes, objects, right? As extension is something that mostly programmers will work with, how about having the extension syntax be a method invocation signature? Having either a type or an instance in a parsing context, we could do :

@instance.doSomething(arg1, arg2, arg3)

or

@Singleton.doSomething(arg1, arg2, arg3)

Then you’d just have a plugin(s) with a several methods… The advantage is that it’s pretty much self-explanatory. Name of the type/instance and method would explain what is going on and who is responsible for what. For instance :

@[content-type_xml](code/ScalaResults.scala)

I mean even this needs an entire paragraph to explain what is actually going on.

I don’t like the idea of generic attributes much {…}. But that’s probably because I just haven’t had a need for that.


#65

Good point. The parser would need to handle [] and []() as well in cases where the extra brackets aren’t required. I still prefer ! over @ for consistency with the image syntax. Is there a reason to use @ over !?


#66

I think it depends on the particular extension. Some extentions would be for displaying particular components, e.g. a video. A writer who is not a programmer might want to easily embed a video in a blog post, for example.


#67

Another thing to add. Order of [] & () & {} is not important, and if any is missing, it is automatically added in as an empty bracket internally.

E.g. !(file.png) —(shorthand for)—> !default[](file.png){}


Multiline [], (), and {} , can be supported by [[[ ... ]]], ((( ... ))), and {{{ ... }}}

e.g.

!summary[ Post-Modern Essay Generator - http://www.elsewhere.org/journal/pomo/ ]
(((
 If one examines textual narrative, one is faced with a choice: either reject constructive prematerialist theory or conclude that reality must come from the collective unconscious. 
 Many dematerialisms concerning not theory, as semanticist postdialectic theory suggests, but posttheory may be found.
)))

#68

I was thinking that the [] might be mandatory to reduce the probability of clashes: someone might accidentally switch a space and a ! (writing e.g. hey !wait) and be really confused if he doesn’t know about directives. Similarly if we go for the @-syntax: @foo could mean a username while @foo[] is an extension.

I agree that () and {} should be optional. But again, I’m in favour of having them always in that order to reduce clashes and confusion on what the right order is.


#69

@lisak We were hoping that markdown stays declarative. Think HTML custom elements, not JavaScript function calls…


#70

I agree with mb21.

When I say !youtube[cat](https://www.youtube.com/watch?v=cbP2N1BQdYc),
what I am saying is not “How or what sequence to embed youtube link” in the page.
All I’m saying is that I declare that I want “to embed youtube link”.

What this means, is I push the implementation details to whatever renders the source to display.

E.g. In html, this declaration will embeds a video player. While on printed paper this same declaration would appear as a “screenshot” with a QR link of the youtube video next to it.


Wikipedia: http://en.wikipedia.org/wiki/Declarative_programming

describing what the program should accomplish in terms of the problem domain, rather than describing how to go about accomplishing it as a sequence of the programming language primitives[2] (the how is left up to the language’s implementation).

Wikipedia: http://en.wikipedia.org/wiki/Imperative_programming

declarative programming, which focuses on what the program should accomplish without prescribing how to do it in terms of sequences of actions to be taken.


(sidenote: Would be nice if I could just type !wikipedia[Imperative Programming] )
(Btw lisak, I really want {...}, since I do use #id often as reference anchors in a large document)


#71

This you look at the examples for inline syntax in the first post? The (){} part is optional and usually not needed, so it’s mostly just @directivename[content]. Better suggestions?

Yes, unfortunately. I think jgm & co. are still busy with the core syntax and not ready to look into extensions yet.


HTML <details> Tag
#72

Yes.

No. I don’t have better ideas. My current opinion is to implement flexible block syntax, but hardcode inline markers for each case. The only inline thing, that i really need at my projects, is math. It can be solver by something like $$…$$

At least, that should not kill my user’s brain until spec advice something better.


#73

I don’t remember, if i have written about it in this thread. Many people need extended syntax to add medias (video, audio). In my practice, links to youtube (and so on) are automatically replaced by embedded player. That’s very comfortable for bulk posts, because remove markup at all.

If you remove examples, related to link autoreplace, you will note, that the rest list of inlines is quite small. Im my case - math only. And math will have separate syntax in spec, i hope.

That’s why i think, that implementing bloсk syntax (without inlines) can be good step forward. If it’s diffucult to solve all task at once, we could split it into parts.


#74

That’s a strategy I use. It’s preferable including a references to specific sites within CommonMark. Unfortunately there is no end to the amount of sites that could be supported.

Maybe !wiki[Imperative Programming] or !encyclopaedia[Imperative Programming] instead where the behaviour is CMS specific. The content management system creator could swap out the prefered encylopaedia with another one in the future (say, if a better alternative to Wikipedia came along) and also define how the link is handled (e.g. wiki info displayed as a link to Wikipedia vs embedded in a popover). You could do a similar thing with !dictionary[Imperative] and !thesaurus[Imperative].


#75

That depends on project & implementations. Usually static list of 10-100, not infinite. Of cause, that should not be included in commonmark directly, because such transforms are subject of external ast processor or parser plugin.

I don’t object against existing syntax. Because it’s preferable for skilled authors, who wish control content directly without magic. It’s only a practical question, what should i implement right now in remarkable. From this point of view, i prefer to postpone inline syntax, until confirmed that included to spec. As i described before, my cases can be solved without such extention (because i’ll write link autoreplacer plugin anyway). Of cause, that still stay possible to add such syntax via extention.


#76

I’ve added a few more examples for inline-directives to the first post. However, it’s obviously up to you to decide whether it makes sense for your implementation. However, for a general purpose markdown implementation I think it would be nice to have it parse those into an AST so different custom directives (depending on the use case) could be easily implemented as modules or filters.


#77

Thanks, that’s helpful. Note, i don’t reject adding, only postpone. I should care not only about spec/extentions, but also about providing universal instrument. If this syntax is “addable” without depending on my opinion and without pain, then instrument is good.


#78

The problem is deciding what goes in that static list. For example, if YouTube is chosen over smaller video sites, that implies a basis towards popular brands. IMO CommonMark and any official extensions should remain agnostic towards site and brand specific content.