Metadata syntax (was Universal syntax for Markdown)

[John MacFarlane]

+++ Tao Klerks [Sep 20 11 03:15 ]:

>    I realize I'm following up on the least-important aspect of this

>    conversation, but I do wonder: what are genuine use cases where

>    meta-data really does contain structured/formattable content that

>    should not be considered part of the document content? It doesn't look

>    like the abstract is really a valid case.


I think that the abstract is a fine case. Although one *could* handle
it the way you suggest, by having the metadata specify a section
of the document to use as the abstract, I don't see the advantage of
that. It is natural distinguish between the body text, which is *always* part
of the produced document, whether a fragment or a standalone document is being
produced, and regardless of the format or template used, and the metadata,
which sometimes appear in the produced document, depending on one's purposes,
and which appear differently in different formats. Once you make this
distinction, the abstract clearly falls on the side of the metadata.

Other cases:

* bibliographic data for the document itself, which you might want
  to print in some presentations but not others
* revision history
* tags
* bibliography entries used in the document
* settings for things like default stylesheets

On the last item:  pandoc includes a powerful citation formatting
system, citeproc.  So you can use plain text citations in your
document, like this [@smith99, p. 30; @barney04], and pandoc will
format them according to a style sheet you select and include
a bibliography (if the style sheet calls for that). This is a huge
convenience, as you can write the document once, and change the
citation style (even from author-date to footnotes) by selecting
a different CSL stylesheet on the command line.

Currently you need to specify the bibliography database on the
command line as well (it can be bibtex, endnote, or any number
of other formats).  Ideally, though, the document itself should
specify where its bibliographical entries are coming from.
This could just be a file path, but if you want the document to
be truly portable, it would be nice to be able to include the structured
bibliography entries themselves in metadata at the end of the document.
This could be done easily with a data description language as
powerful as lua/yaml/json.

John