Index: ChangeLog
===================================================================
--- ChangeLog	(revision e50cd5686952dc31173cfd67f7ebf1d6893945eb)
+++ ChangeLog	(revision aa2f33b3752d45e77d32aa4ef5344218b8b37d08)
@@ -1,3 +1,37 @@
 $Id$
+
+1.2.1-pre-3
+	Variables now have a summary and a long description.
+	        Only the summary is shown with help.
+		The long description is shown with "show variable foo".
+        Fix the scrolling bug where we would sometimes fail to scroll
+             the screen down, leaving the current message off 
+             the bottom of the screen.
+        Added a 'scrollmode' variable which determines how the screen
+	     will scroll as the cursor moves.  The default behaves
+	     identically to previous versions of owl.
+             The following modes are supported:
+	     normal      - This is the owl default.  Scrolling happens
+	                   when it needs to, and an attempt is made to
+	                   keep the current message roughly near
+	                   the middle of the screen.  (default)
+	     top         - The current message will always be the
+	                   the top message displayed.
+	     neartop     - The current message will be one down
+	                   from the top message displayed,
+	                   where possible.
+	     center      - An attempt is made to keep the current
+	                   message near the center of the screen.
+	     paged       - The top message displayed only changes
+	                   when user moves the cursor to the top
+	                   or bottom of the screen.  When it moves,
+	                   the screen will be paged up or down and
+	                   the cursor will be near the top or
+	                   the bottom.
+	     pagedcenter - The top message displayed only changes
+	                   when user moves the cursor to the top
+	                   or bottom of the screen.  When it moves,
+	                   the screen will be paged up or down and
+	                   the cursor will be near the center.\n",
 
 1.2.1-pre-2
Index: functions.c
===================================================================
--- functions.c	(revision e50cd5686952dc31173cfd67f7ebf1d6893945eb)
+++ functions.c	(revision aa2f33b3752d45e77d32aa4ef5344218b8b37d08)
@@ -712,13 +712,10 @@
 
 void owl_function_calculate_topmsg(int direction) {
-  int recwinlines, y, savey, i, j, topmsg, curmsg, foo;
-  owl_mainwin *mw;
+  int recwinlines, topmsg, curmsg;
   owl_view *v;
 
-  mw=owl_global_get_mainwin(&g);
-
+  v=owl_global_get_current_view(&g);
+  curmsg=owl_global_get_curmsg(&g);
   topmsg=owl_global_get_topmsg(&g);
-  curmsg=owl_global_get_curmsg(&g);
-  v=owl_global_get_current_view(&g);
   recwinlines=owl_global_get_recwin_lines(&g);
 
@@ -726,4 +723,110 @@
     return;
   }
