Re: Panel docs

[Telsa Gwynne <hobbit aloss ukuu org uk>]

Very brief addendum.
On Tue, Feb 29, 2000 at 04:54:42PM -0600 or thereabouts, Eric Baudais wrote:
> 
> 1) In the legal notice there should be a period after "UNIX is a trademark
> of X/Open Group" and after "Linux is a trademark of Linus Torvalds".

I have been looking around, and what I see on websites the most 
often is, "Linux is a trademark of Linus Torvalds in the US and some
other countries."

> 4) In Panel Basics, I don't think the use of the <formalpara> tag is good.
> The titles make each point redundent because each title is repeated, as
> the first word in starting sentence.  Plus, those previously
> mentioned words are highlighted.

I disagree, actually. I liked it, because it makes it clear what it's
referring to. I wouldn't have thought of <formalpara> myself: I'd have
used <variablelist> and <term> and got a similar effect.

> This is a good start.  I really liked what I saw and think these minor
> corrections would make it a much better document.

I've snipped most of them. I agree. Sasha and Dan kept sounding like
they thought it wasn't very good on IRC, but I'm really impressed.
I particularly like the warnings and highlights about where people may 
fall down or get confused when something's not where they expect: the 
different locations of where to configure certain things are excellent
things to include.

Other bits and pieces (and, yes, I know line numbers was a silly
way to do this):

   o I would uncapitalise words where you're not sure. I really don't
   think panel is a proper noun, for example, and I think capitalising
   too many words makes it hard to read. To be consistent, if you 
   capitalise panel, I think you'd end up capitalising "Window", too,
   along with launcher, menu, etc.

line 109:
     "...icon(the GNOME)": probably needs a space before the brackets? 

line 621:
     "you are using standard PC keyboard": "..using a standard.."? 

There's a couple of places where I would personally have used a list:
the "Right-click menu" (aargh, it's left-click for me!) and "Components
of the main menu" have lists of different things all in one long paragraph.
It might be clearer as a <variablelist> or even just an <itemizedlist>.
There are other places, too, but those are particularly noticeable. It's
particularly a problem when you don't use the GNOME stylesheet (guess
who forgot, the first time) because the default one doesn't seem to 
do a lot with <guithingy> tags.

Swallowing applications: "you must know the title of the window you
would like to swallow": is this the title as displayed by the titlebar,
or some mystic X title which is cunningly hidden from view? I seem to
recall things like xsomething.xsomething as titles once. If it's not
just what's shown in the titlebar, is there a simple way to get at it
which will work for everyone that we can put in here?

Are you sure that what you say for the details of the "Run..." menu
option works? You say that you can enter a command in the box and then
select the file to browse. I typed 'emacs' in the box, highlighted a
file to look at, and clicked on 'run' and I got "duh-dink" and nothing
happened except that the "Run" dialogue box vanished. I could well be 
doing it wrong: should I be drag-and-dropping the file onto the command 
line? When I try, I inadvertently double-click on the file in the browser, 
and get the "du-dink" noise and vanished dialogue again.

Oh dear, that looks a huge list of criticisms, but that's all I found.
Overall, I think it rocks.

Telsa