Implemented: Improved Definition Lists

New syntax for definition lists that allows spaces in the term. The syntax is: 3 spaces, dollar sign, 1 space, term text, colon, space, definition text.

Example, you type:

   $ This is term one: This is the definition
   $ One more term: Source text spans
     two lines

You get:

This is term one

This is the definition

One more term

Source text spans two lines

The old syntax of 3 spaces, term (without space), colon, space, definition text gets deprecated but remains implemented as an undocumented feature for backward compatibility.

Definition lists can be used for action plans, meeting minutes, glossaries, etc.

Contributors:
-- AdamTheo
-- GaroldJohnson
-- MichaelSparks
-- PeterMasiar
-- PeterThoeny

Discussions

I've updated my patches to work with the new December 01 2001 release.

It's a one line change to TWiki.pm from:

            s/^(\t+)(\S+?):\s/<dt> $2<\/dt><dd> /o && ( $result .= &emitList( "dl", "dd", length $1 ) );

To:

            s/^(\t+)\$?\s?([^:]+? ):(\s|$)/<dt> $2<\/dt><dd> /o && ( $result .= &emitList( "dl", "dd", length $1 ) );  ### MPS - extended def

Justification of the patch is in the discussion below.

Essentially this introduces a new syntax for definition lists that looks like this:

   $ *Action Item 1* (joe) : yada yada yada yada yada yada
     yada yada yada yada yada yada
   $ *Action Item 2* (bob) : rhubarb rhubarb rhubarb rhubarb
     rhubarb rhubarb rhubarb rhubarb

You get:

Action Item 1 (joe)

yada yada yada yada yada yada yada yada yada yada yada yada

Action Item 2 (bob)

rhubarb rhubarb rhubarb rhubarb rhubarb rhubarb rhubarb rhubarb

-- MichaelSparks - 28 Dec 2001

Definition lists whilst not often used, can be very useful. I'd generally do something like this in an email:

   FRED : This is a a name of a rather portly fellow who shouts, upon occasion
       the utterances "Yabbadabbodoooooo!", consumes rather copius amounts of
       beer and brontosaurus steaks whilst bowling.
   BARNEY : Fred's friend, Often heard to say "Righto Fred", and giggle in a
       rather silly way. He also may often be heard to giggle far too often.
   BAMBAM : Barney's rather violenet little child, who often goes on to
       shout things like "BAM! BAM!" when hitting things with his club.

And it's nice to format stuff like that like this using definition lists:

FRED

This is a a name of a rather portly fellow who shouts, upon occasion the utterances "Yabbadabbodoooooo!", consumes rather copius amounts of beer and brontosaurus steaks whilst bowling.

BARNEY

Fred's friend, Often heard to say "Righto Fred", and giggle in a rather silly way. He also may often be heard to giggle far too often.

BAMBAM

Barney's rather violenet little child, who often goes on to shout things like "BAM! BAM!" when hitting things with his club.

To make this wiki'able I'd propose that we could do this by simply taking the current list generating stuff and do something like this as the TWiki source for above which would generate the HTML listed afterwards:

You type:

   # FRED : This is a a name of a rather portly fellow who shouts, upon occasion
     the utterances "Yabbadabbodoooooo!", consumes rather copius amounts of
     beer and brontosaurus steaks whilst bowling.
   # BARNEY : Fred's friend, Often heard to say "Righto Fred", and giggle in a
     rather silly way. He also may often be heard to giggle far too often.
   # BAMBAM : Barney's rather violenet little child, who often goes on to
     shout things like "BAM! BAM!" when hitting things with his club.

You get:

<ul><dl>
<dt><B> FRED </B></dt><DD>
       This is a a name of a rather portly fellow who shouts, upon occasion
       the utterances "Yabbadabbodoooooo!", consumes rather copius amounts of
       beer and brontosaurus steaks whilst bowling.
<dt><B> BARNEY </B></dt><DD>
       Fred's friend, Often heard to say "Righto Fred", and giggle in a
       rather silly way. He also may often be heard to giggle far too often.
<dt><B> BAMBAM </B></dt><DD>
       Barney's rather violenet little child, who often goes on to
       shout things like "BAM! BAM!" when hitting things with his club.
</dl></ul>

Which is rendered as above....

-- MichaelSparks - 19 Mar 2001

