Universal syntax for Markdown

[David Chambers]

First let me say that this thread has me excited. There's a great deal of constructive discussion, and a surprising number of "I agree" replies.

I'll add my two cents on the particulars that have been discussed herein.

Metadata

Just about every Markdown document I create includes metadata (for date, time, and time zone, and sometimes tags). I couldn't live without it, but as a user it doesn't matter to me whether these data are processed by the Markdown library itself or, as Waylan suggested, by "a separate […] library (like YAML) which reads and removes the metadata".

I think Alan's suggestion that Markdown should define syntax for a metadata section (while ignoring the contents of such sections) is an excellent one.

Definition lists

The fact that including more than one definition for a given term is an uncommon requirement should not preclude such use cases from being accommodated. Rather than thinking in terms of the "rendered" content (be it HTML, PDF, or some other format) we should first think in terms of what our content means and how best to express that meaning in a structured fashion.

Definition lists are a good case in point. What is a definition? Text that explains the meaning of or describes some thing. There therefore exists some relationship between the definition and the thing it defines. Also, there may be several ways to describe one thing. What is the relationship between various definitions for a particular thing? Are they equally important? Are they sequential? Can they be grouped in some way? Can one description apply to more than one thing?

Only once we have considered the meaning and structure of our content in the abstract should we consider how best to express it in Markdown and how best to translate it to each of the various publication formats.

Should changing from ordered to bulleted list markers start a new list?

Yes.

Table syntax

As has been stated, there's more diversity in the table syntax supported by the various extensions than exists for most other language additions. This indicates that tables will likely be much harder to "solve" than definition lists or footnotes. That's fine. This needn't all happen at once. Here's how I imagine the transition to "Markdown 2" might work:
Several people write documents (for lack of a better term). Each of these would define how a particular group of edge cases should be handled, or would propose syntax definitions for a language addition that exists as a popular extension. These brave souls would analyze differences between the various implementations and would present the pros and cons of each (in terms of readability, writeability, and implementation complexity) and may follow this with an actual proposal.
These documents are discussed at length on this list, and amendments are made.
The two or three least contentious proposals are further hammered out and eventually — say, 18 to 36 months from now — become part of the "Markdown 2" specification.
Library maintainers decide how best to react to these additions. Some will decide to remain a pure Markdown (1) library, which is fine. Others will decide to maintain full backwards compatibility with Markdown (1) but will update the affected extensions to accept the standardized syntax (exclusively, or in addition to the existing syntaxes). As Alan has suggested, new libraries may emerge which fully support the additions made in "Markdown 2".
Repeat steps 1–4 indefinitely.
The above is not much different from what happens currently. Furthermore, one can see how existing libraries could adopt "Markdown 2" without breaking backwards compatibility in most cases. Features which currently only exist as extensions could continue to exist as extensions in many implementations. As for edge cases which are clarified in "Markdown 2", well, they are by definition unreliable in Markdown as it exists today.

David


On Aug 15, 2011, at 6:51 PM, Alan J. Hogan wrote:


> On document meta:

> 

> On Aug 13, 2011, at 7:14 PM, Waylan Limberg <waylan at gmail.com> wrote:

> 

>> Interestingly, after having this feature for a few years, I would

>> instead prefer a separate library (like say YAML) which  reads and

>> removes the metadata before passing the document on to markdown. In

>> fact, the metadata could even alter some of the arguments passed to

>> markdown, or perhaps skip calling markdown at all (basically like

>> Jekyll - used by Github Pages). To me this is much more flexible and

>> doesn't require markdown to define a metadata syntax at all. Just let

>> YAML (or whatever spec is chosen) determine the syntax and we

>> automatically get the benefits of that spec's well developed data

>> structure.

> 

> Hyde (Jekyll in Python) does this too and it really feels nice. The ability to embed complex arbitrary data in some documents' metadata was very handy (when used in conjunction with the theme and other non-markdown languages).

> 

> Quoth Michel:

> 

>> I'd certainly not put metadata in a Markdown standard. I never felt like this feature belongs in Markdown at all, and I think Waylan has just put the decisive argument: what if in your metadata you want to specify a text format other than Markdown for the text body? It won't work. Localization of "standard" metadata keys is also an issue.

>> 

>> I know it's tempting to have one tool to do it all, but you can still built that do-it-all tool by calling Markdown for parsing the body of the document as needed. And that tool will have more power because it's not limited to Markdown.

> 

> 

> Hard to argue against that.

> 

> And yet in some cases it may be useful to define, in a Markdown-successor standard, the area in which such metadata may exist.

> 

> For instance, when I used Hyde, the format was always:

> 

> ---

> metadata: here

> more: meta

> ---

> 

> That is, the first line was three hyphens, then you had your metadata, then a line with three hyphens.

> 

> Now consider Simplenote (http://simple-note.appspot.com/). They have a feature called "live publishing" where your note becomes accessible, in a read-only manner, as a web page. With Markdown mode on, the published page is first run through Waylan's library.  And because your Simplenote can sync with any number of things and programs - from Scrivener and various third-party apps to your Dropbox or whatever else - it's possible you might want metadata in your Markdown note. Currently Simplenote doesn't do anything special with it, and the last line of your metadata will probably become an H2 when published. Yuck. But if the Markdown successor recognized that top area as being for metadata, then Simplenote could simply discard it (and pull out a `title` attribute if they felt ambitious). 

> 

> Or consider an ebook with metadata in each chapter's file, with those files also being published as webpages -- same thing, it would be great if the website automatically knew that the first bit of the file between the three-hyphen lines was metadata, OK to ignore or attempt to use as desired/instructed.

> 

> YAML is a fairly mature format and well-suited for document meta; whether that would be the preferred meta syntax, if any, is another whole discussion.  I just wanted to point out the benefits of a recognized approach to inserting metadata into documents.

> 

> Alan Hogan

> _______________________________________________

> Markdown-Discuss mailing list

> Markdown-Discuss at six.pairlist.net

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


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20110815/08e7a0d7/attachment.html>