
RFC 7764 – Guidance on Markdown - arthur2e5
https://tools.ietf.org/html/rfc7764
======
Freak_NL
What I would really like is to end up in a situation where email clients all
support text/markdown. It really hits the sweet spot between plain text and
HTML. It has enough structure to show a nice outline, and the triple back-tick
syntax is great for marking bits of text as code.

All without specifying _how_ everything should look. You can read it as
unformatted text, or let the mail client format everything in a style you
like. This is sort-of like HTML without CSS (using the client's default
stylesheet), but also very well readable as unformatted text, and free from
the abuse of HTML email.

Alas. More and more companies are giving up on plain text email (even though
this is required by the standard), and simply send you a hyperlink to click if
you have plain text as your viewing preference for email.

~~~
bhaak
> What I would really like is to end up in a situation where email clients all
> support text/markdown. It really hits the sweet spot between plain text and
> HTML. It has enough structure to show a nice outline, and the triple back-
> tick syntax is great for marking bits of text as code.

Then we would have come full circle. A markup language that has been at least
inspired if not derived from decade old usenet/mail conventions would be back
where it started from.

> [...] and free from the abuse of HTML email.

Are you sure? The advantage of text/plain in mail is that I see every link as
it is and no resources are loaded from external sources.

With markdown support in mail clients, we might be back at early HTML support.
Link destinations would be unknowable again.

> Alas. More and more companies are giving up on plain text email (even though
> this is required by the standard),

If it's not plain text, it has to declare a mime type (how would the mail
client know how to render it?) but I don't think plain text section is
mandatory.

> and simply send you a hyperlink to click if you have plain text as your
> viewing preference for email.

Go tell them, and you can quote me on that, that they are stupid. If my mail
client doesn't render text/html and prefers the text/plain sections that is
because it is configured that way.

I know of no mail client that isn't able to handle HTML.

~~~
wolrah
> Then we would have come full circle. A markup language that has been at
> least inspired if not derived from decade old usenet/mail conventions would
> be back where it started from.

Is this a bad thing?

> Are you sure? The advantage of text/plain in mail is that I see every link
> as it is and no resources are loaded from external sources. > With markdown
> support in mail clients, we might be back at early HTML support. Link
> destinations would be unknowable again.

Not seeing how link destinations become unknowable. With no scripting there's
no way for a site to hide the destination, it is what it is. Your viewer can
choose to display it however it wants. Status bar like a browser, tooltip,
whatever.

> If it's not plain text, it has to declare a mime type (how would the mail
> client know how to render it?) but I don't think plain text section is
> mandatory.

It is though. That's a major advantage of Markdown, by adopting those well-
established mail/usenet conventions where practical and attempting to follow
that sort of principle with less defined formatting there's not really
anything lost if you treat it as plain text. The other way around is almost as
safe, with very little chance of a a plain text message treated as Markdown
being misinterpreted in a way which significantly impacts its meaning.

> I know of no mail client that isn't able to handle HTML.

Any text-mode mail client? I mean sure there are some that can interpret basic
HTML formatting and translate that to control characters for a sufficiently
capable terminal, but modern HTML mail tends to go far beyond that. Basically
what formatting a text-mode client can actually handle also happens to be the
same formatting that Markdown supports. No images, no fonts, no colors, just
paragraphs, links, quotes, and some basic emphasis formatting.

~~~
bhaak
>> Then we would have come full circle. A markup language that has been at
least inspired if not derived from decade old usenet/mail conventions would be
back where it started from.

> Is this a bad thing?

Not a bad thing but in this case it seems a little bit pointless as we
wouldn't have gained much.

It happens a lot that something that is popular now has been there a while ago
so you have some old farts saying "but we already had that 20 years ago!"
although often there are some crucial changes to how it looked then so that it
now has a completely different impact.

For example, we are about to get WebAssembly in the browers, essentially a
bytecode VM. We had that 20 years ago with Java, although the integration of
Java and the browser was not tight enough. Or VR which 20 years ago was quite
hyped and then somehow just died down and for all I know the difference to
today is only that the graphics was crappier back then.

Markdown in the mail client doesn't give you much over what we had 20 years
ago. If I enable format-flowed and use a variable-width font, it probably
looks quite similar to the rendered Markdown.

