Re: Opinions on in-band variation signaling

[Sean Leonard]

On Nov 11, 2014, at 2:49 PM, Michel Fortin  wrote:

> Before this discussion derails on a syntax bikeshedding, I think I should 
> highlight the important part:
> 
> Sean Leonard wrote:
> 
>> Do any implementers have experience with picking the type of Markdown based 
>> on some info at the top of the Markdown content?
> 
> To my knowledge, no one is doing that. But it'd be interesting to hear about 
> it if someone is doing it.

Ok, thanks. That’s the “main thing” I wanted to know.

> As for this:
> 
>> By in-band, I mean a Markdown file with content like this:
>> 
> 
>> !pandoc
>> % This is a Title
>> % Sean Leonard
>> % November 2014
>> 
>> Blah blah *blah*.
>> <<< (fortin’s suggestion)
> 
> I suggested privately to you that using `!pandoc` would be better as a header 
> than `Content-Type: text/markdown; variant="pandoc"` if you wished people to 
> actually write something in a file. But for me this is an enclosure format 
> for Markdown (similar to how mp4 is an enclosure format for many codecs.). 
> The actual Markdown content starts after the metadata header. 

Yes, Michel is right; sorry if there was any confusion on this part.

> Also, lines prefixed by a `%` are ugly, I would never suggest such a thing.

That was not suggested by you; it is, however, pandoc title block syntax. See 
.

This raises an important issue: pandoc will only recognize its title block 
syntax if it is at the start of the file. If you put any text above it, the % 
block loses its pandoc meaning. Therefore, unless you treat the directives as 
metadata in a container/enclosure format, you’re not going to get the behavior 
that you want.

Which goes to the broader point that *any* metadata recorded in-band, even data 
that is “comment-y” such as my proposed link reference armor:

[!pandoc]: # “Ignore”
blah

is bound to cause problems with some Markdown implementation out there. There 
is no free lunch.

Sean



smime.p7s
Description: S/MIME cryptographic signature
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: Opinions on in-band variation signaling

[Aristotle Pagaltzis]

* Sean Leonard  [2014-11-12 00:50]:
> At least one commentator (Larry Masinter) specifically requested that
> the variant identifier be included in-band in the Markdown content,
> rather than as part of the metadata. I disagree with in-band signaling
> (as has been registered earlier on this list).

Both have value.

Ruby’s postulate:
The accuracy of metadata is inversely proportional to the
square of the distance between the data and the metadata.

That is to say, a value signalled in-band will be correct much more
often than one signalled via MIME/HTTP headers.

Also, in-band vs out-of-band simply address different scenarios.

An in-band signal travels with the data automatically, without any
special measures taken, whereas out-of-band metadata has a fair chance
of getting lost somewhere in transit. How is a user agent supposed to
store the variant parameter from the content-type after downloading
a Markdown file to disk?

But if you want to make decisions about the data during transit, having
to parse the payload to find the signal is prohibitively expensive. An
out-of-band signal is cheap, and is visible to a lot of infrastructure
that would never implement such specialised parsing of payloads such as
Markdown. (I mean, that is the exact same reason for having a MIME type
separate from text/plain in the first place.)

It’s nonsensical to portray this as a binary choice between two options.
Those are two separate choices and discussions.

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: Opinions on in-band variation signaling

[Michel Fortin]

Before this discussion derails on a syntax bikeshedding, I think I should 
highlight the important part:

Sean Leonard wrote:

> Do any implementers have experience with picking the type of Markdown based 
> on some info at the top of the Markdown content?

To my knowledge, no one is doing that. But it'd be interesting to hear about it 
if someone is doing it.


As for this:

> By in-band, I mean a Markdown file with content like this:
> 
 
> !pandoc
> % This is a Title
> % Sean Leonard
> % November 2014
> 
> Blah blah *blah*.
> <<< (fortin’s suggestion)

I suggested privately to you that using `!pandoc` would be better as a header 
than `Content-Type: text/markdown; variant="pandoc"` if you wished people to 
actually write something in a file. But for me this is an enclosure format for 
Markdown (similar to how mp4 is an enclosure format for many codecs.). The 
actual Markdown content starts after the metadata header. 

Also, lines prefixed by a `%` are ugly, I would never suggest such a thing.

