Re: Proposal for First Draft of GNOME Style Guide 1.1

[Gleef <gleef capital net>]

On Wed, 29 Jul 1998, John R Sheets wrote:

> Here's one way to do it!
> 
> I threw these ideas together pretty fast (in a couple afternoons)
> using ideas from myself and from the list, and from recent
> conversations with Maciej Stachowiak, so they're far, far from
> being perfect.  (c:  Most of the meat here is pasted directly
> from the existing style guide, albeit reorganized to meet the new
> structure.  Also included are some suggestions on ratings for
> different levels of compliance.  (I took the liberty of making a
> quick hell-in-a-bucket first pass at ranking each item...these
> will no doubt change as the guide goes through the mill -- grind,
> grind, grind.)
> 
> Let me know what you think!
> 
> John
> 
> ---------------
> Levels of Compliance
> 
> C1 - Mandatory (bare minimum)
>      Only the essential styles, to allow quicker GNOME
>      compliance for new apps.
> 
> C2 - Recommended (needed for a proper GNOME app)
>      Features and behavior needed to make an app a full-blooded
>      GNOME app.  (Only C2+ apps allowed in GNOME distribution?)
> 
> C3 - Suggested (should be there)
>      More advanced, harder-to-implement features, beyond the
>      call of duty, yet still within the core group of styles.
> 
> C4 - Optional (fringe feature)
>      The more controversial features that haven't been accepted
>      by the community as a whole, but are fully implemented & stable.
> 
> 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)

I like these categories.  Minor point, a C5 could very well end up as a
C1 or C2 (eg. propigation of a security issue or something).

 
> ---------------
> Universal Guidelines
> 
> 1.1  MENUS
> C1 -  If an application uses a menubar, it must contain at least
> two entries: "File" and "Help". In the event that "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.

There was much debate on this earlier.  Many people objected to putting
things unrelated to files under a menu named "File".  In my opinion, the
best solution is to rename "File" to "Main", and not allow it to be
renamed by an application.  This renaming would apply to the points
below as well. 

There were other proposals, such as requiring applications to have three
(or more) menus, and using an Icon as a menu heading.


> 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 - The last entry in the "File" menu must be called "Exit".
> This button will exit the application completely.
> 
> C1 - The "File" menu must be the leftmost entry on the menubar
> and must be fully left justified.
> 
> 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.

All of these are good.  Wording and structure tweaking I will save for
later.

 
> C2 - The "Help" menu must contain at least one entry called
> "About".

I think this should be a C1.  A program, partiularly an Open Source
program, needs to easily provide information about the authors.  For GUI
programs, requiring an "About" screen would provide this.  I believe
developers could play with the format of About (eg. Electric Eyes), but it
should always be present, and easy to find (hence under Help). 

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

Also good.

 
> 1.2  DIALOGS
> C1 - All dialogs should have at least one button that is labeled
> "Close", "Cancel", "OK", or "Apply."

This needs to be hashed out in much better detail.

 
> C2 - Modal dialogs should be avoided wherever possible.
> 
> C2 - The default highlighted button for a dialog should be the
> safest for the user.
> 
> 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.

Sounds good.  Again wording and structure tweaking are probably in order.

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

This needs work.  What about informational dialogs with just an "OK"
button.  Yes, I know they are annoying and overused, but somethimes they
are necessary.


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

This should be made stronger.  Eg. the affirmative button must be
the leftmost, or the negative button must be the rightmost.

 
> 1.3  KEYBINDINGS
> C1 - All menu items, menubars, dialogs and notebooks should be
> navigable from the keyboard.

Agreed.  However, whenever I read this I think there must be an exception
that I am not thinking of.  Probably a C2 is in order.


> C1 - Menu items that have bindings should list them right
> justified of the menu item label.

Sounds good.

I also think that there should be some configurable keybinding standards.
I (or someone else) will post a real proposal for this later.


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

I think the "Where possible", by definition, makes this a C2. :-)
This section needs wording and strucure tweaking.
 

> C2 - Operations where a cancel button would be harmful to the
> application or user data should use a confirmation dialog.
> 
> 1.5  NAVIGATION
> C?  - ???
> 
> ---------------
> GNOME Guidelines

This seems like an artificial distinction to me, between Universal and
GNOME Guidelines.


