RE: ANNOUNCE: Style Guide available for review.

[Paul Hepworth <phepworth s-vision com>]

> StyleGuide> "Documentation for the application should be written using
> StyleGuide> DocBook"
> 
> Paul> "... and must provide at least a manpage and preferably html
> Paul> documentation.  (If html documentation is provided, the manpage
> Paul> may simply be a stub telling how to access the real
> Paul> documentation.)"
> 
> We should be able to render properly written DocBook documentation
> into man pages and HTML.  So I'd suggest that nobody bother with
> either of these formats, unless and until we discover that DocBook
> can't cope (I doubt this will happen).
> 
> DocBook *can* (we think).  I mean to say here that you must use
> DocBook in such a way as to produce these.  (I.e. if it is possible to
> use DocBook but not generate man and html pages, this is prohibited.)
> 
> 
> Paul> Also, some applications are a more logical fit for a modal
> Paul> dialog rather than a traditional menu-adorned window.  These
> Paul> should contain at least one of Close/Okay/Cancel buttons, and if
> Paul> a menubar is not provided, a Help button.
> 
> I think that if an app fits the dialog (not modal, just dialog) style,
> then it be prohibited from having a menu bar.  The two things just
> seem at odds.  (As an example of this kind of app, consider the
> mouse-properties program.)
> 
Actually, they are indeed modal:  *application modal* not *system
modal*.  (All single-window programs are so.)  Of course, if it spawns
additional dialogs, these would be non-modal.

> Should such apps have About buttons as well?
> 
They really should, but I hate sticking buttons all over.  :-(
What I really want is to be able to add these things to the app icon in
the frame, typically used by the wm to hold move/close/min/etc. options.
How about we hack wm's to allow apps to use the system menus?  :-)
Alternatively, how about just a help button with the requirement that
each help page include a link to the about page in the helpfile.

> "Ok" should actually be capitalized "OK" (is that the nittiest nit, or
> what??).
> 
You are right.  Personally, I prefer it spelled out (Okay).

> I like Apply buttons on dialogs of this sort.  The Apply button should
> be ghosted until the user makes a change.
> 
Yes, for settings-type programs.  (Of course, not for CD-player or
Calculator type programs.)

> StyleGuide> "All operations that have a deterministic time to
> StyleGuide> completion that lasts more than three seconds should
> StyleGuide> indicate progress using a progress bar."
> 
> Paul> Should this be configurable (system-wide, per user) instead of
> Paul> arbitrarily three seconds?  (I don't like to see progress bars
> Paul> unless the operation takes more like ten seconds.)
> 
> This will sound really nutty, but: we should hide this functionality
> behind some API in libgnomeui.  Then in the future we'll be free to
> change the implementation to (I kid you not) contact the CORBA
> "progress service".
> 
> This service could be configured in many different ways:
> 
> * # of seconds until pop up
> * Pop up a dialog for each progress status
> * Don't pop up a dialog, but display all ongoing tasks in a single
>   window somehow
> 
agreed

> Obviously this is something we probably won't do at the beginning.
> 
but the stubs should be in place at the beginning!


Paul