Discussion:
A reminder of the original design goal of Markdown - my personal thoughts
Fletcher T. Penney
2005-09-03 19:44:45 UTC
Permalink
The overriding design goal for Markdown’s formatting syntax is to
make it as readable as possible. The idea is that a Markdown-
formatted document should be publishable as-is, as plain text,
without looking like it’s been marked up with tags or formatting
instructions. While Markdown’s syntax has been influenced by
several existing text-to-HTML filters, the single biggest source of
inspiration for Markdown’s syntax is the format of plain text email.
-- from the Markdown web page

The latest talk of classes and id's reminded me of the original
purpose of markdown as I understood it, and as described on John's
web site. I realize that just because additional features are added
does not mean that I **have** to use them, but it does begin to wear
into the beauty of the Markdown syntax to see it become (almost) as
complicated as XHTML.

First, I want to say that I do think there is room for improvement in
the Markdown syntax. But I am not certain that recent proposals have
been keeping in line with the original stated goals of Markdown.
(Actually, I remember bringing this up a year or two ago on this very
list... ;)

I would like to suggest that we think about what it was that drew us
to using Markdown in the first place. When one's needs start getting
too complicated, requiring the addition of more and more ways of
"sneaking" markup in, that's when you go back to XHTML. That's what
XHTML was designed for.

I would like to see Markdown remain true to it's original intent. A
plain text syntax for structured documents that reads **AS IS**.
It's this simplicity that makes Markdown so attractive to me.

I would like to see support for footnotes (of some sort, there does
not need to be a whole battery of footnote, citation, end-notes,
etc), and I think it can be done in a manner consistent with
Markdown's original design goal.

I would like to see support for header anchors, and I would rather
see this approach:

### Inline HTML ###
becomes
<h3 id="inlinehtml">Inline HTML</h3>

than this approach:

## Header ## {#head2}

I find the second version to be distracting when read as raw text,
and it certainly doesn't follow the original idea of not "looking
like it’s been marked up with tags or formatting instructions."

The final word is John's, but I would like to voice my support for
simplicity and elegance. That's what drew me to Markdown, and where
it's true strength lies. I think that further additions should be
made with this original goal in mind.

Otherwise, I envision myself (and other "purists" if there are any)
creating a "Markdown Lite" that removes any additions that don't fit
the original plan. If the project is going to deviate from this
plan, I believe it should at least deviate on purpose. Not through
the slow unchecked feature-bloat of time.

Just my $0.02...

Fletcher
--
Fletcher T. Penney
***@alumni.duke.edu

A good scapegoat is nearly as welcome as a solution
to the problem.
Mark Smith
2005-09-03 20:14:07 UTC
Permalink
Post by Fletcher T. Penney
I realize that just because additional features are added
does not mean that I **have** to use them...
[...]
Post by Fletcher T. Penney
I would like to see Markdown remain true to it's original
intent. A plain text syntax for structured documents that
reads **AS IS**. It's this simplicity that makes Markdown so
attractive to me.
The final word is John's, but I would like to voice my
support for simplicity and elegance. That's what drew me to
Markdown, and where it's true strength lies.
[...]
Post by Fletcher T. Penney
Otherwise, I envision myself (and other "purists" if there
are any) creating a "Markdown Lite" that removes any
additions that don't fit the original plan.
Point taken on the whole (Markdown needs to stay elegeant and legible in its input form), but I don't follow your progression from conceding that you don't have to use "extras", to arguing for a "lite" fork. I think that producing side projects is a good way to damage the coherence and elegance of the syntax. Better IMO to add in those things necessary for Markdown to become a sufficiently complete "writing for the web" syntax, than to have a bunch of side projects containing a subset of the full syntax. Its not as if its likely to turn into a behemoth like Docbook after all.

Also 0.02,

mark.
A. Pagaltzis
2005-09-03 21:30:45 UTC
Permalink
When one's needs start getting too complicated, requiring the
addition of more and more ways of "sneaking" markup in, that's
when you go back to XHTML. That's what XHTML was designed for.
Except you can’t go back to HTML for just the bits you need,
because once you have a block-level element in there, Markdown
takes its ball and goes home. There’s good reason for that, but
it means you have to either restrict yourself to exactly as much
as Markdown provides and *not a whiff* more, or write HTML, lock,
stock and barrel.
I would like to see Markdown remain true to it's original intent. A
plain text syntax for structured documents that reads **AS IS**.
It's this simplicity that makes Markdown so attractive to me.
The fact that Markdown has a escaping backslash kind of shatters
your argument. And I often find myself in need of it to get
Markdown to interpret emotes correctly. \*sigh\*

