The following are comments on the GNOME 2.2 Desktop User Guide by Sasha
Kirillov, and responses from Eugene O'Connor.

The "{2.0}" notation after some of the comments is for the Sun L10n team to
identify changes that have been made to the GNOME 2.0 Desktop on the
Solaris OE User Guide.

COMMENT 1 
1.1.1: Mouse Button Conventions:
   Maybe mention that if you have a (properly configured) wheel mouse,
   then the wheel acts as a middle button

EOC: What do you configure the mouse to do this? This sounds like a topic
for the System Admin Guide. I'd like to ensure we have the "how to
configure the mouse so that the wheel acts as a middle button" information
in the SAG before we add this to the UG.

COMMENT 2
1.1.2: in the   table, the second  column should be titled "usage",
   not "Definition" 

EOC: Done. {2.0}

COMMENT 3 
1.2.1: for some reason, in the table "Print Screen" and "F1" are shown
    bold, unlike all other key combos. Maybe because you used
    <guibutton> for them and <keycap> for others? Or maybe it is a
    stylesheet bug?  Anyway, it looks
    bad. Same problem in many other tables. 

EOC: This is a stylesheet bug. The problem is that the following examples
are rendered differently by the stylesheets:

Example 1: <keycap>F1</keycap>
Example 2: <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo>

See bug 100476.

COMMENT 4
1.3. Title "Using Windows and Dialogs" is misleading as there  is
     nothing about dialogs in it. Instead, info about navigating
     dialogs is in previous section, 1.2

EOC: Done. {2.0}

COMMENT 5
2.1. 
  In "Menus" paragraph:
   "You can also access the items in the Applications and Actions
    menus from the GNOME Menu." 
    This does not explain what exactly this GNOME Menu is and how one
    opens it. Note that the default desktop shown in the screenshot
  doesn't contain a GNOME menu button. 

EOC: Done. I updated this to explain what the GNOME Menu is, but I don't
think that this is the appropriate place to go into detail on the GNOME
Menu. This is explained in the Menus section later on.  {2.0}

COMMENT 6

  In "Workspaces": 
    "A workspace is a discrete area on the desktop in which you can
    work."  
    Maybe it is just me, but this phrase just confuses me. Does it
  mean that it is part of the desktop? If so, how comes it takes all my
desktop? (of course, I
  am just pretending to be stupid, but this phrase has actually
  confused me. But then, I am not a native speaker...). 

EOC: Done. I see how this could be confusing. I deleted "on the desktop". 
{2.0}

COMMENT 7
2.2.4, "Lock button and Log Out button"

      "The Lock button enables you to end your session."
      Shouldn't this be "Log Out button"?

EOC: Done. {2.0}

COMMENT 8
2.9:
 
   "For convenience, the tools are grouped under the following headings:

    *   Basic
    *   Accessibility
    *   Advanced"
   For some reason, in this list "Accessibility" and "Advanced"  items
   appear bold while "Basic" does not. 

EOC: Accessibility and Advanced are tagged correctly as <guilabel>, Basic
does not appear in the UI. So I suppose this is slightly misleading. But I
can't think how to correct it.

COMMENT 9
3.2 

   Suspend After  Specify how long to wait to put the 
                  monitor in power-saving mode.

   Off After      Specify how long to wait to switch off monitor

   In these items, it is not clear whether the time is measured from
   the time screensaver starts or from the previous phase, i.e., if I
   have "stanby after 20 mins" and "suspend after 40 mins", will it
   suspend 60  mins after the screensaver starts (this is what I
   expect) or 40 mins? 

EOC: To be investigated. Will do for 2.4.

COMMENT 10
4.5.1.1. To Create a Launcher With the Create Launcher Dialog"
  
   The table lists "Generic name" field, while the screenshot doesn't
   show it. 

EOC: Done.  {2.0}
 
COMMENT 11 
   Also: from the instructions in this section, it is not clear how to
   create a launcher of "Link" type. Should the URL be entered in  the
   "Command" field? What type of URLs are acceptable? E.g., are URLs
   with "ssh:..." acceptable? What about special Nautilus URLs such as
   "preferences:///"? 

EOC: I need to look into this. I think the URIs are specified in
gnome-vfs-2.0/modules/default-modules.conf. I'll aim to do this for 2.4.

COMMENT 12 
4.12. Run Button

      "For more information on the Run Program dialog, see Working With
      Menus."

      This should be a link. 

EOC: This will need to be a <ulink> rather than an <xref> because at
present the chapters are shown in Yelp individually, rather than as a book.
In a recent mail, you said the way to code this was:

<ulink url="ghelp:gnome-terminal">GNOME Terminal Manual</ulink>

What is gnome-terminal? Is it the name of the XML file? Sorry if it's an
obvious question, I want to be sure. So link above would be coded like
this:

<ulink url="ghelp:goseditmainmenu">Working With Menus</ulink>

I also see the following code:

<ulink url="ghelp:gnome-feedback" type="help">GNOME Feedback Page</ulink>

What is the role of the "type" attribute?

And how do I link to a sectid within a chapter?

In any case, I think Sander is hoping to "unexpand" the User Guide and make
it a single book again (at present, each chapter is treated as a separate
book). This will enable us to use <xref> for cross-references within the
book. And we can use ulinks for references to other books.

COMMENT 13 
6.2.12
    The table uses the word "shade" without explaining the meaning of
    this. I expect this term to be unfamiliar to most new users. Thus,
    it would be best to provide a link to 6.4.8 which explains this
    term. 

EOC: Yes, I wasn't sure about the change from Shade to Roll Up, so I wanted
to make minimal changes. I have logged a bug about Roll Up and Unroll,
suggesting a change to Show Titlebar Only and Show Full Window. See bug
105502. I'll await the outcome of the discussion before making changes.

COMMENT 14 
6.3.1
    
    The table lists "Roll Up/Unroll" item in Window menu; the
    screenshot shows "Shade" instead. 

EOC: See previous comment.

COMMENT 15 
7.8.1.1. To Set Views Preferences



 "Sort in reverse   ...For example, if you select By Name from the
                      Arrange Items drop-down list box. You can select
                      the Sort in reverse  option to sort the items in
                      reverse alphabetical order."  

 It should be a comma, not a period, right?

EOC: Done. {2.0}

COMMENT 16 
7.8.13

    "Group Choose this option to display the group to which the owner
           of the item belongs." 

 Striclty speaking, this is not quite accurate, as a user may
 belong to several groups.  "Group" is the name of
 the group that owns file. 
 
EOC: Done. {2.0}

COMMENT 17 
Also: when describing premissions, shouldn't we say at least a little
bit about what they are and how one uses them? For example, few new
users understand that "write" permission for a folder actually means
ability to create, delete, or rename files, and has nothing to do with
the abitlity to modify existing files, while "execute" for a folder is
the ability to access files in that folder. 

 This may not be the right place to discuss it, as it is not
 GNOME-specific, but we should, at the very least, give a
 reference. E.g., on Linux, we can refer to fileutils info page. 

EOC: I agree. I'll get this in for 2.4.  {2.0}

COMMENT 18 
 7.9. Using Removable Media

"Nautilus supports the following removable media:

    *  CD-ROM
    *  Iomega Zip disk
    *  Floppy diskette"

As far as I know, it actually supports more than that. E.g., it also
supports Jazz drives, USB storage devices, etc. Better ask Nautilus
developers for exact statement. 

EOC: Done. The full list is Audio CD, Camera, CD-ROM, Floppy diskette,
Iomega Jaz disk, Iomega Zip disk, Memory Stick. I presume Memory Stick is
what you mean by USB storage devices? I need to follow up with Alex to
clarify does the port matter for Memory Sticks.

COMMENT 19 
 8.3 Desktop Background Objects

     This section says 

"You can modify desktop background objects in the following ways:

    * View the properties of the object.                 (no equivalent)
    * Rename the object.                                 To Rename a File
or Folder
    * Change the permissions of the object.              To Change
Permissions
    * Change the icon that represents the object.        To Modify the Icon
for a File or Folder
    * Resize the icon that represents the object.        To Stretch an Icon
in Icon View
    * Add an emblem to the object."                      To Add an Emblem
to a File or Folder

 but does not actually explain how to perform any of these tasks. It
 doesn't even mention that you can right-click on an object to get the
 popup menu (yes, it has been explained elsewhere, but should be
 mentioned here again). 

EOC: I'll get this in for 2.4. 

COMMENT 20
 8.3.3. To Add a Launcher to the Desktop Background

     This section should also explain how to add a menu item as
     launcher to the desktop background. This has been discussed
     before, but should be mentioned again - or, at least, a link must
     be provided.

EOC: I'm not sure what you mean. AFAIK, the only way to add a menu item as
launcher to the desktop background, is to use the menu item popup menu to
add it to a panel, then drag it to the desktop background. Maybe you are
talking about dragging a menu from a Nautilus window to the desktop
background?

COMMENT 21 
  9.3. Choosing Default Fonts
   
    I didn't try GNOME 2.2 yet, but my guess is that "Desktop font" is
    also used by Nautilus. Is that correct? If so, then it maust be
    mentioned. If not, then it must be mentioned here how one
    configures fonts to be used by Nautilus. 

