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

From: [email-masked]
Date: Tue, 16 Dec 2014 23:57:35 -0800

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-04.txt
	Pages           : 14
	Date            : 2014-12-16

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-04

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

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: Sean Leonard <[email-masked]>
Date: Wed, 17 Dec 2014 18:57:44 -0800

The text/markdown draft has been updated. Please comment.

    This draft is a continuation fromdraft-ietf-appsawg-text-markdown-  <http://tools.ietf.org/html/draft-ietf-appsawg-text-markdown-03.txt>
    03.txt  <http://tools.ietf.org/html/draft-ietf-appsawg-text-markdown-03.txt>. These technical changes were made:

       1.  Removed output-type optional parameter.
       2.  Renamed syntax optional parameter to variant.
       3.  Defined variant optional parameter as discussed on mailing
           list.
       4.  RemovedSection 3  <http://tools.ietf.org/html/draft-ietf-appsawg-text-markdown-04#section-3>  (which may be replaced with Content-
           Disposition/preview-type in the future).
       5.  Redid the fragment identifier considerations, simplifying the
           specification considerably.
       6.  Discussed the meaning of "variant" in the context of Markdown.
       7.  Redefined the IANA registry as "Markdown Variants" and
           expanded its applicability outside of this particular media
           type.
       8.  Drastically simplified the registration template.

Sean

On 12/16/2014 11:57 PM, [email-masked] wrote:
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss

---

From: Michel Fortin <[email-masked]>
Date: Thu, 18 Dec 2014 23:07:27 -0500

>> http://tools.ietf.org/html/draft-ietf-appsawg-text-markdown-04

Section 2: 

	Additionally, implementations
	SHOULD record syntax and output-type parameters along with the
	Markdown, such as in extended attributes; however, the exact
	manner of storage is a local matter

Looks outdated. There's no "output-type" in this version of the spec. Also, "syntax" is now "variant". And to me this sounds like empty guidance (do this thing we don't know how to do and which you'll likely end up doing in a non-interoperable way). I'd rather say nothing.

4: Fragment identifiers

In my opinion there is no point in having such a section. The "general-purpose" fragment identifiers are basically undefined. Markdown doesn't have identifiers, and variants that implement something like this often do so in different ways, and sometime they're implicitly generated from title names, footnote numbers, etc, again often in non-compatible ways.

I'd basically replace the whole section 4 with this two-sentence paragraph: "Markdown doesn't define any fragment identifiers, but some variants do. Which fragment identifiers are available for a given document are variant-defined."

4.2: about #line=x

I can't find any browser supporting this for text/plain. Is this in useful anywhere? Beside, take note that it's meaningless in any context where the Markdown text has been interpreted and rendered as something else than a plain text document.

5: Example:

	Content-Type: text/markdown; charset=UTF-8; syntax=Original;
	 output-type="application/xhtml+xml"

Can I say "outdated" again?

6: The variant registry

I still don't know what to think about this. It's good to have a list of variants available, but given I don't expect Markdown parser implementers are going to bother registering things there it looks like a fertile ground for squatting given that first-come first-served policy.

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

---

From: Sean Leonard <[email-masked]>
Date: Sat, 20 Dec 2014 17:46:23 -0800

On 12/18/2014 8:07 PM, Michel Fortin wrote:
> Looks outdated.
Yes--it was missed. It will be addressed/fixed/removed.

> I'd basically replace the whole section 4 with this two-sentence paragraph: "Markdown doesn't define any fragment identifiers, but some variants do. Which fragment identifiers are available for a g…

I thought about this (and also took Graham's comments into 
consideration). Overall I am leaning towards cutting the section down, 
but not eliminating it entirely. There should be enough text to provide 
variant users with guidance that fragment identifiers can be used, 
without imposing many restrictions. So it will probably be closer to 
your quote above.

>
> 4.2: about #line=x
>
> I can't find any browser supporting this for text/plain. Is this in useful anywhere?
This is best addressed to the authors and contributors of RFC 5147. I am 
not aware of specific deployments.

With that said, it is useful (discussed below):

>   Beside, take note that it's meaningless in any context where the Markdown text has been interpreted and rendered as something else than a plain text document.
I am thinking of web-based Markdown editors, among other things. 
Basically if you go to a web-based Markdown editor like dillinger.io, 
you can add a fragment to the URI, and the web app will do something. 
E.g., http://dillinger.io/#installation will jump to the Installation 
header.

I suppose that you could say "hey, that's really a text/html thing!" but 
we need to take a slightly more expansive view. A PDF reader implemented 
on the client would take the application/pdf data from 
http://example.com/example.pdf#page=5 and jump to the fifth page. A PDF 
reader implemented on the server would take 
http://example.com/example.pdf#page=5 and serve a web app in the form of 
a text/html page to the web browser, and then jump to the fifth page. If 
the user clicks a "Save to Disk" button in either implementation, 
they're going to get an application/pdf file on disk. The user 
experience is the same.

Related to this, Graham Klyne said:
I'm uneasy about the choice of "&" as a parameter separator, as it would 
introduce escaping complications if one just wants to copy the fragment 
into an XML/HTML-based format (which I suggest may be a common 
scenario).  I'd be inclined to use ';' as proposed in 
http://w3ctag.github.io/packaging-on-the-web/#fragment-identifiers (you 
could also exploit the syntax described there).  (I note that 
http://tools.ietf.org/html/rfc5147 doesn't allow multiple parameters.)
<<

Part of me wants to simplify this by not discussing parameter separators 
(or for that matter, multiple parameters) at all. But then if someone 
wants to have multiple parameters, it will be much more difficult to get 
interoperable agreement on how to separate them. Personally I like & 
because it is used in HTTP/HTML query strings. I don't find & -> &amp; 
issues to be salient in the Markdown community, because Markdown has 
specific rules for interpreting & in URIs and other productions without 
worrying about XML/HTML escaping. A secure/properly implemented XML/HTML 
processor needs to anticipate and deal with & in the query component of 
URIs anyway, so reusing that in the fragment component does not seem to 
introduce novel problems.

> Can I say "outdated" again?

Yes--that will be fixed.

> I still don't know what to think about this. It's good to have a list of variants available, but given I don't expect Markdown parser implementers are going to bother registering things there it lo…

Let's see how things go. I doubt that vanity is a strong motivator for 
putting things in that registry. There is still an infinite number of 
useful names. The idea is more than anyone "with a need to interoperate" 
should be sufficiently motivated to add a registration.

Sean