OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: DOCBOOK: variablelist (Re: doc domain vs. problem domain semantics)

>From: Norman Walsh <ndw@nwalsh.com>
>To: docbook@lists.oasis-open.org
>Subject: DOCBOOK: Re: doc domain vs. problem domain semantics
>	  (Re[2]: listitem)
>Date: Thu, 03 Jan 2002 07:46:30 -0500
>/ Michael Smith <smith@xml-doc.org> was heard to say:
>| Norman Walsh <ndw@nwalsh.com> writes:
>| Seems like "Associativelist" might be a more accurate name. Isn't a
>| Variablelist basically the same thing as a Lisp/Scheme "alist" --
>| jus a list of associated pairs? That is, aren't the "keys" paired
>| with "values" in an alist just more general names for "terms"
>| paired with "descriptions" (the names used in the Variablelist
>| documentation)?
>Well, varlistentries can have multiple terms, but yes. However,
>wanna bet the number of people confused by assoclist is roughly
>equal to the number of people confused by variablelist? :-)

I think variablelist is particularly confusing, since in glancing at the 
list of elements, I'm failing to notice any other elements named after the 
cardinality of some component of their content (okay, varargs is an 
exception, but that's actually named after a programming language 
feature/concept, and isn't easily mistaken for specifying the arguments to a 
variable, since that wouldn't make much sense).  On the other hand, there 
are similarly named elements with semantics pertaining specifically to 
program variables and types.

At least, with assoclist, people would be less likely to make such 
assumptions, and thus more likely to check the description.

Personally, I think the more notable aspect of variablelist is that it 
allows content to be associated with terms.  I really think descriptivelist 
captures the spirit nicely, though perhaps that wouldn't be quite accurate, 
if someone used the terms as a sort of an index of whatever gets puts in the 
varlistentry listitems.

>| Regardless, I guess "Variablelist" is sort of confusing, not
>| very precise, because it doesn't imply anything about pairing or
>| association. If you think of the name as parallel to "Glosslist"
>| (and don't read the documentation), I guess it might be natural
>| to assume that a Variablelist is a list of variables.
>Yes, I suppose. RTFM, I guess. Renaming variablelist at this point
>would create a significant legacy problem for a very small return,

While I mostly agree with you, here, I also like to see clear, 
straight-forward semantics.  And I don't like to see cruft pile up.

Matthew Gruenke

Send and receive Hotmail on your mobile device: http://mobile.msn.com

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC