Re: list corner case

[Aristotle Pagaltzis]

* Albert Skye <[EMAIL PROTECTED]> [2008-09-09 08:00]:
> Markdown syntax presents a strong pattern of using blank lines
> to separate elements.

> Does it?

> I hadn’t noticed.

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Aristotle Pagaltzis]

* [EMAIL PROTECTED] <[EMAIL PROTECTED]> [2008-09-09 07:45]:
> jacob said:
> >   This entirely contradicts Markdown's purpose and philosophy.
> 
> and aristotle agreed:
> >   That is my opinion too.
> 
> it _might_not_ (or might) be in alignment with the "purpose and
> philosophy" of markdown, but hey, it does not "contradict" it,
> _certainly_ not "entirely".
> 
> this is what gruber says under "markdown philosophy":
> >Markdown is intended to be as easy-to-read and
> >easy-to-write as is feasible. Readability, however, is
> >emphasized above all else.
> 
> he continues:
> >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.
> 
> if the intent is ambiguous -- and it _clearly_ is ambiguous,
> since no one here can state unequivocally what was meant, which
> is why there are competing interpretations at work -- then the
> document certainly will not be _readable_, let alone
> "publishable as-is". so it's out of the realm of the
> philosophy.

With due respect I have to say it seems to me you are utterly
misinterpreting the second paragraph you quoted. My reading is
that “publishable as-is” refers to it not “looking like it’s been
marked up with tags or formatting instructions.” Simply put, all
it says is that Markdown documents should not look like code –
unlike HTML, which does.

Furthermore, regardless of whether you are claiming that a
document is readable or not, I know that as a human I have no
trouble extracting some meaning from any of the examples given
in this thread. Certainly if they contained real text, I would
have even less trouble to understand what the author meant, based
on contextual cues like, oh I dunno, *what the text says*.

My interpretation of the Markdown philosophy is that plaintext
documents have inherent meaning to humans, and the rules of the
syntax should be designed to infer that meaning correctly. You’ll
recall [1] that John’s motivation for designing Markdown was the
tedium of the common tasks in writing HTML by hand – putting in
tags for paragraphs, emphasis, quoting, etc. “It’s 2004.
Shouldn’t your computer be able to determine where you’ve written
paragraphs and sub-heads?” Obviously, the formatter should try
its best to reflect the structure of the written prose with the
appropriate means of HTML.

Imagine that someone was nice enough to buy you a gift: an
original typewritten manuscript for a classic novel. Let’s
say Fitzgerald’s “The Great Gatsby”. You could sit down with
this manuscript and read it, straight through, and get pretty
much the same reading experience as you would when reading it
in the form of a nicely bound and typeset book. Yes, it would
all be set in the typewriter’s smudgy fixed-width
Courier-esque typeface, with underlining instead of italics,
etc. — but the words would still flow, from page to mind,
just as Fitzgerald intended.

Is there such a thing as an invalid classic novel? So how can
there be such a thing as an invalid Markdown document?

The quote from Stanley Kubrick I used to start this article
is one of my very favorites. When you write and read text
that’s marked-up with HTML tags, it’s forcing you to
concentrate on the *think* of it. It’s the *feel* of it that
I want Markdown-formatted text to convey.

I can find no way to reconcile the above with your claim that
ambiguous writer’s intent puts a source document outside the
realm of Markdown’s philosophy of publishability.

[1]: http://daringfireball.net/2004/03/dive_into_markdown

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Albert Skye]

The input has differing markers; presumably, the author (user) intended some 
kind of semantic distinction. This rules out (a). (It could be argued that the 
author is sloppy/lazy but I think supporting that kind of sloppiness/laziness 
is deplorable, which is why I deliberately use the word "author" instead of 
"user").

It may seem preferable to *require* indentation for nesting, but it isn't 
*necessary* (with only list or inline contents). Markdown syntax presents a 
strong pattern of using blank lines to separate elements. Presumably, the 
author intended some kind of semantic significance by joining (not separating) 
the lines. This rules out (c).

Consider this example:

1. Albert
- flowers
- bicycle

2. Lucy
- food
- water
- wine

The intention seems clear enough: each item in the ordered list has a 
subordinate unordered list. Further, if the author is using differing markers 
within an *un*ordered list, it is likely to be semantically significant.

* Albert
- flowers
- bicycle

* Lucy
- food
- water
- wine

