on the philosophical aspects of a specification

[Seumas Mac Uilleachan]

david parsons wrote:

> In article <47CD5989.2020006 at idirect.ca>,

> Seumas Mac Uilleachan  <markdown-discuss at six.pairlist.net> wrote:

>   

>> david parsons wrote:

>>     

>>> In article <d5d.1e15ea7e.34fdd932 at aol.com>,

>>>  <markdown-discuss at six.pairlist.net> wrote:

>>>       

>

>   

>>>> however, implementers can reach agreement easily,

>>>> by leaving users out in the cold, brushing them off

>>>> with a "you will need to follow the spec" which seems

>>>> -- if i understand markdown's cornerstone correctly --

>>>> to be outside gruber's comfort range for his creation...

>>>>         

>

>   

>>>     If a user says "I want paragraphs to start with an explicit

>>> paragraph symbol and all newlines to force a <br/>" , I *will* brush

>>> them off with a "you will need to follow the spec" because that's not

>>> how Markdown works.    I can't imagine any other way to actually write

>>> the language.

>>>       

>

>   

>> [...] What we care about is that the original intent of our written 

>> source is maintained.

>>     

>

>

>    I'm not surprised when

>

> 1986.  What a great season.

>

>    generates a list item, because the existing spec tells me that

>

>    ``[...]a _number-period-space_ sequence at the beginning of a line[...]''

>

>    will trigger an ordered list.

>

>

>

>

>    But what's the intent of ***hello*, sailor**   ?

>   

The stated spec says text wrapped in one * is emphasis, two ** is strong.


>    Should it produce 

>     1. <strong><em>hello</em>, sailor</strong>

>     2. <strong>*hello*, sailor</strong>

>     3. *<strong>hello*, sailor</strong>

>     4. ***hello<em>, sailor<strong>

>     5. ***hello*, sailor**

>     6. <em><strong>hello</strong></em><strong>, sailor</strong>

>     7. <em><strong>hello</em>, sailor</strong> (which makes baby XML cry) ?

>   

Item 4 only makes sense if the source is taken out of context (a 
"snippet"), and then how do we know? Items 2-5 all assume some *'s are 
literal which doesn't follow the spec if the text is wrapped. Items 1,6, 
and 7 all render the same in the browser and the choice of which is up 
to the implementation (following the syntax spec).

>    How about **Hello, sailor ?

>   

Is this a snippet? if not, then the text is not wrapped and the syntax 
does not apply.

>    Is it <strong>Hello, sailor, **Hello, sailor, or <em></em>Hello, sailor?

>

>    And how about _________cut here_________ ?

>   

This is a problem. Anything more than 4 _ per side does not render but 
with 4 it does (in PHP) if you have ____cut here____ are you expecting 
it to be converted to <em><strong><em>cut here</em></strong></em> ?

>

>    Formal specifications are written to avoid surprises in the

>    implementations;    As a user (and there's no way I'd have written an

>    implementation if I wasn't a user) of the language I'd like to avoid

>    surprises when I go between the markdown documents on my website,

>    posts on my weblog, or posts on someone else's wiki and/or weblog.

>   

I did not say that a formal spec was a bad idea. A formal **syntax** 
specification that is clear and unambiguous is where we need to start, 
without losing sight of the great usability that Markdown has right now. 
The biggest problem is that the syntax is ambiguous. The biggest 
strength is that the syntax is flexible (0,1,2 or three spaces at the 
start of a list).

And speaking of ambiguous

  * List
 * List
  * List
   * List
  *  List
 *   List
  *  List
   * List

converts to:

<ul>
<li>List

<ul>
<li>List</li>
</ul></li>
<li>List

<ul>
<li>List</li>

</ul></li>
<li>List

<ul>
<li>List</li>
</ul></li>
<li>List

<ul>
<li>List</li>
</ul></li>

</ul>

which shows up as:


    * List
          o List
    * List
          o List
    * List
          o List
    * List
          o List

What was the intent here? I would suggest more like

    * List
    * List
    * List
          o List
    * List
    * List
    * List 
          o List

Since only the 4th and 8th are indented 4 spaces.