Re: RGSG

[Gleef <gleef capital net>]

On Sat, 1 Aug 1998, Tom Vogt wrote:
> here is the second draft of my "rebel" style guide. I look forward to your
> comments. please DO comment on everything you find unappropriate, think I
> have forgotten and such.
> 
> this is mainly a collection of things discussed here and/or posted earlier.
> I've only written some explanatory text and tried a few clarifications here
> and there. but still - please comment on everything you feel should be
> commented on.
> 
> 'nough talk:

I'll give more specific suggsestions this time around, to language.
Disclaimer, all of what I post is my opinion and mine alone.  I make no
claim of speaking for anyone else.  Feel free to discard any or all of my
opinions.  Some of my points might sound like nitpicking.  I like the base
document, any little points I might make are just to make the base
document better, not because I dislike it.  The nits I pick at today are
by no means all possible nits, I reserve the right to nitpick further :-).

To save space, I'll use a comment form loosely inspired by diff.  I think
it will be clear what I'm trying to say.


> Rebel Gnome StyleGuide
> ======================

- Gnome
+ GNOME

GNOME is an acronym, and should be referred to in all caps.  I'll
shorthand this and all other nits with no explanation needed in one line
(eg. -Gnome+GNOME).


> Foreword
> ========
> 
> this is NOT an official document, nor is it in any way related to the
> "official" Gnome styleguide that is being developed by Bowie Poag.

- Gnome styleguide
+ GNOME User Interface Style Guide

No reason not to call it by its full name.

 
> 
> 
> Chapter One	Declaration of Intent
> =====================================
> 
> the purpose of this document is to set forth guidelines for a consistant
-the+The
> Gnome Look & Feel.
-Gnome Look & Feel +GNOME look and feel.
> Such consistancy is necessary to help the user find his way around the
> system and all compliant programs easily and without the need to relearn
> basic operations.
> The additional goal of this Style Guide is to make the interface as easy
> and intuitively as possible, without taking away power and customizability.
> 
> one term being used throughout this document is "compliant" or "compliance".
-one+One
> Being compliant means a program honors the guidelines contained herein and
> thus "fits in" with the other Gnome applications.
-Gnome+GNOME
> We will define various levels of compliance, and will rate programs according
> to these. This will help users to find consistant programs more easily and
> should help programmers and designers to deal with the issue.
> 
> the levels of compliance are:
> 
> C1 - Mandatory (bare minimum)
>      Contains only the essential styles, so current programs can be brought
>      up to at least some level of compliance fast.
>      C1 features are considered to be of primary importance and non-compliance
>      will be considered a bug for Gnome applications.
-Gnome+GNOME
> 
> C2 - Recommended (needed for a proper Gnome app)
>      Features and behavior needed to make an app a full-blooded
>      Gnome app.
-Gnome+GNOME
>      Only C2+ compliant apps should be considered "true" Gnome programs.
-Gnome+GNOME

- "Only C2+ compliant apps..."
+ "Only applications meeting all of the C1 and C2 entries in this
  guide..."

This would make GNOME compliance more explicit and easier to understand.

 
> C3 - Suggested (should be there)
>      More advanced, harder-to-implement features, beyond the
>      call of duty, yet still within the core group of styles.
>      Should, but don't have to be implemented in finished programs, in no 
>      way mandatory for development versions.
> 
> C4 - Optional (fringe feature)
>      "Nice to have" features that are considered useful, but may not
>      be appropriate for all programs and are not necessary even where
>      appropriate.
> 
> C5 - Under Development (cutting edge, not official style yet)
>      Experimental features that are not fully implemented or
>      supported yet.  (Will fall into C4 or C3 when fully realized)

- "Will fall into C4 or C3"
+ "Will fall into other categories"

