Metadata syntax (was Universal syntax for Markdown)

[Fletcher T. Penney]

I wonder how often multi-paragraph metadata comes up in real world use?  Something like an abstract, IMO, shouldn't be metadata - it should be part of the document.  How to *display* that section graphically (e.g. smaller font?, narrower width, etc.) is a problem for CSS/LaTeX/ODF/whatever - *not* for Markdown itself.

I published a book via Lulu (a friend's PhD thesis) using MMD - it had an abstract, dedication, acknowledgements, preface, ToC, lists of figures, etc.  Each of which was formatted appropriately, without using metadata for any of it.  I customized an XSLT to generate the LaTeX I desired, and the result was fantastic.

The only problem I have run into with MMD's metadata is that it would be nice to support markup inside some fields but not all, and that has rarely been a problem for me.  This was easily remedied in MMD 2, but trickier in MMD 3.


I think the best shot at consensus is a basic syntax for general metadata (obviously I'm partial to MMD ;) that covers 90% of what people do.  Then a more complicated shared syntax for those variants that want to support the "kitchen sink" approach to metadata.


Not to repeat myself, but I again think we're approaching this from the wrong end.  If there's going to be a consensus, I think it's going to have to start with a shared philosophy for the standards.  Each variant may end up with it's own philosophy outside of that, but there has to be a common vision for the purpose of the standard.  

Until that happens, I don't think we'll get anywhere trying to sort out specific implementations for specific features - we don't have a shared understanding of the problem we're trying to solve.


F-


On Sep 19, 2011, at 11:12 AM, John MacFarlane wrote:


> +++ David Chambers [Sep 18 11 15:08 ]:

>>   If we want to avoid defining our

>>   own serialization format, we have two options: we can adopt an existing

>>   format (such as JSON or YAML), or we can hand off the responsibility to

>>   application developers.

> 

> Yes, I agree, and I certainly agree that we shouldn't go down the path

> of reinventing YAML. My proposal was to use lua as a data description

> language, as it is more texty than json, less quirky than YAML, and

> more flexible than either.  But I don't really expect to get consensus

> on that.

> 

> It seems to me that there are three levels at which we might hope

> to achieve consensus about metadata in markdown:

> 

> 1.  Agreement about which bits of the document are metadata, so

>    these won't be processed as part of the document's text.

> 

> 2.  Agreement about a key-value format, so that all implementations

>    can extract metadata into key/value pairs, with literal string

>    values, in the same way.

> 

> 3.  Agreement about how the values are to be parsed into structured

>    data, which bits are to be parsed as markdown, etc.

> 

> Consensus on 1 would be useful, because it would prevent your metadata

> from turning into displayed garbage when processed with another markdown

> implementaiton.

> 

> My own proposal on 1 was to put metadata inside specially marked HTML

> comments.  An advantage is that there is *already* agreement among

> implementations not to make this part of the displayed document, so

> no agreement is needed. In effect, my proposal already achieves

> consensus on 1.

> 

> Another possibility would be to put metadata inside '---' and '---'.

> This would solve two problems with MMD metadata:  it would allow it

> to occur anywhere in the document, and it would avoid unwanted results

> when you happen to have a colon in the first line of your text.

> 

> As for 2, a minimal modification from MMD style metadata would be

> to allow blank lines in fields, by requiring continuation lines

> to be indented four spaces.

> 

> ---

> field1:  Value one.

>    Continued here.

> 

>    Another paragraph.

> 

> field2:  Next field.

> ---

> 

> This would work best if we had something like the '---' '---'

> delimiters, since otherwise you have even more opportunities for

> unwanted captures (a blank line doesn't end metadata).

> 

> John

> 

> _______________________________________________

> Markdown-Discuss mailing list

> Markdown-Discuss at six.pairlist.net

> http://six.pairlist.net/mailman/listinfo/markdown-discuss


--  
Fletcher T. Penney
fletcher at fletcherpenney.net