> 2.1  MENUS
> 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.

This needs to be broken up.  The "About" window must (C1) have certain
things (name, email, copyright, version).  It should (C2) have other
things (link), and it should (C2 or C3) 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 "..."

Sounds good.

 
> C3 -  If it seems appropriate to the specific application, the
> use of floatable menubars is encouraged.

This needs to be fleshed out some, the current floatable menubars
implementation is poor.  I also think that a case could be made for
coming up with a floatable menu (as opposed to menubar) implementation,
and trying to push that up to the GTK developers.


> 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]

>From what I've seen about pie menus, they should be a C5 for now.  All
I've seen is a lot of research about how great they are, and one really
ugly implementation that doesn't go with the GNOME/GTK+ look and feel at
all.  Once we have a good implmentation of pie menus, and have tried out
various ways to use it, then it could come out of the experimental stage.
Of course, if my information about pie menus are as dated as they likely
are, I will happily stand corrected.


> 2.2  DIALOGS
> C3 - If you have a situation where a dialog might spawn another
> dialog please consider using a notebook instead.
> 
> 2.3  KEYBINDINGS
> 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.

The way I see it, there will be three main "customers" of GNOME.  The
first will be (like I assume most of us are) people with personalized
desktops which we want to have control over all the aspects of our
machines.  The second will be system administrators of large distributed
networks, where they want to maintain constistent functionality across
many machines, and reduce their work.  Third will be people who need to
use an application or two which require the GNOME library (these users
won't care about changing the keybindings much, as long as they are sane).

Keybindings are one of those things that the system administrators would
love to lock down.  They are also one of the things that power users would
love to be able to change on the fly.  We should be able to come up with a
keybinding system (and I had heard many good suggestions a month ago) that
would address both.  However, this is one of those items where I think
some gnome-libs programming is probably necessary in order to get it to
where it needs to be.


> 2.4  PROGRESS BAR
> 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.
> 
> 2.5  NAVIGATION
> C1 - All functions of the application should be available through
> the default user interface.

I'm not entirely sure I know what this point is trying to say.


> 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.
> 
> 2.6  LOOK & FEEL
> C1 - [Use GTK+ widgets]

This should be a C2.  There are going to be cases where a developer feels
that the GTK+ (or gnome-libs) widget is inadequate for the needs of the
project, and roll his own.  We also should give detailed guides for custom
designed widgets.

 
> 2.7  COMMUNICATION
> C3 - [Which CORBA interfaces should be implemented]
> 
> C5 - [WM Hints]  (C3 when fully supported)

Some of them (the MWM hints) should be C2 or C3 already.  It's the newer,
GNOME-specific hints that are C5.

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

I think that most theme support is C5 at the moment.  Rasterman has been
the main force behind implementing themes, and he seems caught up in
higher priority things right now.


> 2.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)

Sounds good.


 
> 2.10  APPLETS
> C3 - [Minimum CORBA interface]

My understanding is that Applets (i.e. the programs designed to run inside
the panel) should be a C2 as far as using the standard CORBA interface.

We also should discuss other applet issues, like how much space to take up
in a vertical or horizontal panel, required menu interface items, etc.

Also, there has been talk about making the panel resizable.  If this is to
be, resizable applets would also be a requirement.  Yes, this would be a
serious programming burden, so I don't know if we should even be thinking
about it.


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



 
> 2.12  DISTRIBUTION
> C2 - Licensing under the GNU public license is strongly
> encouraged.

We definately need to elaborate on this.  I would like to like to see a
carefully worded requirement that the programs not use or require code
that is not Open Source as per the service marked definition.  This would
need to be very carefully worded, since there would have to be exceptions
in place to allow porting to other platforms (eg. Solaris, Win32, etc).

Specifically, I would like to see any Motif-style GNOME programs required
to run cleanly against LessTif.  I would like to see any Qt-style GNOME
programs wait until a similar requirement could be made with Harmony or
QTK.

I would rather see us be sticklers for licenses, and occasionally labelled
fanatics by those who don't know or care about licensing issues, than to
have a project with GNU in its title in a position where it finds itself
"endorsing" non-Free software.

Just my two cents, sorry it was so delayed.  On to wading through more of
the messages...

-Gleef