IETF -- Request for input: text/markdown media type

1 
From: IETF Applications Area Working Group (APPSAWG)

To: markdown-discuss@six.pairlist.net
    jgm@berkeley.edu
    david@meteor.com
    vicent@github.com
    neil@reddit.com
    ben@stackexchange.com
    jatwood@codinghorror.com
    comments@daringfireball.net

Cc: presnick@qti.qualcomm.com
    barryleiba@computer.org

Response Contact: superuser@gmail.com

Technical Contact: superuser@gmail.com
    dev+ietf@seantek.com

Purpose: Request for input

Attachments: (none)

Body:

The Applications Area Working Group (APPSAWG) of the Internet Engineering Task Force (IETF) has taken up a proposed work item to register a new Media Type, text/markdown, for the purposes of identifying content in the Markdown format. The current version of the document can be viewed here:

https://datatracker.ietf.org/doc/draft-ietf-appsawg-text-markdown/

We know Sean Leonard approached the Markdown community about starting this work previously (see http://six.pairlist.net/pipermail/markdown-discuss/2014-July/thread.html) and some of the questions that were discussed in that thread are also being asked in the working group. In the interests of ensuring that any choices we make will not conflict with the positions and course of the Markdown community, APPSAWG would like to solicit feedback on a few important questions.

Part of the impetus here is that an unregistered and unspecified media type text/x-markdown appears to be in use. This work seeks to formalize this use and register the name.

Our questions for the Markdown community:

  1. We understand there is not a standard Markdown format, but rather a number of variants based on one original proposal. This leads us to wonder how a consumer would be expected to interpret this media type once it is registered. Typically, a media type registration includes a reference to a single, stable, definition document, but we are not aware of such a thing for Markdown. Can or should this work proceed without one?

    Note that the IETF has no intention to undertake the work of publishing an RFC that contains a Markdown syntax or otherwise blessing any particular Markdown variant, or calling one of them “standard". Any Markdown definition document(s) would be referenced by this work and would be external to the IETF.

  2. One proposal to address this issue is to include a parameter that indicates which flavor of Markdown should be applied in order to translate the input when the media type is encountered. For example:

    Content-Type: text/markdown; flavor="foobar"

    This would likely necessitate a registry of known variants and their respective defining documents so that a consumer has implementation guidance. This puts some burden on the Markdown community to begin formally documenting and registering all of its variants that might use this media type.

  3. The solution in (2) above further raises the question of whether there should be a default variant (i.e., what to do if no flavor clause is present), and if so, which one should be the default. If there is no default, then how should a consumer interpret the absence of the flavor tag?

  4. At the same time, it has been observed that regardless of which variant is in use as input, any Markdown processor will generally produce something useful as output. Given this, is it necessary to know the flavor in use at all? Put another way: Rather than being concerned with variants, should text/markdown merely be a hint to consumers that the content is in some Markdown variant, and beyond that, caveat implementer?

  5. Does the Markdown community have any alternative suggestions in response to any of these questions?

We look forward to your replies, hopefully within the next several weeks, which can be sent to the response and technical contacts listed in the header of this liaison. Markdown community participants are also invited to subscribe and reply to apps-discuss@ietf.org in order to address the entire working group directly.

M. Kucherawy
for the Applications Area Working Group, IETF

1 Like
2

I personally don’t think the flavor is necessary.

Caveat implementer. a Content-Type of HTML could include <blink>, after all…

(also, @seantek I didn’t notice you had already posted this here, sorry about that, I tried to retain all your helpful edits in my repost.)

1 Like
3

No problem. Thanks though!

4

Take a de-facto? I.e. That thought to be most prevalent such as that as currently understood by github. Label others as flavours / variants.

5

I think a flavo(u)r would be handy (if so, could we use a word which has a universally accepted spelling though? Maybe, extensions?) though it does perhaps come with some adminstrative overhead. However, I can imagine situations where it would be useful for a consumer to be provided with a hint on how to more accurately render the markdown (I make a lot of use of kramdown extensions for example).

I don’t think taking a de-facto choice is the right thing to do for unspecified extensions - isn’t the aim of CommonMark to generate a specification? Sounds like the perfect candidate for ‘unspecified extensions’ to me.

2 Likes
6

Why not rather make this text/commonmark, and have the specification which is being discussed on this website as the cannonical one? I mean, that’s part of the idea right, to standardize the spec? :slight_smile:

7

All Markdown flavors are very similar. You can open a text document and tell whether it is Markdown or not, as the basics are all the same. Flavors mostly differ in how they handle corner cases, and which extra features they support (such as math extensions).

This is no different from text/html: the basics are the same, and you can instantly tell whether a document is HTML or not. Yet corner-cases and features differ between browsers and HTML versions, and HTML that renders one way in Internet Explorer 6 won’t render the same in Firefox 32, but you wouldn’t consider doing text/html; flavor="ie6".

And just as you wouldn’t expect Firefox to render an IE6 flavor HTML document any differently, it’s unreasonable to expect any Markdown implementation to understand multiple flavors of Markdown. Even if there would exist such an implementation, it would have to understand all supported flavors down to the level of weird unknown corner-cases.

Therefore, flavor provides no benefits. An implementation will either just render the document using whatever flavor it claims to adhere to and ignore the flavor completely, or reject the document as it has the wrong flavor even if it could render most of such documents fine. Since all Markdown flavors have some sort of graceful degradation, they should just render the document if it has the text/markdown content type. Nothing more, nothing less.

So, in my opinion, just text/markdown is fine. It dictates the content type (which it should) but not the implementation details (which it shouldn’t).

1 Like
8

While I agree that flavor/extension isn’t necessary, I think it would be very useful.

The consumer app would decide what to do if it encounters no extension or one it doesn’t recognize, but for those it does, it could automagically transform-display the doc, or launch a choice of external toolchains to do so, based on the extension specified.

Such a mecanism could enable elegantly precise yet end-user friendly implementations within a currently-chaotic ecosystem.

1 Like
9

vertlink said:

All Markdown flavors are very similar.

all light-markup formats look very similar, yes…
markdown, restructured-text, asciidoc, and more.

but you see they do not create the same output;
the effect is relatively large, thus easily observed.

the markdown flavors are more similar, it is true,
but that also means that you might not observe
the glitch of a difference when one occurs, which
– in the opinion of many – is even more insidious.

if you think such glitches do not happen, or are rare,
you either haven’t used different flavors too much or
you haven’t actually looked hard to find the glitches.
(but you can be sure that your audience saw them.)

the incredible amount of support that this project got
– contrasted with comparable calls in 2009 and 2012 –
provides compelling evidence that many people have
already experienced the pain of inconsistent flavors…

You can open a text document
and tell whether it is Markdown or not,
as the basics are all the same.

once we strip stuff back to the “basics” –
the stuff that everyone considers “basic”
– we end up with a paucity of functionality.

so yeah, if you don’t need much markup,
at all, then “the basics” will work just fine.

but once you step up from that, watch out.

Flavors mostly differ in
how they handle corner cases

so often one person’s “corner case” is
another person’s “middle of the room”.

all Markdown flavors have some sort of
graceful degradation

i don’t see much evidence for that position.

-bowerbird

10

You are a master of taking things out of context. If you read the rest of my post, I hope you can conclude that I neither considered only the basic bottom line of Markdown nor disregard the inconsistencies of Markdown flavors.

Here’s the gist: currently no two implementations of Markdown are the same. Even if they claim to support the same Markdown flavor (e.g. Github flavor), there will be obscure cases where their outputs differ because they adhere to the informal and incomplete original specification. Therefore, if we’re talking about output consistency then it’s meaningless to talk about flavors.

All Markdown implementations that I know will happily display any Markdown document I throw at it. Perhaps not exactly as I intended, but they won’t throw half of the document out the window or cop out. That’s what I mean by graceful degradation, by lack of a better word.

1 Like
11

your “out of context” is my “middle of the room”.

currently no two implementations
of Markdown are the same.
Even if they claim to support
the same Markdown flavor
(e.g. Github flavor), there will be
obscure cases where their outputs differ

ok, so now you’ve added yet another wrinkle,
which is that it is “implementations” that differ,
and their outputs only differ in “obscure cases”.

at which point my complexity bucket overflows,
and i throw in the towel on this part of the thread.

for my money, it is the inconsistencies which matter.
that is, when the same input creates different output.

we also differ on definitions for “graceful degradation”,
apparently, if you really and truly mean “won’t throw
half of the document out the window or cop out”…

but i’m not the dictionary cop here, so feel free to
use your way to talk about stuff however you like,
and i will try my best not to take it out of context.

-bowerbird

12

draft-ietf-appsawg-text-markdown-03 and draft-seantek-text-markdown-use-cases-00 have been posted.

The processor parameter was removed. The flavor parameter was renamed to the syntax parameter, as it designates a Markdown-derivative syntax without regard to any particular implementation.

Registrations of additional syntaxes are supplied in the use-cases document. CommonMark is one of the registrations.

2 Likes
13

draft-ietf-appsawg-text-markdown-05 has been posted.

The syntax parameter was renamed to the variant parameter.

1 Like
14

FYI, It seems a doc related to this is out: https://tools.ietf.org/html/rfc7763

3 Likes
15

And the document for the markdown variants: https://www.rfc-editor.org/rfc/rfc7764.txt