Besides, that is kind of a fallacious argument, because if you
need something that Markdown syntax cannot express, say you want
to

Center An Important Point For Emphasis

then you need to write HTML. HTML doesn’t look much like
plaintext, does it?

Fact is, Markdown is not plaintext. It is a simplified XHTML
authoring syntax, any way you turn it. It tries to look as much
like plaintext as possible, *for the common uses*; and the point
is to try and hit the 80/20 spot. Currently, Markdown is more at
65/5, and that is pretty good, but it can do better.

I use Markdown all the time when I write comments on weblogs; the
HTML I need there is so minimal that Markdown is always
sufficient. But I use more “advanced” HTML features (it’s kind of
laughable to call them that) so frequently in my own weblog’s
entries that Markdown is almost useless.

Having attribute syntax would make every HTML construct involving
supported tags expressible directly in Markdown, without having
to abdicate all of the Markdown simplicity as soon as you need
the vaguest bit of uncatered-for output. You can always go in
afterwards and add more plain-looking syntax for those constructs
which will really benefit from being native citizens.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>
Michel Fortin
2005-09-05 17:36:31 UTC
Permalink
About these two forms:

<h3 id="inlinehtml">Inline HTML</h3>

### Inline HTML ### {#inlinehtml}
Post by Fletcher T. Penney
I find the second version to be distracting when read as raw text,
and it certainly doesn't follow the original idea of not "looking
like it’s been marked up with tags or formatting instructions."
I disagree. I find the second form less "marked up" and more readable
than than the first. The reason is that the header content (Inline
HTML) is placed first and isn't mixed with had-to-read metadata. The
id attribute is somewhat left-aligned and can more easily be ignored
as "markup" than in the first form where everything is packed and the
id attribute is shown first.

I think this the id attribute for headers makes a lot of sense since
you need it to make links to different parts of a document. Event the
Markdown syntax description document needs this. So it *is*, in my
view, pretty necessary.

Well, we could argue that what is really necessary is a way to link
to headers, not to set manually the id attribute of each one. But
there is many reasons to not want automatic id generation: What
happen to internal links if you change slightly the name of one
header? Will adding a new section in the middle of the document break
outside links to other headers? These two problems cannot appear if
you set your own id and do not change them.

Now, I also think you have a good point: there is no reason to allow
this syntax everywhere if it is not needed. While I think the id
attribute is pretty necessary for headers, I'm less sure about other
attributes and other elements. Currently, I see these as "important":

* Cite attribute for blockqutoes
* Image width and height (maybe)
* Class attribute (do we need this absolutely everywhere?)

(Did I forgot something?)
Post by Fletcher T. Penney
Otherwise, I envision myself (and other "purists" if there are any)
creating a "Markdown Lite" that removes any additions that don't
fit the original plan. If the project is going to deviate from
this plan, I believe it should at least deviate on purpose. Not
through the slow unchecked feature-bloat of time.
I think for that to be successful, such a Markdown Lite would need to
be either

1. significantly faster that a "bloated" Markdown; or
2. standard Markdown would need to cause enough trouble to people
not using the "advanced features" to make them switch.

The first condition will probably be hard to achieve without a total
rewrite since I think the parts of Markdown that are most time-
consuming right now are for working around inline HTML. This include
HTML produced by Markdown's own conversion of its syntax, so you
cannot remove inline HTML support and say it will run faster.

The second condition presume a Markdown with more features will be
less usable. I somewhat doubt this: the Markdown syntax says you
don't have to use every features and I don't see this changing. If
you prefer to write `<strong>` instead of `**`, do it; if you prefer
to write `<h3 id="somehting"></h3>` instead of `### {#something}`,
just do so.


