$Id: AbiWord_list_notes.txt,v 1.1 1999/07/19 15:07:35 jeff Exp $

This is a quick note describing a proposed format/syntax
for lists within AbiWord.  This should be considered to
be a starting point for discussion, rather than a definitive
solution. -- Jeff, 7/19/1999


===============================================================================
<p PROPS="type:LI;
          [style:LIx;]
          [level:x;]
          [format:ff;]
          ..."
   id="xx"
   [prev="yy"]
   [next="zz"]
   [start="value"]
   ...> ... content ... </p>


"style:LIx"	    is an optional reference to a named style, "LIx".
		    "LIx" is a reference to a list-item-at-level-x
		    or it could be any other style reference.

"type:LI"	    is a trigger to the formatter that this is a
		    ListItem (and thus has an implicit computed field
		    containing for the item label).

"level:x"	    is an optional field and contains the nesting
		    level and is used in computing a numeric label.
		    (this does not control the formatting, indenting,
		    etc. (those are controlled by the style); rather
		    this field is used in computing a "1.2....x"
		    style numeric label.)  if omitted, the value is 1.

id="xx"		    provides a unique name for this list item

prev="yy"	    optional keyword.  provides a link to the previous
		    list item.  this is primarily for numeric lists.
		    the value of the numeric label for this list item
		    is a function of the value of the previous one.
		    it is can be omitted for the first item in a list.

next="zz"	    optional keyword.  provides a link to the next list
		    item.  this is primarily used as the other half of
		    a doubly linked list.  inserting a new list item
		    after the current one must update the next->prev
		    ***and*** must cause the labels on the rest of the
		    list to update.  it can be omitted for the last
		    item in a list.

[note: "xx", "yy", and "zz" are random or generated numbers or strings.]

start="value"	   defines an absolute starting value (primarily used
		   for numeric lists).  if omitted, the value of this
		   list item is 1+ the value of the previous matching
		   list item.  if there is no previous value, the value
		   is 1.

format="ff"	   defines a template for the label on this list item.
		   this describes the formating of the bullet/number/etc.
		   this field may be present on the <p> tag or inherited
		   from the named style.  if not present on either, we
		   should supply a nice fat bullet character.
    where ff is:

    [1] a simple string format for the current level:
	%[[0]<w>]d      decimal number with optional width and leading zeros.
	%i              roman numeral
	%I              uppercase roman numeral
	%a              alpha
	%A              uppercase alpha
	%*              same as previous item at this level (chase prev chain)
	%b              the bullet character symbol b[x]

    [2] a simple string with additional text around it.  for example:
	"%d."		expands to "1." 
	"%i."		expands to "iv."
	"A%02d.<tab>"	expands to "A01.<tab>"

    [3] a multi-level string.  composes the current level value with the
	value for the containing level.  for example:
	"%d.%i."        %d. applied to containing level
			and %i applied to this level.
	"%A.%d.%i."	%A applied to 2 levels up, %d to 1 level up, and %i
			applied to this level.
	"%*.%i."	complete pattern of containing level and %i applied
			to current level.

    where b[x] is:
	a character from a vector of symbol chars -- this is
	the progression of symbol chars as lists get deeper "closed-dot,
	open-dot, diamond, etc." -- this vector is defined somewhere else.
	(handwave, havewave)

===============================================================================
with all this, we should be able to:

[a] have flat and nested lists.
[b] have lists which are intertwined in tables and other structures
    (paragraphs, sections, etc).
[c] have numbered lists which are intertwined in other lists (yes, Word
    does this).
[d] have lists which start at an arbitrary number.
[e] have lists which automatically recompute their label as editing occurs.

===============================================================================