Is the current definition list syntax not sufficient?

You type:

 
   FRED: This is a a name of a rather portly fellow who shouts, upon occasion
     the utterances "Yabbadabbodoooooo!", consumes rather copius amounts of
     beer and brontosaurus steaks whilst bowling.
   BARNEY: Fred's friend, Often heard to say "Righto Fred", and giggle in a
     rather silly way. He also may often be heard to giggle far too often.
   BAMBAM: Barney's rather violenet little child, who often goes on to
     shout things like "BAM! BAM!" when hitting things with his club.

You get:

FRED

This is a a name of a rather portly fellow who shouts, upon occasion the utterances "Yabbadabbodoooooo!", consumes rather copius amounts of beer and brontosaurus steaks whilst bowling.

BARNEY

Fred's friend, Often heard to say "Righto Fred", and giggle in a rather silly way. He also may often be heard to giggle far too often.

BAMBAM

Barney's rather violenet little child, who often goes on to shout things like "BAM! BAM!" when hitting things with his club.

-- PeterThoeny - 20 Mar 2001

OK, Classic case of RTFM, sorry guys... Having now RTFM, this looks alot more what I'd like However, the limitation of not having spaces in the definition term is not nice. Also I personally like putting the definition term in bold, and currently you have to use HTML tags to get this in the definition term...

ie if you type this,

 
   *FRED*: This is a a name of a rather portly fellow who shouts, upon occasion
     the utterances "Yabbadabbodoooooo!", consumes rather copius amounts of
     beer and brontosaurus steaks whilst bowling.
   *BARNEY*: Fred's friend, Often heard to say "Righto Fred", and giggle in a
     rather silly way. He also may often be heard to giggle far too often.
   *BAMBAM*: Barney's rather violenet little child, who often goes on to
     shout things like "BAM! BAM!" when hitting things with his club.

You don't get this:

FRED

This is a a name of a rather portly fellow who shouts, upon occasion the utterances "Yabbadabbodoooooo!", consumes rather copius amounts of beer and brontosaurus steaks whilst bowling.

BARNEY

Fred's friend, Often heard to say "Righto Fred", and giggle in a rather silly way. He also may often be heard to giggle far too often.

BAMBAM

Barney's rather violenet little child, who often goes on to shout things like "BAM! BAM!" when hitting things with his club.

Why's the so nasty space etc? Well it'd be nice to be able to type this:

<ul>
   *Action 1*: Get the beers in. *Fred*
   *Action 2*: Buy the brontosaurus steaks. *Barney*
   *Action 3*: Look after the kids *Dino*
   *Action 4*: Drink all the beer *Fred*
   *Action 5*: Take fred home and apologize to Wilma *Barney*
</ul>

And get this:

Action 1

Get the beers in. Fred

Action 2

Buy the brontosaurus steaks. Barney

Action 3

Look after the kids Dino

Action 4

Drink all the beer Fred

Action 5

Take fred home and apologize to Wilma Barney

Rather than have to type this:

<ul>
   <b>Action&nbsp;1</b>: Get the beers in. *Fred*
   <b>Action&nbsp;2</b>: Buy the brontosaurus steaks. *Barney*
   <b>Action&nbsp;3</b>: Look after the kids *Dino*
   <b>Action&nbsp;4</b>: Drink all the beer *Fred*
   <b>Action&nbsp;5</b>: Take fred home and apologize to Wilma *Barney*
</ul>

I'll probably try knock something up to do this this afternoon if I have the time...

-- MichaelSparks - 21 Mar 2001

After a bit of fiddling, I've found that the change necessary is trivial, in Twiki.pm ~line 1142, change:

       s/^(\t+)(\S+?):\s/
 $2
 /o && ( $result .= &emitCode( "DL", length $1 ) );

       s/^(\t+)([^:]+?):\s/
 $2 
 /o && ( $result .= &emitCode( "DL", length $1 ) );

You can then get space in the resulting definition terms. And action bold as well due to the extra space between $2 & <DD;>

Taking this latter observation means that I've also changed my local twiki to always have spaces either side when tags are placed around it - eg changed:

In TWiki/Plugins/Default.pm Changed:

                                                                                                                              
    $_[0] =~ s/(^|\s)\*_([^\s].*?[^\s])_\*(\s|$)/$1<STRONG><EM>$2<\/EM><\/STRONG>$3/go;

