Re: Metadata syntax (was Universal syntax for Markdown)
On Tue, Sep 20, 2011 at 1:30 AM, David Sanson dsan...@gmail.com wrote: On Sep 19, 2011, at 4:02 PM, Rob McBroom mailingli...@skurfer.com wrote: Those sound like reasons for the metadata to *identify* the abstract, but I see no requirement that it must be literally *stored* there. If the metadata contained something like abstract: relative/path/to/abstract.mdown That would allow for all of the above scenarios while keeping the metadata syntax/section simple. But that makes the document far less portable, and I'm liable to lose the extra file at some point. I'd much rather have it be self-contained---not, of course, if that means that the document suddenly becomes weirdly ugly and complicated, but I don't see anyone proposing a solution that makes documents weird and ugly and complicated. Given that the abstract is actually part of the content (it is generally printed as part of the document, right?) it would seem more sensible to have the meta-data refer to a section name/path within the document. We can probably assume any markdown parser is capable of identifying the content between a heading and its next same-or-higher-depth sibling. Abstract could be a default value, supporting the simplest case first example Fletcher T. Penney provided above; This way content is in the right place (in the document, and appearing where you would expect it to with a simple abstract-unaware markdown converter), english speakers just write their document, and others can provide the abstract header, without needing to know anything about parsing or serialization rules. 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. ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Metadata syntax (was Universal syntax for Markdown)
+++ 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 ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Metadata syntax (was Universal syntax for Markdown)
On Tue, Sep 20, 2011 at 9:56 AM, John MacFarlane j...@berkeley.edu wrote: 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. In that case, you're talking about metadata in the more general sense - like link definitions, footnotes, and other constructs that are currently treated as a special case in markdown. I'm all for having a special syntax for defining the abstract, as long as the author doesn't have to worry about any escaping conventions and can just write it like he/she would any other regular markdown content. 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 Point taken, most of these are good cases for supporting structured content, but not formattable/markdown content, right? 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. Absolutely - but the (possibly unattainable) ideal would be a situation where tools and experts can specify complex structured metadata, and regular joe can change his title, author, and other basic/simple values and lists, specifying values that contain apostrophes, commas and other natural punctuation, wihout blowing anything up in the process. As soon as he needs to specify/modify something that contains structure (or even something multi-line?) it seems fair that he should have to use a tool or do some research on the standard (esp. as most if not all of the structured-data use cases relate to tools already). My concern with a pure-lua/yaml/json metadata format is that it requires specialized knowledge (not related to the existing markdown standards/experience) on the part of the user for even the most trivial changes to the simplest fields - *especially* if structured/markdown content such as the abstract is placed in a metadata field! ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Metadata syntax (was Universal syntax for Markdown)
+++ Tao Klerks [Sep 20 11 10:34 ]:
On Tue, Sep 20, 2011 at 9:56 AM, John MacFarlane [1]j...@berkeley.edu
wrote:
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.
In that case, you're talking about metadata in the more general sense -
like link definitions, footnotes, and other constructs that are
currently treated as a special case in markdown. I'm all for having a
special syntax for defining the abstract, as long as the author doesn't
have to worry about any escaping conventions and can just write it like
he/she would any other regular markdown content.
Yes, absolutely. There are two ways to approach this while keeping
'abstract' a metadata field:
(1) There could be a special syntax for designating metadata fields
as markdown (or alternatively markdown could be the default, and there
could be a special syntax for designating them plain strings).
I showed in my original post how lunamark implements this:
abstract = m[[
Here's the abstract. You can put anything you want
here, including blank lines. No special escaping is
needed. It can be flush left, but I've left a small
indent because it looks nice.
* item 1
* item 2
]]
The 'm' indicates that the content is markdown. If you left it
out, you'd have a plain string.
(2) It could just be conventional that certain fields ('abstract',
'title', etc.) are interpreted as markdown.
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
Point taken, most of these are good cases for supporting structured
content, but not formattable/markdown content, right?
Right in most cases, but one might want a free-form revision history
that is just markdown, and bibliographic entries might include
abstracts etc.
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.
Absolutely - but the (possibly unattainable) ideal would be a situation
where tools and experts can specify complex structured metadata, and
regular joe can change his title, author, and other basic/simple values
and lists, specifying values that contain apostrophes, commas and other
natural punctuation, wihout blowing anything up in the process. As soon
as he needs to specify/modify something that contains structure (or
even something multi-line?) it seems fair that he should have to use a
tool or do some research on the standard (esp. as most if not all of
the structured-data use cases relate to tools already).
My concern with a pure-lua/yaml/json metadata format is that it
requires specialized knowledge (not related to the existing markdown
standards/experience) on the part of the user for even the most trivial
changes to the simplest fields - *especially* if structured/markdown
content such as the abstract is placed in a metadata field!
I understand the concern. YAML is particularly bad this way, because you
get used to not quoting or escaping things, but then your document blows up
when you have a colon in the field. I think lua is a nice compromise--more
regular and predictable, but you don't have to quote the fields as in json,
and you have a really nice multiline string syntax that eliminates the need
for escaping.[^1] But my lua-based proposal is compatible with also having a
simpler way of specifying title, author, and date -- e.g. pandoc's, or Michael
Thompson's proposal involving centering, or MMD's (though I think the Hamlet
problem is serious).
[^1]: What if your abstract contains `]]`, you might ask?
re: Metadata syntax (was Universal syntax for Markdown)
sherwood said: Well if your dogs are like mine, they will eat practically anything. Lately in addition to their kibble they've been catching pocket gophers and mice. A border collie is much less lovable with 'mouse breath' gophers and mice taste _great_ to a dog -- a dietary delicacy for many millennia now... it's your kibble they don't really care for. its redeeming feature is that it's so _easy_. but i bet there are several brands of kibble which your dogs still turn up their noses at. as the ad man replied, when asked why his costly campaign hadn't moved more units of the client's dogfood: dogs hate its taste. people are the same way. they'll eat a _lot_ of things, including some that you consider to taste _dreadful_ (e.g., ms-word), but that does not mean that they will eat _anything_. *** anyway, this conversation sounds confused... aside from questions of philosophy, it seems to me that there is confusion about just what sort of metadata we're all talking about, and how it's used, by whom, for what purposes... and so on and so forth, and hmm baby swing. but maybe i'm the only one confused... :+) you all seem like bright competent fellows, so i'm sure you'll get it all worked out, so i'm gonna go back to my sandbox and play. have a nice day... -bowerbird___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
