Virgil Arrington | 28 Oct 17:06 2014

SmartyPants and dashes

Please bear with me as I am just a user and, by no means, a developer. However, I've noticed some inconsistent behavior among different implementations of SmartyPants when it comes to en-dashes and em-dashes.

1. Calibre 2.7

When I recently uploaded a Markdown source file to Calibre and selected its "Smarten punctuation" feature, it converted a double-hyphen "--" into an em-dash, and a triple hyphen "---" into an en-dash. This behavior was the opposite that I have come to expect using both LaTeX and ReText, my default Markdown editor.

I reported the matter as a Calibre bug, but received a response saying that the Calibre behavior was based on the official SmartyPants source code, which states as follows:

"The string, with each instance of "--" translated to an em-dash HTML entity, and each "---" translated to an en-dash HTML entity. Two reasons why: First, unlike the en- and em-dash syntax supported by EducateDashesOldSchool(), it's compatible with existing entries written before SmartyPants 1.1, back when "--" was only used for em-dashes. Second, em-dashes are more common than en-dashes, and so it sort of makes sense that the shortcut should be shorter to type. (Thanks to Aaron Swartz for the idea.)"

Confused by this, I tested two other methods of using SmartyPants, and received inconsistent results.

2. Python Markdown v2.5.1

I use ReText as my Markdown editor. It uses the Smartypants extension that is provided with Python Markdown v2.5.1. It translates "--" as an endash and "---" as an emdash, the *opposite* as Calibre. Below is the translation table found at

ASCII symbol Replacements HTML Entities Substitution Keys
' ‘ ’ ‘ ’ 'left-single-quote', 'right-single-quote'
" “ ” “ ” 'left-double-quote', 'right-double-quote'
<< >> « » &laquo; &raquo; 'left-angle-quote', 'right-angle-quote'
... &hellip; 'ellipsis'
-- &ndash; 'ndash'
--- &mdash; 'mdash'

At the bottom of the Python/SmartyPants extension page is the following:

"SmartyPants extension is based on the original SmartyPants implementation by John Gruber. Please read it’s documentation for details."

Based on this, I went to Gruber's page and got yet more inconsistency.

3. SmartyPants by John Gruber.

At Gruber's SmartyPants page, ( the following is found:

"SmartyPants can perform the following transformations:
  • Straight quotes ( " and ' ) into “curly” quote HTML entities
  • Backticks-style quotes (``like this'') into “curly” quote HTML entities
  • Dashes (“--” and “---”) into en- and em-dash entities
  • Three consecutive dots (“...”) into an ellipsis entity"

Based on the order of the dashes listed, it would appear as if Gruber is suggesting that "--" would turn into an en-dash, and "---" into an em-dash (consistent with ReText, but not with Calibre). But, if I use Gruber's online Dingus translator (, I get yet a third variation of the conversion. Gruber's online translator converts "--" into an em-dash (as does Calibre) but it turns "---" into an em-dash plus a hyphen (no en-dash). 

There appears to be either confusion or disagreement in the Markdown/SmartyPants world as to how to create typographic dashes. Is there any way that the developers can come together on this very small part of the Markdown world?

Markdown-Discuss mailing list
Markdown-Discuss <at>

the issue with markdown was that it was too simple

> <at> chacon/living-the-future-of-technical-writing-2f368bd0a272

>   scott chacon, github cofounder, author of "pro git", on release of 
the second edition

>   The issue with Markdown was that it was too simple.
>   It didn’t specify things like table formatting, cross references,
>   indexing, callouts, source code examples, etc.
>   All of which Asciidoc does in a format that is just as easy to 

if you want to correct someone, correct scott chacon. he said it, not 


Markdown-Discuss mailing list
Markdown-Discuss <at>
Sean Leonard | 24 Oct 21:46 2014

Using fragment identifiers with Markdown docs

Hi Markdown folks:

I wanted to see if people have feelings or opinions about using fragment 
identifiers with Markdown (and Markdown-derivative, such as pandoc, 
kramdown, etc.) content.

It is useful to say things like

So that a Markdown editor could scroll to the right content.

To my mind, the prime candidates for this treatment are the [link 
reference identifiers][lref] and for some formats, the attributed text 
{#blahblah }. Link reference identifiers are part of the original 
Markdown syntax. On the other hand, they don't produce any identifiers 
in HTML/XHTML. Clearly attributed text is useful to identify both 
Markdown and output regions.



mofo syne | 24 Oct 10:25 2014

markdown for speech synthesis?

Have anyone ever considered the possibility of using markdown to
perform speech synthesis markups?

Just a thought:

There is already a speech synthesis markup language call SSML:

However I do wonder if there is a need to perhaps consider what a
markdownish speech synthesis markup language may look like. I don't
think you can exactly use markdown syntax to do speech synth. Take for
example sarcasm, you can't exactly do it in pure text markup.

So far what I can think of:

* `...` :-- indicates pause in speech
* `*` :-- can be used to ephasis words in speech
* `\<switch>` :-- at end of the line indicates how entire sentence
should be carried out
 * `You must reallly love to be a good guy /s`
* `"scare quotes"` :-- Or maybe sarcasm is better done as scare quotes
`"` around the sarcastic expression?
* `:D` :-- emotion icons can perhaps be used to indicate previous
statement should be carried out in a certain tone. e.g. ` This really
doesn't make me feel good D: `
* `--> #id <--` :-- Allows the speaker to 'point' to a particular
section in a page?

What is your thoughts on this? If this can be included alongside or
inline with a markdown page, it might have some useful applications,
like say a modifiable automatic lecturer.


Here's a link to the current discussion page:

just announced

this was just announced, from
the folks who do


in a related note, i have finished
my "beyond markdown" series...
> <at> bbirdiman/beyond-markdown-part-11-444393af1ed0

i put up a web-app as a playground.

Sean Leonard | 18 Oct 01:35 2014

New Version Notification for draft-ietf-appsawg-text-markdown-03.txt

And here is the other.


From: internet-drafts <at>
Subject: New Version Notification for draft-ietf-appsawg-text-markdown-03.txt
Date: October 17, 2014 at 4:33:52 PM PDT

A new version of I-D, draft-ietf-appsawg-text-markdown-03.txt
has been successfully submitted by Sean Leonard and posted to the
IETF repository.

Name:		draft-ietf-appsawg-text-markdown
Revision:	03
Title:		The text/markdown Media Type
Document date:	2014-10-17
Group:		appsawg
Pages:		22

  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.

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at

The IETF Secretariat
Sean Leonard | 18 Oct 01:33 2014

New Version Notification for draft-seantek-text-markdown-use-cases-00.txt

Here is one.

From: internet-drafts <at>
Subject: New Version Notification for draft-seantek-text-markdown-use-cases-00.txt
Date: October 17, 2014 at 4:21:21 PM PDT

A new version of I-D, draft-seantek-text-markdown-use-cases-00.txt
has been successfully submitted by Sean Leonard and posted to the
IETF repository.

Name:		draft-seantek-text-markdown-use-cases
Revision:	00
Title:		text/markdown Use Cases
Document date:	2014-10-17
Group:		Individual Submission
Pages:		20

 This document elaborates upon 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.
 Background information, local storage strategies, and additional
 syntax registrations are supplied.

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at

The IETF Secretariat
Sean Leonard | 18 Oct 01:31 2014

text/markdown draft-03 guide (and use-cases-00 guide)

Hello Markdown World:

The following Internet-Drafts are about to be posted:


As discussed in apps-discuss <at> to make the drafts shorter yet more informative, I split them in
two. The secondary document has seven additional syntax registrations, background information, and
preservation strategies. The main registration document registers the media type. They are meant to be
read together; however, the secondary document makes no normative statements (no RFC 2119 key words).

  1. Introduction
  2. Markdown Media Type Registration Application
  3.  Optional Parameters
    3.1. syntax
    3.2. output-type
  4. Fragment Identifiers
  5.  Example

1. (Introduction)
    1.1. On Formats
    1.2. Markdown Design Philosophy
    1.3. Uses of Markdown
    1.4. Uses of Labeling Markdown Content as text/markdown
  2.  Strategies for Preserving Media Type and Parameters
  3.  Registration Templates for Common Markdown Syntaxes
    3.1. MultiMarkdown
    3.2. GitHub Flavored Markdown
    3.3. Pandoc
    3.4. Fountain (
    3.5. CommonMark
    3.6. kramdown-rfc2629 (Markdown for RFCs)
    3.7. rfc7328 (Pandoc2rfc)
  4.  Examples for Common Markdown Syntaxes

Thank you,

Sean Leonard | 10 Oct 17:56 2014

(text/markdown) link label vs. link identifier and last-one-wins

In working on the text/markdown spec, I am making a reference to the syntax of links, specifically the things [1] and [Google] used in this construct:

Hello I am some [Markdown][1] and I use [Google][].

[Google]: "This is Google"

What is the common Markdown way of identifying this syntax element?

stmd (CommonMark) consistently calls it the "link label". (To be clear, it also calls [Markdown] a link label, even though that element does not have the same behavior as [1].)

However, [Markdown Syntax][MDSYNTAX] refers to it once as a "link identifier" in the bullet point: "Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces)". Elsewhere it refers to it as a label. For example: "Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link" and "Then, anywhere in the document, you define your link label like this, on a line by itself".

I reviewed, which consistently uses the variable name $link_id (see also $g_urls, and comments such as # Link defs are in the form: ^[id]: url "optional title").

On this basis, I am going to call it "link identifier". Questions?

Also, seems to define last-wins behavior: the last link definition is indexed as the definition in $g_urls. (See _StripLinkDefinitions.) Older ones get overwritten by newer ones. Is this common or normative behavior? How do other implementations do it?

It's important that I keep the original reference list short; I would rather not refer normatively to documents other than Gruber's own Markdown rules.


Markdown-Discuss mailing list
Markdown-Discuss <at>

maybe we should discuss it

in terms of my last post here:


i was intrigued to see this today:


this mirrors earlier flipboard tech:


p.s.  by now, you might have figured out that
you can search twitter for "beyond markdown".
mofo syne | 4 Oct 05:34 2014

Sub reddit for general discussion on lightweight markup languages

If anybody is a reddit user, let me know, I might need a few moderators.

Might want to also update the sidebar with useful information.