If we limit ourselves to C4 or C3, and something comes through that we
need to bump up to a C2 or C1 instead, there will be complaints.  This
alternate wording may reduce these.
 
      
>      
>      
>      
> Chapter Two	Default Gnome Elements
> ======================================
-Gnome+GNOME
> 
> this chapter contains suggestions to the developers of the core Gnome
-this+This
-Gnome+GNOME
> applications like the panel, properties and other configuration dialogs,
> help browser and many more.
> We consider these applications important enough to deserve a special
> treatment due to two reasons. First, they will create the first impression
> a new Gnome user has. Second, all other apps will be measured by the core
-Gnome+GNOME
> applications.
> 
> 
> 2.1  THE PANEL
> --------------
> 
> 
> 2.2  CONFIG DIALOGS
> -------------------
> 
> 
> 2.3  HELP BROWSER
> -----------------
> 
> 
> 2.6  FIND UTILITY
> -----------------
> 
> (has probably to be redone COMPLETELY. look into the interface hall of shame
> and compare.)
> 
> 
> 
> 2.5  OTHERS
> -----------
> 
> 
> 
> Chapter Three	Gnome Application Style Guide
> =============================================
-"Three Gnome" +"Three   GNOME"
> 
> this chapter contains the various items of interest for Gnome applications.
> They are sorted by topics and marked with C-Levels for compliance.
> 
> (dev-note: the current stuff is a mess, unsorted and all. subchapters should
> be introduced once the main points are clear)
> 
> 
> 3.1  MENUS
> ----------
> C1 -  If an application uses a menubar, it must contain at least
> two entries: "Prog" and "Help". A third entry, "File" must be available
> if appropriate. In the event that the name "File" is not
> appropriate, another label may be used in its place. In the
> remainder of this document, this menubar entry will always be
> referred to as the "File" entry.

Prog, I like the sound of it.  Remember, however that all the required
menu headings will have to be translated.  Using a real word might make
this task easier.

The discussion of the "File" menu needs to be a separate item (or items).
Personally, I think calling such a menu "File" should be a C3, perhaps a
C2, but not a C1.


> C1 - The "Prog" menu is a special Gnome menu that contains items
-Gnome+GNOME
> relevant to the application as a whole. 
> The topmost entry in the "Prog" menu must always be "About". The
> last entry in the "Prog" menu must be called "Exit". This item 
> will exit the application completely.

I think that Help is far far more appropriate for the About item than
Prog.  In addition to the argument that "That's the way it's always been
done", the information that is in the About window is critical to helping
the user.  When all available help is exhausted, the user needs to ask
someone else.

The About window contains all the information that the user needs to tell
someone what program they are using.  It also should contain the email
address of the program maintainer, if nobody else can be found to help.

Also, the items in the Prog menu are likely to be very high use, common
items.  I have never seen someone bother with the About window unless
they: A) Need information about the program to get help or figure out a
problem, or B) Are bored.  This usage would argue far more for being in
the Help menu than in prime real estate in Prog.


> The "Prog" menu must be the leftmost entry on the menubar
> and must be fully left justified.
> 
> C1 -  If a menubar is not present in an application, two buttons
> must be present somewhere labeled "Help" and "Exit". If the help
> for that application does not contain "About" information ( see
> below ) then an additional "About" button must also be provided.

Button program requirements should be described in a separate section than
Menu programs, to make it clearer which requirements go with which.


> C1 - Menu items that open dialogs or require additional user
> information should indicate it with a "..."  after the label. For
> example, the "About" menu entry in the "Help" menu should
> actually look like "About...".
> 
> C1 -  Menu items that contain sub-menus should indicate this with
> a right justified arrow.
> 
> C1 -  Menubar items and menu entries that are currently not
> available in the application should appear grayed out.
> 
> C2 - The "Help" menu must contain at least one entry called
> "Gnome", that starts the Gnome helpbrowser with its main page.
-Gnome+GNOME (two instances)
> 
> C1 - All menus should contain at least one entry, except for user
> generated lists ( bookmarks, etc. ) which may initially contain
> no items.

I think that user generated lists that are empty should have a standard
"-(No Entries)-" item in it.  This, like those "This Page Intentionally
Left Blank" pages in some manuals, will reasure the user that they aren't
missing something (and be the source of jokes :-).

 
> C2 - The "About" button will display a dialog with information
> containing at least the name and email address of the author,
> copyright information, version, and a link to the application
> repository information. Please use the gnome_about widget.

