Markdown Extra Specification (First Draft)

Sherwood Botsford sgbotsford at
Tue May 6 18:18:53 EDT 2008

As a suggestion for the next pass at this, add an example of each, and
how it should be rendered.
I found fireball's web site fairly lucid for this.

Example abbreviation definition
*[TLA] :Three Letter Acronym

Note, If I'm reading this correctly then
* [TLA]: Three Letter Acronym

would be incorrect, as there is a space after the asterisk and after the
It's also not clear if this critter has to appear on a line by itself.

If the abbreviation is long enough that it spans line ends, is that ok?

* [ODITLOID]: A Day in the Life of Ivan
Denisovich (Alexander Solzhenitsyn)

A lot of the critters that appear as references aren't clear about how they
appear in the text, and how they appear when resolved. The footnote
dfinition starts with [^ but does the footnote in the text also start
that way?

2.2.1 Link Reference

A link reference is alone on a line. It begins with the reference name
inside square brackets, optionally followed by a space or a
no-break-space, a colon, a URI (either enclosed in angle brackets or
not), and an optional title enclosed in single or double quotes, or in
parenthesis (which can be preceded by a newline).

four things:
1. Sometimes the link is *(@*&^(^ long. So if I'm editing with vi, I
have everything else in 60-70 column
lines, then this great bloody honker. I'd like an optional syntax for
breaking a long URI into chunks.

Eg. the usual unix convention of \ with optional trailing whitespace
means continued on next line, with the \ and whitespace going to the bit

2. I'd like some way to hook references to an external file, or database
lookup instead of doing them internally.

3. Why three versions of quoting characters for the title?

4. Why the <> around the URI?

5. Only if you put the title in () can you start on a newline?

2.2.2 Abbreviation
Again, I'd like a hook so that I can put these in an external file. In
my tree farm web page I'd like to use botanical descriptions, but be
able to let users see the definition on mouse over or click. But the
word 'glabrous' may appear on 40 pages. Be nice if I only had to define
it once. If someone is creating an annotated Shakespeare they would want
to use an Elizabethan English dictionary as their external file, style
it so that defined words are barely different from the text, and let the
confused reader click for enlightenment.

2.2.2 footnotes

Note possible numbering error both abbreviation and footnotes are 2.2.2

How does the footnote appear in the text? For clarity in reading, all
the things that refer to something else
should be visible different. E.g. In markdown we presently have
[link text ][LINKREF]
![Image alt text][IMGREF]
^[FOOTNOTE] (although I'd prefer _[FOOTNOTE] as it tells me it's below
the ruler line at the bottom of the page)
Except from your text it appears it should be [^FOOTNOTE] which is at
odds with the image and abbreviation
How are footnotes numbered?

I think you could make a case for a footnote being the child of the
block element that the reference appears in.
This may potentially allow clever people with CSS to have the footnote
appear as a sidebar div, adjacent to the reference.

2.3.7 Table syntax

Suggested syntax
[TT] Table title

|[TH] elements | separated by pipes | with white space | on either side |

| anything | that | appears | with | leading and trailing |

| is | formated | as a | table row|

|> This cell spans two columns | and | so forth|

| This cell also spans two columns <| and | so forth|

|>> This cell spans three columns | in the | table |

| This cell spans two rows | in the | table|

| " " | because it has ditto marks | in the cell below |

Since many tables are done without a title or header, the pipe syntax is
the usual.
You can spent some time pretty printing it.
Suggested implementation would have warnings when the number of cells
per row is inconsistent.

2.4.2 and 2.4.3 Emphasis and strong emphasis.
The current markdown uses either _ or * for emphasis and any combination
of the two
doubled for strong emphasis. I suggested that * be used for strong
(default bold) and _ be used for emphasis.
(default italic) This gives three combinations possible with the same
set of symbols, and fits the general
intuitive nature of markdown.

2.4.6 Hard line break
This one bites me regularly, as I learned to touch type in high school
and to end a sentence with
a period followed by two spaces. This means that every time I end a
sentence on a line end, I
get an involuntary break. Lots of head scratching over this one. I don't
like markup that depends on invisible
trailing characters.

I would favour ending a line with a forward slash. You sometimes see
this in poetry where line length exceeds
the column width. And it has an easy mnuemonic: If a back slash means
concatenate the next line onto this one
then forward slash means, force the line break here.

Thus my address would appear

Sherwood Botsford /
RR 1 Site 2 Box 5 /
Warburg, Alberta T0C 2T0 /

I would propose that any amount of white space surrounding the / would
be allowed. So if you wanted
to add extra space so the /'s would line up, you could.

Abbreviation is element 2.2.2 and 2.4.7 Is this correct? It is both a
document element and a span
element? Ditto Link. Will this cause trouble for designing the parser?

More information about the Markdown-Discuss mailing list