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 waylan at gmail.com From qaramazov at gmail.com Mon Sep 8 13:37:18 2008 From: qaramazov at gmail.com (Yuri Takhteyev) Date: Mon, 8 Sep 2008 10:37:18 -0700 Subject: list corner case In-Reply-To: References: Message-ID: >> 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/ From bobtfish at bobtfish.net Mon Sep 8 13:45:39 2008 From: bobtfish at bobtfish.net (Tomas Doran) Date: Mon, 8 Sep 2008 18:45:39 +0100 Subject: list corner case In-Reply-To: <20080908012404.GA24079@berkeley.edu> References: <20080908012404.GA24079@berkeley.edu> Message-ID: <819D4276-402D-4489-9ACB-28069A16A74D@bobtfish.net> 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 From Bowerbird at aol.com Mon Sep 8 13:48:27 2008 From: Bowerbird at aol.com (Bowerbird at aol.com) Date: Mon, 8 Sep 2008 13:48:27 EDT Subject: list corner case Message-ID: 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. ************** 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: From waylan at gmail.com Mon Sep 8 15:35:26 2008 From: waylan at gmail.com (Waylan Limberg) Date: Mon, 8 Sep 2008 15:35:26 -0400 Subject: list corner case In-Reply-To: References: Message-ID: On Mon, Sep 8, 2008 at 1:48 PM, 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 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 waylan at gmail.com From andrea at censi.org Mon Sep 8 15:39:04 2008 From: andrea at censi.org (Andrea Censi) Date: Mon, 8 Sep 2008 12:39:04 -0700 Subject: list corner case In-Reply-To: References: Message-ID: > 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) From jacobolus at gmail.com Mon Sep 8 15:56:57 2008 From: jacobolus at gmail.com (Jacob Rus) Date: Mon, 08 Sep 2008 12:56:57 -0700 Subject: list corner case In-Reply-To: References: Message-ID: Bowerbird at aol.com 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 From pagaltzis at gmx.de Mon Sep 8 23:51:16 2008 From: pagaltzis at gmx.de (Aristotle Pagaltzis) Date: Tue, 9 Sep 2008 05:51:16 +0200 Subject: list corner case In-Reply-To: References: Message-ID: <20080909035116.GP5008@klangraum.plasmasturm.org> * Jacob Rus [2008-09-08 22:00]: > Bowerbird at aol.com 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 // From pagaltzis at gmx.de Mon Sep 8 23:59:41 2008 From: pagaltzis at gmx.de (Aristotle Pagaltzis) Date: Tue, 9 Sep 2008 05:59:41 +0200 Subject: list corner case In-Reply-To: References: <20080908012404.GA24079@berkeley.edu> <20080908021423.GB30194@klangraum.plasmasturm.org> Message-ID: <20080909035941.GQ5008@klangraum.plasmasturm.org> * Waylan Limberg [2008-09-08 17:15]: > On Sun, Sep 7, 2008 at 10:14 PM, Aristotle Pagaltzis 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
1. 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 // From pagaltzis at gmx.de Tue Sep 9 00:11:19 2008 From: pagaltzis at gmx.de (Aristotle Pagaltzis) Date: Tue, 9 Sep 2008 06:11:19 +0200 Subject: list corner case In-Reply-To: References: Message-ID: <20080909041119.GR5008@klangraum.plasmasturm.org> * Yuri Takhteyev [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 // From pagaltzis at gmx.de Tue Sep 9 00:15:55 2008 From: pagaltzis at gmx.de (Aristotle Pagaltzis) Date: Tue, 9 Sep 2008 06:15:55 +0200 Subject: list corner case In-Reply-To: References: <20080908012404.GA24079@berkeley.edu> Message-ID: <20080909041555.GS5008@klangraum.plasmasturm.org> * Waylan Limberg [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 // From qaramazov at gmail.com Tue Sep 9 00:27:45 2008 From: qaramazov at gmail.com (Yuri Takhteyev) Date: Mon, 8 Sep 2008 21:27:45 -0700 Subject: list corner case In-Reply-To: <20080909041119.GR5008@klangraum.plasmasturm.org> References: <20080909041119.GR5008@klangraum.plasmasturm.org> Message-ID: > 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/ From Bowerbird at aol.com Tue Sep 9 01:41:34 2008 From: Bowerbird at aol.com (Bowerbird at aol.com) Date: Tue, 9 Sep 2008 01:41:34 EDT Subject: list corner case Message-ID: 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: From mistlail at yahoo.co.uk Tue Sep 9 01:57:59 2008 From: mistlail at yahoo.co.uk (Albert Skye) Date: Mon, 8 Sep 2008 22:57:59 -0700 Subject: list corner case In-Reply-To: <20080908012404.GA24079@berkeley.edu> References: <20080908012404.GA24079@berkeley.edu> Message-ID: <20080908225759320897.bec44179@yahoo.co.uk> 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). From pagaltzis at gmx.de Tue Sep 9 02:28:02 2008 From: pagaltzis at gmx.de (Aristotle Pagaltzis) Date: Tue, 9 Sep 2008 08:28:02 +0200 Subject: list corner case In-Reply-To: References: <20080909035116.GP5008@klangraum.plasmasturm.org> Message-ID: <20080909062802.GB20866@klangraum.plasmasturm.org> * Bowerbird at aol.com [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 // From pagaltzis at gmx.de Tue Sep 9 02:30:34 2008 From: pagaltzis at gmx.de (Aristotle Pagaltzis) Date: Tue, 9 Sep 2008 08:30:34 +0200 Subject: list corner case In-Reply-To: <20080908225759320897.bec44179@yahoo.co.uk> References: <20080908012404.GA24079@berkeley.edu> <20080908225759320897.bec44179@yahoo.co.uk> Message-ID: <20080909063034.GC20866@klangraum.plasmasturm.org> * Albert Skye [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 // From mistlail at yahoo.co.uk Tue Sep 9 14:22:31 2008 From: mistlail at yahoo.co.uk (Albert Skye) Date: Tue, 9 Sep 2008 11:22:31 -0700 Subject: list corner case In-Reply-To: <20080909063034.GC20866@klangraum.plasmasturm.org> References: <20080908012404.GA24079@berkeley.edu> <20080908225759320897.bec44179@yahoo.co.uk> <20080909063034.GC20866@klangraum.plasmasturm.org> Message-ID: <20080909112231211190.d2bb2768@yahoo.co.uk> >> 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. From tom at jumpingrock.net Tue Sep 9 14:26:58 2008 From: tom at jumpingrock.net (Tom Humiston) Date: Tue, 9 Sep 2008 14:26:58 -0400 Subject: list corner case In-Reply-To: <20080909112231211190.d2bb2768@yahoo.co.uk> References: <20080908012404.GA24079@berkeley.edu> <20080908225759320897.bec44179@yahoo.co.uk> <20080909063034.GC20866@klangraum.plasmasturm.org> <20080909112231211190.d2bb2768@yahoo.co.uk> Message-ID: <7B7B2639-2DB2-4AFF-8D21-773E042E5003@jumpingrock.net> The syntax (supplemented by the cheatsheet on Gruber's dingus page) already gives us the rules. All we're talking about here is what to do when a text appears to invoke rules in a contradictory fashion. So I think it's a matter of simply sorting out the priority of these rules. - If you want an unordered list, you start with a hyphen, plus, or asterisk. - If you want an ordered list, you start with a number and a dot. You don't get to choose the individual numbers beyond the first (and any attempt will be ignored), and (in the current version, at least) even the first will, no matter what, be interpreted as 1. - If you want a list nested within another, you add indentation. I've noted the above in the order they're presented by Gruber, more or less. And I think there's at least an idea that each is more specific than the one before, or occurs "in nature" less generally. As with CSS rules, I'd give precedence to specificity. Let's look at the OP's example: - foo 2. bar* Nested? No -- there's no indentation. Ordered? No -- it doesn't start with a number. List? Yes; it starts with a hyphen. * In all examples, I've substituted foo, bar, and baz in place of number words to avoid confusion. Aristotle's first examples: * foo * bar 1. baz 2. quux * qux - foo - bar 1. baz 1. quux - qux These come out identical to the first example: Nested? No. Ordered? No (again, look at the first list item, then compare it with the rule for indicating an ordered list). And thirdly, are they lists at all? Yes: one list begins with an asterisk, the other a hyphen. Waylan's example: - foo 2. bar (with four spaces before) Nested? Yes, it's indented -- which makes 'bar' the beginning of a separate list. Is this separate list ordered? Yes. This leaves only the outer list, which is clearly unordered. Yuri's example: 0. foo - bar 2. baz Nested? No. Ordered? Yes -- it begins with a number (clearly to be rendered, according to the rule for ordered lists, as 1 followed by 2 and 3). Aristotle's second example: 1. foo 1. bar 1. baz Nested? No -- there's no indentation. Ordered? Yes; there's a number (any number) and a dot before the first item. Again, to be rendered, according to the rule, as 1, 2, 3. Albert's example (or examples): 1. Albert - flowers - bicycle 2. Lucy - food - water - wine Nested? No. Ordered? Yes, both of them. Two separate lists? Yes. In all of the above, I've used Gruber's syntax to create a three-step flowchart, but for greater elucidation we could slice it differently: First let us ask, is there nesting, and second, is the list ordered or unordered? Based on the syntax, the first question needs only to look for an indent, and the second needs only to check the first item's marker type. Further, the syntax and its examples state that ANY number (plus a dot) before the first item will trigger an ordered list, and that ANY number before a subsequent item will serve only to identify it as another list item. So -- happily -- the presence of digits and marks that don't follow a linear sequence, no matter what they say of the intent of the author or user, needn't concern us. --- All of this is to say that we've been chasing corner cases when we don't need to. Corner cases refer to the superset of possible inputs. And given the philosophy implied in Gruber's overview, including the statement that Markdown's "syntax is very small, corresponding only to a very small *subset* of HTML tags" (emphasis mine), I think this focus on corner cases, and the attending abhorrence for the ambiguity that Markdown's syntax explicity allows, is clearly against Markdown's grain. Bowerbird is right. The syntax says enough about it. Let it go. From Bowerbird at aol.com Tue Sep 9 15:13:35 2008 From: Bowerbird at aol.com (Bowerbird at aol.com) Date: Tue, 9 Sep 2008 15:13:35 EDT Subject: list corner case Message-ID: 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 prose the 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: From pagaltzis at gmx.de Tue Sep 9 16:28:24 2008 From: pagaltzis at gmx.de (Aristotle Pagaltzis) Date: Tue, 9 Sep 2008 22:28:24 +0200 Subject: list corner case In-Reply-To: References: <20080909063034.GC20866@klangraum.plasmasturm.org> Message-ID: <20080909202824.GB5008@klangraum.plasmasturm.org> * Bowerbird at aol.com [2008-09-09 21:15]: > aristotle said: > > Obviously, the formatter should try its best > > to reflect the structure of the written prose > > the 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. How does doing the sometimes-wrong thing fail to force the author to become less ambiguous? Is forcing the author to become less ambiguous even a goal of Markdown? > 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. I see. Regards, -- Aristotle Pagaltzis // From waylan at gmail.com Tue Sep 9 16:33:00 2008 From: waylan at gmail.com (Waylan Limberg) Date: Tue, 9 Sep 2008 16:33:00 -0400 Subject: list corner case In-Reply-To: References: Message-ID: On Tue, Sep 9, 2008 at 3:13 PM, wrote: > > i've put forth a position that "do nothing" is a better method, > because that will force the author to become less ambiguous. > Actually, any method that returns results different than what the author expects will "force the author to become less ambiguous." Depending on the author, that could be any one of the proposed solutions. So, "do nothing" isn't really better in that respect - its just different. Besides, you've failed to provide a legitimate interpretation of what "do nothing" does. As I stated before, we *must* return valid html. So, should "do nothing" wrap the offending text in a