I imagine this interpretation may be distasteful to implementers because it 
means that it is possible to make ugly nested lists. In any case, a syntax 
defines a state space which almost inevitably supports some ugly states; this 
does not mean that those states must (or ever will) be present.

Let it (b).
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

re: list corner case

[Bowerbird]

jacob said:
>   This entirely contradicts Markdown's purpose and philosophy.

and aristotle agreed:
>   That is my opinion too.

it _might_not_ (or might) be in alignment with the
"purpose and philosophy" of markdown, but hey,
it does not "contradict" it, _certainly_ not "entirely".

this is what gruber says under "markdown philosophy":
>Markdown is intended to be 
>as easy-to-read and easy-to-write as is feasible.
>Readability, however, is emphasized above all else.

he continues:
>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.

if the intent is ambiguous -- and it _clearly_ is ambiguous,
since no one here can state unequivocally what was meant,
which is why there are competing interpretations at work --
then the document certainly will not be _readable_, let alone
"publishable as-is".   so it's out of the realm of the philosophy.

and if you privilege one interpretation, what you will be saying
to some people is that their other interpretations were flawed.
and they're _markdown_developers_, not just "ordinary" users.
so maybe it ain't as simple as the philosophy says it should be.

but, you know, i really _don't_ care...   do what you will...:+)

-bowerbird



**
Pt...Have you heard the news? There's a new fashion blog, 
plus the latest fall trends and hair styles at StyleList.com.
  
(http://www.stylelist.com/trends?ncid=aolsty000514)
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Yuri Takhteyev]

> But in actual discussion here on list, as far as I saw, with the
> exception of "Bowerbird" who made up option D, everyone voted for
> C, with some of us calling A a reasonable secondary option. (Did
> I misread the discussion?)

I used the word "voted" figuratively.  What I meant is that
standardizing on A would require 6 implementations to change.
Standardizing on C would require changing 10, including Markdown.pl.

- yuri

-- 
http://sputnik.freewisdom.org/
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Aristotle Pagaltzis]

* Waylan Limberg <[EMAIL PROTECTED]> [2008-09-08 15:30]:
> Although I seem to recall talk in the past about the following:
> 
> 1. foo
> - bar
> - baz
> 
> Where the first item sets the list as ordered, and the rest
> just defines the items. The argument made was that the author
> could then reorder, insert or delete any random item without
> feeling the need to renumber the items.

I thought this was attractive, but it occured to me that whenever
you want that, you can get it just as well by instead writing the
list this way:

1. foo
1. bar
1. baz

> Personally, I'm the type that's going to renumber the items
> anyway

If you kept Markdown documents in a version control system, you
would avoid that. :-)  (Renumbering items when shifting them
around can cause a lot of noise in diffs from spurious changes.)

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Aristotle Pagaltzis]

* Yuri Takhteyev <[EMAIL PROTECTED]> [2008-09-08 19:40]:
> Between A and C it seems that A wins the popularity contest 7:3
> ((John skipped markdown.lua's  "vote" for A).  So, A also wins
> the plurality vote even if B is not eliminated.  So, I would
> declare it the "right" behavior.

Sure, but the implementors never talked about this. They just had
to resolve this case individually. And what do you do when you
don’t feel strongly about it? You look at what Markdown.pl does.
Which does A. It doesn’t at all seem surprising to me that A wins
in that contest.

But in actual discussion here on list, as far as I saw, with the
exception of “Bowerbird” who made up option D, everyone voted for
C, with some of us calling A a reasonable secondary option. (Did
I misread the discussion?)

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Aristotle Pagaltzis]

* Waylan Limberg <[EMAIL PROTECTED]> [2008-09-08 17:15]:
> On Sun, Sep 7, 2008 at 10:14 PM, Aristotle Pagaltzis <[EMAIL PROTECTED]> 
> wrote:
>> Any inferred nesting would have to subordinate them to an implied
>> 3rd item in the surrounding unordered list that is not written
>> out in these examples – semantically equivalent roughly to this:
>>
>> -  foo
>> -  bar
>> -
>>   1. baz
>>   1. quux
>> -  qux
>>
> Not necessarily. Take the following example (with 4 spaces
> before item "two"):
>
> -  one
>2. two
>
> With the exception of Maruku (which falls flat on it's face
> here), every implementation consistently renders this:
>
> 
> one 
> two
> 
> 
> 
>
> While I hate to deflate any argument against option B, the fact is,
> there doesn't have to be any "implied 3rd item in the surrounding
> unordered list".

I am not sure where you have argued anything at all?

My entire point is that as a human reader I see the last item in
my example lists as really belonging to the same list as the
first two items, even though there’s another list in the middle.
I don’t think there’s any strong argument to be made that this is
not the case.

Actually I see *all* the items as belonging to the same list. The
two numbered ones just happen to have a relationship to each
other that the others don’t share.

But there is no way to express that in Markdown. Because there is
no way to express that in HTML. Lists can only be ordered or not
as a whole.

The example I gave with the implied 3rd item in the impliedly
outer list is just an attempt to convey roughly the same
semantics in HTML and Markdown as what I see, but it is not an
argument that this is how it should actually be rendered, since
it wasn’t written that way by the author.

The only available option in HTML, which is what Markdown should
do IMO, is simply render this as three distinct lists.

> However, without the indentation, I don't think it's clear to
> the casual reader that that should be a nested ordered list -
> which I've already discussed in my previous comment.

Honestly I don’t care. If you insist on more indentation for a
nested list, then imagine that I had used more indentation. It
doesn’t matter for the purpose of the argument.

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Aristotle Pagaltzis]