EOC: I think that Nautilus windows use what is specified in the Application
font. I need to double-check that.

COMMENT 22 
  9.6. Customizing Menus and Toolbars

     Some people will look in this section to find out how to edit
     menus (which, after all, is a form of customization) - and not
     find it here. We should give a link to "5.6. Customizing Your
     Menus". We should also say that the menu font and colors are
     determined by the widget theme and provide a link to appropriate
     section. 

EOC: I changed the title of this section to "Customizing Menus and Toolbars
in Applications". Do you think this solves the problem? {2.0}

COMMENT 23 
 9.10.1. Desktop Theme Settings
   
  "You can find many GTK themes on the Internet."

   Since we now call them "widget themes" rather than "GTK themes",
   this looks cryptic. Better: "you can find many widget themes (which
   are also called GTK2 themes) on the Internet". By the way, why not
   provide a link to art.gnome.org? 

EOC: Theme functionality will be updated for 2.2.1, this should solve this
problem. I don't know if it is advisable to put the art.gnome.org link in
the User Guide. Is downloading and installing themes really a typical user
task?

COMMENT 24 
---------------------------------
Finally, here are some more suggestions for the glossary:

 MIME type 

EOC: Done. {2.0}

COMMENT 25

 link (aka symlink)

EOC: Done. {2.0}

COMMENT 26

 shade (a window) (?) 

EOC: See my response to COMMENT 13.

COMMENT 27
1. Working with Panels-> Launchers->To create a launcher
  "Documentation  This field is currently not in use"

This is incorrect. This field is indeed used: it gives help URI which is
used when you  right-click on launcher and choose  "Help on <application
name>".  

EOC: Done. {2.0}

COMMENT 28
2. Nautilus Manual->Modifying the appearance...->Using views. 

I think one should  list the  existing views. OK, icon view and list
view are self explanatory; music view less so, but "Content Loser view"
(and the button I now have on Nautilus toolbar, "Kill Content Loser") -
I am really lost...

EOC: I need to investigate further - I haven't seen this view or button.
I'll aim to address this for 2.4.

COMMENT 29
3. Theme preference tool: it seems that the tab names have been changed.
There is no longer a "widget" tab: instead, it is called "Controls". In
addition, there is an "Icon" tab. Finally, there is no longer such thing
as "Nautilus theme" (thank god). 

EOC: Done.

COMMENT 30

In addition, here are some things that I think should be added to the
UG. I could help you to write some of this stuff if you want:

4. i18n stuff (this is my favorite): how one uses GNOME with languages
other than English? SUN probably plans to address it in translated docs,
but I think this should be in the English language version too. For
example, because the translated ones are not yet available. Not to
mention that many people who use English as their main language
occasionally need to read or type a document in another language. I
could write this up if you want.

EOC: I am not sure how Sun plans to address this. I wouldn't really know
where to start with this one. I do think that the SAG would be a more
appropriate location for this. If you want to write this up, I'd be happy
to try to find a location for it. However, we would need to ensure that,
whatever the location of the information, it complies with the GDSG.

COMMENT 31 
5. Font management: (probably belongs to admin guide). At the moment, it
is not mentioned anywhere except release notes that one can add fonts by
copying them to ~/.fonts directory. 

EOC: Yes, I think this is SAG material - I am trying to find out what story
is with fonts for Sun.

COMMENT 32
6. Some other minor notes from the release notes: e.g., update
notification. 

EOC: I'll investigate this and plan to have it for 2.4.

COMMENT 33
7. Information on "special" URLs accessed by Nautilus, such as
"network:///", "smb:///", "fonts:///" (the latter one doesn't seem to be
included in default build of Nautilus). It probably suffices to say
something like:
"Nautilus can also be used to browse your local network. You can access
your local network by clicking on "Network neighborhood" icon in "start
here" location, or by entering network:/// in "location" field of
Nautilus."

EOC: I'll plan to do this for 2.4. I think this is similar to COMMENT 11.

COMMENT 34
contrary to what the UG says, not all item you move to trash are stored
in ~/.Trash directory. For files on other filesystems - e.g., on a
floppy disk - it works differently: trash is stored in the file
.Trash-<username> on the floppy itself. I am not sure it is a wise
solution, and it sure makes things  more complicated to explain, but we
must document it anyway....

EOC: Done. In both Nautilus File Manager and Desktop Background chapters. I
deleted the reference to the /.Trash directory. This information is not
related to the UI, and I don't think users need to know this.
Interestingly, as far as I can tell, Trash displays ~/.Trash and
.Trash-<username> as one. So the user really doesn't need to know this.
{2.0}