-- 
Michel Fortin
michel.for...@michelf.ca
https://michelf.ca



smime.p7s
Description: S/MIME cryptographic signature
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: Opinions on in-band variation signaling

[mofo syne]

Oh and the proposed variant identifier (or document declaration if I
read correctly) I'm proposing is:

>>>

!CommonMark: 0.1.23-github.username.projectname
Author: Bane Liciea
Title: Why you should hire me
Date: 32-4-2002
Layout: Resume

... content blabalba ...

<<< ( 
http://talk.commonmark.org/t/the-case-for-a-commonmark-declaration-tag/584/9
)

`!CommonMark: 0.1.23-github.username.projectname` is located in the
very first line of a document and `!CommonMark:` is the magic word
along with the version identifier (optional, if missing assume latest
version).

 below the document declaration is simple key:value document metadata.
Which in archive analogy, is like the label stuck on top of microfilm
casing. So it is easier to scan and read as a batch (Keep reading
metadata after `!CommonMark:` until an empty line is detected)

Well that's my preference anyhow. No frills, just simple key:value
suggestions on what the document is and how the parser is recommend to
present it (e.g. 'layout: Resume' ).

Of course for pandoc, I would suggest that the magic word would be
`!pandoc: ` on the very first line, and simple
metadata immediately below (as I suggested in previous email).



On Wed, Nov 12, 2014 at 11:03 AM, mofo syne  wrote:
> Was thinking that generic block directives concept in
> http://talk.commonmark.org/t/block-directives could assist with this.
>

> !pandoc:
> This is a Title
> Sean Leonard
> November 2014
> <<< (compact)
>
> or if there is spaces in the metadata block. No need for %, since we
> know that it is metadata already.
>

> !pandoc:
> 
> This is a Title
> Sean Leonard
> November 2014
> 
> <<< (fenced)
>
> Good for document declaration. E.g. should we load resume.css or
> blog.css default styles.
>
> On Wed, Nov 12, 2014 at 10:47 AM, Sean Leonard  wrote:
>> Regarding the text/markdown registration:
>>
>> At least one commentator (Larry Masinter) specifically requested that the 
>> variant identifier be included in-band in the Markdown content, rather than 
>> as part of the metadata. I disagree with in-band signaling (as has been 
>> registered earlier on this list). Nevertheless, I wanted to take a straw 
>> poll and see if anyone has tried to implement in-band Markdown variation 
>> identifiers, with any success. Do any implementers have experience with 
>> picking the type of Markdown based on some info at the top of the Markdown 
>> content? Does it work—or will it never work? Or is it “bad” for particular 
>> reasons?
>>
>> By in-band, I mean a Markdown file with content like this:
>>
>
>> !pandoc
>> % This is a Title
>> % Sean Leonard
>> % November 2014
>>
>> Blah blah *blah*.
>> <<< (fortin’s suggestion)
>>
>
>> [!pandoc]: # "This is a pandoc document."
>> % This is a Title
>> % Sean Leonard
>> % November 2014
>>
>> Blah blah *blah*.
>> <<< (seantek’s suggestion)
>>
>> -Sean
>> ___
>> Markdown-Discuss mailing list
>> Markdown-Discuss@six.pairlist.net
>> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Re: Opinions on in-band variation signaling

[mofo syne]

Was thinking that generic block directives concept in
http://talk.commonmark.org/t/block-directives could assist with this.

>>>
!pandoc:
This is a Title
Sean Leonard
November 2014
<<< (compact)

or if there is spaces in the metadata block. No need for %, since we
know that it is metadata already.

>>>
!pandoc:

This is a Title
Sean Leonard
November 2014

<<< (fenced)

Good for document declaration. E.g. should we load resume.css or
blog.css default styles.

On Wed, Nov 12, 2014 at 10:47 AM, Sean Leonard  wrote:
> Regarding the text/markdown registration:
>
> At least one commentator (Larry Masinter) specifically requested that the 
> variant identifier be included in-band in the Markdown content, rather than 
> as part of the metadata. I disagree with in-band signaling (as has been 
> registered earlier on this list). Nevertheless, I wanted to take a straw poll 
> and see if anyone has tried to implement in-band Markdown variation 
> identifiers, with any success. Do any implementers have experience with 
> picking the type of Markdown based on some info at the top of the Markdown 
> content? Does it work—or will it never work? Or is it “bad” for particular 
> reasons?
>
> By in-band, I mean a Markdown file with content like this:
>