We might want to separate out Style issues (such as what information is
supplied in an About window) from Coding issues (such as what widget to
use).  I think coding issues should be addressed, just separately, so it's
easier to update as the coding issues change.  Also, by this entry,
Electric Eyes would not be a GNOME app, since it doesn't meet the C2
requirement of using the gnome_about widget.

 
> C3 - If the "File" menu contains a "New" menu entry, it should

- If the "File" menu contains a "New"...
+ If there is a "New"...

> indicate what you will be creating. For example, if the
> application creates a new word processing document, it should say
> "New Document" instead of just "New". If the application is able
> to create more than one type of resource, it should indicate that
> it will create a dialog with a "..."
> 
> C3 -  If it seems appropriate to the specific application, the
> use of floatable menubars is encouraged.
> 
> C2 - All menu items that have a corresponding button elsewhere in
> the application that uses an icon should also contain the same
> icon. The icon should be scaled to the proper menu size and be
> left justified in front of the label on the menu.
> 
> C4 - [Pie Menus]

While I like Pie Menus, they seem solidly in the C5 category.  As far as I
know, there isn't a GTK+ or GNOME implementation of them.  If there is,
point me at it, I want to see.

 
> 
> 
> 3.2  DIALOGS
> ------------
> C1 - All dialogs should have at least one button that is labeled
> "Close", "Cancel", "OK", or "Apply."
> 
> C2 - Modal dialogs should be avoided wherever possible.
> 
> C2 - The default highlighted button for a dialog should be the
> safest for the user.
> 
> C4 - The default selection should be user-customizable.
> 
> C2 - All dialogs should default to a size large enough to display
> all of the information in the dialog without making a resize
> necessary.
> 
> C2 - All dialogs should set the titlebar with an appropriate
> string.
> 
> C2 - A dialog which consists of a single entry box shall have its
> OK button be the default (which is to say that enter shall accept
> the entry), and the escape key shall be bound to the Cancel
> button.
> 
> C1 - In a dialog the "OK" or "Apply" button should not be
> highlighted until the user has made a change to the configurable
> data in the dialog.
> 
> C1 - If a dialog contains more than one button for the
> destruction of that dialog, ( for example, an "OK" and a "Cancel"), 
> the affirmative button should always fall to the left of the
> negative.
> 
> C2 - "Dialogs" that only display information with no user interaction
> should have only a single button labeled "close".
-close+Close
> 
> C3 - If you have a situation where a dialog might spawn another
> dialog please consider using a notebook instead.

I've never liked how this section was worded.  I might write and submit an
alternate proposal.

 
> 
> 
> 
> 3.3  KEYBINDINGS
> ----------------
> C1 - All menu items, menubars, dialogs and notebooks should be
> navigable from the keyboard.
> 
> C1 - Menu items that have bindings should list them right
> justified of the menu item label.
> 
> C2 - All applications that have common operations should use the
> binding interface that is outlined in the gnome key binding
> standard. Using the interface outlined in this standard will
> allow users to define  their own set of favorite key bindings and
> still maintain consistency across applications.
> 
> C1 - Applications should not allow users to change the default
> bindings for common operations.
> 
> 
> 
> 3.4  PROGRESS BAR
> -----------------
> C2 - All operations that have a deterministic time to completion
> in which no other obvious application activity would normally be
> taking place should indicate progress using a progress bar. This
> progress bar should begin its activity at the beginning of the
> operation.
> 
> C1 - Where possible, all operations that use a progress bar
> should have a cancel button as well.
> 
> C2 - Operations where a cancel button would be harmful to the
> application or user data should use a confirmation dialog.
> 
> C3 - Progress bars can be either set into the application panel
> or create their own dialog, depending on the individual design of
> the application.
> 
> C2 - All operations that do not have a deterministic time to
> completion should indicate progress using a dialog that contains
> either an animated icon or changing number to indicate progress.
> 
> 
> 
> 3.5  NAVIGATION
> ---------------
> C1 - All functions of the application should be available through
> the default user interface.
> 
> C1 - If the "Exit" menu entry or button is used or a destroy
> event is emitted, and the user has unsaved information, the

- a destroy event is emitted, ...
+ a SIGINT or SIGTERM signal is received, ...

