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
John
* John MacFarlane <jgm at berkeley.edu> [2008-09-08 03:25]:> I'm curious how people think the following *should* be interpreted: > > - one > 2. twoFor the purpose of the argument I?ll expand a little with more realistically likely examples: * foo * bar 1. baz 2. quux * qux - foo - bar 1. baz 1. quux - qux In those examples I see the 3rd and 4th items as having an implied relationship that is stronger than among the rest of the items, but I do not see those two as subordinate to the 2nd item. 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 Therefore, I would say these should be rendered as either three separate lists or as a single unordered list, but definitely not as an unordered list with an ordered list nested inside its 2nd item. Regards, -- Aristotle Pagaltzis // <http://plasmasturm.org/>
On Sun, Sep 7, 2008 at 9:24 PM, John MacFarlane <jgm at berkeley.edu> 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 waylan at gmail.com
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 listi'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 ************** Psssst...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=aolsty00050000000014) -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20080908/5b3c0a2e/attachment.htm>
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
waylan said:> So, then, how do we interpret "do nothing"."nothing" is exactly as john put it in his e-mail:> -? one > 2. twoor, in aristotle's examples:> *? foo > *? bar > 1. baz > 2. quux > *? qux...and...> -? foo > -? bar > 1. baz > 1. quux > -? quxambiguous 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. ************** Psssst...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=aolsty00050000000014) -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20080908/d33088b9/attachment.html>
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 ************** Psssst...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=aolsty00050000000014) -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20080909/d5b93c85/attachment.html>
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).
* Albert Skye <mistlail at yahoo.co.uk> [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 // <http://plasmasturm.org/>
>> Markdown syntax presents a strong pattern of using blank lines >> to separate elements. > > > Does it? > > I hadn?t noticed.Good call, thank you; having concluded long ago that blank-line separation for block elements is it a good idea, I had forgotten that most implementations* were so lax about it. In any case, (b) still seems the most useful behaviour to me. * It seems ironic to follow the details of an informal and neglected implementation (i.e., Markdown.pl), rather than the spirit of the documentation. If you all want a formal (i.e., consistent) standard then you should define it yourselves because John Gruber is clearly not interested, and poring over the details of his implementation/documentation is not likely to yield one.
aristotle said:> I know that as a human I have no trouble extracting some > meaning from any of the examples given in this thread.well, um, nobody has any trouble "extracting some meaning". the problem is that different people extract different meaning.> 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.emphasis on _correctly_... i can make examples where your interpretation will be correct, according to the semantic knowledge that humans would bring. i can also make examples where other interpretations are correct, according to the semantic knowledge that humans would bring. you will privilege some of these examples, and not the others...> Obviously, the formatter should try its best > to reflect the structure of the written prosethe question is what to do when the structure is ambiguous. you're saying "do something, anything" is the right approach. i've put forth a position that "do nothing" is a better method, because that will force the author to become less ambiguous. this position has enough rigor that you cannot destroy it. i'd say it's far better to say "i don't prefer it" and move on. -bowerbird ************** Psssst...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=aolsty00050000000014) -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20080909/510ee9d5/attachment.htm>
waylan said:> Actually, any method that returns results different than what the > author expects will "force the author to become less ambiguous."assuming they notice. if you put the results in some kind of indented block, they might not. (which is probably why this "corner case" hasn't been noticed before. it took some sleuthing for john to uncover different implementations.) if you leave it hanging there as a bare paragraph (i.e., "do nothing") they're far more likely to notice that it wasn't formatted "as intended", and that's likely to get them to ask themselves what they'd intended... ("markdown didn't seem to know what i wanted; oh, i was too vague.") but at any rate, what you've made here is a good point, so i feel i can make good on my intention to opt out of this thread from now on... -bowerbird ************** Psssst...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=aolsty00050000000014) -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://six.pairlist.net/pipermail/markdown-discuss/attachments/20080909/9c9f67dc/attachment.htm>
It has been interesting to hear people's thoughts on this. Let me summarize the considerations I've been weighing. Against (b): it's just too unexpected. Nothing in the markdown syntax description would lead one to expect that changing the list marker would start a sublist. I'm curious, though, to hear whether Michel Fortin has a rationale for doing it this way in PHP Markdown; I think he's the only (b)-category implementer who hasn't weighed in on this discussion. One argument for (c) that initially appealed to me is that it allows the writer to have two consecutive lists without any intervening block element--something that is otherwise impossible in markdown. So it adds expressive power, whereas (a) just gives you another (more obscure) way to express something you can already express. The more I thought about it, though, the less impressive I found this consideration. For (c) only gives you a way to have consecutive lists if one is ordered and one unordered. It doesn't help if you want to have two consecutive ordered lists, e.g.: 1. foo 2. bar 1. baz 2. quux This gets parsed as one big ordered list by all implementations. It seems to me that if markdown needs a way to express consecutive lists, it needs a *general* way to do so, one that will work even if the lists are of the same type. Another argument for (c) is that John Gruber's markdown syntax description gives the definite impression that ALL the markers in an ordered list are numbers, and that ALL the markers in an unordered list are *, +, or -. "Unordered lists use asterisks, pluses, and hyphens ? interchangably ? as list markers..." "Ordered lists use numbers followed by periods..." Gruber does say that "the actual numbers you use to mark the list have no effect on the HTML output Markdown produces," but note that he says "numbers" here; there is no suggestion that you can use bullet markers in an ordered list. On this ground it might be argued that (a) would not be the expected interpretation. On the other hand, (a) is the most well-established interpretation, since it's the interpretation of Markdown.pl and all the implementations that have essentially copied its regular expression transformations. I know there's markdown out there that continues ordered lists with unordered list markers (I found one instance of this when I replaced BlueCloth with rpeg-markdown and someone complained that his lists had changed). I've also seen at least one markdown cheat-sheet that advertises this behavior <http://greg.vario.us/doc/markdown.txt>. So even though I think (c) is a slightly better interpretation of the markdown syntax document, I'm inclined to defer to the canonical implementation here, in the interest of not breaking existing documents. That means that, even though my two implementations fall into groups (b) and (c), I'm starting to favor (a). John +++ John MacFarlane [Sep 07 08 18:24 ]:> 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 > > John > > _______________________________________________ > Markdown-Discuss mailing list > Markdown-Discuss at six.pairlist.net > http://six.pairlist.net/mailman/listinfo/markdown-discuss >
In article <20080908012404.GA24079 at berkeley.edu>, John MacFarlane <markdown-discuss at six.pairlist.net> wrote:>I'm curious how people think the following *should* be interpreted: > >- one >2. twoI think it *should* be an unordered list followed by an ordered list, but the oracle says it's just one list (and it doesn't matter if there is any spacing between the two items, oh joy!) It's trivial for me to hold my nose and relax the emblockulator to follow the oracle, so as much as I don't like the idea that's what I'm going to have to do for discount version 1.3.0 -david parsons