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

Shawn Van Ittersum svicalifornia at gmail.com
Tue Apr 20 00:24:26 EDT 2010


Sorry it has taken me so long to reply.  A lot going on lately! :)

Eric pretty well summarized my feelings on the ">" syntax.  To that, I'll add that because ">" is used so commonly in HTML/XML to end tags, it's very confusing to find it in the middle of a kramdown tag.  This is even more troublesome when we consider that HTML/XML/ERB will likely appear in some kramdown documents.

I apologize for not seeing the syntax on ALDs.  I hadn't used them yet, so I went to check that out.  I also went to the Maruku docs on attribute lists (which are here: http://maruku.rubyforge.org/proposal.html).  I see now that my proposed syntax for extensions didn't differentiate them clearly enough from ALDs.

So here's a new set of proposals:

1. Personally, I wish the Maruku team had adopted the equal sign (=) to assign attributes to references in ALDs:

  {:ref=.class1 #id ... }

I'd like to request that as an optional alternate syntax to the Maruku convention, as it is so much clearer than adding an extra colon.  However, we should still support the Maruku convention, so we'll still need to make the extension syntax distinct (see next point).

2. Amending my proposal for extensions, I had also considered with the idea of a standard prefix character on extension directives.  In this case, we don't even need the colon, since the prefix serves as a signal that we are invoking a kramdown extension.  Since invoking an extension is something like calling a subroutine, it seems appropriate (and also looks pretty good, I think) to borrow the ampersand from Perl:

  {&extension arg1 arg2 ... }

Other alternatives would include:

  {@extension arg1 arg2 ... }
  {!extension arg1 arg2 ... }
  {%extension arg1 arg2 ... }

Then we make a rule that ALD reference names can't start with such a prefix character, and there we have the distinction between ALDs and extensions.

3. For indicating closing tags and tags with no body, I continue to advocate the use of the slash as in HTML/XML:

  {&nomarkdown}Content{/nomarkdown}
  {&options ... /}
  {&shorthand}Content{/}

(Note that the ampersand is not necessary on the closing tag.)

Adopting the slash takes advantage of decades of HTML convention and familiarity, without actually using the angle brackets <...> that will get confused with ERB and HTML tags that should be left untouched by kramdown.

4. It would be incredibly cool if kramdown would support custom extensions in the future.  I'm working on a software documentation project now in kramdown, where I will often need to link to a separate system that contains database schema definitions.  I would love to define a ruby method and be able to call it in the middle of my kramdown documents:

  User data is stored in the {&db_schema_link users /} table.

with a corresponding Ruby method (note the return value of the custom extension method is in kramdown syntax, to be evaluated by kramdown):

  def db_schema_link(table_name)
	"[#{table_name}](http://docs.project.com/schema/#{table_name}.html)"
  end

The method would be defined in the Ruby context in which the kramdown document was executed.  There could also be a new standard extensions to define inline custom extensions, or include a Ruby file to be evaluated in the kramdown context and define the custom extensions:

  {&ruby}
	def my_extension ...
    
    end
  {/}
  {&require my_extensions.rb /}

5. With the added support for custom extensions, we will have a clear use case for nested extension calls:

  {&comment}
	This block contains a {&custom_extension}invocation{/}
    but we can still quickly comment it by surrounding it with a comment tag.
  {/}

  {&one_custom_extension} might also take {&another_extension}'s return value{/} as part of its input.{/}


In summary, I think we should adopt slashes as in HTML, support tag nesting, and use this syntax:

IAL  {: ...}
ALD  {:ref:  ...}  or  {:ref = ...}
Ext  {&extension}{/extension}  or  {&extension /}

Shawn

On Mon, 19 Apr 2010 15:37:28 -0400, Eric Sunshine wrote:
> Hi Thomas,
> 
> I was going to wait until Shawn posted since he probably has more 
> significant comments to make, whereas mine are fairly minor. However, 
> it seems best to write down my thoughts down before forgetting them 
> entirely.
> 
> On 4/16/2010 5:23 AM, Thomas Leitner wrote:
>>    So, how do we make the current syntax shorter?
>>    *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"}
> 
> The mnemonic significance to the ">" is not entirely obvious other 
> than ">" being a closing symbol of XML/HTML tokens. My personal 
> aesthetic reaction also is that it also looks rather ugly.  Some 
> other possibilities, including mnemonic hints:
> 
>     {:options/ key="val"}  hint: XML/HTML
>     {:options$ key="val"}  hint: regular expressions
>     {:options. key="val"}  hint: written language
>     {:options! key="val"}  hint: emphatic "that's all!"
>     {:/options key="val"}  hint: XML/HTML
> 
> The last example could potentially be confused as a closing tag (if 
> you go that route), thus probably would not be wise. Shawn's proposal 
> of "{:options ... /}" also had merit in the spirit of XML/HTML, 
> although I understand that you prefer to have such tokens at the 
> start rather than end of the sequence. (Perhaps you could clarify the 
> reasoning behind this.) If tokens at the end of sequence were 
> allowed, then another possibility would be:
> 
>     {:options key="val":}  hint: symmetry of {: and :}
> 
>> 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?
> 
> The conservative in me feels uncomfortable with the idea of removing 
> or making optional the leading colon. The sequence "{:" is 
> sufficiently uncommon in text that I don't worry about conflicts, but 
> opening with a bare "{" seems too dangerous.
> 
>> 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...
> 
> Is it documented anywhere that the leading colon is optional in 
> Maruku IALs? I never knew this until you mentioned it and I tested it 
> for myself. Every example on the Maruku site includes the colon. In 
> any event, unnecessarily breaking compatibility with Maruku (or other 
> Markdown processors) seems like a bad idea.
> 
> -- ES
> _______________________________________________
> kramdown-users mailing list
> kramdown-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/kramdown-users


More information about the kramdown-users mailing list