Re: Panel docs

[Dan Mueth <d-mueth uchicago edu>]

Drake,

Thanks for the feedback:)


> 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".

Fixed. (in both the panel docs and the templates.)

> 2) In the Introduction, I think the article "the" shouldn't be in the text
> for the link to the Main Menu section because it does not describe the
> main menu, but is part of the sentence structure in the paragraph.

yep. fixed.

> 3) In Panel Basics, I think the link to Figure 1 should be taken out
> because the figure is right below the text and people can clearly see what
> you are pointing to.

* NOTE THIS *

I think this belongs here.  My reasoning is that sgml should not assume
the appearance of the output will always be that they lie together. When I
do db2ps or db2whatever, the screenshot may not be close to this sentence.
So, I think we always have to refer to the figure number.  In my original
version, I said things like "In the figure above" and such.  I recently
removed all that.  Now I start by saying, "The example Panel in Figure
1..." and then to avoid referring to Figure 1 constantly, I later say "In
the example Panel", since I already told the reader the example Panel is
in Figure 1.

* I think this is an important point and would recommend other authors do
the same.  

> 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 thought this looked weird too. I have not figured out if words like
Drawer should be tagged they way they are.  I suspect we will decide they
are not tagged this way, so they will not be bold and it will look
correct.

> 5) In Introduction to Panel Objects, "In the example Panel" should be
> restated "In Figure 1," as a link, because the example panel doesn't point
> to the panel above the list but can be any panel, even the default panel.
> 
> 6) In Introduction to Panel Objects, "the default icon used for user
> Menus."  The word "user" should be included inside <guilabel> because it
> is a specific menu that users can access and modify.  I believe another
> example would be to include "<guilabel>system menu</guilabel>."

Again, we need to develop the standards for these things by concensus and
put them in the Handbook so everybody can use the same notation/markup.

> 7) In Introduction to Panel Objects in the second to last sentence in the
> Applets list item, you repeat for twice in close proximity. "both of which
> are for Electric Eyes. For more information on Applets."  I think this is
> redundant and will sound better if the "for" before "Electric Eyes" is
> deleted.

yep.

> 8) In Introduction to Panel Objects, "Each of these object types is
> described in detail in the following sections."  The next sections after
> Introduction to Panel Objects do not describe the objects of the panel.  I
> think it would be better if you said "in the following chapters."

The Handbook is an article, so it has sections but no chapters.

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

Thanks for the suggestions.

Dan