RE: gcalc docs (unfinished)

[Gregory Leblanc <GLeblanc cu-portland edu>]

> -----Original Message-----
> From: David C. Mason [mailto:dcm@redhat.com]
> Sent: Friday, April 28, 2000 9:52 AM
> To: gnome-doc-list@gnome.org
> Subject: Re: gcalc docs (unfinished)
> 
> Telsa Gwynne <hobbit@aloss.ukuu.org.uk> writes:
> 
> > > And  if you
> > > do use <itemizedlist>, I think using &mdash; is quite
> > > appropriate. Definitely it is better than just using - . 
> > 
> > I think a colon would be nicer, but now we're getting 
> really quibbly :)
> 
> If you want to be 100% DocBook compliant you would *never* use an
> &mdash; in an <itemizedlist> to separate a term from a definition -
> you would use <variablelist> as the reference page for <variablelist>
> states: "A list in which each entry is composed of a set of one or
> more terms and an associated description"
> 
> Having said that - I have done it in the past and I have even used
> many <formalpara>s to create a different style altogether.
> 
> Telsa is correct - Docbook is suppose to be written *without* format
> in mind - formatting is another step altogether. It does creep in
> though, and we have probably all done it at one point or another - but
> it is a good idea to try and suppress the desire as much as possible.
> 
> As to the stylesheets - someone might want to point out to me what the
> exact problem is with how the lists are appearing - I'm not sure I
> understood what the problem was and I may be able to fix it. BTW, the
> API docs use a *very* different stylesheet so don't worry about that.

Well, here's where the issue that started the thread is.  In the GNOME
Calculator doc (see, I've reformed!), I'm writing an explanation of how each
button works, along with an example for most of them.  I'm using a variable
list, with examples inside of the items.  The markup works ok, but when it's
rendered into HTML (probably others, I haven't looked), it got too much
whitespace to look quite right.  It's hard to explain, but here's the latest
version of the gcalc doc that I've got available to me here at work.
Thanks,
	Greg

gcalc.sgml