+
+  switch (owl_global_get_scrollmode(&g)) {
+  case OWL_SCROLLMODE_TOP:
+    topmsg = owl_function_calculate_topmsg_top(direction, v, curmsg,
+					       topmsg, recwinlines);
+    break;
+  case OWL_SCROLLMODE_NEARTOP:
+    topmsg = owl_function_calculate_topmsg_neartop(direction, v, curmsg, 
+						   topmsg, recwinlines);
+    break;
+  case OWL_SCROLLMODE_CENTER:
+    topmsg = owl_function_calculate_topmsg_center(direction, v, curmsg,
+						  topmsg, recwinlines);
+    break;
+  case OWL_SCROLLMODE_PAGED:
+    topmsg = owl_function_calculate_topmsg_paged(direction, v, curmsg, 
+						 topmsg, recwinlines, 0);
+    break;
+  case OWL_SCROLLMODE_PAGEDCENTER:
+    topmsg = owl_function_calculate_topmsg_paged(direction, v, curmsg, 
+						 topmsg, recwinlines, 1);
+    break;
+  case OWL_SCROLLMODE_NORMAL:
+  default:
+    topmsg = owl_function_calculate_topmsg_normal(direction, v, curmsg,
+						  topmsg, recwinlines);
+  }
+  owl_global_set_topmsg(&g, topmsg);
+}
+
+/* Returns what the new topmsg should be.  
+ * Passed the last direction of movement, 
+ * the current view,
+ * the current message number in the view,
+ * the top message currently being displayed,
+ * and the number of lines in the recwin.
+ */
+int owl_function_calculate_topmsg_top(int direction, owl_view *v, int curmsg, int topmsg, int recwinlines) {
+  return curmsg;
+}
+
+int owl_function_calculate_topmsg_neartop(int direction, owl_view *v, int curmsg, int topmsg, int recwinlines) {
+  if (curmsg>0 
+      && (owl_message_get_numlines(owl_view_get_element(v, curmsg-1))
+	  <  recwinlines/2)) {
+    return curmsg-1;
+  } else {
+    return curmsg;
+  }
+}
+  
+int owl_function_calculate_topmsg_center(int direction, owl_view *v, int curmsg, int topmsg, int recwinlines) {
+  int i, last, lines;
+
+  last = curmsg;
+  lines = 0;
+  for (i=curmsg-1; i>=0; i--) {
+    lines += owl_message_get_numlines(owl_view_get_element(v, i));
+    if (lines > recwinlines/2) break;
+    last = i;
+  }
+  return last;
+}
+  
+int owl_function_calculate_topmsg_paged(int direction, owl_view *v, int curmsg, int topmsg, int recwinlines, int center_on_page) {
+  int i, last, lines, savey;
+  
+  /* If we're off the top of the screen, scroll up such that the 
+   * curmsg is near the botton of the screen. */
+  if (curmsg < topmsg) {
+    last = curmsg;
+    lines = 0;
+    for (i=curmsg; i>=0; i--) {
+      lines += owl_message_get_numlines(owl_view_get_element(v, i));
+      if (lines > recwinlines) break;
+    last = i;
+    }
+    if (center_on_page) {
+      return owl_function_calculate_topmsg_center(direction, v, curmsg, 0, recwinlines);
+    } else {
+      return last;
+    }
+  }
+
+  /* Find number of lines from top to bottom of curmsg (store in savey) */
+  savey=0;
+  for (i=topmsg; i<=curmsg; i++) {
+    savey+=owl_message_get_numlines(owl_view_get_element(v, i));
+  }
+
+  /* if we're off the bottom of the screen, scroll down */
+  if (savey > recwinlines) {
+    if (center_on_page) {
+      return owl_function_calculate_topmsg_center(direction, v, curmsg, 0, recwinlines);
+    } else {
+      return curmsg;
+    }
+  }
+
+  /* else just stay as we are... */
+  return topmsg;
+}
+
+
+int owl_function_calculate_topmsg_normal(int direction, owl_view *v, int curmsg, int topmsg, int recwinlines) {
+  int savey, j, i, foo, y;
   
   /* Find number of lines from top to bottom of curmsg (store in savey) */
@@ -761,6 +864,5 @@
       }
       if (j<0) j=0;
-      owl_global_set_topmsg(&g, j);
-      return;
+      return j;
     }
   }
@@ -778,8 +880,9 @@
 	j--;
       }
-      owl_global_set_topmsg(&g, j+1);
-      return;
-    }
-  }
+      return j+1;
+    }
+  }
+
+  return topmsg;
 }
 
@@ -1219,10 +1322,9 @@
       "Variables: (use 'show variable <name>' for details)\n");
   owl_variable_dict_get_names(owl_global_get_vardict(&g), &varnames);
-  owl_variable_get_summaryheader(&fm);
   numvarnames = owl_list_get_size(&varnames);
   for (i=0; i<numvarnames; i++) {
     varname = owl_list_get_element(&varnames, i);
     if (varname && varname[0]!='_') {
-      owl_variable_get_summary(owl_global_get_vardict(&g), varname, &fm);
+      owl_variable_describe(owl_global_get_vardict(&g), varname, &fm);
     }
   }
Index: help.c
===================================================================
--- help.c	(revision 6794f72456590c5f86ebd58206474534693d974f)
+++ help.c	(revision aa2f33b3752d45e77d32aa4ef5344218b8b37d08)
@@ -105,10 +105,9 @@
 			 "Variables:\n");
   owl_variable_dict_get_names(owl_global_get_vardict(&g), &varnames);
