Markdown Discuss - Dec 2006 - Revised 2005 proposal for meta-data

Hello to all!

This is the revised 2005 proposal for meta-data, much more in detail:

http://maruku.rubyforge.org/proposal.md
http://maruku.rubyforge.org/proposal.html
http://maruku.rubyforge.org/proposal.pdf

I wait for comments.

At the end of the document, there are some open issues.
And I need a regexp wizard to look over the "grammar" section.

Cheers,
-- 
Andrea Censi
      "Life is too important to be taken seriously" (Oscar Wilde)
Web: http://www.dis.uniroma1.it/~censi

Le 2006-12-29 ? 7:53, Andrea Censi a ?crit :
> This is the revised 2005 proposal for meta-data, much more in detail:
>
> http://maruku.rubyforge.org/proposal.md
> http://maruku.rubyforge.org/proposal.html
> http://maruku.rubyforge.org/proposal.pdf
>
> I wait for comments.

     {#myid .class1 .class2}
     {id=myid class=class1 class=class2}
     {id=myid class="class1 class2"}

In my current implementation, the first and the last one are  
equivalent, but not the one in the middle: the second class will  
override the first one. I think it's more coherent to reserve the  
magic to the ".class" syntax. And overriding may also be a useful  
feature in some circumstances where you have a remotely-defined class  
you want to replace completly:

     ## Header ## {boo class="override"}

     {boo}: .boo style=color:green;font-weight:bold

  - - -

"tags"

Why not "attribute definitions" and "attribute references"
in the
same spirit as link definitions and link references? "Tag" makes me  
think of HTML tags.

  - - -

"An unquoted value must not start with a double quote, and may  
contain everything except whitespace"

You need an exception for the closing brace when the attribute is  
defined inline, and I would allow attribute values to be enclosed in  
single quotes too, just like HTML and XML permits it.

  - - -

"Identifiers must begin with a letter ([A-Za-z]) and may be followed  
by any number of letters, digits ([0-9]), hyphens (-), underscores  
(_), colons (:), and periods (.)."

This seems too restrictive. First, id and class in HTML and XML both  
allow much more Unicode characters, and second: what should happen  
when someone introduce an invalid character somewhere? Do we pass it  
unmodified, try to correct it, or skip it completely? I'd go with the  
former, except for the cases where it would destroy the markup like  
having an attribute name with `>` or `=`.

  - - -

"Question: should we allow whitespace at the sides of = in key/value  
pairs?"

I don't think so, not if we're mixing them with attribute references  
and magic shortcuts. I don't think this would be very readable:

     [link][1]{.class hreflang = fr ref}

     {ref}: lang = en .class

  - - -

"Question: should : be a synonym for = in attributes list."

While it would certainly be nice, I think it's a better idea to have  
an HTML-like syntax to define HTML attributes. Beside, it's not very  
clear what will happen when you have a space after the colon. Compare  
this:

     [link][1]{.class hreflang: fr ref}

     {ref}: lang: en .class

with this:

     [link][1]{.class hreflang=fr ref}

     {ref}: lang=en .class

I think the key/value association is clearer in the second example.


  - - -

Other considerations: allowing arbitrary attribute values on span  
elements may pose problem to the current parsers. For instance, this  
link:

     [test][1]{title="`coco`"}

is hard to parse correctly, because if the link reference [1] is not  
defined, the link becomes pure text and `coco` must be changed to a  
code span, while if the link is defined then `coco` is an attribute  
and must not be changed to a code span. The only way to get this  
correctly is to parse all the span expressions together, creating a  
"real" parser as some have suggested.

I think this problem is inexistent with the way block elements are  
parsed.


Michel Fortin
michel.fortin at michelf.com
http://www.michelf.com/

On 12/29/06, Andrea Censi <andrea at censi.org>
wrote:
>
> I wait for comments.

Are you wedded to the curly brackets?

The way I see it, Markdown already has a span-level metadata syntax:

    This is [a link](http://example.com "Title").

In Python it might be this function:

    def link(link_text, href, title=None):
        element="a"

        # blah blah

But it could just as easily be this one:

    def meta(text, href=None, title=None, **kwargs):
        if not "element" in kwargs:
            if href:
                element="a"
            else:
                element="span"

        # blah blah

And exist in text like so:

    This is [a link](http://example.com xml:lang="en").

    [Not a *link*...](class="not-a-link" element="blink")

Like the curly-bracket proposal, something similar was also [discussed
in 2005][1], though only in relation to reference-style links and
images.

[1]: http://six.pairlist.net/pipermail/markdown-discuss/2005-October/001578.html

I think it's more elegant, but that's obviously a personal preference.

 * * *

The footnote syntax isn't official, but it's pretty popular:

    Blah blah blah [^note_id] blah.

    [^note_id]: Note text.

That's just arbitrary metadata applied to a specific point inside a
block. It's a natural syntax to extend to other types of metadata,
indicated by their own "magic" characters:

    > Blockquote hooray! [@cite="http://example.com/"
class="ext"]

    ## Heading [.classname]

The rules regarding placement etc. could be essentially the same as
they are in the curly-bracket syntax.

I prefer it because square brackets already indicate editorial content
(i.e. a form of metadata) in plain text.

Anyway, YMMV, $0.02, etc. Happy new year!

> From: "Andrea Censi" <andrea at censi.org>
> Date: Sun, 31 Dec 2006 08:10:00 -0500
> Subject: Re: Revised 2005 proposal for meta-data
> 
> I tried to summarize:
> 
> In a paragraph:
> - MUST  be escaped: \ ` { [        (or else they trigger things)
> - MIGHT be escaped:
>   -  `+ * -` (only if ambiguous with list)
>   -  `.`     (only if ambiguous with numbered list)
>   -  `_`     (only if ambiguous with emphasis)
>   -  `!`     (only if ambiguous with image)
>   -  `#`     (only if ambiguous with header)
>   -  `(`     (only if ambiguous with link def)
>   - } ] )    (for consistency with other rules)
> 
> In a quoted value:
> - MUST  be escaped: \ ' " `
> - MIGHT be escaped:
>   -  ` {} [] () + * - !   # (for consinstency with other rules)
> 
> Inside brackets,
> - MUST  be escaped: \      and the matching bracket
> - MIGHT be escaped:
>   -  ` {} [] () + * - !  |  # (for consinstency with other rules)
> 
FWIW, you can simplify this slightly by getting rid of the "might be
escaped" list -- just decree "*any* (punctuation) character might be
escaped" (using a backslash)[^1].  Almost for free, this lets people quote
a
space ("\ " would be marked down to "&nbsp;"), as well
as quote a newline: a
backslash at the end of a line would translate naturally to
"<br/>".

This rule simpler for both markdown-users and markdown-implementers.
(Though it highlights the question of what a backslash as the last character
would mean.)

[1] Even further, you could allow non-punctuation to be escaped.  Though it
might surprise users who write a back\slash only to have markdown seem to
mysteriously erase that character.

--Ian