> !pandoc
> % This is a Title
> % Sean Leonard
> % November 2014
>
> Blah blah *blah*.
> <<< (fortin’s suggestion)
>

> [!pandoc]: # "This is a pandoc document."
> % This is a Title
> % Sean Leonard
> % November 2014
>
> Blah blah *blah*.
> <<< (seantek’s suggestion)
>
> -Sean
> ___
> Markdown-Discuss mailing list
> Markdown-Discuss@six.pairlist.net
> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Opinions on in-band variation signaling

[Sean Leonard]

Regarding the text/markdown registration:

At least one commentator (Larry Masinter) specifically requested that the 
variant identifier be included in-band in the Markdown content, rather than as 
part of the metadata. I disagree with in-band signaling (as has been registered 
earlier on this list). Nevertheless, I wanted to take a straw poll and see if 
anyone has tried to implement in-band Markdown variation identifiers, with any 
success. Do any implementers have experience with picking the type of Markdown 
based on some info at the top of the Markdown content? Does it work—or will it 
never work? Or is it “bad” for particular reasons?

By in-band, I mean a Markdown file with content like this:

>>>
!pandoc
% This is a Title
% Sean Leonard
% November 2014

Blah blah *blah*.
<<< (fortin’s suggestion)

>>>
[!pandoc]: # "This is a pandoc document."
% This is a Title
% Sean Leonard
% November 2014

Blah blah *blah*.
<<< (seantek’s suggestion)

-Sean
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss

Progress on text/markdown at IETF 91

[Sean Leonard]

Hello Markdown Community:

There was discussion and progress on text/markdown at IETF 91. Here are slides:
http://tools.ietf.org/agenda/91/slides/slides-91-appsawg-1.pdf

and here are the interim minutes:
http://tools.ietf.org/wg/appsawg/minutes

The view is that the syntax parameter of draft-03 should be simplified to a 
parameter currently called “variant”, which is a simple US-ASCII 
case-insensitive identifier. Other considerations are discussed on the 
apps-discuss IETF mailing list. The proposal was posted last week, and is below.

I will work on draft-04 over the next couple of weeks.

Sean

***

From
http://mailarchive.ietf.org/arch/msg/apps-discuss/kaSgQOOolkXUdmYKeh78npLAlXQ
***
Optional Parameters:
variant: An optional identifier that serves as a “hint” to the recipient of the 
specific Markdown variant that the author intended. When omitted, there is no 
hint; the interpretation is entirely up to the receiver and context. This 
identifier is plain US-ASCII and case-insensitive. People who want interop can 
optionally register them using a simple webform (IANA registry), which just 
asks for the Identifier, a Description, and Contact Information. If a receiver 
does not recognize the variant identifier, the receiver MAY present the 
identifier to a user to inform him or her of it.
Other parameters MAY be included with the media type. The semantics of such 
parameters MAY be defined by the variant; they are not defined here. As an 
alternative, the variant MAY be registered under another media type; this 
text/markdown registration does not preclude other registrations.
***

With the text above in the registration template, pretty much all of Section 3 
(draft-03) would be eliminated. Additionally, Section 6 (IANA Considerations) 
would be cut down to about 1/3 of its current size.

Definition:
"Variant" means a lightweight markup language that differs in some respect from 
other Markdown-derived languages. The purpose of a variant is to distinguish a 
given variation from other Markdown variations, as well as from Gruber's 
original syntax specification and implementation, where two parties wish to 
interoperate by implementing the common variation.

The IANA Registry shall be called "Markdown Variants". The intent of this name 
is to broaden the uses of variant identifiers, so protocols that do not rely on 
Internet media types can still tag Markdown content with a variant name. For 
example, a file can be named "file.pandoc.markdown", which could have the 
equivalent meaning as "Content-Type: text/markdown; variant=pandoc". (Credit 
goes to Michel Fortin for suggesting that the classification of variants have 
broader value than just the media type registration; for example, in content 
management systems that do not use media types to classify formats.)
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
https://pairlist6.pair.net/mailman/listinfo/markdown-discuss