Subject: Re: [apps-discuss] New Version Notification for draft-seantek-text-markdown-use-cases-01.txt

From: Sean Leonard <[email-masked]>
Date: Thu, 1 Jan 2015 15:26:09 -0800

Hello,

On Dec 31, 2014, at 8:10 AM, Graham Klyne <[email-masked]> wrote:

> Hi,
> 
> I took a quick skim.  I'm not sure I find the background rationale especially useful, and haven't reviewed it in detail (but I've no objection to it - as if that mattered!).

Ok.
Well, it hasn’t changed much (actually not at all) from past revisions.

> 
> In the sections on the various markdown flavours/variants, I think it might be helpful to provide separate links for format documentation vs implementations. I had the impression that links provided were for one or the other or maybe both, according to what is at hand.  Mainly, for implementations, I think it could be helpful to call out (a) available implementations that can be used locally, and (b) public systems that do useful things with specific markdown flavors.

The links in the References field are to the documentation of the syntax for the variant. Frequently, the only documentation about the variant is in documentation accompanying the primary implementation (e.g., pandoc = README section called pandoc’s markdown).

The prior registration template distinguished between syntax documentation and extant implementations. There was a lot of pushback on draft-03 that the whole thing was too complicated. (I deemed the objection legitimate on grounds that if the registration process is too cumbersome, people who want to interoperate with a variant will not bother to register at all.) I tried to simplify the template as much as possible; this is the result.

I don’t see a principled distinction between (a) and (b). Sure, pandoc is shipped as a command-line tool [a]; “GitHub Flavored Markdown” is used by github.com, which is a web app dingus [b]. But anyone can stick a web service front-end onto pandoc (there are examples out there; consider Authorea for example). MarkdownPad, a local editor, implements GFM. Therefore the fact that there are implementations on either side of the client-server divide doesn’t really impact the registration.

> 
> (Does this also suggest a tweak to the registration template?)

Yes, see text-markdown-05 for the new registration template, which has been drastically simplified. (In particular look at the diff between draft-03 and draft-04.)

Sean

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Thu, 8 Jan 2015 17:05:07 -0800

On Thu, Jan 1, 2015 at 3:26 PM, Sean Leonard <[email-masked]> wrote:

> The links in the References field are to the documentation of the syntax
> for the variant. Frequently, the only documentation about the variant is in
> documentation accompanying the primary implementation (e.g., pandoc =
> README section called pandoc’s markdown).
>
> The prior registration template distinguished between syntax documentation
> and extant implementations. There was a lot of pushback on draft-03 that
> the whole thing was too complicated. (I deemed the objection legitimate on
> grounds that if the registration process is too cumbersome, people who want
> to interoperate with a variant will not bother to register at all.) I tried
> to simplify the template as much as possible; this is the result.
>

I don't think enumerating implementations in a registry is useful because
that will be the most volatile part of what gets registered.  On the other
hand, a reference to the defining document is pretty important to include.

-MSK

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Thu, 8 Jan 2015 17:05:29 -0800

On Wed, Dec 31, 2014 at 8:10 AM, Graham Klyne <[email-masked]> wrote:

> I took a quick skim.  I'm not sure I find the background rationale
> especially useful, and haven't reviewed it in detail (but I've no objection
> to it - as if that mattered!).
>

Graham,

Are you referring to Section 1 and perhaps Section 2 with that remark?  I
believe we asked Sean to split out the registrations into a separate
document, so that part seems to be okay for the moment.

-MSK

---

From: Graham Klyne <[email-masked]>
Date: Fri, 09 Jan 2015 09:37:51 +0000

> document, so that part seems to be okay for the moment.

I was referring to section 1.  Taken in isolation, my comment should not be 
regarded as any kind of blocker.

For me, the substantive part of the document is the registrations.  The rest 
might be useful to some, but I suspect that most people for whom this work is 
useful will already have their own experience of what Markdown is and how to use it.

As for splitting out the registrations, I'm assuming this draft *is* the 
separate document.  I thought there were differing opinions whether they should 
be in the main MIME type document of a separate informational document.  Either 
works for me.  I do seem to recall there was broader consensus to move the 
framing material (sections 1, 2 and maybe 4) out of the main document (YMMV). 
I've no objection to this document going forward in broadly its present form.

#g