, a

or some incomplete list as I proposed earlier. I shouldn't need to restate the argument for the later option here. The point is, even "do nothing" is open for interpretation. What I consider a good clue to the author may not be obvious to someone else and vise versa. -- ---- Waylan Limberg waylan at gmail.com From tom at jumpingrock.net Tue Sep 9 17:58:51 2008 From: tom at jumpingrock.net (Tom Humiston) Date: Tue, 9 Sep 2008 17:58:51 -0400 Subject: list corner case In-Reply-To: References: Message-ID: Shorter version of my previous post: Gruber gives this example... 3. Bird 1. McHale 8. Parish ...and states that it will be numbered 1-2-3. Which is enough to make clear that in Markdown's design, the kind of goofy content in list- item markers that we're discussing is ignored. Simple. All this other talk strokes programmers' egos but doesn't result in more usable software. Read Alan Cooper's excellent book, "The Inmates Are Running the Asylum"; you'll see what I mean. From Bowerbird at aol.com Tue Sep 9 18:45:23 2008 From: Bowerbird at aol.com (Bowerbird at aol.com) Date: Tue, 9 Sep 2008 18:45:23 EDT Subject: list corner case Message-ID: 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: From waylan at gmail.com Tue Sep 9 18:53:28 2008 From: waylan at gmail.com (Waylan Limberg) Date: Tue, 9 Sep 2008 18:53:28 -0400 Subject: list corner case In-Reply-To: References:

