Metadata syntax (was Universal syntax for Markdown)

[John MacFarlane]

I can think of many reasons for putting an abstract into metadata.
The treatment of the abstract (like that of author and title) varies
quite a bit depending on the output format.  In LaTeX, it goes in
a special environment; in HTML, it may go in a special DIV; for some
purposes, you may want to omit it entirely and just store it for
bibliographic purposes.  If the markdown processor pulls it out
as metadata, then a templating system can put it where it needs to
go in the final document.

Now of course, you can always postprocess the output of your markdown
processor, locate the abstract, and mess around with the result. But that's
uglier and much harder for end users than the approach above, which lunamark
takes. Users are more likely to be able to modify a default template
than write their own XSLT transformations.

John

+++ Fletcher T. Penney [Sep 19 11 14:34 ]:

> 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

> 

> 

> 

> 

> _______________________________________________

> Markdown-Discuss mailing list

> Markdown-Discuss at six.pairlist.net

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