-  owl_variable_get_summaryheader(&fm);
   numvarnames = owl_list_get_size(&varnames);
   for (i=0; i<numvarnames; i++) {
     varname = owl_list_get_element(&varnames, i);
     if (varname && varname[0]!='_') {
-      owl_variable_get_summary(owl_global_get_vardict(&g), varname, &fm);
+      owl_variable_describe(owl_global_get_vardict(&g), varname, &fm);
     }
   }
Index: owl.h
===================================================================
--- owl.h	(revision ae9e6be1895f1cd07dd578471f94909f444b2a6e)
+++ owl.h	(revision aa2f33b3752d45e77d32aa4ef5344218b8b37d08)
@@ -12,6 +12,6 @@
 static const char owl_h_fileIdent[] = "$Id$";
 
-#define OWL_VERSION         1.2.1-pre-1
-#define OWL_VERSION_STRING "1.2.1-pre-1"
+#define OWL_VERSION         1.2.1-pre-3
+#define OWL_VERSION_STRING "1.2.1-pre-3"
 
 #define OWL_DEBUG 0
@@ -46,4 +46,12 @@
 #define OWL_DIRECTION_DOWNWARDS 1
 #define OWL_DIRECTION_UPWARDS   2
+
+#define OWL_SCROLLMODE_NORMAL   0
+#define OWL_SCROLLMODE_TOP      1
+#define OWL_SCROLLMODE_NEARTOP  2
+#define OWL_SCROLLMODE_CENTER   3
+#define OWL_SCROLLMODE_PAGED    4
+#define OWL_SCROLLMODE_PAGEDCENTER 5
+
 
 #define OWL_TAB               3  /* This *HAS* to be the size of TABSTR below */
@@ -114,5 +122,6 @@
   int   ival_default;  /* for types int and bool     */
   char *validsettings;		/* documentation of valid settings */
-  char *docstring;		/* documentation of valid settings */
+  char *summary;		/* summary of usage */
+  char *description;		/* detailed description */
   void *val;                    /* current value */
   int  (*validate_fn)(struct _owl_variable *v, void *newval);
Index: variable.c
===================================================================
--- variable.c	(revision ae9e6be1895f1cd07dd578471f94909f444b2a6e)
+++ variable.c	(revision aa2f33b3752d45e77d32aa4ef5344218b8b37d08)
@@ -10,26 +10,26 @@
 static int in_regtest = 0;
 