Oh, one thing I forgot about unstyled HTML pages. Mobile browsers suck a
rendering that.

>> I know of no mail client that isn't able to handle HTML.

> Any text-mode mail client? I mean sure there are some that can interpret
> basic HTML formatting and translate that to control characters for a
> sufficiently capable terminal, but modern HTML mail tends to go far beyond
> that. Basically what formatting a text-mode client can actually handle also
> happens to be the same formatting that Markdown supports. No images, no
> fonts, no colors, just paragraphs, links, quotes, and some basic emphasis
> formatting.

Any text-mode mail client will have ways of rendering HTML with the help of
external programs. That's not surprising, as they already needed that for
things like images or PDFs. Some even let you fire up a browser to read them,
some have some basic HTML parsing capabilities but I think most just do let
some program convert the HTML to text to display inline as if it were a
text/plain section.

As you can't rely on scripting being enabled (are there actually any mail
client that still have HTML scripting?) the HTML needs to have all the text
you want the receiver to read, so converting it to text usually works fine. I
can't remember reading any legit HTML mail in the last years where this wasn't
the case.

------
verandaguy
I'm actually kind of excited about this! A `text/markdown` MIME type could
(maybe? hopefully?) pave the way for native content authoring in Markdown
without having to use an HTML-targeting compiler between the author and the
browser.

I might be being optimistic, but if that ever happens, it could be the start
of a new era in internet content authorship!

~~~
bhaak
Which markdown? There are various variants out there and the original is
unsuitable for more than a most basic web page.

The RFC for text/markdown includes a variant specifier but that only makes me
think that we would be repeating the mistake of early browers when there were
browser-specific HTML tags.

~~~
Ajedi32
Good point; we'd definitely need a standard. Thankfully, [CommonMark][1] has
been in development a while now, and features a complete, unambiguous spec,
reference implementation, and test suite.

A little more work on that to get it to version 1.0 and we'd be golden.

