<html><head></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div>On Sep 18, 2011, at 10:47 AM, John MacFarlane wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><span class="Apple-style-span" style="border-collapse: separate; font-family: 'Lucida Grande'; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; ">* There's no provision for structured data (e.g. key/value<br>&nbsp;tables or lists), or for boolean or numerical fields.</span></blockquote><div><div><br></div><div>I'm not convinced that Markdown should have any say as to which data structure a particular value should be transformed into.</div><div><br></div><div>These are the things I believe Markdown certainly should define:</div><div><ul><li>delimiters for metadata blocks (whitespace or otherwise)</li><li>syntax for key–value pairs</li><li>valid keys</li><li>valid values</li></ul></div><div>Perhaps Markdown's responsibilities should be limited to the following:</div><div><ul><li>ensuring that metadata are omitted from the HTML output</li><li>storing the key–value pairs (as strings) in a dictionary-like object</li></ul></div><div>The reason I lean towards this approach is that the alternative (defining syntax for lists, numbers, etc.) would impose extra syntax in common cases. Take the following, for example:</div><div><br></div><div><span class="Apple-style-span" style="font-family: Times; "><pre style="word-wrap: break-word; white-space: pre-wrap; ">date: Sunday, 22 May 2011
time: 6:30pm
zone: America/Los_Angeles
tags: JavaScript, regex, regular expressions</pre></span><div><br></div></div><div>To a human reader, "tags" is clearly a list. How, though, would a parser know that "tags" is a list but "date"—which also contains a comma—is not? Resolving this ambiguity would require that the tags be wrapped in square brackets (or the addition of some other syntax):</div><div><br></div><div><span class="Apple-style-span" style="font-family: Times; "><pre style="word-wrap: break-word; white-space: pre-wrap; ">date: Sunday, 22 May 2011
time: 6:30pm
zone: America/Los_Angeles
tags: [JavaScript, regex, regular expressions]</pre></span><div><br></div></div><div>What if list items are allowed to contain commas? Perhaps an item may be quoted to resolve this ambiguity. What happens, then, if one wishes to include a quoted item:</div><div><br></div><div><span class="Apple-style-span" style="font-family: Times; "><pre style="word-wrap: break-word; white-space: pre-wrap; ">tags: [foo, bar, "baz!"]</pre></span><div><br></div></div><div>If quotation marks are optional, would this necessitate wrapping "baz!" in an extra pair?</div><div><br></div><div>These are certainly edge cases, but as we've agreed defining correct behaviour in such cases is important. 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.</div><div><br></div><div>I favour the latter, because serialization formats, by necessity, contain quite a bit of punctuation. Transforming strings from a metadata dictionary into appropriate values is something with which I have first-hand experience.&nbsp;<a href="http://mango.io/about/">Mango</a>&nbsp;provides a&nbsp;<a href="http://mango.io/docs/settings/#meta-lists">META_LISTS</a>&nbsp;setting which determines which keys' (string) values should be transformed in lists. Sure, this required a bit of work on my part, but the end result is pleasing (no extra punctuation in my Markdown files).</div><div><br></div><div>Won't this lead to a situation where one application cannot correctly process another application's metadata? Yes. If we're unwilling to accept this I fear we'll end up reinventing YAML. ;)</div><div><br></div><div>David</div><div><br></div><div><br></div><div>On Sep 18, 2011, at 11:07 AM, Fletcher T. Penney wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><div><br>On Sep 18, 2011, at 1:47 PM, John MacFarlane wrote:<br>&lt;snipped&gt;<br><br><blockquote type="cite">To my mind, multimarkdown comments just aren't flexible enough:<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">* There's no way to have multiline metadata fields that contain<br></blockquote><blockquote type="cite"> blank lines, e.g. an abstract with two paragraphs.<br></blockquote><br>True - but in MMD an abstract would be included in the document with a separate header, not as metadata. &nbsp;But you're correct that blank lines are not allowed. &nbsp;I've never needed them, but they aren't allowed.<br><br><blockquote type="cite">* There's no provision for structured data (e.g. key/value<br></blockquote><blockquote type="cite"> tables or lists), or for boolean or numerical fields.<br></blockquote><br>True. &nbsp;I've never needed them, and have never had them requested. &nbsp;But there is no provision for that.<br><br><blockquote type="cite">* Metadata fields are interpreted as raw strings, not markdown.<br></blockquote><blockquote type="cite"> That's sometimes what you want, but not always. &nbsp;Titles<br></blockquote><blockquote type="cite"> often contain emphasis and other formatting, for example,<br></blockquote><blockquote type="cite"> and sometimes even footnotes (for acknowledgements). &nbsp;If<br></blockquote><blockquote type="cite"> these are just going into an html meta field, it doesn't much<br></blockquote><blockquote type="cite"> matter, but if you're using the metadata fields in templates,<br></blockquote><blockquote type="cite"> it does. &nbsp;(And sure, you could always run a raw string through<br></blockquote><blockquote type="cite"> your markdown processor again, before passing it to the template engine,<br></blockquote><blockquote type="cite"> but that creates problems for things like reference links and<br></blockquote><blockquote type="cite"> footnotes.)<br></blockquote><br>This is a slight difference in behavior from MMD 2. &nbsp;I'm considering approaches to allow processing the contents of the metadata, as this can be an issue occasionally.<br><br><blockquote type="cite">Another major problem, in my view, is that if a document starts<br></blockquote><blockquote type="cite">with a phrase followed by a colon, it gets swallowed into metadata:<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite"> &nbsp;&nbsp;% multimarkdown<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;To be or not to be: that is the question.<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;^D<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&lt;?xml version="1.0" encoding="UTF-8" standalone="yes" ?&gt;<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&lt;!DOCTYPE html&gt;<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&lt;html xmlns="<a href="http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"&gt;<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&lt;head&gt;<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;meta name="tobeornottobe" content="that is the question."/&gt;<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&lt;/head&gt;<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&lt;body&gt;<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&lt;/body&gt;<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&lt;/html&gt;<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">That's not what most authors would expect!<br></blockquote><br>This is true. &nbsp;But a blank line at the top of the document solves the problem. &nbsp;And it doesn't match a URL on the first line as metadata, so I'm not sure how often this really happens in real life.<br><br><blockquote type="cite">For this reason, I would favor something more like reStructuredText<br></blockquote><blockquote type="cite">field lists, which marks the fields explicitly as fields:<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite"> &nbsp;&nbsp;:title: &nbsp;&nbsp;&nbsp;Here is the title.<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;:author: &nbsp;&nbsp;John<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;:abstract: The abstract here.<br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&nbsp;&nbsp;It can span multiple lines.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite"> &nbsp;&nbsp;&nbsp;&nbsp;As long as the indentation is maintained.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite"> &nbsp;&nbsp;This is not part of the metadata.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">This is slightly less texty because of the leading colon, but less likely to<br></blockquote><blockquote type="cite">capture regular text.<br></blockquote><br>This becomes a matter of values. &nbsp;To me, the ugliness of this approach outweighs the virtually negligible chance that I will have a document triggering metadata when I don't mean it. &nbsp;But it's certainly not as bad as some other alternatives. &nbsp;If it was proposed as a standard, I would try to vote against it, but would not necessarily "boycott" it within MultiMarkdown.<br><br><br><blockquote type="cite">Also, because this is recognizable as metadata wherever it occurs<br></blockquote><blockquote type="cite">in the document, one could then drop the requirement that the<br></blockquote><blockquote type="cite">metadata occur at the top of the document, which I think is<br></blockquote><blockquote type="cite">undesirable. &nbsp;When there's lots of metadata, it's nicer to put<br></blockquote><blockquote type="cite">it at the bottom (or at least to put some of it at the bottom),<br></blockquote><blockquote type="cite">so it doesn't interfere with reading the article. lunamark's<br></blockquote><blockquote type="cite">lua_metadata allows that, by the way -- so you don't have to<br></blockquote><blockquote type="cite">start the document with something that doesn't look like plain<br></blockquote><blockquote type="cite">text.<br></blockquote><br>I don't view metadata as necessarily belonging at the bottom, but the flexibility is a bonus.<br><br><blockquote type="cite">One nice point that David Sanson made is that one could combine<br></blockquote><blockquote type="cite">a simple, "texty" metadata format for common things like titles<br></blockquote><blockquote type="cite">and authors with a flexible, more "cody" format for everything else.<br></blockquote><blockquote type="cite">One should keep this in mind in thining about how to balance flexibility<br></blockquote><blockquote type="cite">vs. textiness.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">John<br></blockquote><br>My vote would be for something more akin to MMD's metadata as the first option, and then for something more robust as the optional variant for those who need it. &nbsp;The "cody" alternative could allow lists, key value pairs, multiple paragraphs, etc. &nbsp;I suspect it would be used by only a minority of users, but that the minority is going to be over-represented on this discussion list.<br><br><br>F-<br><br>-- &nbsp;<br>Fletcher T. Penney<br><a href="mailto:fletcher@fletcherpenney.net">fletcher@fletcherpenney.net</a><br><br><br><br><br>_______________________________________________<br>Markdown-Discuss mailing list<br>Markdown-Discuss@six.pairlist.net<br>http://six.pairlist.net/mailman/listinfo/markdown-discuss<br></div></blockquote></div><br></body></html>