* Jacob Rus <[EMAIL PROTECTED]> [2008-09-08 22:00]:
> [EMAIL PROTECTED] wrote:
>> if one can do all those things another way, then i wouldn't
>> treat this as _any_ of them. just leave it as-is, so people
>> get channeled into doing each of those things "correctly".
>>
>> [...]
>>
>> i think, in the long run, that makes it easier for people,
>> because it demands that they be clear in their thought.
>>
>> if they are ambiguous about what they want, do nothing!
>
> This entirely contradicts Markdown’s purpose and philosophy.

That is my opinion too.

Regards,
-- 
Aristotle Pagaltzis // 
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Jacob Rus]

[EMAIL PROTECTED] wrote:

if one can do all those things another way,
then i wouldn't treat this as _any_ of them.
just leave it as-is, so people get channeled
into doing each of those things "correctly".

[...]

i think, in the long run, that makes it easier for people,
because it demands that they be clear in their thought.

if they are ambiguous about what they want, do nothing!


This entirely contradicts Markdown’s purpose and philosophy.

-Jacob

___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Andrea Censi]

> Either C or E works for me, but I'll settle with A as a lousy
> compromise seeing it already appears to have the popular vote.

+1 for C, for what it's worth.

-- 
Andrea Censi
PhD student, Control & Dynamical Systems, Caltech
http://www.cds.caltech.edu/~andrea/
 "Life is too important to be taken seriously" (Oscar Wilde)
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Waylan Limberg]

On Mon, Sep 8, 2008 at 1:48 PM,  <[EMAIL PROTECTED]> wrote:
> waylan said:
>>   So, then, how do we interpret "do nothing".
>
> "nothing" is exactly as john put it in his e-mail:
>>   -  one
>>   2. two

Well, as any generated output (anything except raw html) should be
valid html, at the least it would be wrapped in some container (could
be a  or  or something). More realistically, as I understand
how most of the parsers work, I would expect such a drastic
interpretation of "do nothing" to be:


one
2. two


That is, the second line is simply seen as a continuation (another
line) of the first list item as it does not start with indentation
(indicating nesting) or a matching list item indicator (indicating
another item of the same type). In other words, if the line does not
start with the *same* list item type it is seen as a line of plain
text - no different than:

- foo
bar