[1]: [http://commonmark.org/](http://commonmark.org/)

~~~
legulere
Is it really unambiguous? There is no grammar, but the spec describes things
in English. It's really hard to avoid ambiguities and impossible to proof
unambiguousness without formal methods.

~~~
Ajedi32
I guess it's hard to say for sure that it's completely unambiguous, but that's
definitely the intent. [The spec][1] even says:

> This document attempts to specify Markdown syntax unambiguously.

So if you're aware of any ambiguities in the spec, those are bugs which should
be reported and fixed.

[1]: [http://spec.commonmark.org/0.27/](http://spec.commonmark.org/0.27/)

~~~
the_duke
You may want to work on specifying a formal grammar in EBNF or similiar.

Great for library / parser implementers and it helps discover ambiguities.

~~~
taylorfausak
From John MacFarlane, the author of the CommonMark spec:

> If anyone wants to contribute a BNF, please do! But I'm very skeptical that
> it can be done, due to the many quirks of the syntax.

[https://github.com/jgm/CommonMark/issues/113#issuecomment-60...](https://github.com/jgm/CommonMark/issues/113#issuecomment-60467783)

~~~
dozzie
So it's basically as useless for general processing as Markdown, because you
won't have a grammar from which you can generate parser, hence all the parsers
will be handcoded with various quirks differing from one to another and none
of which will produce a parse tree.

------
mrottenkolber
The best decision would be to drop Markdown from everything and pretend it
never existed. Then design a similar format with a formal grammar, and use
that.

The sad thing is this won't happen. Given the traction I suspect there will be
broken, incompatible Markdown implementations 100 years from now. Markdown
really has the potential to become the worst universally popular standard in
computing history.

What bothers me is that its not one guy (Gruber) who made a mistake and
designed a language without a formal grammar (hey, mistakes happen), its that
armies of developers wrote broken parsers for a language without a formal
grammar. This is an impossible task, why did they not refuse to create
something fundamentally broken, by definition. Now there are apparently people
who want to standardize Markdown, _without_ a formal grammar. How can they not
realize that it will be _impossible_ to ever implement the standard? How do
they not see that what they are doing is professionally unethical?

~~~
jgord
Nooo.. it just needs a proper formal grammar adopted, that captures the best
of the common variants.

Then people can extend their tools to use that single variant and standard
parser/grammar.

Most [good] languages were implemented first without a formal grammar -
lex/yacc/bnf usually came later, if at all.

~~~
stewbrew
Markdown is quirk mode plain text. That was probably ok for its original
purpose but it is not for what it is used nowadays. There are much better
plain text like formats around and it's a shame markdown is in the position it
is now. IMHO a well-defined subset of LaTeX (or context) with almost plain
text markup for the 10 most commonly used commands would have been the better
solution on the long run.

------
jalfresi
Don't markdown files already have a MIME type of text/plain? Isn't that the
point of markdown?

~~~
deckar01
In the context of emails, I don't believe using a special MIME type for
markdown provides any benefit. Raw markdown is plain text and generated
content is HTML.

It seems interesting in the context of version controlled markdown files
written for a particular hosting platform's markdown flavor, but I don't think
a specification for identifying the flavor is the solution. This could be no
different than any other form of documentation that is generated by a script
or framework, but code hosting platforms have decided to make opinionated
decisions for a magical UX.

------
inlineint
I'm not sure wouldn't someone say that it is bloating of such simple format as
Markdown, but I really want to see embedding of TeX math formulas in Markdown
RFC/standard.

I'm talking about $\frac 3 4$ and $$\int x dx$$ notation. It is already
implemented in some Markdown parsers, such as Pandoc and Jupyter Notebook, but
because it is not standardized there are also a lot of parsers that don't
support it. I think that adding it to the RFC/standard would reduce friction
in math communications and make them more accessible, especially if Markdown
format become widely used for email communications.

------
c-smile
"Oh how many of them had fallen into that chasm..." (C) M. Tsvetaeva

Instead of markdown we need something what I name as flat structural text
format.

    
    
         <text>Base level text</text>
         <text li="disk">Bulleted list item</text>
         <text li="numeric">Numeric list item</text>
         <text li="numeric" level=2>Another list item</text>
         ...
         <text>Inline <span bold>bold</span><span bold italic>bold and italic</span></text>   
         ...
    

In this case it will be trivial[1] to write WYSIWYG editor that has 1:1
mapping between markup and screen representation.

That 1:1 mapping is mission critical for human editing - our mental model of
text is flat.

In fact that markdown is an attempt to provide such flat structural text
representation. Ugly one we shall admit.

Microsoft Word, AFAIU, uses also flat DOM model internally, that's why its
WYSIWYG is quite good.

HTML version 2 was last version that allowed unambiguous WYSIWYG editing of
HTML. The one that had no idea of CSS.

[1] [http://blocknote.net](http://blocknote.net) \- WYSIWYG HTML editor that
uses internal flat model.

~~~
crooked-v
This entirely misses the point of Markdown: that it's completely readable as a
document _without_ needing to apply any kind of visual formatting to it.

~~~
c-smile
> completely readable ...

That's very subjective and only in very simple cases. Like "markdown" version
here, on HN.

------
nicky0
> 1\. Dive into Markdown

Is that an obscure Mark Pilgrim reference or just a coincidence?

~~~
jschulenklopper
More than a coincidence, I think.

John Gruber wrote a post titled "Dive into Markdown",
[https://daringfireball.net/2004/03/dive_into_markdown](https://daringfireball.net/2004/03/dive_into_markdown),
and mentioned Mark Pilgrim in that post as well. It seems that John made a
pun, applying the well-known titles of Mark's books to Markdown.

I guess the RFC copies the post title (and the opening quote by Stanley
Kubrick) to pay an homage to John's start with Markdown?

~~~
nicky0
Also, at the time, Mark Pilgrim had a blog called "Dive into Mark".

------
kevin_thibedeau
Meanwhile Restructured Text chugs along with a more capable syntax designed
for extensibility from the start and without the problematic fragmentation of
dialects.

------
austincheney
[https://github.com/prettydiff/biddle](https://github.com/prettydiff/biddle)
Can parse markdown to formatted stdout (ANSI colors, wordwrap, and so forth)
on the console in both posix and Windows.

------
smartmic
I am still struggling with Markdown. In my opinion, the lack of a common,
standardized specification thwarts its practicability as universal internet
standard.

I still wonder why not more powerful markup languages like asciidoc spread
more.

------
glaberficken
Amateur question: Why can´t browsers just fetch a markdown file and render its
html representation? (is this what the article implies?)

~~~
verandaguy
Browsers implement well-defined web standards, which Markdown unfortunately
isn't. The original author, John Gruber (of daringfireball.net), hasn't been
too supportive of having a single, fixed Markdown standard, and this has
resulted in spinoffs with various syntaxes and features:

\- GitHub-flavoured Markdown

\- CommonMark

\- etc...

On top of that, there isn't even some meta-standard which would allow
hashbang-style preambles/doctype declarations to determine which version of
Markdown is being served.

So, between the fact that there's no fixed de-facto standard and no _de jure_
standard syntax or feature set recognized by any of the major standards bodies
(IETF being one of these), it would be impractical for browser vendors to
implement support for Markdown.

Finally, the standards that browsers implement take time both while being
defined, as well as while being implemented; these are things that will be
seen by _billions_ of people worldwide, and there's extremely little room for
error, so revisions are always necessary at every stage in development. For
example, work on HTML5 can be traced back as far as 2004, meaning that from
inception to release, development took about a decade.

~~~
Ajedi32
Couldn't they just adopt CommonMark? That flavor already has a complete spec
and test suite, and is specifically designed to be as compatible with existing
implementations as possible. I believe the only thing really missing is for
more of the community to start rallying around the standard.

~~~
verandaguy
Community engagement's a big part of it, though. I can define my own,
extremely thorough and well-documented standard for Markdown, and get, say,
all my friends to use it and provide feedback; that wouldn't make it popular
enough to be included in a browser.

------
xer0x
OMG wow! This could be really helpful!

------
slezyr

      ```
      function test() {
        return "notice this feature?");
      }
      ```
    

Ummm...

------
MBCook
Did anyone ask Gruber for his help in this? Or is this like the stupid attempt
at 'common markdown' a year or so ago to wrest 'control' out of his hands
because he was 'a terrible steward' (or whatever the quote was).

If a single guy invented the standard, and you're not involving him (or at
least getting his blessing), then this seems hostile.

I haven't seen him mention this on Twitter, which is what makes me wonder.

~~~
zeveb
I don't think Common Markdown was a stupid attempt; I thought it was a
praiseworthy attempt to standardise places where differing Markdown
implementations differ, needlessly harming interoperability.

I think that Gruber deserves a colossal amount of credit for inventing the
single-most-common end-user-usable marked-up-text format around. That's
independent of what he's done in the dozen years since December 2004, which is
the last update he made to his Markdown project's page.

~~~
hallman76
Gruber gets credit for creating it AND for holding it back. Markdown needs a
common standard. Gruber needs to hand Markdown over to folks who will let his
legacy shine.

~~~
jessaustin
You write "credit for... holding it back" in an ironic sense, but ISTM that's
really the only reason that markdown has seen wide adoption while numerous
other simple markup languages have not. There haven't been dozens of different
doodads grafted on at different times in different fashions to confuse users
and converters, so people just use it and it just works.

~~~
Ajedi32
> There haven't been dozens of different doodads grafted on at different times
> in different fashions to confuse users and converters

Oh, but there have. For instance, code fences are not part of the original
markdown spec, but are commonly supported in just about every implementation
out there, and are rendered in about [7 different ways][1] depending on which
converter you're using.

Play around for a little in BabelMark and you'll see why a standard is needed.

[1]:
[http://johnmacfarlane.net/babelmark2/?normalize=1&text=%60%6...](http://johnmacfarlane.net/babelmark2/?normalize=1&text=%60%60%60%0Acode+here%0A%60%60%60)

~~~
jessaustin
Well that's one doodad, and apparently it has had the effect I predicted.
Never mind, go ahead and have fun with your new super-markdown. One rather
doubts it will displace actual markdown anytime soon.

~~~
Ajedi32
That's exactly the problem: there is no "actual Markdown". Just a bunch of
mutually incompatible competing implementations.

If something like CommonMark had existed from the beginning, we wouldn't have
this issue because everyone would be following the standard.