To:

                                                                                                                              
    $_[0] =~ s/(^|\s)\*_([^\s].*?[^\s])_\*(\s|$)/$1<STRONG><EM>$2<\/EM><\/STRONG>$3/go;

And changed these:

            s/([\s\(])__([^\s]+?|[^\s].*?[^\s])__([\s\,\.\;\:\!\?\)])/$1<STRONG><EM>$2<\/EM><\/STRONG>$3/go;
            s/([\s\(])\*([^\s]+?|[^\s].*?[^\s])\*([\s\,\.\;\:\!\?\)])/$1<STRONG>$2<\/STRONG>$3/go;
            s/([\s\(])_([^\s]+?|[^\s].*?[^\s])_([\s\,\.\;\:\!\?\)])/$1<EM>$2<\/EM>$3/go;                                    

To:

            s/([\s\(])__([^\s]+?|[^\s].*?[^\s])__([\s\,\.\;\:\!\?\)])/$1<STRONG><EM> $2 <\/EM><\/STRONG>$3/go;
            s/([\s\(])\*([^\s]+?|[^\s].*?[^\s])\*([\s\,\.\;\:\!\?\)])/$1<STRONG> $2 <\/STRONG>$3/go;
            s/([\s\(])_([^\s]+?|[^\s].*?[^\s])_([\s\,\.\;\:\!\?\)])/$1<EM> $2< \/EM>$3/go;                                    

And changed this:

sub fixedFontText
{
    my( $theText, $theDoBold ) = @_;
    # preserve white space, so replace it by "  " patterns
    $theText =~ s/\t/   /go;
    $theText =~ s|((?:[\s]{2})+)([^\s])|'  ' x (length($1) / 2) . "$2"|eg;
    if( $theDoBold ) {
        return "<code><b>$theText</b></code>";
    } else {
        return "<code>$theText</code>";
    }
}                                                                                                                             

To This:

sub fixedFontText
{
    my( $theText, $theDoBold ) = @_;
    # preserve white space, so replace it by "  " patterns
    $theText =~ s/\t/   /go;
    $theText =~ s|((?:[\s]{2})+)([^\s])|'  ' x (length($1) / 2) . "$2"|eg;
    if( $theDoBold ) {
        return "<code><b> $theText </b></code>";
    } else {
        return "<code> $theText </code>";
    }
}                                                                                                                             

Which results in a bold, fixed width font text for a twiki link as a definition term being possible, which is very useful - eg for code documentation, or glossaries, or even script writing

What's the policy on CVS commits of this sort of thing?

ie you type:

   *=ThisIsSomeText=*: Bla Bla Bla Bla
   *ThisIsSomeText*: Bla Bla Bla Bla
   =ThisIsSomeText=: Bla Bla Bla Bla
   This Is Some Text: Bla Bla Bla Bla
   *This Is Some Text*: Bla Bla Bla Bla

ThisIsSomeText?

Bla Bla Bla Bla

ThisIsSomeText?

Bla Bla Bla Bla

ThisIsSomeText?

Bla Bla Bla Bla

This Is Some Text

Bla Bla Bla Bla

This Is Some Text

Bla Bla Bla Bla

-- MichaelSparks - 21 Mar 2001

I know what you mean, I don't like the no-space-limitation myself. Your code changes would be very easy to add to the TWiki core, but unforunately it would break existing text:

1) A bullet can span several line. This has been implemented so that you can paste e-mail into TWiki without reformatting. If we allow spaces in definition list terms we would have unwanted side effects if follow up lines happen to have colons, as in:

   * This is a paragraph that talks
      about blah blah blah. Some
      people like it: Hot, Sweet

2) Introducing spaces between HTML tags and text of WikiSyntax would break existing text. There are lots of places like FunkName() written in fixed font that would suddenly be unwanted WikiName links.

We could replace the existing "n * 3 spaces TERM: DESCRIPTION" rule with a better one, e.g. one that fits into the WikiSyntax; is easy to remember; and is intuitive. Suggestions? (We can keep the existing rule as an undocumented legacy rule.)

-- PeterThoeny - 21 Mar 2001

