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

From: Sean Leonard <[email-masked]>
Date: Sun, 01 Feb 2015 09:12:50 -0800

On 1/9/2015 7:02 AM, Michel Fortin wrote:
> The complexity has been scaled down from the earlier drafts, that's good.
>
> Having a registry for variants remains unnecessary in my view, and, while I understand Sean personally has a use case for it, what remains unclear to me is how the registry is going to be populated. It seems to me that the only person that needs it is Sean and thus he'll either be the one populating it or it'll be left mostly empty. Perhaps I'm wrong, but who else has shown interest in the thing?

I wanted to respond to this point (and if any disagree, please voice a 
different view).

First of all, compared to prior drafts (particularly draft-03) this 
latest draft-05 and use-cases-01 are drastically simplified. I am 
willing to simplify them further...but need concrete direction. 
Otherwise I think we are on the final stretch.

Various efforts over the years to resolve the Markdown "standardization 
problem" have turned into cat-herding exercises. Even now in the "stmd" 
community (aka CommonMark community) <http://talk.commonmark.org/>, most 
threads have turned into "me too" pleas to add "just one more feature". 
Constantly changing specs and definitions hinder interoperability, i.e., 
getting two different implementations (possibly across space and time) 
to produce consistent results. As folks are desiring to use Markdown for 
various archival or pre-archival purposes, this is a problem because 
just labeling content as .markdown or text/markdown alone will not 
result in uniform behavior across space and time.

I do not believe that Markdown has a standardization problem, because it 
was not meant to be standardized. It's like MIT's old Building 20: if 
the wall doesn't work for you, poke a hole in it for your own purposes 
and ask questions later. That was part of John Gruber's design 
philosophy. However, since Markdown is ever-changing, there is a 
labeling problem for people who want or need consistent behavior.

The registry is going to be populated by "people who have a need to 
interoperate". I.e., if you want interop (per above: consistent 
referenceable behavior), you'll take the trouble to register an 
identifier. I have tried to simplify the registration template as much 
as possible, without sacrificing the information required for 
interoperability. For example, I removed the version sub-identifier 
since that was a source of additional complexity. If someone wants to 
register "CommonMark-0.17" distinctly from "CommonMark" (version 
unspecified), that is possible.

Both the Markdown community and this (IETF) community have expressed a 
need for registered variants. See, e.g., 
<http://blog.codinghorror.com/the-future-of-markdown/> point 5. If the 
registration activity slows down, that's fine. Either people will have 
moved from Markdown to the shiny new thing, or they don't need to label 
their content in an interoperable way.

Thanks,

Sean

---

From: Graham Klyne <[email-masked]>
Date: Wed, 04 Feb 2015 15:33:39 +0000

Sean,

You asked for feedback - I'm not exactly disagreeing, but don't think the 
registry is a sword to be fallen upon...

I agree with the general gist that it's sometimes useful to be able to describe 
or name Markdown variants for specific purposes.  Hence I believe a variant 
parameter for the MIME content-type is useful to have.

How to document consensus on what the variant values mean?  An IANA registry is 
one way of doing this, and seems a reasonable option to the extent it relates to 
a parameter defined in an IETF protocol element.  But other options are also 
possible, and if there's significant push-back against defining an IANA 
registry, I'd be inclined to create a wiki somewhere (GitHub?) and point to that 
instead.  If it turns out to be useful, a more formal registry could be defined 
later.

It might even be the case that the best design for a registry would be clearer 
if there were some track record of (less formal) documentation of variants.

Just my 2¢.

#g
--

