Consistent attribute syntax

[mofosyne]

This proposal is to ensure consistency in implementing attributes {} as seen in pandoc.

This is the attribute format that is in consensus so far in http://talk.commonmark.org/t/consistent-attribute-syntax:

 {#myId .myClass  key=val key2="val 2"}

• #myId in html is the id=myId field of a html tag. This is useful for anchors. There will be no uniqueness checking requirements since it's the writers job to pick unique names not CommonMark.
• .myClass in html is the class=myClass field of a html tag. This is useful for general styling, e.g. syntax highlighting in code fields.
• key=val key2="val 2" is treated depending on context. Most of the time, it's just appended to the html tag like #myId and .myClass. It can be thought of as the 'settings' of the CommonMark elements. E.g. width and height of embedded videos.

Discussed:

• json style vs html : What was discussed, is using json like syntax instead of html as inspiration. However json is too verbose with , when does the job just as well in HTML. Plus CommonMark can parse html tags, so it's good to keep some consistency with html (and thus reduce mental switching cost).
• Uglyness if too many is used : Most people won't need it for everyday writing (except for anchors perhaps). But when they do, it will be a life saver. Thus it's not going to be used everywhere, and thus {} will be visually manageable.

Contentious issue:

There is one objection by chrisalley that { size: 10, duration: 10, cycle: forever } is more readable than { size=10 duration=10 cycle=forever }

---

Consistent attribute syntax in practice:

Url Links

 [description](url){#myId .myClass  key=val key2="val 2"}

Embedded Media

!mediaType[description](url){#myId .myClass key=val key2="val 2"}

• assumed to be image if mediaType left blank

• syntactic sugar ( content of () handled by mediaType handler/extension):

  ![](file.mp4 "video title" 80x10 )
  

  is equivalent to typing:

  !video[](file.mp4){title="video title" width=80 height=10}
  

Extension Directives (For extra extensions!):

@name[content](arg){#myId .myClass key=val key2="val 2"}

• name :~ extension name

or

@@@name[content](arg){#myId .myClass key=val key2="val 2"}
    >>extension code/content to process here<<
@@@

Code:

`<someCodeHere>`{#myId .myClass key=val key2="val 2"}

Shorthand version:

`<someCodeHere>`myClass 

fenced code:

``````{#myId .myClass  key=val key2="val 2"}
     someFunction();
``````

short hand version:

``````myClass 
     someFunction();
``````

Header:

# HeaderTextHere {#myId .myClass key=val key2="val 2"}

# HeaderTextHere # {#myId .myClass key=val key2="val 2"}

HeaderTextHere 
################## {#myId .myClass key=val key2="val 2"}

HeaderTextHere 
~~~~~~~~~~~~~~~~~~ {#myId .myClass key=val key2="val 2"}

HeaderTextHere 
------------------ {#myId .myClass key=val key2="val 2"}

HeaderTextHere 
================== {#myId .myClass key=val key2="val 2"}

Block styling

This is a paragraph with a little texts.
And more text here.
{#myId .myClass key=val key2="val 2"}

This is a paragraph with a lot of text. That's why it's somewhat hard to make out there is an attribute. {.this-class-is-ignored-and-left-as-it-is-in-text}
{.some-class}

List

Normal list with individual item styling and block styling:

- item one {#myId .myClass key=val key2="val 2"}
- item two {#myId .myClass key=val key2="val 2"}
{#myId .myClass key=val key2="val 2"}

[jgm]

This is a discussion item, and belongs on talk.commonmark.org, not here.
Please open a thread there (or contribute to an existing one -- I believe this is already being discussed).

[mofosyne]

So, what is needed before it can be put up officially? Or is this via just directly pulling git request to specs? There seems to already be a consensus about this, or does it need to be more strictly defined and agreed upon?

There is currently a #105 request by mb21 on this nature

[jgm]

There is a consensus, perhaps, among people who have commented on that
topic on the talk page. I have not, myself, even had a chance to look at
it. In any case, consideration of extensions needs to be tabled until the
core is settled. It's fine to discuss these, but it's premature to post an
issue.

On Wed, Sep 10, 2014 at 10:02 AM, mofosyne [email protected] wrote:

So, what is needed before it can be put up officially? Or is this via just
directly pushing git request to specs? There seems to already be a
consensus about this, or does it need to be more strictly defined and
agreed upon?

—
Reply to this email directly or view it on GitHub
#102 (comment).