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

[Sean Leonard <[e-mail]>]

Hello,

On Dec 31, 2014, at 8:10 AM, Graham Klyne <[e-mail]> 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