On 01/02/2015 17:12, Sean Leonard wrote:
>> Having a registry for variants remains unnecessary in my view, and, while I
>> understand Sean personally has a use case for it, what remains unclear to me
>> is how the registry is going to be populated. It seems to me that the only
>> person that needs it is Sean and thus he'll either be the one populating it or
>> it'll be left mostly empty. Perhaps I'm wrong, but who else has shown interest
>> in the thing?
>
> I wanted to respond to this point (and if any disagree, please voice a different
> view).
>
> First of all, compared to prior drafts (particularly draft-03) this latest
> draft-05 and use-cases-01 are drastically simplified. I am willing to simplify
> them further...but need concrete direction. Otherwise I think we are on the
> final stretch.
>
> Various efforts over the years to resolve the Markdown "standardization problem"
> have turned into cat-herding exercises. Even now in the "stmd" community (aka
> CommonMark community) <http://talk.commonmark.org/>, most threads have turned
> into "me too" pleas to add "just one more feature". Constantly changing specs
> and definitions hinder interoperability, i.e., getting two different
> implementations (possibly across space and time) to produce consistent results.
> As folks are desiring to use Markdown for various archival or pre-archival
> purposes, this is a problem because just labeling content as .markdown or
> text/markdown alone will not result in uniform behavior across space and time.
>
> I do not believe that Markdown has a standardization problem, because it was not
> meant to be standardized. It's like MIT's old Building 20: if the wall doesn't
> work for you, poke a hole in it for your own purposes and ask questions later.
> That was part of John Gruber's design philosophy. However, since Markdown is
> ever-changing, there is a labeling problem for people who want or need
> consistent behavior.
>
> interoperate". I.e., if you want interop (per above: consistent referenceable
> behavior), you'll take the trouble to register an identifier. I have tried to
> simplify the registration template as much as possible, without sacrificing the
> information required for interoperability. For example, I removed the version
> sub-identifier since that was a source of additional complexity. If someone
> wants to register "CommonMark-0.17" distinctly from "CommonMark" (version
> Both the Markdown community and this (IETF) community have expressed a need for
> registered variants. See, e.g.,
> registration activity slows down, that's fine. Either people will have moved
> from Markdown to the shiny new thing, or they don't need to label their content
> in an interoperable way.
>
> Thanks,
>
> Sean
>
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>

---

From: Sean Leonard <[email-masked]>
Date: Sun, 08 Feb 2015 23:57:46 -0800

"ok"

Thanks for the feedback.

In draft-05, the registry is optional, not required. The text says "To 
promote interoperability, identifiers MAY be registered in the 
registry..." so I think that both options are covered. If folks do not 
want to use the registry, they do not have to. At the same time, we may 
as well create the registry for folks who want to use it, especially to 
guarantee stability of what values mean. I guess I am wary of punting on 
the registry now since that means there is another uphill battle to get 
a document through IETF consensus specifically to create the registry. 
We want this to be easy for folks to use, i.e., have everything tied 
down and handed to the community in one IETF Action (passing this draft 
+ the use cases draft).

There is a track record of documentation of variants...just check out: 
<https://www.google.com/search?q=markdown+implementations> 
<http://johnmacfarlane.net/babelmark2/> 
<http://stackoverflow.com/questions/889434/markdown-implementations-for-c-c> 
<http://www.w3.org/community/markdown/wiki/MarkdownImplementations> 
<http://en.wikipedia.org/wiki/Markdown#Implementations>

None of these references are stable enough to promote interoperability 
with named identifiers, but I think that it shows that the community is 
trying.

Hopefully we are mostly on the same page, at least enough to move 
forward with this draft.

Cheers,

Sean

On 2/4/2015 7:33 AM, Graham Klyne wrote:
> Sean,
>
> You asked for feedback - I'm not exactly disagreeing, but don't think 
> the registry is a sword to be fallen upon...
>
> I agree with the general gist that it's sometimes useful to be able to 
> describe or name Markdown variants for specific purposes. Hence I 
> believe a variant parameter for the MIME content-type is useful to have.
>
> How to document consensus on what the variant values mean?  An IANA 
> registry is one way of doing this, and seems a reasonable option to 
> the extent it relates to a parameter defined in an IETF protocol 
> element.  But other options are also possible, and if there's 
> significant push-back against defining an IANA registry, I'd be 
> inclined to create a wiki somewhere (GitHub?) and point to that 
> instead.  If it turns out to be useful, a more formal registry could 
> be defined later.
>
> It might even be the case that the best design for a registry would be 
> clearer if there were some track record of (less formal) documentation 
> of variants.
>
> Just my 2¢.
>
> #g
> -- 
>
>
>> latest
>> referenceable

---

From: Sean Leonard <[email-masked]>
Date: Mon, 09 Feb 2015 00:08:01 -0800

Just some public notes on some ABNF nits/issues in draft-markdown-05:

Currently Section 6.1 says:

      ALPHA [*(%d33-126) (ALPHA / DIGIT)]

This should be changed to:

      ALPHA [*VCHAR (ALPHA / DIGIT)]

which means the same thing.

The rules import rule names from the RFC 5234 Core Rules. Currently 
there is no RFC 5234 reference. I am not inclined to add one because it 
is "obvious", but in my last draft the IESG requested a RFC 5234 
reference, so I figured I would poll the list to see if there is 
consensus that it needs to be added, before it goes to LC.

<RFC-Aside>
Recently on rfc-interest there has been some discussion about making 
ABNF more formalized and complicated. I think the ABNF in this draft is 
a prime example of ABNF that does *not* need to be formalized in an 
"ABNF module" with imports and exports. It is also an example of ABNF 
that exists in the prose text, rather than ABNF that is sequestered into 
discrete Figure blocks. The ABNF is really just for expository purposes; 
furthermore, they are not even comprised of complete ABNF statements 
(there are no rulenames provided).
</RFC-Aside>

Sean

On 12/22/2014 3:01 PM, [email-masked] wrote:
> 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-05.txt
> 	Pages           : 14
> 	Date            : 2014-12-22
>
> 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.

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Mon, 09 Feb 2015 09:59:16 +0100

>consensus that it needs to be added, before it goes to LC.

That something like `ALPHA / DIGIT` is an unordered choice between the
two non-terminals is not obvious, it could just as well be an ordered
choice or something else entirely. If you have an ABNF grammar, you do
need to reference a specification for the semantics of the syntax.
-- 
Björn Höhrmann · mailto:[email-masked] · http://bjoern.hoehrmann.de
D-10243 Berlin · PGP Pub. KeyID: 0xA4357E78 · http://www.bjoernsworld.de
 Available for hire in Berlin (early 2015)  · http://www.websitedev.de/

---

From: Sean Leonard <[email-masked]>
Date: Mon, 09 Feb 2015 01:05:00 -0800

On 2/9/2015 12:59 AM, Bjoern Hoehrmann wrote:
> choice or something else entirely.

Sorry but I am not sure that I follow. Can you clarify what you mean?

The specification says:
I.e., the identifier MUST start with a letter and MAY contain 
punctuation in the middle, but not at the end: the last character MUST 
be alphanumeric.

So, the alphanumeric {ALPHA / DIGIT} is at the end; it is not "between" 
anything (whether terminal or non-terminal).

Thanks, Sean

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Mon, 09 Feb 2015 10:17:57 +0100

>anything (whether terminal or non-terminal).

I am just saying that it does not make sense to use ABNF syntax without
referencing a specification for ABNF (starting with the fact that there
are other "ABNF"s than "IETF ABNF"). As for the specific example, there
are ABNF-like formats that, for instance, use `|` as distinct from `/`
where `|` is an unordered choice and `/` is an ordered choice (consider
how you interpret them if both sides of the operator match; with un-
ordered choices you have an ambiguity in the grammar, while an ordered
choice does not allow ambiguity).
-- 
Björn Höhrmann · mailto:[email-masked] · http://bjoern.hoehrmann.de
D-10243 Berlin · PGP Pub. KeyID: 0xA4357E78 · http://www.bjoernsworld.de
 Available for hire in Berlin (early 2015)  · http://www.websitedev.de/

---

From: Alexey Melnikov <[email-masked]>
Date: Mon, 09 Feb 2015 11:10:56 +0000

Hi Sean,

On 09/02/2015 08:08, Sean Leonard wrote:
> there is no RFC 5234 reference. I am not inclined to add one because 
> it is "obvious",
There is no such thing as "obvious RFC reference". There are no implicit 
RFC references.
> but in my last draft the IESG requested a RFC 5234 reference, so I 
> figured I would poll the list to see if there is consensus that it 
> needs to be added, before it goes to LC.
Please just add it :-).
> ABNF more formalized and complicated. I think the ABNF in this draft 
> is a prime example of ABNF that does *not* need to be formalized in an 
> that exists in the prose text, rather than ABNF that is sequestered 
> into discrete Figure blocks. The ABNF is really just for expository 
> purposes; furthermore, they are not even comprised of complete ABNF 
> statements (there are no rulenames provided).
> </RFC-Aside>
>
> Sean
>

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Mon, 9 Feb 2015 06:36:45 -0800