I saw that, and have been avoiding the problem since implementing this on my local twiki, but I think it'd be nice to keep going down this route - I'll have a fiddle with various combiniations to see what works well, and what fails horribly.

-- MichaelSparks - 22 Mar 2001

Just some brainstorming on a syntax that has no side effects.
Take 1:

   $ This Is Some Text: Bla Bla Bla Bla
   $ *This Is Some Text*: (same in bold)

Take 2:

   $ This Is Some Text :: Bla Bla Bla Bla
   $ *This Is Some Text* :: (same in bold)

Take 3:

   :: This Is Some Text :: Bla Bla Bla Bla
   :: *This Is Some Text* :: (same in bold)

Take 4:

   * This Is Some Text :: Bla Bla Bla Bla
   * *This Is Some Text* :: (same in bold)

I kind of like Take 2. Other ideas?

-- PeterThoeny - 22 Mar 2001

I like the idea, but to work, it'd require space around the :: to be forced to allow someone to use TWiki::Store as a defintion term... (And hence think perl in general - a generic POD to Twiki converter would be nice to automate, or nicer, vice versa (This is the only thing I have against Take 4)

Eg imagine documenting the twiki modularisation using this....

Out of these this just leaves Take 1 as the most viable of the 4. Thouh I can't see a problem in having Take 1 also written as:

Take 1:

   $ This Is Some Text : Bla Bla Bla Bla
   $ *This Is Some Text* : (same in bold)

( NB extra space... )

Pattern to match this is somthing like:

       s/^(\t+)\$\s([^:]+?):\s/<DT> $2 <DD> /o && ( $result .= &emitCode( "DL", length $1 ) );

-- MichaelSparks - 23 Mar 2001

Although I don't have a strong preference, I like Take 1 on the basis of it being a little simpler and maybe more forgiving (especially if a space before the colon is optional).

-- RandyKramer - 24 Mar 2001

I've changed the code on my system such that the pattern for a defintion list looks like this:

      s/^(\t+)\$\s(([^:]+|:[^\s]+)+?):\s/<DT> $2 <DD> /o && ( $result .= &emitCode( "DL", length $1 ) );

For 20 Dec 2001 release we need:

     s/^(\t+)\$\s(([^:]+|:[^\s]+)+?):\s/<DT> $2 <DD> /o && ( $result .= &emitList( "DL", "dd", length $1 ) );

-- GaroldJohnson

This works really nicely, and results in allowing stuff like this:

     $ This:WouldBeNice : yada yada yada yada yada yada

     $ *This::WouldBeNice* : yada yada yada yada yada yada

     $ :::: : yada yada yada yada yada yada

     $ *::::* : yada yada yada yada yada yada

     $ =This:WouldBeNice= : yada yada yada yada yada yada

     $ ==This::WouldBeNice== : yada yada yada yada yada yada

     $ =::::= : yada yada yada yada yada yada

     $ ==::::== : yada yada yada yada yada yada

     $ *This isa new* : yada yada yada yada yada yada

     $ *This isa new*: yada yada yada yada yada yada

     $ ==ThisIsAlsoWorthTrying==: yada yada yada yada yada yada

     $ *ThisIsAlsoWorthTrying*: yada yada yada yada yada yada

     $ *Thisisold*: yada yada yada yada yada yada

     $ *Thisisold*: yada yada yada yada yada yada

     $ ==ThisIsSomeText== : yada yada yada yada yada yada

     $ *ThisIsSomeText*: yada yada yada yada yada yada

     $ =ThisIsSomeText=: yada yada yada yada yada yada

     $ This Is Some Text: yada yada yada yada yada yada

     $ *This Is Some Text* : yada yada yada yada yada yada

     $ <nop> : yada yada yada yada yada yada

-- GaroldJohnson - 28 Feb 2002 -- Formatted table to align examples.

-- MichaelSparks - 24 Mar 2001

I like this. I often use colons to format name/value pairs as in email headers, and this allows that while making the use of definition lists explicit. I have incorporated the patch in my local TWiki.

-- GaroldJohnson - 27 Feb 2002

This is nice bugfix (or extension of narrowly defined feature). Any chances including in BeijingRelease?

Also, can I suggest adding syntax for blank <DT> part maybe using <NOP>? Is it possible/valid? Sometimes I want to add another aligned shifted paragraph of yada yada, but without bullet.