Michel Fortin
***@michelf.com
http://www.michelf.com/
Yuri T.
2005-09-05 18:51:13 UTC
Permalink
Post by Michel Fortin
Well, we could argue that what is really necessary is a way to link
to headers, not to set manually the id attribute of each one. But
there is many reasons to not want automatic id generation: What
happen to internal links if you change slightly the name of one
header? Will adding a new section in the middle of the document break
outside links to other headers? These two problems cannot appear if
you set your own id and do not change them.
I think a good solution here would be to have automatic id generation that
could be overriden with an implicit {#...} code. So, for instance,

### My Header

would produce

<h3 id="myheader">My Header</h3>

while

### My New Header {#whatever_it_was_before}

would procude

<h3 id="whatever_it_was_before">My New Header</h3>

This way the most of the documents can avoid the {#...} syntax, but it would
still be there for you if you want.

As for class attributes, I've been wondering if it might make sense to allow
people to style differently lists, etc. that are marked with different
symbols Let's suppose that *text* produced <em class="md_star">text</em>
while _text_ produced <em class="md_underscore">text</em>. This would give
the user a simple and clean way of marking up two different kinds of
emphasys. (E.g., I could *text* for original emphasis in quotations and
_text_ for _my_ emphasis, which would allow me to style them differently
later.) The same applies to lists: if you have two kinds of lists, you can
mark some with asterisks and others with hyphens. Note that none of this
hurts the user who wants to treat *...* and _..._ as the same, since that's
what they would get by default.

- yuri
Fletcher T. Penney
2005-09-05 18:51:38 UTC
Permalink
Post by Fletcher T. Penney
<h3 id="inlinehtml">Inline HTML</h3>
### Inline HTML ### {#inlinehtml}
Post by Fletcher T. Penney
I find the second version to be distracting when read as raw text,
and it certainly doesn't follow the original idea of not "looking
like it’s been marked up with tags or formatting instructions."
I disagree. I find the second form less "marked up" and more
readable than than the first. The reason is that the header content
(Inline HTML) is placed first and isn't mixed with had-to-read
metadata. The id attribute is somewhat left-aligned and can more
easily be ignored as "markup" than in the first form where
everything is packed and the id attribute is shown first.
You misunderstood - the markup text for version 1 is:

### Inline HTML ###

The markup text for version 2 is:

### Inline HTML ### {#inlinehtml}

The output for both would be:

<h3 id="inlinehtml">Inline HTML</h3>


Clearly, the first version has less markup (i.e. none). Both could
be referenced by linking to "#inlinehtml".
Post by Fletcher T. Penney
I think this the id attribute for headers makes a lot of sense
since you need it to make links to different parts of a document.
Event the Markdown syntax description document needs this. So it
*is*, in my view, pretty necessary.
I agree that headers are important. I just think they can be done
automatically, without adding any markup to the raw text (re-read my
original post).

Check out my wiki page for the Markdown Syntax to see my version in use:

http://fletcher.freeshell.org/wiki/MarkdownSyntax

And then view the raw text. The outline at the top is all done
without any embedded HTML or id tags.
Post by Fletcher T. Penney
Well, we could argue that what is really necessary is a way to link
to headers, not to set manually the id attribute of each one. But
there is many reasons to not want automatic id generation: What
happen to internal links if you change slightly the name of one
header? Will adding a new section in the middle of the document
break outside links to other headers? These two problems cannot
appear if you set your own id and do not change them.
At some point, you have to say "This document is too complicated for
Markdown... Time for me to handcode it, or use another tool."
Remember, Markdown was not (originally) designed to be a replacment
for (X)HTML. I feel like that is what it is headed towards (which,
to reiterate, is John's call. I'm expressing my opinion that I think
that would be a mistake, but that is only my opinion.)
Post by Fletcher T. Penney
Now, I also think you have a good point: there is no reason to
allow this syntax everywhere if it is not needed. While I think the
id attribute is pretty necessary for headers, I'm less sure about
other attributes and other elements. Currently, I see these as
* Cite attribute for blockqutoes
Agreed, but I think it can be done in a manner that "emulates" plain
text/email methods, in other words something that doesn't look like
markup tags.
Post by Fletcher T. Penney
* Image width and height (maybe)
My vote would be no on this - again, if you are finding this
necessary for precise page layout, it might be better to use another
tool/ handcode the XHTML.
Post by Fletcher T. Penney
* Class attribute (do we need this absolutely everywhere?)
I would argue not - again, the (original) goal of Markdown was not to
rewrite XHTML. This may have changed, but then I feel it is opening
a niche that the original markdown filled perfectly - a lightweight,
highly human readable syntax to do 90% of what you need on for a
basic text-based HTML document.
Post by Fletcher T. Penney
(Did I forgot something?)
Post by Fletcher T. Penney
Otherwise, I envision myself (and other "purists" if there are
any) creating a "Markdown Lite" that removes any additions that
don't fit the original plan. If the project is going to deviate
from this plan, I believe it should at least deviate on purpose.
Not through the slow unchecked feature-bloat of time.
I think for that to be successful, such a Markdown Lite would need
to be either
1. significantly faster that a "bloated" Markdown; or
2. standard Markdown would need to cause enough trouble to people
not using the "advanced features" to make them switch.
The first condition will probably be hard to achieve without a
total rewrite since I think the parts of Markdown that are most
time-consuming right now are for working around inline HTML. This
include HTML produced by Markdown's own conversion of its syntax,
so you cannot remove inline HTML support and say it will run faster.
The second condition presume a Markdown with more features will be
less usable. I somewhat doubt this: the Markdown syntax says you
don't have to use every features and I don't see this changing. If
you prefer to write `<strong>` instead of `**`, do it; if you
prefer to write `<h3 id="somehting"></h3>` instead of `###
{#something}`, just do so.
I don't think a "Markdown Lite" would be successful in the sense of
pulling people away from using Markdown, nor is that in any way my
purpose. I think it would be successful in the sense that I (and
maybe 1 or 2 other people... ;) would prefer to use a tool that
sticks to the original purpose Markdown filled, and keep things simple.

From the beginning of this thread, I have expressed the
understanding that just because a feature exists, doesn't mean I have
to use it. I am, of course, free to stick to the basics, no matter
how much feature bloat Markdown acquires. The problem is that I
would like to continue to create other tools centered around Markdown
(e.g. MultiMarkdown) that use the Markdown syntax as the central
document form for other purposes, including human reading of the raw
plain text. And for that to be consistent, I want to avoid creating
documents with lots of unnecessary markup in them, that are then
incompatible with other Markdown syntax based tools. So for my
purposes, even if no one else in the world cares, I could foresee
creating a Markdown Lite (which, in reality would probably just be a
version freeze of the original Markdown). This would allow all of my
documents to be compatible with the other tools, regardless of what
other features get added to the newest version.

This isn't a plea of "That feature is not necessary for me, therefore
it is unnecessary for everybody." It's simply a statement that I
support Markdown's original purpose

When I first discovered Markdown, I was thrilled that there was a
simple, straightforward, intrinsically readable format for converting
plain text to HTML. I looked at other syntaxes, especially those
that seemed to be more popular, or those that had more accessory
utilities built around them. Other languages have had converters to
pdf's for quite a while. For markdown, I had to write my own. But I
enjoyed writing it, because Markdown (as it stands) is a wonderfully
straightforward syntax that accomplishes it's goal with style and
simplicity. I hate to see that get lost in the drive make it fit
every purpose under the sun.

F-
--
Fletcher T. Penney
***@alumni.duke.edu

If I were two-faced, would I be wearing this one?
- Abraham Lincoln (1809-1865)
Michel Fortin
2005-09-05 22:02:26 UTC
Permalink
Post by Fletcher T. Penney
### Inline HTML ###
### Inline HTML ### {#inlinehtml}
<h3 id="inlinehtml">Inline HTML</h3>
Clearly, the first version has less markup (i.e. none). Both could
be referenced by linking to "#inlinehtml".
Sorry. In this case I can't argue: version 1 has less markup and
surely is ideal when reading markdown text directly.
Post by Fletcher T. Penney
I agree that headers are important. I just think they can be done
automatically, without adding any markup to the raw text (re-read
my original post).
That would be ideal. However, I believe this will often produce sub-
optimal ids. As an example, in the syntax document on your wiki I can
find this id "automaticescapingforspecialcharacters" which is much
too long. Just as an ideal weblog software allow you to choose your
own "slug" for an entry (because clean URL matters), you should be
allowed to write your own ids too.

And I would add that a small change in the text of one header will
break every link to that header in the document or in other documents.

I'm also particularly interested to see what an automatically given
id would be like given Japanese text in the header, or accented
letters as found in many languages.

Finally, as John previously mentioned, id collisions can happen.
Isn't that enough reasons to not generate an id attribute automatically?


Michel Fortin
***@michelf.com
h