We'll call this Option E. I'd argue that this would actually be a
dumber parser than a true "do nothing" solution as the truly "do
nothing" parser would need knowledge of, and code to test for the
special case and act differently (as Yuri points out, that's ugly - I
know I wouldn't want to write the parser for that), whereas option E
just dumbs the parser down a little.

This would also present an interesting solution to the "I want two or
more consecutive, but different lists in my document" problem.
Consider:

1. one
2. two

* foo
* bar

- blah
- baz

No more of that "must use two blank lines between each list" monkey
business that we've discussed before and no-one has bothered to
implement. Which, btw, is another reason why I like C better than A.

Either C or E works for me, but I'll settle with A as a lousy
compromise seeing it already appears to have the popular vote.

-- 

Waylan Limberg
[EMAIL PROTECTED]
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

re: list corner case

[Bowerbird]

waylan said:
>   So, then, how do we interpret "do nothing".

"nothing" is exactly as john put it in his e-mail:
>-  one
>2. two

or, in aristotle's examples:
>*  foo
>*  bar
>1. baz
>2. quux
>*  qux
...and...
>-  foo
>-  bar
>1. baz
>1. quux
>-  qux

ambiguous markdown = straight text with no markup at all,
spitting out exactly what was put in...


>I also think that the above option D is 
>not only a lot harder to implement, 
>but also not intuitive at all.

that's the point.   it's not meant to be "intuitive".

it's meant to signal "i don't know what you want,
so you'll need to be a little bit less ambiguous..."

after all, whenever you fail to get the desired effect,
it causes you to go in and see what you "did wrong".

i think that's the right course of action for ambiguity.

it's certainly better than doing something that will be
_non-intuitive_ for a certain percentage of the users.

-bowerbird

p.s.   and what's interesting here is the fact that
-- over and above not knowing _what_ to do --
we cannot clearly say what the user _intended_...
(well, we can, but will disagree among ourselves.)
given that we don't know the underlying intention,
it seems it would be impossible to know what to do.
the cornerstone of the philosophy is that we _do_
know what the user intended, so we will just do it.
but if the underlying intention isn't clearly specified...
it's not that i'm afraid of the "edge cases" -- they are
_delicious_ -- but they fly in the face of the philosophy,
and thus can -- for good reasons -- be ignored entirely
with a do-nothing approach that forces users to be clear.
...again, though, this is just a stance for your consideration.



**
Pt...Have you heard the news? There's a new fashion blog, 
plus the latest fall trends and hair styles at StyleList.com.
  
(http://www.stylelist.com/trends?ncid=aolsty000514)
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Tomas Doran]

On 8 Sep 2008, at 02:24, John MacFarlane wrote:


I'm curious how people think the following *should* be interpreted:

-  one
2. two

http://babelmark.bobtfish.net/?markdown=-++one%0D%0A2.+two%0D%0A%0D%0A

As you can see, implementations split into three groups here:

(a)  treat as an unordered list
 Markdown.pl,  Python markdown, MultiMarkdown, BlueCloth,  
MarkdownJ,

 Showdown

(b)  treat as an unordered list with an ordered sublist
 PHP Markdown, Text::Markdown, Pandoc

(c)  treat as an unordered list followed by an ordered list
 Maruku, Discount, PEG Markdown



Nice case.. I think that what Text::Markdown is doing here (i.e.  
option B) is _wrong_..


My gut feeling is that option (c) is what users expect, otherwise  
they wouldn't have changed the list item marker - however if the  
community has very strong feelings that (a) is more 'correct' then  
I'll go with that.


Cheers
Tom

___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Yuri Takhteyev]

>> if they are ambiguous about what they want, do nothing!
>
> While, generally, I would agree with this line of thinking, we must
> remember that one of the basic concepts behind Markdown is that it
> should never return an error for invalid markup. So, then, how do we
> interpret "do nothing". Some would argue that "do nothing" is what
> Option A is doing, while other's might argue the same for Option C. Or
> would you prefer option D: wrap the entire block of text in a  and
> move on?

I would instead say: "do whatever is simplest while being reasonable".
 To me, A seemed simplest, which is why I chose it, though I
definitely can see how one can argue for C as the simplest option.  B
is too clever and is not worth the effort for the case that doesn't
have an obvious intuitive interpretation.  D would be ugly and
actually adds complexity over A and C.

