This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
variablelist (Re: doc domain vs. problem domain semantics)
- From: "Matt G." <matt_g_ at hotmail dot com>
- To: docbook at lists dot oasis-open dot org
- Date: Fri, 04 Jan 2002 09:05:53 +0000
- Subject: DOCBOOK: variablelist (Re: doc domain vs. problem domain semantics)
- Bcc:
>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,
>IMHO.
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