RSG

[Tom Vogt <tom lemuria org>]

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:




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

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.



Chapter One	Declaration of Intent
=====================================

the purpose of this document is to set forth guidelines for a consistant
Gnome Look & 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".
Being compliant means a program honors the guidelines contained herein and
thus "fits in" with the other Gnome applications.
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.

C2 - Recommended (needed for a proper Gnome app)
     Features and behavior needed to make an app a full-blooded
     Gnome app.
     Only C2+ compliant apps should be considered "true" Gnome programs.

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)

     
     
     
     
Chapter Two	Default Gnome Elements
======================================

this chapter contains suggestions to the developers of the core 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
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
=============================================

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.

C1 - The "Prog" menu is a special Gnome menu that contains items
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.
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.

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.

C1 - All menus should contain at least one entry, except for user
generated lists ( bookmarks, etc. ) which may initially contain
no items.

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.

C3 - If the "File" menu contains a "New" menu entry, it should
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]



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

C3 - If you have a situation where a dialog might spawn another
dialog please consider using a notebook instead.




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
application should pop up a modal dialog to ask the user if they
are sure they want to exit the application without saving.

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)



3.8  THEMES
-----------
C3 - [Color-reactiveness]

C? - [Appearance Guidelines (Graphics, etc.)]

C? - [Sound Guidelines]



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



		

Chapter Four	Writing Gnome Programs
======================================

this chapter contains guidelines, pointers to the used Gnome-library
functions and other help to make the life of Gnome coders easier. Also
contained are several examples, templates and the skeleton of a fully
Gnome compliant "hello world" application that can be used as a good
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
-----------------------
		




-- 
The universe does not have laws -- it has habits, and habits can be broken.