Subject: [apps-discuss] I-D Action: draft-ietf-appsawg-text-markdown-03.txt

From: [email-masked]
Date: Fri, 17 Oct 2014 16:33:52 -0700

A New Internet-Draft is available from the on-line Internet-Drafts directories.
 This draft is a work item of the Applications Area Working Group Working Group of the IETF.

        Title           : The text/markdown Media Type
        Author          : Sean Leonard
	Filename        : draft-ietf-appsawg-text-markdown-03.txt
	Pages           : 22
	Date            : 2014-10-17

Abstract:
   This document registers the text/markdown media type for use with
   Markdown, a family of plain text formatting syntaxes that optionally
   can be converted to formal markup languages such as HTML.

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-ietf-appsawg-text-markdown/

There's also a htmlized version available at:
http://tools.ietf.org/html/draft-ietf-appsawg-text-markdown-03

A diff from the previous version is available at:
http://www.ietf.org/rfcdiff?url2=draft-ietf-appsawg-text-markdown-03

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at tools.ietf.org.

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

---

From: Graham Klyne <[email-masked]>
Date: Sat, 18 Oct 2014 21:22:32 +0100

Sean,

I just took a quick look at the new draft.

I don't remember anything about fragment identifiers in the previous draft that 
I reviewed.  I think what you have in the latest draft is seriously broken.  
E.g. "#o#page=6" is not a valid fragment identifier in a URI, per 
http://tools.ietf.org/html/rfc3986#section-3.5 (there's no such thing as a 
secondary fragment, and a fragment can't contain an unescaped '#')

To my mind, this MUST be fixed.  I'm not sure that the whole section about 
fragments makes sense, and would be inclined to just drop it.

<aside>
Sean, this is by way of personal advice, not a technical comment. Please accept 
it in the constructive spirit in which it is intended...

You've tapped a vein of interest and good-will in advancing the proposal to 
register text/markdown, but some (myself included) have pointed out that the 
specification is over-reaching in its scope.  I really urge you to rein in the 
scope of what you're proposing or there is, IMO, a real danger of reviewer 
fatigue setting in and the whole effort going nowhere.  The media registration 
need not and should not attempt to address every known issue around Markdown as 
a media type - other refinements can come later if they are really valuable.
</aside>

#g
--

On 18/10/2014 00:33, [email-masked] wrote:
> _______________________________________________
> I-D-Announce mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/i-d-announce
> Internet-Draft directories: http://www.ietf.org/shadow.html
> or ftp://ftp.ietf.org/ietf/1shadow-sites.txt

---

From: Sean Leonard <[email-masked]>
Date: Sat, 18 Oct 2014 14:04:31 -0700

On 10/18/2014 1:22 PM, Graham Klyne wrote:
> I don't remember anything about fragment identifiers in the previous 
> draft that I reviewed.  I think what you have in the latest draft is 
> seriously broken.  E.g. "#o#page=6" is not a valid fragment identifier 
> in a URI, per http://tools.ietf.org/html/rfc3986#section-3.5 (there's 
> no such thing as a secondary fragment, and a fragment can't contain an 
> unescaped '#')
>
> To my mind, this MUST be fixed.  I'm not sure that the whole section 
> about fragments makes sense, and would be inclined to just drop it.

Hmmm...just looked at it. You're right. I guess that in a URI there can 
literally be only zero or one # character.

At a minimum, the delimiter should not be "#". Let's go with ":", which 
was my original idea (#t:line=10 using [RFC5147]).

The broader question (which the section on fragment identifiers was 
supposed to raise) is "what do fragment identifiers mean in the context 
of Markdown content?" Because guess what...the media type registration 
is where fragment identifiers get defined. Section 4.11 of [RFC6838].

At a minimum, we should not have less semantics than text/plain 
[RFC5147]. Unless people think otherwise. (I would like to hear 
arguments why Markdown content should not be addressable using 
text/plain fragments.)

Then the question is should we have more than text/plain fragments. To 
[Michel Fortin's point][o]: some Markdown-derivative syntaxes have an 
attribute specification {#o} that can be applied to header fields. This 
is the case with PHP Markdown Extra, and with pandoc 
(header_identifiers, which derives the rule from PHP Markdown Extra). 
Pandoc also allows for attribute specifications to be attached to code 
blocks (fenced_code_attributes extension). That is why in the pandoc 
syntax registration, I added #id#<identifier> for {#<identifier>}. 
(Note: now it should be #id:<identifier>.)

[o]: 
http://mailarchive.ietf.org/arch/msg/apps-discuss/J4SkvytTQPqlBPzXej8Mn5rv524

Adding more fragment identifiers makes the spec more complex. But is 
this complex for the sake of complexity, or complex because we are 
dealing with a complex technology? Nobody is forcing header {#o} down 
anyone's throat. Most Markdown syntaxes (including [MDSYNTAX]) don't 
have it. We could remove the prefix "id:" (and the prefix "t:") so that 
the fragments are "simpler", but then there would be name clashes if you 
say line=10 and somebody puts in {#line=10} in the Markdown.

All of this goes to the broader point of whether and to what extent 
"text/markdown" can be used for different implementations 
(implementations of what??) to interoperate. We have a situation where 
there are probably over 100 different "Markdown" syntaxes out there on 
the market with some kind of traction in particular communities.

Should they all be "text/markdown; charset=foo" and call it a day? Are 
we satisfied that there will be 100 different syntaxes that have 
disjoint (and occasionally conflicting) features with no way to 
distinguish intelligently between them?

Should there be 100 different, separate media type registrations? (This 
may not be as bad as it sounds. But it means that, de-facto, the 100 
different registrations will not have common points of interoperability 
between each other.)

Should we have a new "markdown" top level type, or a new 
"text/markdown." facet prefix?

Should we call this "text/editable; syntax=Markdown"?

What makes some text "text/editable" and other text (say, troff, html) 
not "editable"?

Should we say "text/plain; mdsyntax=GFM" for texts in Markdown Syntax? 
What are the security implications of overloading text/plain with an 
open-ended list of syntaxes that include URIs and executable code?

Those are the myriad of different ways to do this. I am happy to defer 
to WG consensus. But we have many different ways that this can be 
skinned; what matters for standards activity is not that one way is 
"best", but that everybody agrees to do it the same way. Until then, 
everybody will be using "text/x-markdown" and nobody will know exactly 
what that means.

Respectfully submited,

Sean

---

From: "Fletcher T. Penney" <[email-masked]>
Date: Sat, 18 Oct 2014 17:37:50 -0400

> distinguish intelligently between them?

Yes.  Absolutely yes.

> different registrations will not have common points of interoperability

Yes.  Absolutely yes.  If the content being used is not Markdown, then 
they should not use "text/markdown."

> "text/markdown." facet prefix?

I am indifferent on this -- depends on what the prevailing "culture" is 
for media types.  Out of my area of expertise.

> Should we call this "text/editable; syntax=Markdown"?

No.  All text is editable.

> open-ended list of syntaxes that include URIs and executable code?

I assume by "mdsyntax" you mean "markdownsyntax".  To reiterate my 
earlier points -- this is like "kleenex".  To be more accurate you 
*could* say "markupsyntax=markdown" or "markupsyntax=GFM", etc.  I think 
"text/markdown" and "text/GFM" would be better, but there is certainly 
room to debate.

> everybody will be using "text/x-markdown" and nobody will know exactly

The problem is not really what "text/x-markdown" means.  It's really 
clear.  It means "Markdown."  The problem is that people don't know what 
Markdown means.  It is not "GFM" or "PHP MD Extra", etc.  It's Markdown. 
  I don't think a media type, no matter how elaborate or complicated, is 
going to solve that problem.

F-

-- 
Fletcher T. Penney
[email-masked]

---

From: Michel Fortin <[email-masked]>
Date: Sat, 18 Oct 2014 17:58:28 -0400

Le 18-oct.-2014 à 17:04, Sean Leonard <[email-masked]> a écrit :

> Should they all be "text/markdown; charset=foo" and call it a day? Are we satisfied that there will be 100 different syntaxes that have disjoint (and occasionally conflicting) features with no way to distinguish intelligently between them?

That's what people have been doing all this time. We'd be no worse than before.

I agree that it'd be nice to be able to distinguish between all variants in an automated manner, but I don't think it's pragmatic. My opinion is that what is possible is of limited utility and not very realistic due of complex coordination and maintenance requirements combined with low incentives. It's probably possible if you limit yourself to some specific usage scenarios, but I don't really know.

As a way to try to satisfy your requirement, I've proposed an open scheme before. Just let people use whatever variant identifier(s) they want in a mostly free-form parameter. Maybe an ad-hoc standard will emerge from those who actually use that attribute for something, in which case it'll be defined and evolved organically on those people's time based on their actual requirements. For everyone else it'll just be a fancy optional field to declare your love to a specific variant.

Indeed, we could just do without any parameter (other than charset) and call it a day. I'm okay with that too. It's clearly the least controversial approach.

-- 
Michel Fortin
[email-masked]
https://michelf.ca

---

From: Graham Klyne <[email-masked]>
Date: Mon, 20 Oct 2014 08:15:36 +0100

TL;DR: drop the section about fragment identifiers; simply say fragment 
identifiers are the same as for text/plain (per RFC 5147).

On 18/10/2014 22:04, Sean Leonard wrote:
> The broader question (which the section on fragment identifiers was supposed to
> raise) is "what do fragment identifiers mean in the context of Markdown
> content?" Because guess what...the media type registration is where fragment
> identifiers get defined. Section 4.11 of [RFC6838].
>
> At a minimum, we should not have less semantics than text/plain [RFC5147].
> Unless people think otherwise. (I would like to hear arguments why Markdown
> content should not be addressable using text/plain fragments.)

Absent a clear use-case for fragments in markdown, I'd suggest simply deferring 
to text/plain fragments.

The rationale for markdown is that it is usable as a simple text file ("A 
Markdown-formatted document should be publishable as-is, as plain text" and 
"Markdown is a writing format." [not a publishing format] - 
http://daringfireball.net/projects/markdown/syntax).  Trying to layer more logic 
into the markdown *source* file, IMO, rather defeats the object.

> Then the question is should we have more than text/plain fragments. To [Michel
> Fortin's point][o]: some Markdown-derivative syntaxes have an attribute
> specification {#o} that can be applied to header fields. This is the case with
> PHP Markdown Extra, and with pandoc (header_identifiers, which derives the rule
> from PHP Markdown Extra). Pandoc also allows for attribute specifications to be
> attached to code blocks (fenced_code_attributes extension).

But all this applies to the output generated for publication, not to the 
markdown source.  Just as markdown constrains itself to "issues that can be 
conveyed in plain text", I think the same philosophy should apply to markdown 
fragment identifiers.  None of this prevents the use of features you describe, 
with fragments applied correspondingly to the published output.  That's not part 
of the source media type.

> Adding more fragment identifiers makes the spec more complex. But is this
> complex for the sake of complexity, or complex because we are dealing with a
> complex technology? Nobody is forcing header {#o} down anyone's throat. Most
> Markdown syntaxes (including [MDSYNTAX]) don't have it.

All the more reason to not enshrine it in the fragment syntax.

> "text/markdown" can be used for different implementations (implementations of
> what??) to interoperate. We have a situation where there are probably over 100
> different "Markdown" syntaxes out there on the market with some kind of traction
> in particular communities.

Quite: "implementations of what??"   As we don't currently know, we shouldn't be 
trying to standardize.  If clear use cases emerge in time, the community can 
come back and update the specification (or create a new one).  That's way harder 
to do if the review has to read around poorly conceived features in the original 
specification.  In this, I believe that less truly is more.

(I note that RFC5147 fragment syntax is compatibly extensible as a base for more 
comprehensive specifications if such prove to be useful in the future.  So 
there's no pressure to second-guess future requirements here.)

#g