Between A and C it seems that A wins the popularity contest 7:3 ((John
skipped markdown.lua's  "vote" for A).  So, A also wins the plurality
vote even if B is not eliminated.  So, I would declare it the "right"
behavior.

Another thing about B: if we were to go this route, we would then have
to also discuss how to handle

0. zero
-  one
2. two

Does the introduction of "zero" make "two" a top level element or is
it still a sub-item of "one"?  Why?

- yuri

-- 
http://sputnik.freewisdom.org/
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Waylan Limberg]

On Mon, Sep 8, 2008 at 12:27 PM,  <[EMAIL PROTECTED]> wrote:
>
> if they are ambiguous about what they want, do nothing!
>

While, generally, I would agree with this line of thinking, we must
remember that one of the basic concepts behind Markdown is that it
should never return an error for invalid markup. So, then, how do we
interpret "do nothing". Some would argue that "do nothing" is what
Option A is doing, while other's might argue the same for Option C. Or
would you prefer option D: wrap the entire block of text in a  and
move on?

The fact is, the authors of each implementation need to make that
decision. Obviously, everyone hasn't made the same decision. Yet,
theoretically, all implementations *should* do the same thing. So,
yeah, we need to have this discussion.

That said, I think you do have a point. Option B does not fit into "do
nothing" no matter how you look at it. That's one more strike against
IMO. I also think that the above option D it not only a lot harder to
implement, but also not intuitive at all. At least with A, B or C, the
user can look at the resulting list(s) and get a few clues about what
might be wrong in their source text.

-- 

Waylan Limberg
[EMAIL PROTECTED]
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

re: list corner case

[Bowerbird]

john said:
>(a)  treat as an unordered list
>(b)  treat as an unordered list with an ordered sublist
>(c)  treat as an unordered list followed by an ordered list

i'd come at it from the opposite angle.

suppose i wanted to do (a).   how would i do it?
suppose i wanted to do (b).   how would i do it?
suppose i wanted to do (c).   how would i do it?

if one can do all those things another way,
then i wouldn't treat this as _any_ of them.
just leave it as-is, so people get channeled
into doing each of those things "correctly".

i see no reason to "privilege" any one choice,
especially when "intuitions" are so disparate...
no matter how you slice it, it will seem "wrong",
at least to some people, and that is a negative...

it's not as if _everything_ needs to be _something_...
it's possible to take a stance that some formulations
are simply too ambiguous for unequivocal treatment.

i think, in the long run, that makes it easier for people,
because it demands that they be clear in their thought.

if they are ambiguous about what they want, do nothing!

just one opinion, for your consideration...

-bowerbird



**
Pt...Have you heard the news? There's a new fashion blog, 
plus the latest fall trends and hair styles at StyleList.com.
  
(http://www.stylelist.com/trends?ncid=aolsty000514)
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Waylan Limberg]

On Sun, Sep 7, 2008 at 10:14 PM, Aristotle Pagaltzis <[EMAIL PROTECTED]> wrote:
> Any inferred nesting would have to subordinate them to an implied
> 3rd item in the surrounding unordered list that is not written
> out in these examples – semantically equivalent roughly to this:
>
> -  foo
> -  bar
> -
>   1. baz
>   1. quux
> -  qux
>
Not necessarily. Take the following example (with 4 spaces before item "two"):

-  one
2. two

With the exception of Maruku (which falls flat on it's face here),
every implementation consistently renders this:


one 
two




While I hate to deflate any argument against option B, the fact is,
there doesn't have to be any "implied 3rd item in the surrounding
unordered list". However, without the indentation, I don't think it's
clear to the casual reader that that should be a nested ordered list -
which I've already discussed in my previous comment.

-- 

Waylan Limberg
[EMAIL PROTECTED]
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss

Re: list corner case

[Waylan Limberg]

On Sun, Sep 7, 2008 at 9:24 PM, John MacFarlane <[EMAIL PROTECTED]> wrote:
> I'm curious how people think the following *should* be interpreted:
>
> -  one
> 2. two
>

Personally, I would prefer C.

For what it's worth, I'm also one of the few that seems to think
anything less than 4 spaces of indentation should be ignored in the
list syntax - but that's another discussion we've already had. I'm
just saying that may be part of the reason why I completely rule out
option B. Given the general lack of polarity of my opinion on the
indentation issue, I'm guessing most wouldn't like C for the same
reason, even if it is the only way *my* brain parses that list.

Although I seem to recall talk in the past about the following:

1. foo
- bar
- baz

Where the first item sets the list as ordered, and the rest just
defines the items. The argument made was that the author could then
reorder, insert or delete any random item without feeling the need to
renumber the items. Personally, I'm the type that's going to renumber
the items anyway, but I suspect that's why option A is the most
popular among current implementations.

I realize the actual numbering is irrelevant to an ordered list, as
long as the numbers are there, but it's about what's more readable and
I suppose out-of-order numbering is less readable to some than the
above mixed list. Readability really is the issue here and for those
that don't want to so strictly enforce indentation I can see how
option B looks logical, but for the above to work, then the converse
also needs to work (perhaps not technically - but for consistency)
which forces us to only accept option A - even if it's not my personal
favorite.

-- 

Waylan Limberg
[EMAIL PROTECTED]
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss