A reminder of the original design goal of Markdown - my personal thoughts

[Fletcher T. Penney]

On Sep 5, 2005, at 1:36 PM, Michel Fortin wrote:


> About these two forms:

>

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

>

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

>

> Fletcher T. Penney wrote:

>

>

>> 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".



> 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.


> 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.)


> 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


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.


> *   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.


> *   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.


> (Did I forgot something?)

>

>

>> 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
fletcher at alumni.duke.edu

If I were two-faced, would I be wearing this one?
     - Abraham Lincoln (1809-1865)


-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 3949 bytes
Desc: not available
Url : http://six.pairlist.net/pipermail/markdown-discuss/attachments/20050905/9613352f/smime.bin