Message-ID: On Tue, Sep 9, 2008 at 5:58 PM, Tom Humiston wrote: > Shorter version of my previous post: > > Gruber gives this example... > > 3. Bird > 1. McHale > 8. Parish > > ...and states that it will be numbered 1-2-3. Which is enough to make clear > that in Markdown's design, the kind of goofy content in list-item markers > that we're discussing is ignored. Simple. > In other words, you're arguing for option A. However, while, the above example indicates what the expected behavior is when the list indicators are of the same type, it provides no hints as to what should be expected when the list indicators are of different types. You seem to be suggesting that we shouldn't even look at that, but we have to to identify that line as either (1) another list item of the same level, or (2) an additional line of the previous list item. That second possibility is what you left out of your long post, and what forces every implementation to specifically look for the list indicator on every item - not just the first. In my observation, most implementations use different code (usually different regex) to check for ol indicators than for ul indicators. So (nearly) every implementation is going to notice the difference in indicator style, while they may not notice the inconsistency in numbering of a numbered list (that's the nature of regex). Those that follow option A have consciously chose to ignore that difference in type. The thing is, humans do not ignore that difference. I realize most humans do not ignore the non-sequential numbering either and that's why I'm willing to settle for option A as a close second to option C - the way my brain sees it. -- ---- Waylan Limberg waylan at gmail.com From jgm at berkeley.edu Tue Sep 9 21:26:28 2008 From: jgm at berkeley.edu (John MacFarlane) Date: Tue, 9 Sep 2008 18:26:28 -0700 Subject: list corner case In-Reply-To: <20080908012404.GA24079@berkeley.edu> References: <20080908012404.GA24079@berkeley.edu> Message-ID: <20080910012628.GA349@berkeley.edu> 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 . 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 > From michel.fortin at michelf.com Tue Sep 9 22:05:02 2008 From: michel.fortin at michelf.com (Michel Fortin) Date: Tue, 09 Sep 2008 22:05:02 -0400 Subject: list corner case In-Reply-To: <20080910012628.GA349@berkeley.edu> References: <20080908012404.GA24079@berkeley.edu> <20080910012628.GA349@berkeley.edu> Message-ID: <5CA0CB4A-B7A2-4626-BDD7-CBF03EE15088@michelf.com> Le 2008-09-09 ? 21:26, John MacFarlane a ?crit : > 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. Bug report posted on this list by Dhruba Bandopadhyay on September 18, 2004: > The markdown text: > > * one > * two > > 1. one > 2. two > > gives the XHTML: > >

I felt it was worth a fix, so: > 1.0.1b (6 Jun 2005) > > * Fix for an ordered list following an unordered list, and the reverse. There > is now a loop in _DoList that does the two separately. Seems like most implementation still parse the above as one big unordered list though: - - - That said, about the situation where there is no space between the two lists, I'm not sure why it should be treated differently than with Dhruba's report. If you take the following: * one * two * three * four you only get one list. With my fix, this doesn't change; the only change is that it now stops the list when it can't find another list marker *matching the current list type*, plain and simple. -- Michel Fortin michel.fortin at michelf.com http://michelf.com/ From sgbotsford at gmail.com Tue Sep 9 23:27:27 2008 From: sgbotsford at gmail.com (Sherwood Botsford) Date: Tue, 9 Sep 2008 21:27:27 -0600 Subject: list corner case In-Reply-To: <5CA0CB4A-B7A2-4626-BDD7-CBF03EE15088@michelf.com> References: <20080908012404.GA24079@berkeley.edu> <20080910012628.GA349@berkeley.edu> <5CA0CB4A-B7A2-4626-BDD7-CBF03EE15088@michelf.com> Message-ID: <534004cc0809092027o6f5de6f6w5fc9e7b5ef643b0e@mail.gmail.com> I'll admit the interpretation of 1. foo * baz - bar - biff * qix - qak 7. qux as a single list counter intuitive. My gut feel for that, after having used markdown.pl with ttree for a few months is that this would be a three level nested list. I KNOW that's not what the docs say. But the philosophy of markdown is that of an email message. Who changes bullets in the middle of a list? And since indents in email are normally used for quoting, I expect the above to be shorthand for 1. foo * baz - bar - biff * qix - qak 2. qux -------------- next part -------------- An HTML attachment was scrubbed... URL: From orc at pell.portland.or.us Wed Sep 10 00:49:22 2008 From: orc at pell.portland.or.us (david parsons) Date: 9 Sep 2008 21:49:22 -0700 Subject: list corner case References: <20080908012404.GA24079@berkeley.edu> Message-ID: In article <20080908012404.GA24079 at berkeley.edu>, John MacFarlane wrote: >I'm curious how people think the following *should* be interpreted: > >- one >2. two I 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 From michel.fortin at michelf.com Wed Sep 10 08:23:40 2008 From: michel.fortin at michelf.com (Michel Fortin) Date: Wed, 10 Sep 2008 08:23:40 -0400 Subject: list corner case In-Reply-To: <5CA0CB4A-B7A2-4626-BDD7-CBF03EE15088@michelf.com> References: <20080908012404.GA24079@berkeley.edu> <20080910012628.GA349@berkeley.edu> <5CA0CB4A-B7A2-4626-BDD7-CBF03EE15088@michelf.com> Message-ID: <5F3B447B-A6B5-45C3-851E-DB2C17AF5B01@michelf.com> Le 2008-09-09 ? 22:05, Michel Fortin a ?crit : > That said, about the situation where there is no space between the > two lists, I'm not sure why it should be treated differently than > with Dhruba's report. If you take the following: > > * one > * two > > * three > * four > > you only get one list. With my fix, this doesn't change; the only > change is that it now stops the list when it can't find another list > marker *matching the current list type*, plain and simple. Oops, I got this all wrong. PHP Markdown in fact creates a sublist for three and four with this input: * one * two 1. three 2. four Sounds like a bug to me. This should be the same as: * one * two 1. three 2. four which means: an unordered list followed by an unordered one. I need to add a test for that to MDTest... -- Michel Fortin michel.fortin at michelf.com http://michelf.com/ From shuntim.luk at polyu.edu.hk Thu Sep 11 00:42:27 2008 From: shuntim.luk at polyu.edu.hk (LUK ShunTim) Date: Thu, 11 Sep 2008 12:42:27 +0800 Subject: list corner case In-Reply-To: <5F3B447B-A6B5-45C3-851E-DB2C17AF5B01@michelf.com> References: <20080908012404.GA24079@berkeley.edu> <20080910012628.GA349@berkeley.edu> <5CA0CB4A-B7A2-4626-BDD7-CBF03EE15088@michelf.com> <5F3B447B-A6B5-45C3-851E-DB2C17AF5B01@michelf.com> Message-ID: <48C8A1B3.8010504@polyu.edu.hk> Michel Fortin wrote: > Le 2008-09-09 ? 22:05, Michel Fortin a ?crit : > >> That said, about the situation where there is no space between the two >> lists, I'm not sure why it should be treated differently than with >> Dhruba's report. If you take the following: >> >> * one >> * two >> >> * three >> * four >> >> you only get one list. With my fix, this doesn't change; the only >> change is that it now stops the list when it can't find another list >> marker *matching the current list type*, plain and simple. > > Oops, I got this all wrong. PHP Markdown in fact creates a sublist for > three and four with this input: > > * one > * two > 1. three > 2. four FWIW, pandoc did the same thing but John Gruber's markdown(.pl), version 1.0.1 in debian, renders it as a *single unordered* list. > > Sounds like a bug to me. This should be the same as: > > * one > * two > > 1. three > 2. four > > which means: an unordered list followed by an unordered one. I need to > add a test for that to MDTest... > Pandoc did exactly that but markdown(.pl) still renders it as a single unordered list but with double spacing between list items. This is the html

one
two
three
four

Regards, ST -- From nickbw at draftastic.com Thu Sep 11 18:36:51 2008 From: nickbw at draftastic.com (Nick Blanchard-Wright) Date: Thu, 11 Sep 2008 18:36:51 -0400 (EDT) Subject: [ANN] Draftastic -- Markdown-based collaborative editor Message-ID: Hi everyone, We've just launched a collaborative editing site that relies heavily on Markdown. We wanted to say thanks, and we'd love any feedback from the Markdown community. http://draftastic.com/ is a realtime, multi-user text editor. It does locking on arbitrary blocks of text, rather than locking at the page level or trying to merge character-by-character changes, neither of which ever seemed comfortable. Basically, it's version control for natural language. The blocks are all handled by WMD (which could not have come at a better time!) client-side, and PHP Markdown server-side, with some XSS filtering thrown in. All the interesting Markdown-related features are in the free version (we're charging for hosting, not tools). It should be plenty for personal use and small projects, but if your organization has contributed to Markdown and it wants a larger instance, it's entitled to a 20% discount by way of: https://draftastic.com/signup?code=tharkdown Thanks! Nick Blanchard-Wright and Charlie Loyd From jgm at berkeley.edu Sat Sep 13 23:04:04 2008 From: jgm at berkeley.edu (John MacFarlane) Date: Sat, 13 Sep 2008 20:04:04 -0700 Subject: [ANN] pandoc 1.0.0.1 Message-ID: <20080914030404.GA19930@berkeley.edu> I'm pleased to announce the release of pandoc version 1.0.0.1. Pandoc is a general text markup format converter. In addition to strict markdown and an extended markdown syntax (including tables, footnotes, definition lists, enhanced ordered lists, LateX math, etc.), pandoc can read HTML, LaTeX, and reStructuredText. It can write HTML, LaTeX, ConTeXt, DocBook, RTF, OpenDocument XML, ODT, MediaWiki, groff man, S5, GNU Texinfo, markdown, and reStructuredText. Downloads: http://pandoc.googlecode.com/ User's guide: http://johnmacfarlane.net/pandoc/README.html Examples: http://johnmacfarlane.net/pandoc/examples.html Interactive demo: http://johnmacfarlane.net/pandoc/trypandoc/ Bug tracker: http://code.google.com/p/pandoc/issues/list Mailing list: http://groups.google.com/group/pandoc-discuss Some highlights of this release: + New GNU Texinfo writer (contributed by Peter Wang) + New OpenDocument XML writer (contributed by Andrea Rossato) + New ODT (OpenOffice document) writer + New MediaWiki markup writer + New delimited (="fenced") code block syntax + Cleaner code and build system + New Windows installer + Better support for math, including display math + Better HTML sanitizing for use in web applications + Many minor improvements and bug fixes (see changelog for details) Pandoc can optionally be compiled with support for + syntax highlighting of delimited code blocks, using the highlighting-kate library (over 50 languages are supported) (specify -fhighlighting) + automatically generated citations and bibliography, using Andrea Rossato's hs-citeproc library (specify -fciteproc) I am particularly excited about Rossato's experimental citation support. It's basically a BibTeX-like system that one can use in markdown, and it works with all of pandoc's output formats. So you can have automatically generated citations in a blog post, a wiki page, or even a man page! It's not yet complete, but it's far enough along for those with an adventurous spirit to use. I am very grateful to everyone who contributed bug reports and code, and especially to Andrea Rossato and Peter Wang for their major contributions. From tammy.lists at warmfuzzy.com Thu Sep 25 20:47:53 2008 From: tammy.lists at warmfuzzy.com (Tammy Cravit) Date: Thu, 25 Sep 2008 17:47:53 -0700 Subject: [ANN] markupwc: A simple word counting utility for Markdown files Message-ID: <0c2901c91f71$8246bfd0$0445a8c0@eclectus> I am a professional freelance writer and mystery novelist, and I often work on a variety of systems -- Linux/Unix, Mac, PC and my AlphaSmart. For that reason, I write the majority of my articles, short stories and novels using Markdown, which I then convert HTML for the Web or (via Pandoc) to RTF/ODT/etc. for publication. In support of that work, I've recently developed a utility, mkdwc, which strips the markup from one or more Markdown (or, if you rename it to ttwc, Textile) files and then performs a word/line/character count much like the Unix wc(1) utility. mkdwc is written in Ruby, and should be pretty cross-platform. Anyone interested is welcome to download it from: http://www.wordsofwonder.net/markdown/ Comments, feedback, patches/updates, feature requests, etc. are all welcome. (Please note: The email address I use on the list is only for list traffic; if you want to make sure I'll see your e-mail, send it to tammy at wordsofwonder.net instead.) Warmly, Tammy