-#define OWLVAR_BOOL(name,default,docstring) \
-        { name, OWL_VARIABLE_BOOL, NULL, default, "on,off", docstring, NULL, \
+#define OWLVAR_BOOL(name,default,summary,description) \
+        { name, OWL_VARIABLE_BOOL, NULL, default, "on,off", summary,description, NULL, \
         NULL, NULL, NULL, NULL, NULL }
 
-#define OWLVAR_BOOL_FULL(name,default,docstring,validate,set,get) \
-        { name, OWL_VARIABLE_BOOL, NULL, default, "on,off", docstring, NULL, \
+#define OWLVAR_BOOL_FULL(name,default,summary,description,validate,set,get) \
+        { name, OWL_VARIABLE_BOOL, NULL, default, "on,off", summary,description, NULL, \
         validate, set, NULL, get, NULL }
 
-#define OWLVAR_INT(name,default,docstring) \
-        { name, OWL_VARIABLE_INT, NULL, default, "<int>", docstring, NULL, \
+#define OWLVAR_INT(name,default,summary,description) \
+        { name, OWL_VARIABLE_INT, NULL, default, "<int>", summary,description, NULL, \
         NULL, NULL, NULL, NULL, NULL, NULL }
 
-#define OWLVAR_INT_FULL(name,default,docstring,validset,validate,set,get) \
-        { name, OWL_VARIABLE_INT, NULL, default, validset, docstring, NULL, \
+#define OWLVAR_INT_FULL(name,default,summary,description,validset,validate,set,get) \
+        { name, OWL_VARIABLE_INT, NULL, default, validset, summary,description, NULL, \
         validate, set, NULL, get, NULL, NULL }
 
-#define OWLVAR_PATH(name,default,docstring) \
-        { name, OWL_VARIABLE_STRING, default, 0, "<path>", docstring,  NULL, \
+#define OWLVAR_PATH(name,default,summary,description) \
+        { name, OWL_VARIABLE_STRING, default, 0, "<path>", summary,description,  NULL, \
         NULL, NULL, NULL, NULL, NULL, NULL }
 
-#define OWLVAR_STRING(name,default,docstring) \
-        { name, OWL_VARIABLE_STRING, default, 0, "<string>", docstring, NULL, \
+#define OWLVAR_STRING(name,default,summary,description) \
+        { name, OWL_VARIABLE_STRING, default, 0, "<string>", summary,description, NULL, \
         NULL, NULL, NULL, NULL, NULL, NULL }
 
@@ -37,6 +37,6 @@
  * list of strings which can be specified.  The tokens, starting at 0,
  * correspond to the values that may be specified. */
-#define OWLVAR_ENUM(name,default,docstring,validset) \
-        { name, OWL_VARIABLE_INT, NULL, default, validset, docstring, NULL, \
+#define OWLVAR_ENUM(name,default,summary,description,validset) \
+        { name, OWL_VARIABLE_INT, NULL, default, validset, summary,description, NULL, \
         owl_variable_enum_validate, \
         NULL, owl_variable_enum_set_fromstring, \
@@ -44,6 +44,6 @@
         NULL }
 
-#define OWLVAR_ENUM_FULL(name,default,docstring,validset,validate, set, get) \
-        { name, OWL_VARIABLE_INT, NULL, default, validset, docstring, NULL, \
+#define OWLVAR_ENUM_FULL(name,default,summary,description,validset,validate, set, get) \
+        { name, OWL_VARIABLE_INT, NULL, default, validset, summary,description, NULL, \
         validate, \
         set, owl_variable_enum_set_fromstring, \
@@ -54,91 +54,145 @@
 
   OWLVAR_BOOL( "personalbell" /* %OwlVarStub */, 0,
-	       "ring the terminal bell when personal messages are received" ),
+	       "ring the terminal bell when personal messages are received",
+	       "" ),
 
   OWLVAR_BOOL( "bell" /* %OwlVarStub */, 1,
-	       "enable / disable the terminal bell" ),
+	       "enable / disable the terminal bell", "" ),
 
   OWLVAR_BOOL_FULL( "debug" /* %OwlVarStub */, OWL_DEBUG,
 		    "whether debugging is enabled",
+		    "If set to 'on', debugging messages are logged to the\n"
+		    "file specified by the debugfile variable.\n",
 		    NULL, owl_variable_debug_set, NULL),
 
   OWLVAR_BOOL( "startuplogin" /* %OwlVarStub */, 1,
-	       "send a login message when owl starts" ),
+	       "send a login message when owl starts", "" ),
 
   OWLVAR_BOOL( "shutdownlogout" /* %OwlVarStub */, 1,
-	       "send a logout message when owl exits" ),
+	       "send a logout message when owl exits", "" ),
 
   OWLVAR_BOOL( "rxping" /* %OwlVarStub */, 0,
-	       "display received pings" ),
+	       "display received pings", "" ),
 
   OWLVAR_BOOL( "txping" /* %OwlVarStub */, 1,
-	       "send pings" ),
+	       "send pings", "" ),
 
   OWLVAR_BOOL( "displayoutgoing" /* %OwlVarStub */, 1,
-	       "display outgoing messages" ),
+	       "display outgoing messages", "" ),
 
   OWLVAR_BOOL( "loginsubs" /* %OwlVarStub */, 1,
-	       "load logins from .anyone on startup" ),
+	       "load logins from .anyone on startup", "" ),
 
   OWLVAR_BOOL( "logging" /* %OwlVarStub */, 0,
-	       "turn personal logging on or off" ),
+	       "turn personal logging on or off", 
+	       "If this is set to on, personal messages are\n"
+	       "logged in the directory specified\n"
+	       "by the 'logpath' variable.  The filename in that\n"
+	       "directory is derived from the sender of the message.\n" ),
 
   OWLVAR_BOOL( "classlogging" /* %OwlVarStub */, 0,
-	       "turn class logging on or off" ),
+	       "turn class logging on or off",
+	       "If this is set to on, class messages are\n"
+	       "logged in the directory specified\n"
+	       "by the 'classlogpath' variable.\n" 
+	       "The filename in that directory is derived from\n"
+	       "the name of the class to which the message was sent.\n" ),
 
   OWLVAR_BOOL( "colorztext" /* %OwlVarStub */, 1,
-	       "allow @color() in zephyrs to change color" ),
+	       "allow @color() in zephyrs to change color",
+	       "Note that only messages received after this variable\n"
+	       "is set will be affected." ),
 
   OWLVAR_ENUM_FULL( "disable-ctrl-d" /* %OwlVarStub:lockout_ctrld */, 1,
-		    "don't send zephyrs on C-d (or disable if in the middle of the message if set to 'middle')", "off,middle,on",
+		    "don't send zephyrs on C-d",
+		    "If set to 'off', C-d won't send a zephyr from the edit\n"
+		    "window.  If set to 'on', C-d will always send a zephyr\n"
+		    "being composed in the edit window.  If set to 'middle',\n"
+		    "C-d will only ever send a zephyr if the cursor is at\n"
+		    "the end of the message being composed.\n\n"
+		    "Note that this works by changing the C-d keybinding\n"
+		    "in the editmulti keymap.\n",
+		    "off,middle,on",
 		    NULL, owl_variable_disable_ctrl_d_set, NULL),
 
   OWLVAR_BOOL( "_burningears" /* %OwlVarStub:burningears */, 0,
-	       "[NOT YET IMPLEMENTED] beep on messages matching patterns" ),
+	       "[NOT YET IMPLEMENTED] beep on messages matching patterns", "" ),
 
   OWLVAR_BOOL( "_summarymode" /* %OwlVarStub:summarymode */, 0,
-	       "[NOT YET IMPLEMENTED]" ),
+	       "[NOT YET IMPLEMENTED]", "" ),
 
   OWLVAR_PATH( "logpath" /* %OwlVarStub */, "~/zlog/people",
-	       "path for logging personal zephyrs" ),
+	       "path for logging personal zephyrs", 
+	       "Specifies a directory which must exist.\n"
+	       "Files will be created in the directory for each sender.\n"),
 
   OWLVAR_PATH( "classlogpath" /* %OwlVarStub:classlogpath */, "~/zlog/class",
-	       "path for logging class zephyrs" ),
+	       "path for logging class zephyrs",
+	       "Specifies a directory which must exist.\n"
+	       "Files will be created in the directory for each class.\n"),
 
   OWLVAR_PATH( "debug_file" /* %OwlVarStub */, OWL_DEBUG_FILE,
-	       "path for logging debug messages when debugging is enabled" ),
+	       "path for logging debug messages when debugging is enabled",
+	       "This file will be logged to if 'debug' is set to 'on'.\n"),
   
   OWLVAR_PATH( "zsigproc" /* %OwlVarStub:zsig_exec */, NULL,
-	       "name of a program to run that will generate zsigs" ),
+	       "name of a program to run that will generate zsigs",
+	       "This program should produce a zsig on stdout when run.\n"
+	       "Note that it is important that this program not block.\n" ),
 
   OWLVAR_STRING( "zsig" /* %OwlVarStub */, "",
-	         "zephyr signature" ),
+	         "zephyr signature", 
+		 "If 'zsigproc' is not set, this string will be used\n"
+		 "as a zsig.  If this is also unset, the 'zwrite-signature'\n"
+		 "zephyr variable will be used instead.\n"),
 
   OWLVAR_STRING( "appendtosepbar" /* %OwlVarStub */, "",
-	         "string to append to the end of the sepbar" ),
+	         "string to append to the end of the sepbar",
+		 "The sepbar is the bar separating the top and bottom\n"
+		 "of the owl screen.  Any string specified here will\n"
+		 "be displayed on the right of the sepbar\n"),
 
   OWLVAR_BOOL( "zaway" /* %OwlVarStub */, 0,
-	       "turn zaway on or off" ),
+	       "turn zaway on or off", "" ),
 
   OWLVAR_STRING( "zaway_msg" /* %OwlVarStub */, 
 		 OWL_DEFAULT_ZAWAYMSG,
-	         "zaway msg for responding to zephyrs when away" ),
+	         "zaway msg for responding to zephyrs when away", "" ),
 
   OWLVAR_STRING( "zaway_msg_default" /* %OwlVarStub */, 
 		 OWL_DEFAULT_ZAWAYMSG,
-	         "default zaway message" ),
+	         "default zaway message", "" ),
 
   OWLVAR_STRING( "view_home" /* %OwlVarStub */, "all",
-	         "home view to switch to after 'X'" ),
+	         "home view to switch to after 'X' and 'V'", 
+		 "SEE ALSO: view, filter\n" ),
 
   OWLVAR_INT(    "edit:maxfillcols" /* %OwlVarStub:edit_maxfillcols */, 70,
-	         "maximum number of columns for M-q to fill text to (or unlimited if 0)" ),
+	         "maximum number of columns for M-q to fill text to",
+		 "This specifies the maximum number of columns for M-q\n"
+		 "to fill text to.  If set to 0, ther will be no maximum\n"
+		 "limit.  In all cases, the current width of the screen\n"
+		 "will also be taken into account.  It will be used instead\n"
+		 "if it is narrower than the maximum, or if this\n"
+		 "is set to 0.\n" ),
 
   OWLVAR_INT(    "edit:maxwrapcols" /* %OwlVarStub:edit_maxwrapcols */, 0,
-	         "maximum number of columns for line-wrapping (or unlimited if 0)" ),
+	         "maximum number of columns for line-wrapping",
+		 "This specifies the maximum number of columns for\n"
+		 "auto-line-wrapping.  If set to 0, ther will be no maximum\n"
+		 "limit.  In all cases, the current width of the screen\n"
+		 "will also be taken into account.  It will be used instead\n"
+		 "if it is narrower than the maximum, or if this\n"
+		 "is set to 0.\n\n"
+		 "It is recommended that outgoing messages be no wider\n"
+		 "than 60 columns, as a courtesy to recipients.\n"),
 
   OWLVAR_INT_FULL( "typewinsize" /* %OwlVarStub:typwin_lines */, 
 		   OWL_TYPWIN_SIZE,
-		  "number of lines in the typing window", "int > 0",
+		  "number of lines in the typing window", 
+		   "This specifies the height of the window at the\n"
+		   "bottom of the screen where commands are entered\n"
+		   "and where messages are composed.\n",
+		   "int > 0",
 		   owl_variable_int_validate_gt0,
 		   owl_variable_typewinsize_set,
@@ -146,13 +200,49 @@
 		   ),
 
