Definition lists

[John Gruber]

Michel Fortin <michel.fortin at michelf.com> wrote on 07/27/05 at 8:10 am:


> What I have in mind right now is the mandatory blank line before each 

> definition, which would give this:

> 

>   Term

>   :   Definition

>   :   Definition

> 

>   Term

>   :   Definition

> 

>   Term

>   :   Definition


I think this is the way to go. Tough noogies for anyone who wants to
skip the blank lines.

The other issue is how do we deal with multiple terms per definition. E.g.:

    Term 1
    Term 2
    :  Definition that applies to both Term 1 and Term 2

    Term 3
    Term 4
    :  Two definitions
    :  Both of which definitions apply to Terms 3 and 4.

The rule here could be that Terms could not contain newlines; each
hard line of the term block preceding the definitions would be
considered a separate `<dt>` element.

How would this look for dict lists with paragraphs?

    Term A
    Term B
    
    :   Here's the first paragraph of the definition of Terms A
        and B. Blah blah blah.
        
        Here's the second paragraph.
    
    Term C
    Term D
    
    :   This definition contains a paragraph followed by a blockquote.
    
        > Markdown is a text-to-HTML conversion tool for web
        > writers. Markdown allows you to write using an
        > easy-to-read, easy-to-write plain text format, then
        > convert it to structurally valid XHTML (or HTML).



> This somewhat break with default HTML rendering of the browsers, which 

> do not put that much space between a definition and the following term. 


I wouldn't worry about that. Particularly since I think the default
browser rendering for `<dl>`s is pretty ugly.



> It also add one line to each term which is a lot of space when you have 

> many terms with small one-line definitions. But I feel this is the best 

> compromise.

> 

> Another way would be to add an unambiguous term marker, but this would 

> probably lead to too much markup characters and I have no idea what to 

> use for such marker. Here is an (ugly) example:

> 

>   ~Term

>   :   Definition

>   :   Definition

>   ~Term

>   :   Definition

>   ~Term

>   :   Definition


No, not tilda. In my head, I've been thinking that we could use a
trailing colon for the terms, if we need a marker for them in
addition to a marker for the defs:

    Term 1:
    :   Definition
    Term 2:
    :   Definition
    Term 3:
    Term 4:
    :   Definition
    
This would be exactly equivalent to:

    Term 1:
    :   Definition

    Term 2:
    :   Definition

    Term 3:
    Term 4:
    :   Definition

I think the version without the blank lines looks too squished. But
with the colon markers, we could allow it, since I think it would be
easy to parse. The only potential confusion would be a hard-wrapped
definition that ended with a colon:

    Term 1:
    :   This is a definition that ends
    with a colon:
    Term 2:
    :   Definition

But that's such a dumb thing to write, I can't say I'm worried about
it. (I'm thinking the above would parse with "with a colon" as a
term, not as part of the definition for Term 1.)

The other reason I've been thinking about using colons both ways is
that we could maybe get away with single-line dt/dd pairs:

    Term 1:: Definition a
    Term 2:: Definition b
    Term 3:
    Term 4:: Definition c
    Term 5:: Definition d
        : Definition e

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

-J.G.