Re: A Modest Definition List Proposal
On Feb 19, 2009, at 9:47 AM, David E. Wheeler wrote: 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.pgta Sorry, that second link should have been: [2] http://pgtap.projects.postgresql.org/documentation.html 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 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
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 => { ... },
);
Const
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: Tables
> - A table should look like a table in plain text > - It must be easy to create > - It must be flexible about how much text can go in a cell > - It shouldn't force you to use a fixed-width font I agree with the comment that the first and last desiderata are in tension. Since one of the guiding goals of markdown is to be *readable*, I decided in pandoc to go for the first and forget about the last. So, here's what a simple table looks like in pandoc -- pretty much just how you'd naturally write it in a plain text email (assuming you use a fixed-width font): Right Left Center Default --- -- -- --- 12 121212 123 123 123 123 1 1 1 1 Table: Demonstration of simple table syntax. As you can see, these simple tables also allow the user to specify the alignment of columns, and allow the user to specify a caption, all without anything that looks like markup. (I suppose the English-centricism of the caption syntax is objectionable. It would also be nice to have more flexibility in indicating borders. So there's room for improvement on this model.) Another desideratum is that table cells should not be limited to one line. So pandoc also allows tables like this: - Centered Default Right Left HeaderAligned Aligned Aligned --- --- --- - Firstrow12.0 Example of a row that spans multiple lines. Secondrow 5.0 Here's another one. Note the blank line between rows. - Table: Here's the caption. It, too, may span multiple lines. In fact, an even more general table syntax is needed, and eventually pandoc will probably support reStructuredText-style box tables, which allow arbitrary block-level elements in cells. Your comment suggested that you think this is too much work for the writer. But John Gruber has emphasized that markdown is meant to be a format that is easy on the *reader* (as well as the writer); markdown documents should look good on their own, without any conversion to another format. None of the table syntaxes that don't force a fixed width font really satisfy that, in my view. So that's the rationale behind pandoc's table syntax -- though I certainly understand why others made different decisions. Best, John +++ Daniel Winterstein [Feb 19 09 09:16 ]: > @John: Thank you for pointing me to those table syntax ideas. They are > all sensible, but look like hard work for the user. > > Since there is no standard, I'd like to suggest a couple of > possibilities and get people's comments. > > Design goals: > > - A table should look like a table in plain text > - It must be easy to create > - It must be flexible about how much text can go in a cell > - It shouldn't force you to use a fixed-width font > > Suggestion 1: > > - A table begins with a header row where columns are separated by |s. > It ends with a blank line. > - It can optionally include lines of -s, which are ignored when > generating html > - Within a table, columns are separated by either a tab or 3 or more > spaces. Actual alignment of text is up to the user. Alignment varies > of course depending on font. In my examples below, I have aligned the > columns _for my email editor_. > - If you want more control over a particular cell or row, you can use > an html cell or row > - If you need more control than that, use an html table > > Example: > > | Wine | Tasting notes > > Black Stump Bordeaux peppermint flavoured Burgundy > Sydney Syrup ranks among the world's best sugary wines > Château Blue lingering afterburn > Old Smokey 1968 compares favourably to a Welsh claret > 1970 Coq du Rod Laver recommended by the Australian Wino Society > Melbourne Old-and-Yellow a good fighting wine is, which is > particularly heavy and best suited for hand-to-hand combat. > Table: Lesser Australian wines > > > Idea 2: Use a table tag to mark a table block. If the contents are not > html, then convert them > > > Wine Tasting notes > Château Chunder a fine wine which really opens up the sluices > at both ends. > Sydney Syrup ranks among the world's best sugary wines > Château Blue lingering afterburn > Old Smokey 1968 compares favourably to a Welsh claret > 1970 Coq du Rod Laver recommended by the Australian Wino Society > Melbourne Old-and-Yellow a good fighting wine is, which is > particularly
Re: Tables
On Thu, Feb 19, 2009 at 3:16 AM, Daniel Winterstein wrote: > > Since there is no standard, I'd like to suggest a couple of > possibilities and get people's comments. > > Design goals: > > - A table should look like a table in plain text > - It must be easy to create > - It must be flexible about how much text can go in a cell > - It shouldn't force you to use a fixed-width font It seems to me that your first and last design goals are incompatible. A table looks like a table because of its vertical alignment, and there's no way to ensure vertical alignment in plain text unless you use a fixed-width font. To me, PHP Markdown Extra and MultiMarkdown have the right idea. The pipe characters make the table easy to write and are the traditional cell separators in ASCII tables. Once the table is written, it's relatively easy to add spaces to get everything aligned and make the plain text version look good. Getting the plain text aligned also helps you see where you have extra or missing columns. I wrote a [TextMate command][1] for doing this, and I'm sure it wouldn't be difficult to add similar commands to other text editors. -- Dr. Drang [1]: http://www.leancrew.com/all-this/2008/08/tables-for-markdown-and-textmate/ ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
Re: Tables
On Thu, Feb 19, 2009 at 4:16 AM, Daniel Winterstein wrote: > @John: Thank you for pointing me to those table syntax ideas. They are > all sensible, but look like hard work for the user. > > Since there is no standard, I'd like to suggest a couple of > possibilities and get people's comments. > Well, if I was to implement a table feature, I would just copy PHP's implementation. It's already well documented, in use, and has at least one copy (in MultiMarkdown) with embellishments. Why reinvent the wheel? Oh, and looking at your suggestions, they all look like a bunch of jumbled up randomly spaced text. Yes, I made sure my email client was set to fixed width, but still, my eyes couldn't follow the columns. As JG states, readability comes before writability, so we make the author add in the pipes (more work to write), so the reader can easily read it. -- \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 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: Tables
@John: Thank you for pointing me to those table syntax ideas. They are all sensible, but look like hard work for the user. Since there is no standard, I'd like to suggest a couple of possibilities and get people's comments. Design goals: - A table should look like a table in plain text - It must be easy to create - It must be flexible about how much text can go in a cell - It shouldn't force you to use a fixed-width font Suggestion 1: - A table begins with a header row where columns are separated by |s. It ends with a blank line. - It can optionally include lines of -s, which are ignored when generating html - Within a table, columns are separated by either a tab or 3 or more spaces. Actual alignment of text is up to the user. Alignment varies of course depending on font. In my examples below, I have aligned the columns _for my email editor_. - If you want more control over a particular cell or row, you can use an html cell or row - If you need more control than that, use an html table Example: | Wine | Tasting notes Black Stump Bordeauxpeppermint flavoured Burgundy Sydney Syrupranks among the world's best sugary wines Château Bluelingering afterburn Old Smokey 1968 compares favourably to a Welsh claret 1970 Coq du Rod Laver recommended by the Australian Wino Society Melbourne Old-and-Yellowa good fighting wine is, which is particularly heavy and best suited for hand-to-hand combat. Table: Lesser Australian wines Idea 2: Use a table tag to mark a table block. If the contents are not html, then convert them WineTasting notes Château Chunder a fine wine which really opens up the sluices at both ends. Sydney Syrupranks among the world's best sugary wines Château Bluelingering afterburn Old Smokey 1968 compares favourably to a Welsh claret 1970 Coq du Rod Laver recommended by the Australian Wino Society Melbourne Old-and-Yellowa good fighting wine is, which is particularly heavy and best suited for hand-to-hand combat. Pros: can provide class information and border settings. Idea 3: Use a caption at the end of the table to mark a table block, with empty captions being allowed. Example: WineTasting notes Black Stump Bordeauxpeppermint flavoured Burgundy Sydney Syrupranks among the world's best sugary wines Château Bluelingering afterburn. Old Smokey 1968 compares favourably to a Welsh claret 1970 Coq du Rod Laver recommended by the Australian Wino Society Melbourne Old-and-Yellowa good fighting wine is, which is particularly heavy and best suited for hand-to-hand combat. Table: Lesser Australian wines What do you think? Regards, Daniel ___ Markdown-Discuss mailing list Markdown-Discuss@six.pairlist.net http://six.pairlist.net/mailman/listinfo/markdown-discuss