-- PeterMasiar - 28 Feb 2002

Using <nop> in the <DT> part does work, and I added an example to the test. Also <br> and <p> work in the definition part.

-- GaroldJohnson - 28 Feb 2002

After thinking about it for a time, I changed the intro character from '$' to ':'. This is used on other wikis, and I rather like the symmetry.

-- GaroldJohnson - 07 Mar 2002

I like format staring with ':' more, too. Any chances of implementing this patch here on TWiki.org? It might be usefull to have for nice TWikiGlossary.

-- PeterMasiar - 08 Mar 2002

The above patch:

 s/^(\t+)\$\s(([^:]+|:[^\s]+)+?):\s/<DT> $2 <DD> /o && ( $result .= &emitList( "DL", "dd", length $1 )

Works very well for me in the latest alpha (Dec 05 2002). I did need to make a couple of minor changes:

 s/^(\t+)\$\s(([^:]+|:[^\s]+)+?):\s/<dt> $2 <\/dt><dd> /o && ( $result .= &emitList( "dl", "dd", length $1 ) );

Note as above you can change the "\$" symbol in the s/^(\t+)\$\s(([^:]+|:[^\s]+)+?) part to a ":" character to be more like other wikis. I have decided to keep it as a $ for now, though.

-- AdamTheo - 06 Dec 2002

Hi all.

I'm trying to figure out how to put this modification in a Plugin so I don't have to keep modifying the TWiki.pm script everytime I upgrade. However, I have tried and failed to get it working. Here is the current code from TWiki.pm that does definition lists:

s/^(\t+)(\S+?):\s/<dt> $2<\/dt><dd> /o && ( $result .= &emitList( "dl", "dd", length $1 ) );

I believe it fails since it runs a function and relies on outside variables. Any ideas how to do this sort of thing in a Plugin?

-- AdamTheo - 02 Jan 2003

Empty Definition term

Also, can I suggest adding syntax for blank <DT> part maybe using <NOP>? Is it possible/valid?

Sometimes I want to add another aligned shifted paragraph of yada yada, but without bullet - using an empty definition term would be useful to achieve this. This can be done using <nop> in the <DT> part. Also <br> and <p> work in the definition part. Also using   works.

Examples:

   $ <nop>: bla bla bla 
   $ &nbsp;: bla bla bla 

Open Issues

1. Suggestion to allow ":" instead/as well as "$" should be discussed. Apparently some other wiki's use a leading ":", so changing to use that might make sense.
2. Incorporation into the main codebase needs to happen. The alternative is to make this a plugin...

-- MichaelSparks - 14 Jun 2003

I'd like to bring this patch back up for discussion. I'm getting tired of current limitation in Definition List format. There was a lot of good discussion leading up to this patch and it addresses the main limitations of not being about to bold the term and not allowing spaces in the term. Is there any reason not to include this into the core? Or could someone speak to Adam's comment so we could perhaps have it as a plugin? This could be a very useful format with a variety of uses but I suspect it is used very little in its current form.

-- LynnwoodBrown - 27 Jan 2004

Making this feature a plugin would be pretty silly (since the functionality is already in the core already, this is just a regular expression tweak). If you did move it out to a plugin, you should move all the functionality along these lines out into a plugin - taking all the other lists with it, and similarly for tables includes and so on.

(Actually whilst I note that's silly, it's not; having pluggable rendering for core features would be useful - it's just that doing for 1 thing is pretty silly.)

-- MS - 28 Jan 2004

This feature here is a good candidate to go into the core.

-- PeterThoeny - 28 Jan 2004

I went ahead and applied the patch manually

• In BeijingRelease the patch works as described above with control of display in bold or not.
• In the lastest Alpha release, the term is automatically displayed bold (which is what I wanted anyway) but there's no control over it.

About all I can offer in the way of help is updating the documentation.

-- LynnwoodBrown - 28 Jan 2004

OK, I restored the old discussions and refactored the top part to be in line with the current standard. The $ term: definition syntax is relatively easy to remember; lets take this instead of the : term: definition syntax also discussed.

The code of AdamTheo is now in TWikiAlphaRelease and at TWiki.org.

-- PeterThoeny - 30 Jan 2004

Awesome, thanks Peter!

-- MattWilkie - 30 Jan 2004