SIGINT is the signal sent when the user hits Control-C from a calling
shell.  SIGTERM is the default signal sent by kill, and the signal that
most window managers refer to as close.  This behavior might
also be appropriate for SIGQUIT, but I'm not sure where this
signal is likely to come from.

> application should pop up a modal dialog to ask the user if they
> are sure they want to exit the application without saving.

+ C1 - If a SIGKILL signal is received the program should close down in
+ the fastest, non-destructive way possible.  The program should not ask
+ for any user input.

The SIGKILL signal is sent when "kill -9" is run, and in most window
managers when destroy is selected.  Most machines, during system shutdown
will send a SIGTERM to all programs, wait, and then send a SIGKILL to all
remaining programs.  SIGKILL will need to exit gracefully, even if the
user is unable to deal with a dialog.

I seem to remember that if a child process's parent disappears, the child
becomes owned by init, which sends it a SIGHUP.  Incorrect SIGHUP handling
will make the process a zombie.  If this is true, SIGHUP should also have
this behavior.

 
> C3 - Document based applications should contain four menu entries
> in the "File" menu for the last four documents opened. In the
> event that there haven't been four documents accessed, entries
> that have not been filled should be grayed out.
> 
> 
> 3.6  LOOK & FEEL
> ----------------
> C1 - [Use GTK+ widgets]
> 
> 
> 
> 3.7  COMMUNICATION
> ------------------
> C3 - [Which CORBA interfaces should be implemented]
> 
> C5 - [WM Hints]  (C3 when fully supported)

The Window Manager / Communication falls into three categories, only one
of which is not "fully supported".
  1) Session Management Support (I think this should be a C1)
  2) MWM Hints (I think this should be a C2, but C3 could be argued)
  3) GNOME hints, (C5, for now).


> 
> 
> 3.8  THEMES
> -----------
> C3 - [Color-reactiveness]
> 
> C? - [Appearance Guidelines (Graphics, etc.)]
> 
> C? - [Sound Guidelines]

As far as I know, this entire section is C5.


> 
> 
> 3.9  APPLICATIONS
> -----------------
> C2 - Applications should have an entry in the gnome application
> repository
> 
> C2 - [Session Management]
> 
> C3 - [Drag & Drop]
> 
> C5 - [Document-Object compliance] (C3 when fully supported)
> 
> 
> 
> 3.10  APPLETS
> -------------
> C3 - [Minimum CORBA interface]
> 
> 
> 
> 3.11  DOCUMENTATION
> -------------------
> C2 - Documentation for the application should be written using
> DocBook. DocBook supports generation of many document formats
> including HTML and PostScript. For an introduction in using
> DocBook, please see the DocBook tutorial.
> 
> 
> 
> 3.12  DISTRIBUTION
> ------------------
> C3 - Licensing under the GNU public license is strongly

- GNU public license is...
+ GNU Public License or Library GNU Public License, as appropriate, is...

> encouraged.
> 
> 
> 
> 		
> 
> Chapter Four	Writing Gnome Programs
> ======================================
-Gnome+GNOME
> 
> this chapter contains guidelines, pointers to the used Gnome-library
-Gnome+GNOME
> functions and other help to make the life of Gnome coders easier. Also
-Gnome+GNOME
> contained are several examples, templates and the skeleton of a fully
> Gnome compliant "hello world" application that can be used as a good

-Gnome compliant "hello world"
+GNOME-compliant "Hello World"

> starting point for other programs.
> 
> (...)
> 
> 
> 
> Appendices
> ==========
> 
> A1 - Alternative Ideas
> ----------------------
> 
> a place to collect ideas that didn't make it into the body of the document,
> but still MIGHT be of interest. Archived in case they get a revival. Also a
> store for alternative ways to do things that didn't fit in with the overall
> concept, but might if that gets changed.
> 
> 
> "Prog" Menu - Gnome Foot
> ------------------------
> Idea: Replace the "Prog" menu with a small Gnome footprint icon or a small
> icon of the application.
> 
> Left out because it overuses the Gnome icon (in version 1), is inconsistant
> with the menubar (all text otherwise) and may lead to usability problems
> (look at M$ office for an example).
> 
> 
> 
> 
> 
> A2 - External Resources
> -----------------------
> 		

I think this should start out by containing the full list from the
original style guide.


-Gleef