Re: gcalc docs (unfinished)

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Fri, Apr 28, 2000 at 10:24:31AM -0400 or thereabouts, Alexander Kirillov wrote:
> On Fri, Apr 28, 2000 at 08:06:28AM +0100, Telsa Gwynne wrote:
> > Why does everyone love the em-dash so much? I was thinking about
> > this, because we seem to be using an <itemizedlist> and then
> > separating the name and the definition with em-dashes all the
> > time. What's wrong with <variablelist> if we want to separate
> > name and function?
> 
> There is nothing wrong with <variablelist>, of course - it is just a
> matter of taste whether to use it or <itemizedlist>. I prefer
> <itemizedlist> because I generally like my headings (like function or
> button name) inline, unless it is followed by a really long
> explanation. 

Eep. Isn't that a stylesheet thing? I agree that inline is good: it's
particularly good when you have a long list of things and don't want
to use huge quantities of screenspace or paper: if you've tried to
print the results of the standard stylesheets, you'll doubtless have
noticed that you get:

page one:
	title
page two:
	chapter title
page three
	section title and maybe some actual content.

This is something that rapidly gets annoying if you have a lot of
chapter titles taking up a single piece of paper each! If you have
a 640x480 screen, once you've shrunk the help-browser to a sensible
size you only see half a dozen varlistentry things at best, too.
So I agree about that to some extent. 

But I thought that using different markup to produce a particular
appearance was a DocBook Sin?

We already have our own templates. Modifying it to lose the huge
amounts of whitespace in the ps files and to turn <variablelists>
into something that is more like

     termgoeshere      tab tab tab     explanation explanation explanation
                       explanation explanation explanation explanation

might be possible, perhaps? Or just removing the blank line?

(Or are the GDP stylesheets used by the folk who document APIs and
code, too? They might not be so keen on this..)

> 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 :)

Telsa