+  OWLVAR_ENUM( "scrollmode" /* %OwlVarStub */, OWL_SCROLLMODE_NORMAL,
+	       "how to scroll up and down",
+	       "This controls how the screen is scrolled as the\n"
+	       "cursor moves between messages being displayed.\n"
+	       "The following modes are supported:\n\n"
+	       "   normal      - This is the owl default.  Scrolling happens\n"
+	       "                 when it needs to, and an attempt is made to\n"
+	       "                 keep the current message roughly near\n"
+	       "                 the middle of the screen.\n"
+	       "   top         - The current message will always be the\n"
+	       "                 the top message displayed.\n"
+	       "   neartop     - The current message will be one down\n"
+	       "                 from the top message displayed,\n"
+	       "                 where possible.\n"
+	       "   center      - An attempt is made to keep the current\n"
+	       "                 message near the center of the screen.\n"
+	       "   paged       - The top message displayed only changes\n"
+	       "                 when user moves the cursor to the top\n"
+	       "                 or bottom of the screen.  When it moves,\n"
+	       "                 the screen will be paged up or down and\n"
+	       "                 the cursor will be near the top or\n"
+	       "                 the bottom.\n"
+	       "   pagedcenter - The top message displayed only changes\n"
+	       "                 when user moves the cursor to the top\n"
+	       "                 or bottom of the screen.  When it moves,\n"
+	       "                 the screen will be paged up or down and\n"
+	       "                 the cursor will be near the center.\n",
+	       "normal,top,neartop,center,paged,pagedcenter" ),
+
   OWLVAR_ENUM( "webbrowser" /* %OwlVarStub */, OWL_WEBBROWSER_NETSCAPE,
 	       "web browser to use to launch URLs",
+	       "When the 'w' key is pressed, this browser is used\n"
+	       "to display the requested URL.\n",
 	       "none,netscape,galeon,opera" ),
 
   OWLVAR_BOOL( "_followlast" /* %OwlVarStub */, 0,
-	       "enable automatic following of the last zephyr" ),
+	       "enable automatic following of the last zephyr",
+	       "If the cursor is at the last message, it will\n"
+	       "continue to follow the last message if this is set.\n"
+	       "Note that this is currently risky as you might accidentally\n"
+	       "delete a message right as it came in.\n" ),
 
   /* This MUST be last... */
-  { NULL, 0, NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL }
+  { NULL, 0, NULL, 0, NULL, NULL, NULL, NULL,
+    NULL, NULL, NULL, NULL, NULL, NULL }
 
 };
@@ -300,6 +390,10 @@
 
 
-char *owl_variable_get_docstring(owl_variable *v) {
-  return v->docstring;
+char *owl_variable_get_description(owl_variable *v) {
+  return v->description;
+}
+
+char *owl_variable_get_summary(owl_variable *v) {
+  return v->summary;
 }
 
@@ -420,18 +514,6 @@
 }
 
-#define OWL_VARIABLE_HELP_FMT "     %-15s %-9s %-9s %s\n"
-
-/* appends to the end of the fmtext */
-void owl_variable_get_summaryheader(owl_fmtext *fm) {
-  char tmpbuff[512];
-  snprintf(tmpbuff, 512,  
-	   OWL_VARIABLE_HELP_FMT OWL_VARIABLE_HELP_FMT,
-	   "name",            "settings", "default", "meaning",
-	   "---------------", "--------", "-------", "-------");
-  owl_fmtext_append_bold(fm, tmpbuff);
-}
-
-void owl_variable_get_summary(owl_vardict *d, char *name, owl_fmtext *fm) {
-  char defaultbuf[10];
+void owl_variable_describe(owl_vardict *d, char *name, owl_fmtext *fm) {
+  char defaultbuf[50];
   char buf[1024];
   int buflen = 1023;
@@ -446,13 +528,11 @@
   }
   if (v->type == OWL_VARIABLE_INT || v->type == OWL_VARIABLE_BOOL) {
-    v->get_tostring_fn(v, defaultbuf, 10, &(v->ival_default));
+    v->get_tostring_fn(v, defaultbuf, 50, &(v->ival_default));
   } else {
-    v->get_tostring_fn(v, defaultbuf, 10, v->pval_default);
-  }
-  snprintf(buf, buflen, OWL_VARIABLE_HELP_FMT, 
+    v->get_tostring_fn(v, defaultbuf, 50, v->pval_default);
+  }
+  snprintf(buf, buflen, OWL_TABSTR "%-20s - %s (default: '%s')\n", 
 		  v->name, 
-		  owl_variable_get_validsettings(v),
-		  defaultbuf,
-		  owl_variable_get_docstring(v));
+		  owl_variable_get_summary(v), defaultbuf);
   owl_fmtext_append_normal(fm, buf);
 }
@@ -474,5 +554,5 @@
   owl_fmtext_append_normal(fm, name);
   owl_fmtext_append_normal(fm, " - ");
-  owl_fmtext_append_normal(fm, v->docstring);
+  owl_fmtext_append_normal(fm, v->summary);
   owl_fmtext_append_normal(fm, "\n\n");
 
@@ -495,4 +575,10 @@
   owl_fmtext_append_normal(fm, owl_variable_get_validsettings(v));
   owl_fmtext_append_normal(fm, "\n\n");
+
+  if (v->description && *v->description) {
+    owl_fmtext_append_normal(fm, "Description:\n");
+    owl_fmtext_append_normal(fm, owl_variable_get_description(v));
+    owl_fmtext_append_normal(fm, "\n\n");
+  }
 }
 
