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

Shawn Van Ittersum svicalifornia at gmail.com
Tue Apr 20 04:31:20 EDT 2010

On Tue, 20 Apr 2010 10:17:06 +0200, Thomas Leitner wrote:
>> 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).
> I don't think that the equal sign would be a good choice. I.e., while
> reading your above example one can easily think that `ref` has the
> value `.class1`. I also don't want to add optional alternate syntax if
> there is no good reason for it - convenience is too little. 

Both good points.  The Maruku syntax is fine.

> Also, for consistency I don't want to omit the leading colon, even in
> extensions. And I think that the ampersand is too "blocky", ie. the
> beginning of the extension name is hard to read. The exclamation mark
> would be a better choice in this regard I think.

OK.  Works for me.

>> 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
> I think that this is not the way to go. You are mixing two things here:
> a markup language that is used for writing probably large amounts of
> text and which supports a certain syntax for marking up some parts of
> the text. And a template processor which is used to execute arbitrary
> code.
> kramdown is a markup language and not a template processor. Its syntax
> is used for semantically marking up parts of the text as paragraph,
> block quotes, emphasis, link and so on. This has and should have nothing
> to do with executing arbitrary code. While implementing kramdown I
> thought that this would be good idea and therefore added support for
> it, even using it on the kramdown homepage... However, my opinion on
> that changed.
> The current "extensions" are useful in kramdown as a markup language
> since often one wants to omit draft text or one's notes from the output
> (comment) or work around an edge case where kramdown does not work
> correctly (nomarkdown) or wants to set options on how the kramdown
> document is converted (options).
> What you want to achieve can already be achieved in a much simpler way:
> just use ERB tags and run ERB first and the kramdown. This will do
> exactly what you want! And it is much more flexible than any solution
> within kramdown. If you don't want to be tied to a syntax that is Ruby
> specific, you can use another template processor like [moustache] which
> is language agnostic.

Well, OK.  Kind of a disappointment, but I can live with it.  And you're right, it seems like there's no need to rebuild an ERB-style template engine in kramdown, when there's already ERB.  I'll have to modify the kramdown-wiki I've made to process ERB before kramdown.  No big deal.

>    Therefore I think that extensions in kramdown are really not that
>             useful and I would like to remove them!

For all that I've contributed on this matter of extensions syntax, I've never actually used them yet, so I don't even know if I would miss them.  But it seems like other have and might.

> As for the syntax: In the case of not having custom extensions, it can
> be simplied to something like the following (same for block and span
> extensions):
>   {:comment}some comment{:/comment}      # verbose form
>   {:comment}some comment{:/}             # short form
>   {:options key="val" /}                 # no-body form
> In this case we also don't need an extra differentiator like `!` at the
> beginning of a extension name since the names are "well known". Also
> note that the short form would need to have the leading colon as well!

So you're suggesting that the extension names be "reserved words," not available as ALD reference names.  I'm cool with that.


More information about the kramdown-users mailing list