On Mon, Feb 9, 2015 at 3:10 AM, Alexey Melnikov <[email-masked]>
wrote:

The rules import rule names from the RFC 5234 Core Rules. Currently there
> is no RFC 5234 reference. I am not inclined to add one because it is
> "obvious",
>> figured I would poll the list to see if there is consensus that it needs to
>> be added, before it goes to LC.
>>
> Please just add it :-).

+1. What's the harm?

-MSK

---

From: Graham Klyne <[email-masked]>
Date: Mon, 09 Feb 2015 15:32:39 +0000

On 09/02/2015 07:57, Sean Leonard wrote:
> "ok"
>
> Thanks for the feedback.
>
> In draft-05, the registry is optional, not required. The text says "To promote
> interoperability, identifiers MAY be registered in the registry..." so I think
> that both options are covered. If folks do not want to use the registry, they do
> not have to. At the same time, we may as well create the registry for folks who
> want to use it, especially to guarantee stability of what values mean. I guess I
> am wary of punting on the registry now since that means there is another uphill
> battle to get a document through IETF consensus specifically to create the
> registry. We want this to be easy for folks to use, i.e., have everything tied
> down and handed to the community in one IETF Action (passing this draft + the
> use cases draft).
>
> None of these references are stable enough to promote interoperability with
> named identifiers, but I think that it shows that the community is trying.
>
> Hopefully we are mostly on the same page, at least enough to move forward with
> this draft.

