Re: A Modest Definition List Proposal
On Tue, Apr 13, 2010 at 3:21 PM, Tom Humiston t...@jumpingrock.net wrote: Found this unsent reply stuffed in my drafts folder... On 19 Feb 2009, at 6:48 AM, Michel Fortin wrote: Definition lists are already some sort of specialized niche syntax within Markdown and HTML: useful when you need one, but not something a lot of people care for or even know it exists. Definition lists are suitable for many kinds of term/value pairings, and not just definitions, but I had no concept of DLs as a flexible and handy semantic structure until I learned CSS. CSS encourages one to consider a document's *structure* (its HTML elements) as separate from its *presentation* (the appearance of those elements). I now regularly mark up, say, each workshop in a list as a DT, with its details (description, cost, meeting times, contact info) as DDs. Other CSS users may prefer to use unordered lists or the like, and sometimes I do, too. Is my use of DL appropriate? According to [Russ Weakley][1]: In this respect see the working draft for [html5][1]. In part is says: The dl element represents an association list consisting of zero or more name-value groups (a description list). It's called a description list! They're not even called definition lists any more. In fact, a number of examples on that page would not fit the definition model, but are considered completely appropriate for a dl. True, markdown is currently not specifically intended at a html5 tool (although it could be as valid html4 and valid xhtml are also valid html5), but given that html5 is to a large extent just a spec indicating how people and/or browsers are actually doing things, I see it an an admission that definition list was a bad (too restrictive) name for an otherwise useful feature. [1]: http://www.w3.org/TR/html5/semantics.html#the-dl-element -- \X/ /-\ `/ |_ /-\ |\| Waylan Limberg ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
Le 2010-04-13 à 15:21, Tom Humiston a écrit : Is my use of DL appropriate? When in doubt, check HTML5 (which tend to make everything unambiguous). Here it says: The dl element represents an association list consisting of zero or more name-value groups (a description list). Each group must consist of one or more names (dt elements) followed by one or more values (dd elements). Within a single dl element, there should not be more than one dt element for each name. Name-value groups may be terms and definitions, metadata topics and values, or any other groups of name-value data. The values within a group are alternatives; multiple paragraphs forming part of the same value must all be given within the same dd element. The order of the list of groups, and of the names and values within each group, may be significant. http://www.whatwg.org/specs/web-apps/current-work/multipage/grouping-content.html#the-dl-element Note that it renames definition list to description list, in support for the idea that it's not only for definitions. -- Michel Fortin michel.for...@michelf.com http://michelf.com/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On Apr 13, 2010, at 12:41 PM, Michel Fortin wrote: http://www.whatwg.org/specs/web-apps/current-work/multipage/grouping-content.html#the-dl-element Note that it renames definition list to description list, in support for the idea that it's not only for definitions. This is great news. Thanks for passing it on (Waylan too)! Best, David ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal (David E. Wheeler)
* Aristotle Pagaltzis pagalt...@gmx.de [2009-02-28 16:18]: You can make a lot easier to write with a very simple tweak: Sorry for the noise. Someday I’ll consistently remember to read the whole thread before following my impulse to respond. Regards, -- Aristotle Pagaltzis // http://plasmasturm.org/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal (David E. Wheeler)
Le 2009-02-25 à 22:00, Dr. Drang a écrit : 1. Regular Markdown--by which I mean Gruber's Markdown.pl--looks good[^1] regardless of whether you're using proportional or monospaced fonts. I can't think of any construct in which the width of the characters makes a difference. Well, if you want list items spanning on multiple lines to align properly, it's pretty hard to do with spaces using a proportional font. 1. List item spanning on more than one line. 2. Plain text tables almost always look like crap *unless* you're using a monospaced font, because columns always include a mixture of visible characters and spaces. I suspect this is one of the reasons Gruber hasn't put tables into Markdown.pl. You can sometime use tabs in proportional fonts in some situations. It helps aligning things correctly, and not only for tables, but also with the list item example above. Although if you later view it with a different font it'll probably look like crap too. 3. Markdown was not intended to cover every situation; it's meant to be a simple, readable substitute for simple (X)HTML. In this spirit, we shouldn't expect table additions to Markdown to be able to handle every type of table, just the simpler types. I like the table syntax of PHP Markdown Extra and MultiMarkdown for this reason. That's in part why I'm reticent to add a new type of table with cells spanning on multiple rows to PHP Markdown Extra. 4. Using a script[^2] to align the pipes of a plain text table is very practical if you're writing in a monospaced font. You can write and edit the table quickly without regard to alignment, then make it readable by applying the script to it. It's much easier to make tables this way than to type them out in HTML. Indeed. I never though of that, but it's a good idea. That said, it's pretty easy to write a properly-aligned table without a script too. I've been doing that for some time. -- Michel Fortin michel.for...@michelf.com http://michelf.com/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal (David E. Wheeler)
On Feb 25, 2009, at 9:57 AM, Sherwood Botsford wrote: I suspect that if you were going to write a lot of tables, you'd write a perl program that would take an existing table that you slopped together, and would fix the spacing of pipes on all the lines to match the pipe spacing on the first line. Since I write most of my MultiMarkdown documents in TextMate, I (and others) have written Bundles that will do just this. I type out a table using the MMD delimiters (|), and the bundle command takes care of aligning columns and making it look nice. Sadly, I suspect that plain text tables require either the use of tabs (which vary based on the readers application), or fixed whitespace and a monospace font - which is tough to manually write. My thoughts: + I am perfectly willing to change the MMD table syntax if a better alternative (particularly a standard one) comes along + Not everyone uses monospace fonts - as nice as that would be for tables, I think it's not reasonable to expect that to be a requirement for viewing tables + I hope someone out there smarter than me creates a better table syntax ;) F- -- Fletcher T. Penney fletc...@fletcherpenney.net Beauty lies in the hands of the beer holder. - Anonymous ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal (David E. Wheeler)
Le 2009-02-25 à 1:04, Benoit Perdu - TransMékong a écrit : Taking David's example further, here is a first try: id | name | description | more info -+-+---+- 6 | Inset | An inset element | just one element 8 | Stories | Another element | another element : with 2 lines, without : colons on the left. 9 | Other | Another element | another element : : : with 2 lines, with : : : colons on the left. 5 | Illust. | An illustration | new line, would this do? : : and I think you : Is it parseable? : : know what I mean. I doubt the no-colon-on-the-left lines will work. I mean, how do you know you're writing in fourth column without counting whitespace? (And if count whitespace it's unusable with proportional fonts.) The colon at each empty cell looks like vertical ellipsis, that makes it pretty legible Colons are a nice way to do it, but I doubt the table will be readable by anyone not already aware of the syntax. To see what I mean, just take a look at the last column and forget for a moment that you know the difference in meaning between : and |. It then looks like one big paragraph of continuous text. You can disambiguate by reading the text, then figure out the meaning of | and :, but that's removing the usefulness of a table which should be scannable at first glance. If you want multiple lines per cell, I'd suggest using a more explicit grid, something like this: id | name | description | more info |=|==|= 6 | Inset | An inset element | just one element |-|--|- 8 | Stories | Another element | another element | | | with 2 lines |-|--|- 9 | Other | Another element | another element | | | with 2 lines |-|--|- 5 | Illust. | An illustration | line breaks are not | | andn I think you | possible in a table | | know what I mena.| This is totally unambiguous and easy to scan for the reader. The problem is that, even though it's easy to read, it's also more tedious to write. -- Michel Fortin michel.for...@michelf.com http://michelf.com/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal (David E. Wheeler)
id | name | description | more info |=|==|= 6 | Inset | An inset element | just one element |-|--|- 8 | Stories | Another element | another element | | | with 2 lines |-|--|- 9 | Other | Another element | another element | | | with 2 lines |-|--|- 5 | Illust. | An illustration | line breaks are not | | andn I think you | possible in a table | | know what I mena.| This is totally unambiguous and easy to scan for the reader. The problem is that, even though it's easy to read, it's also more tedious to write. One minor change. You don't need pipes in the horizontal separator lines. E.g: id | name | description | more info I suspect that if you were going to write a lot of tables, you'd write a perl program that would take an existing table that you slopped together, and would fix the spacing of pipes on all the lines to match the pipe spacing on the first line. Tables are critters where formatting is tangled with content. And with proportional type, a text only system requires agreement on tab spacing at minimum to get anything to look right. (I'm not a fan of monospace, so all these examples are wonky.) Add to this, the need for centering, the need for column spans. Allignment could be done with your horizontal separators. |---| Means use your default alignment. (Same as cell above) || Means left alignment. The can appear anywhere between the |'s |--| Means right alignment. |-=| means center alignment. Column spans could be done by replacing the pipe with an underscore. |=_===| |This is a cell that spans two| columns, and is centred. |--|--| |Column 1 |Column 2| I'm working in a proportional font, so the above example is sure to be wonky. Note that these two ideas are contradictory. To merge, them (makes reading slightly harder, but writing slightly easier. | Default alignment | | Left Alignment | | Right Alignment | |= Centered alignment =| The alignment tags don't have to be paired, but can be for eye candy purposes. || Spans two columns of the stuff below | | Column 1 | Column 1 | -- Sherwood Botsford Sherwood's Forests Warburg, Alberta T0C 2T0 http://www.sherwoods-forests.com 780-848-2548 ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal (David E. Wheeler)
On Feb 24, 2009, at 10:04 PM, Benoit Perdu - TransMékong wrote: Taking David's example further, here is a first try: id | name | description | more info -+-+---+- 6 | Inset | An inset element | just one element 8 | Stories | Another element | another element : with 2 lines, without : colons on the left. 9 | Other | Another element | another element : : : with 2 lines, with : : : colons on the left. 5 | Illust. | An illustration | new line, would this do? : : and I think you : Is it parseable? : : know what I mean. The colon at each empty cell looks like vertical ellipsis, that makes it pretty legible Yes, nice. I think I like how it looks without the left colons better, though it could potentially work both ways. Adding a 'wrappable' cell definition would go a long way to make it perfect. Do you mean something more should be added, or that the use of `:` to define wrapped cells in this example is what goes a long way? Thanks, David ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal (David E. Wheeler)
David E. Wheeler wrote: On Feb 25, 2009, at 6:57 AM, Sherwood Botsford wrote: One minor change. You don't need pipes in the horizontal separator lines. E.g: id | name | description | more info They could be optional; I prefer them. Tables are critters where formatting is tangled with content. And with proportional type, a text only system requires agreement on tab spacing at minimum to get anything to look right. (I'm not a fan of monospace, so all these examples are wonky.) I think you might be using the wrong markup language, then. The use of monospace fonts is an expectation for reading Markdown. Really, it's the whole point. Wait, what? Monospace is an expectation?!? I have never used monospace in my e-mail programs. Isn't THAT the main expectation of Markdown? That it approximates e-mail writing? I think the only time I actually use monospace fonts is with Alt-F1 (or Ctrl-Alt) Admittedly it is easier to create legible text documents with lots of bullets and tables and definition lists if you are using a monospace font but in my experience monospace fonts are generally just harder to read. The beauty of markdown is that you can approximate the spacing of monospace by varying the whitespace. Or just let it be wonky. (Of course what looks beautiful in one proportional font will be wonky in another anyway) Add to this, the need for centering, the need for column spans. Allignment could be done with your horizontal separators. |---| Means use your default alignment. (Same as cell above) || Means left alignment. The can appear anywhere between the |'s |--| Means right alignment. |-=| means center alignment. I dislike these. I have other ideas for alignment, but I need to do some more thinking and drafting before I have a proposal to submit. Column spans could be done by replacing the pipe with an underscore. |=_===| |This is a cell that spans two| columns, and is centred. |--|--| |Column 1 |Column 2| I'm working in a proportional font, so the above example is sure to be wonky. Yes, and basically illegible. Note that these two ideas are contradictory. To merge, them (makes reading slightly harder, but writing slightly easier. | Default alignment | | Left Alignment | | Right Alignment | |= Centered alignment =| The alignment tags don't have to be paired, but can be for eye candy purposes. || Spans two columns of the stuff below | | Column 1 | Column 1 | IMHO, any formatting should be invisible in Markdown. That is, it should be implicit. The use of all these extra characters to show alignment and whatnot makes for ugly text-only tables. Best, David ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal (David E. Wheeler)
Le 2009-02-25 à 9:57, Sherwood Botsford a écrit : id | name | description | more info |=|==|= 6 | Inset | An inset element | just one element |-|--|- 8 | Stories | Another element | another element | | | with 2 lines |-|--|- 9 | Other | Another element | another element | | | with 2 lines |-|--|- 5 | Illust. | An illustration | line breaks are not | | andn I think you | possible in a table | | know what I mena.| This is totally unambiguous and easy to scan for the reader. The problem is that, even though it's easy to read, it's also more tedious to write. One minor change. You don't need pipes in the horizontal separator lines. E.g: id | name | description | more info My idea was to follow the way it currently works for tables in PHP Markdown Extra, which was made this way to make the difference clearer from the header syntax and to allow specifying text alignment for columns. http://michelf.com/projects/php-markdown/extra/#table I suspect that if you were going to write a lot of tables, you'd write a perl program that would take an existing table that you slopped together, and would fix the spacing of pipes on all the lines to match the pipe spacing on the first line. If you're going to write a Perl program for creating Markdown tables, why not create tables in HTML directly? It'd be a lot simpler to write a converter for that, and it would avoid cluttering the syntax with something you need a special program to make anyway. -- Michel Fortin michel.for...@michelf.com http://michelf.com/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal (David E. Wheeler)
On Wed, Feb 25, 2009 at 8:34 PM, Seumas Mac Uilleachan seu...@idirect.ca wrote: David E. Wheeler wrote: On Feb 25, 2009, at 6:57 AM, Sherwood Botsford wrote: Tables are critters where formatting is tangled with content. And with proportional type, a text only system requires agreement on tab spacing at minimum to get anything to look right. (I'm not a fan of monospace, so all these examples are wonky.) I think you might be using the wrong markup language, then. The use of monospace fonts is an expectation for reading Markdown. Really, it's the whole point. Wait, what? Monospace is an expectation?!? I have never used monospace in my e-mail programs. Isn't THAT the main expectation of Markdown? That it approximates e-mail writing? Well, I wouldn't say monospace is an expectation, but Markdown does rely heavily (perhaps more so than most) on whitespace. It just so happens that that whitespace is easier for the human eye to read when the text is monospace. However, yes, email is rarely written in monospace. Of course, on most cases, the white space is all at the beginning of the line (code blocks, lists) and the different levels of indent are still discernible when not in monospace. So, when the comment is made that the examples are wonky because they are not in monospace, then IMO, the proposed syntax fails. We all know that Markdown is to be readable first, writable second. If every reader of the document must read it in monospace, then that's not readable first - it's writable first. I'd also like to point out JB comments [1] that Markdown it supposed to cover only a common subset of HTML. If your trying to represent something more complex, then you need to use HTML. I would say multiline table cells fall into that more complex category. I know I'm never going to use any of this overly complex syntax that has been proposed thus far. I'll just write some raw HTML for my table and be done with it quickly. Don't get me wrong, if I have some vary basic tables that can easily be represented with the simplest syntax, then sure, I'll use something link PHP Extra's. Anything more than that will get raw HTML. [1]: http://daringfireball.net/projects/markdown/syntax#html -- \X/ /-\ `/ |_ /-\ |\| Waylan Limberg ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal (David E. Wheeler)
If you're going to write a Perl program for creating Markdown tables, why not create tables in HTML directly? It'd be a lot simpler to write a converter for that, and it would avoid cluttering the syntax with something you need a special program to make anyway. Depends on how you use the program. I end up doing most of my actual coding in vi. In vi I write markdown source, because it's quick, I can sort of see how it lays out, and I don't worry about a billion html tags. I spend my time writing content, not matching tags. In my other writing I use par a lot. This is a program to reformat ascii text. It can do clever things like reformat email with multiple quoted levels, to different line lengths without sprinkling 's everywhere midline. If you are a dedicated markdown user, a perl program that you can pipe a table through to put it in whatever syntax your favorite version of markdown likes, AND such a program removes a lot of the tedium of adjusting the space so that you, the writer can live with it, you have a win. I don't want to have a separate source file for my table, nor do I want to include an html table in my markdown. I want a perl command, or vi macro that takes bad table text (from markdown's view, and my personal view) and turns it into good table text. KIS Tables are complicated. How they are represented in simple text is going to be a compromise between control and legibility. The idea solution would be one that maximizes legibility in simple cases while allowing control short of full html code where the author needs it. -- Sherwood Botsford Sherwood's Forests Warburg, Alberta T0C 2T0 http://www.sherwoods-forests.com 780-848-2548 ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On 19 Feb 2009, at 12:53 PM, David E. Wheeler wrote: Thanks John. Like I said, I prefer it to a colon because, in my mind at least, a colon goes at the end of things, not the beginning of things. I lean toward colon because I see colons coming not at the beginning or end, but in the middle, between things. In this case, between a term and its definition(s). -J.G. ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On Feb 23, 2009, at 8:59 AM, John Gruber wrote: Thanks John. Like I said, I prefer it to a colon because, in my mind at least, a colon goes at the end of things, not the beginning of things. I lean toward colon because I see colons coming not at the beginning or end, but in the middle, between things. In this case, between a term and its definition(s). I can see that, but: 1. The same is true for tildes; even more true, since there is usually a space on either side of a tilde 2. The colon is very hard to see in some fonts; it makes a lousy bullet, IMHO, especially when it's the first character on a line 3. I've been thinking about table syntax, looking at what the OSS databases do, and PostgreSQL has a nice use for colons to show continued records: id | name |description +-+ 6 | Inset | An inset element type 8 | Related Stories | A related stories element type. 5 | Illustration| An illustration media type : and I think you know what I mean. 2 | Column | A weekly column story type 10 | Story | A story document type That seems kind of nice to me because a colon is kind of like a broken pipe. But that's for a later discussion, and might not conflict with PHP Markdown Extra's use of a colon for DLs, anyway. As I said, we could support both just as we support `*`, `+`, and `-` for unordered list bullets. Best, David ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
Le 2009-02-19 à 1:52, Yuri Takhteyev a écrit : Correct. Or one could say there is no way to get any standard blessed as official here period. The closest you can get is to convince Michel to add it to Markdown Extra, in which case there is a reasonable chance that some of the other implementations will add optional support for it. In this particular case, I find it hard to see this proposal going very far, though. (Of course, Michel can prove me wrong.) It seems I've been called into this discussion. :-) Well, that whole thread left me wondering. I'm of opinion that using a tilde is as good as a colon, perhaps even better visually. It has the advantage of looking better when you add a colon at the end of your term (which, I think, happen often enough): Term: : Definition Term: ~ Definition The current syntax using a colon has been there... since PHP Markdown Extra's debuts (July 2005). There is obviously a lot of documents out there using it, so there's not way I'll just change it to something else. As for accepting the tilde as an alternate marker, there's obviously a precedent of that: unordered lists which can be made of `*`, `+`, or `- `, so it wouldn't be counter-nature to add one for definition lists. On the other hand, that precedent was meant to allow other syntaxes in common use to work with Markdown; I'm not sure any syntax we can come with for definition lists is already in common use. Definition lists are already some sort of specialized niche syntax within Markdown and HTML: useful when you need one, but not something a lot of people care for or even know it exists. So in the end I'm pretty much ambivalent to this proposal: I like it but I don't think it's worth wasting another marker character and dealing with possible clashes (legitimate text with a tilde in it). That said, perhaps I'll change my mind the next time I have to write a definition list. -- Michel Fortin michel.for...@michelf.com http://michelf.com/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On 18 Feb 2009, at 1:44 PM, David E. Wheeler wrote: What I came up with is a single character change to the PHP Markdown Extra syntax. I just published a detailed explanation of my thoughts and reasoning for this on [my blog](http://justatheory.com/computers/markup/modest-markdown-proposal.html ). Unlike most syntax suggestions, your suggestion to use tilde as the marker for definitions strikes me as genuinely Markdown-ish. I'm not sure it's any better than colon, though. -J.G. ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On Feb 19, 2009, at 3:48 AM, Michel Fortin wrote:
It seems I've been called into this discussion. :-)
And thanks for taking the bate. :-)
A quick comment: I started using Markdown about six months ago to
write the documentation for pgTAP, my PostgreSQL unit-testing
framework. Since the format for PostgreSQL documentation is a plain-
text README, and I knew I was going to want it in HTML and perhaps
other formats, I adopted Markdown for the documentation without a
second thought. It felt right, it works almost exactly like I've
always worked in email, and I've been absolutely thrilled with the
[plain text][1] and [HTML][2] results.
[1] https://svn.kineticode.com/pgtap/trunk/README.pgtap
[2] https://svn.kineticode.com/pgtap/trunk/README.pgtap
It has just been a delight to work with, very rewarding. And I guess I
shouldn't be surprised that the community behind it, represented by
this list, is no different. I really appreciate you guys taking the
time to really ponder a possible change to something you've been using
as-is for almost 4 years when a late interloper like myself barges in
and says, “what about this?” Such openness is all to rare in the OSS
world, and just makes me love Markdown all the more.
So thanks for taking me and my proposal seriously. Later, we'll see if
folks are as willing when I look at tables. ;-P
Well, that whole thread left me wondering. I'm of opinion that using
a tilde is as good as a colon, perhaps even better visually. It has
the advantage of looking better when you add a colon at the end of
your term (which, I think, happen often enough):
Term:
: Definition
Term:
~ Definition
Yes, much more natural looking to me, and it stands out a bit more; in
a lot of non-programming fonts, colons are really tiny.
The current syntax using a colon has been there... since PHP
Markdown Extra's debuts (July 2005). There is obviously a lot of
documents out there using it, so there's not way I'll just change it
to something else.
Yes, I was pleased to realize that that one character was the only
thing that wasn't working for me in the PHP Markdown Extra syntax. I
started pondering the syntax thinking that a more radical change would
be necessary to make it appeal to me. But this is so simple and easy
to allow for backwards compatibility that I was really happy to have
it. Plus, it's dead easy to modify existing implementations to support
it, which both makes it an easier sell and makes it easier for me to
just do on my own.
As for accepting the tilde as an alternate marker, there's obviously
a precedent of that: unordered lists which can be made of `*`, `+`,
or `-`, so it wouldn't be counter-nature to add one for definition
lists. On the other hand, that precedent was meant to allow other
syntaxes in common use to work with Markdown; I'm not sure any
syntax we can come with for definition lists is already in common
use. Definition lists are already some sort of specialized niche
syntax within Markdown and HTML: useful when you need one, but not
something a lot of people care for or even know it exists.
Even with the colon, the Markdown Extra syntax is so much better than
any other DL syntax I've seen. So I agree about the lack of precedent
in other markup syntaxes. But I didn't know that `*`, `+`, and `-`
were there for compatibility; as a user of Markdown, I just thought it
was for convenience that I could use either one. In fact, I actually
thought they were there so that I could use different bullets at
different levels of a nested list, which would be more natural than
using just one in plain text.
All that is just to say that I think there are two ways to look at the
precedent of list bullets, regardless of the history, and that
convenience and flexibility apply to the idea of the
interchangeability of `:` and `~` in definition lists.
So in the end I'm pretty much ambivalent to this proposal: I like it
but I don't think it's worth wasting another marker character and
dealing with possible clashes (legitimate text with a tilde in it).
I think we determined that that was only an issue in single-line term/
definition combinations, which aren't implemented with `::` either,
AFAIK. When the `~` has to come at the beginning of the line, it's no
worse than the possible conflict of using `-` for an unordered list
bullet.
That said, perhaps I'll change my mind the next time I have to write
a definition list.
This came up for me because I write a lot of documentation for
libraries I write, and many of the functions and methods support a
parameter list of arguments. This is a very natural fit for definition
lists, so I could potentially use them all the time, like so:
~~
### `new()` ###
$fsa = FSA::Rules-new(
\%params,
foo_state = { ... },
bar_state = { ... },
);
Re: A Modest Definition List Proposal
On Feb 19, 2009, at 9:42 AM, John Gruber wrote: What I came up with is a single character change to the PHP Markdown Extra syntax. I just published a detailed explanation of my thoughts and reasoning for this on [my blog](http://justatheory.com/computers/markup/modest-markdown-proposal.html ). Unlike most syntax suggestions, your suggestion to use tilde as the marker for definitions strikes me as genuinely Markdown-ish. I'm not sure it's any better than colon, though. Thanks John. Like I said, I prefer it to a colon because, in my mind at least, a colon goes at the end of things, not the beginning of things. The colon just looks weird to me, while the tilde does not. I'm speaking purely from a visual communication point of view about the plain-text representation here, of course. But, like I said, it's dead easy to support both in the existing implementations. Best, David ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
A Modest Definition List Proposal
Howdy, I've been thinking a lot about definition list syntax, and what I did and didn't like about the PHP Markdown Extra syntax (which seems to be a de-facto standard, discount notwithstanding, yes?). What I came up with is a single character change to the PHP Markdown Extra syntax. I just published a detailed explanation of my thoughts and reasoning for this on [my blog](http://justatheory.com/computers/markup/modest-markdown-proposal.html ). If you would excuse the temerity of my late entry into what I'm sure has been a contentious issue, I would love feedback. In a nutshell, I embrace the PHP Markdown Extra syntax, with one change: I would like to see the colon replaced with a tilde (for backwards compatibility, both should be supported). That means that a simple definition list would look like this: Apple: ~ Pomaceous fruit of plants of the genus Malus in the family Rosaceae. ~ An american computer company. Orange: ~ The fruit of an evergreen tree of the genus Citrus. And a more complicated one would look like this: Term 1: ~ This is a definition with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. ~ Second definition for term 1, also wrapped in a paragraph because of the blank line preceding it. Term 2: ~ This definition has a code block, a blockquote and a list. code block. block quote on two lines. 1. first list item 2. second list item See my blog entry for more detailed description of why I prefer the tilde to the colon for this purpose. The best things about it are that it makes for a more natural bullet, already has precedent in dictionaries, and suggest equivalency if you're familiar with mathematics, which makes for a nice mnemonic. Comments? Has this ship already sailed? Best, David ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On Wed, Feb 18, 2009 at 1:44 PM, David E. Wheeler da...@kineticode.com wrote: [snip] In a nutshell, I embrace the PHP Markdown Extra syntax, with one change: I would like to see the colon replaced with a tilde (for backwards compatibility, both should be supported). That means that a simple definition list would look like this: [snip] Comments? Has this ship already sailed? You make a convincing argument. And I must admit your proposal is very nice to look at/read/write. But if it ain't broke, don't fix it. The current implementation was set before I came along some few years ago, and I have never searched through the archives to see how it came about or why. But, people have been using it for this long without issue and there are already numerous existing documents out there that use it, so I see no reason to change it. In fact that last point (numerous existing documents) seems to be the de-facto response to any suggested changes on this list - and understandably so. No doubt that's why you suggested leaving the existing syntax in place, but then we would have two ways to define deflists. What happens when an author mixes the two? Ack! Yeah, this ship has sailed IMO. -- \X/ /-\ `/ |_ /-\ |\| Waylan Limberg ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On Feb 18, 2009, at 12:19 PM, Waylan Limberg wrote:
Comments? Has this ship already sailed?
You make a convincing argument. And I must admit your proposal is very
nice to look at/read/write.
Thank you.
But if it ain't broke, don't fix it.
The current implementation was set before I came along some few years
ago, and I have never searched through the archives to see how it came
about or why. But, people have been using it for this long without
issue and there are already numerous existing documents out there that
use it, so I see no reason to change it. In fact that last point
(numerous existing documents) seems to be the de-facto response to any
suggested changes on this list - and understandably so. No doubt
that's why you suggested leaving the existing syntax in place, but
then we would have two ways to define deflists. What happens when an
author mixes the two? Ack! Yeah, this ship has sailed IMO.
I don't think it's a problem to have two different kinds of bullets
for definition list items; after all, you can already use +, -, or *
for unordered lists. And you can mix them without penalty, so the same
would be true here.
FWIW, the change to MultiMarkdown.pl to make this work would just be
this:
--- bin/MultiMarkdown.pl.orig 2008-01-18 15:08:43.0 -0800
+++ bin/MultiMarkdown.pl2009-02-18 12:28:47.0 -0800
@@ -2559,7 +2559,7 @@
my $definition = qr{
\n?[ ]{0,$less_than_tab}
- \:[ \t]+(.*?)\n
+ [:~][ \t]+(.*?)\n
((?=\n*[ ]{0,$less_than_tab}\S)|\n\n|\Z) # Lookahead for non-space
at line-start,
# two returns, or end of doc
}sx;
Plus documentation, of course. Doesn't get much simpler than that.
Thanks for your reply.
Best,
David
___
Markdown-Discuss mailing list
Markdown-Discuss@six.pairlist.net
http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On Feb 18, 2009, at 10:44 AM, David E. Wheeler wrote: See my blog entry for more detailed description of why I prefer the tilde to the colon for this purpose. The best things about it are that it makes for a more natural bullet, already has precedent in dictionaries, and suggest equivalency if you're familiar with mathematics, which makes for a nice mnemonic. Comments? Has this ship already sailed? Aristotle was kind enough to point me to some older posts on the subject of definition lists, where I saw this message from Mssr. Gruber: On Jul 27, 2005, at 7:33 AM, John Gruber wrote: And since the ones with multiple terms and/or definitions are the exception, not the norm, I think in the common cases, you'd wind up with something that looks like this: Term 1:: Definition a blah blah blah blah blah Term 2:: Definition b foo bar baz Term 3:: Definition c even more blah blah blah Was this ever implemented? I haven't noticed it in the documentation for PHP Markdown Extra or MultiMarkdown. I think that, using the tilde as I've suggested in this thread, this can be even better: Term 1 ~ Definition a blah blah blah blah blah Term 2 ~ Definition b foo bar baz Term 3 ~ Definition c even more blah blah blah Basically, it's the same rule, only you don't have to have a newline before the definition starts. Also, the single ~ is a little less “unnatural” looking than the double : (and I say that as a Perl hacker, so I'm used to “::”!). Best, David ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On Feb 18, 2009, at 2:50 PM, Tom Humiston wrote: A problem I see with your suggestion about not including newlines is that interpreting the form xxx ~ yyy as a DT/DD pair precludes the use of ~ (space-tilde-space) in some other ways it's likely to be used ~ for instance, as an alternative to the plain hyphen. Yeah. I think ~~ would work okay, too, and gets around that problem. Term 1 ~~ Definition a blah blah blah blah blah Term 2 ~~ Definition b foo bar baz Term 3 ~~ Definition c even more blah blah blah Although I think that it's a bit of a red herring. I also suppose that's why the suggestion in 2005 was for double colons. Colon-newline seems pretty clear, if anything is. (Mind you, I am NOT involved in writing implementations whatsoever; I'm just watching the mailing list.) I didn't see anyone suggest tilde for definitions in 2005, though I did notice that Aristotle tried it out for terms. I agree with him that tildes didn't work so well there. :-) Best, David ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
Yeah, Markdown users in the hard sciences would trigger that constantly. best, Joe On 2/18/09, Yuri Takhteyev qarama...@gmail.com wrote: Right. I actually think that using ~ as a range operator (essentially) is fairly rare outside of electronic circles, at least in US English. In other words, by at least 5% of the world population. :) But even just looking at the US English, ~ is often used for approximation, for the home directory, for equivalence, etc. So, things like The cost is ~ $3, cd to ~ before doing this, The N needs a ~ over it, If we assume x ~ y, then will all suddenly become definition lists? Term 1 o Definition a blah blah blah blah blah Term 2 o Definition b foo bar baz Term 3 o Definition c even more blah blah blah É. O unico problema é o o do Portugues, que é um artigo nessa linguagem. (Our friend o is a _word_ in some languages.) - yuri -- http://spu.tnik.org/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss -- Joseph Lorenzo Hall ACCURATE Postdoctoral Research Associate UC Berkeley School of Information Princeton Center for Information Technology Policy http://josephhall.org/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On Feb 18, 2009, at 4:37 PM, Yuri Takhteyev wrote: Right. I actually think that using ~ as a range operator (essentially) is fairly rare outside of electronic circles, at least in US English. In other words, by at least 5% of the world population. :) But even just looking at the US English, ~ is often used for approximation, for the home directory, for equivalence, etc. So, things like The cost is ~ $3, cd to ~ before doing this, The N needs a ~ over it, If we assume x ~ y, then will all suddenly become definition lists? Yeah, okay. Forget the one-line format, then. No one has implemented it so far anyway, as near as I can tell. :-) Term 1 o Definition a blah blah blah blah blah Term 2 o Definition b foo bar baz Term 3 o Definition c even more blah blah blah É. O unico problema é o o do Portugues, que é um artigo nessa linguagem. (Our friend o is a _word_ in some languages.) D'oh! Oh yeah! Sorry for the cultural imperialism. :-) Best, David ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
* David E. Wheeler da...@kineticode.com [2009-02-19 02:00]: Yeah, okay. […] D’oh! Oh yeah! Told you it is a thorny problem. :-( It *looks* simple, yeah… Regards, -- Aristotle Pagaltzis // http://plasmasturm.org/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: A Modest Definition List Proposal
On Feb 18, 2009, at 6:59 PM, Aristotle Pagaltzis wrote: Yeah, okay. […] D’oh! Oh yeah! Told you it is a thorny problem. :-( It *looks* simple, yeah… I still think that ~ works well (at least as well as :) in a non- single-line usage, which is all that's currently implemented with :, anyway. That said, there is no way to get any standard blessed as official here aside from Gruber adding it to Markdown.pl, right? Except for folks adding their own preferred methods to the existing implementations… Best, David ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
