[kramdown-users] Syntax of IALs, ALDs and extensions

[Thomas Leitner]

Hello everybody,

there was much discussion about the current extension syntax and how to
change it to

1) make it possible to use it inline
2) make the syntax shorter
3) allow nesting of extension tags

I have summed up my thoughts regarding the above three points belows.
You will find a summary at the end of the post.

ad 1)
  The inline syntax for extensions should be less verbose than the
  current syntax. Shawn has posted some useful ideas in another thread
  regarding a possible syntax - thanks to Shawn for the writeup!. I
  agree that we would need a shorthand for the closing tag. See the
  remarks in 2) for a proposal.

ad 2)
  The currently used syntax for IALs, ALDs and extensions uses
  `{:` and `}` as common start/end tags. This syntax was mainly
  inspired by a syntax proposal from Maruku (available in
  docs/proposal.md of the Maruku gem). It mentions that the colon was
  added to allow an extension syntax later on and for easily removing
  all special tags. This is also true for kramdown which basically uses
  just this syntax.

  So, how do we make the current syntax shorter?

  *IALs*: They only use the above mentioned start and end tags and
  everything between is used as content. Therefore IALs can't be made
  shorter. The only thing that one could remove is the leading colon
  (see below). So the syntax will stay the same:

      {: #id .cls key="val"}

  *ALDs*: Nearly the same as IALs except that we could also potentially
  drop the colon after the ALD name. However, I think having the colon
  there is really useful to make it clear that this is a *definition*.
  So I don't think that we can make this any shorter. So the syntax
  will stay the same:

      {:ald: #id .cls key="val"}

  *Extensions*: We need to be able to differentiate between extensions
  that have a body and those that don't. As written above a shorthand
  closing tag would also be nice. How about the following (adapted from
  Shawn's proposal) - only using the inline syntax, the block syntax
  will be the same except that the start/end tags have to appear on a
  separate line:

  Extension without body:

      {:options> key="val"}

  Extension with body 

      {:comment}some text here{:comment}
      {:comment .id key="val"}some text here{:}
      {:nomarkdown}this is *not* marked up{:}

  The differences to the current syntax are:

  * Extension names don't need to start with a colon since the missing
    `:` after the extension name separates them from an ALD.
  * The trailing `>` character signifies that the extension does not
    use a body. Iff we don't want to support custom extensions, then
    there is no need for the additional `>` character to distinguish
    extensions with and without a body.
  * The closing tag is either `{:NAME}` or the shorthand `{:}`.

  Note: This new syntax also does not allow nesting of tags! However,
  since most people will use the shorthand closing tag, we could
  probably changed the end tag syntax to `{:/NAME}` (as proposed by
  Shawn). This would allow support for proper nesting.

  What do you think about this proposal? Is this a better solution than
  the current one? Could the syntax be still more concise?

ad 3)
  Nesting is currently not allowed and not useful considering the
  currently available extensions (nomarkdown, comment, options). It
  certainly would be nice to have a syntax that allows nesting.
  However, I don't think that there will be much additions to the above
  three extensions - anyone having an idea for a new and generally
  useful extension?

  One reason why there is probably no need for other extensions is that
  a library like kramdown is often used in conjunction with a framework
  that provides a syntax for extension. So there is really no need for
  allowing general extension within kramdown.

  Regarding the issue with nesting: Has anyone used Atlassian
  Confluence? Their markup language supports extensions but also
  without support for nesting tags - as far as I know - and with a very
  similar syntax.


Removing the leading colon/making it optional?
----------------------------------------------

I said in another mail that I don't want to remove the leading colon in
IALs/ALDs/extension because it makes it easy to remove the special
kramdown tags to get more valid Markdown text. I was thinking about
this and how often braces are used in normal text... If they are rarely
used, we could probably remove the leading colon and get a more concise
syntax - what do you think about this?

Maruku currently only needs the leading colon with ALDs but not with
IALs where it is optional. Iff we remove the leading colon, we would
make the syntax incompatible with Marukus...


Summary
=======

I would like to introduce the following changes:

* No syntax support for custom extensions. We keep the current
  extensions 'comment', 'nomarkdown' and 'options'. This also means
  that the extension syntax gets simplified (as stated above).

  If one really wants to use custom extensions, I imagine two ways:
  
  * Using a framework that does exactly this
  * Using special XML tags like `<my:ext>`. Since this situation is
    handled by the HTML parser, nesting of tags will work fine. One
    only needs to adapt the HTML converter to treat the tag `my:ext`
    specially.

* No support for nesting the available extension since it does not make
  sense and makes parsing the extensions unnecessarily hard

* Update the syntax for extensions as proposed above, keeping the
  leading colon.

Best regards,
  Thomas