Yes, mostly.  Let's move forwards!  I was mainly offering an alternative in case 
the registry proves to be a sticking point in IETF review.

One point I'd make about "documentation of variants" is that my suggestion would 
be that the specification would indicate a preferred venue for this, to avoid 
the proliferation problems.  Beyond that, assuming one chooses a stable venue, 
stability is really a function of how much the interested parties care about 
stability.

#g
--

>> describe or name Markdown variants for specific purposes. Hence I believe a
>> variant parameter for the MIME content-type is useful to have.
>>
>> How to document consensus on what the variant values mean?  An IANA registry
>> is one way of doing this, and seems a reasonable option to the extent it
>> relates to a parameter defined in an IETF protocol element.  But other options
>> are also possible, and if there's significant push-back against defining an
>> IANA registry, I'd be inclined to create a wiki somewhere (GitHub?) and point
>> to that instead.  If it turns out to be useful, a more formal registry could
>> be defined later.
>>

---

From: Sean Leonard <[email-masked]>
Date: Mon, 09 Feb 2015 07:36:40 -0800

On 2/9/2015 6:36 AM, Murray S. Kucherawy wrote:
> On Mon, Feb 9, 2015 at 3:10 AM, Alexey Melnikov 
> <[email-masked] <mailto:[email-masked]>> wrote:
>
>     The rules import rule names from the RFC 5234 Core Rules.
>     Currently there is no RFC 5234 reference. I am not inclined to add
>     one because it is "obvious",
>     There is no such thing as "obvious RFC reference". There are no
>     implicit RFC references.
>
>         but in my last draft the IESG requested a RFC 5234 reference,
>         so I figured I would poll the list to see if there is

Ok; I'll add the RFC 5234 reference.

Sean