RE: ANNOUNCE: Style Guide available for review.

[Paul Hepworth <phepworth s-vision com>]

> > "Documentation for the application should be written using DocBook"
> > add
> > "... and must provide at least a manpage and preferably html
> > documentation.  (If html documentation is provided, the manpage may
> > simply be a stub telling how to access the real documentation.)"
> > 
> 
> DocBook will generate HTML among others.  I'd like to stay
> away from man pages if at all possible.  Maintaining one
> form of documentation is easier for developers, and more
> importantly, less confusing for users.
> 
It is only one form.  It's just that it is *rendered* in two formats:
man and html.  I'm led to believe that DocBook supports this sort of
thing.  But again, I can't argue with Miguel's "then add the docbook
tags for man pages and submit the patch yourself."


> > Add this item:
> > "All menus must be navagable by mouse using both pull-down (drag)
> and
> > drop-down (click) actions and by keyboard using cursor keys and
> > accelerators.  Each menu item should have a unique accelerator."
> > 
> 
> This is dealt with in the Keyboard Binding Policies.  Also,
> I don't think that every menu item needs an accelerator.  It
> can get really confusing for users.
> 
By accelerator here, I don't mean the right-justified
Shift+RightAlt+WiggleYourNose+F92 thing.  I mean the underlined letter
in the menu item.
Back in M$ Excel 4, they didn't provide any for the popup menus,
requiring me to 
do {click;  move mouse;  click} until hand_is_tired
when I could have done {click; press letter} instead (no mouse motion
required).  With a key assigned to invoke the context menu, it would
even be better:  {menuKey; letterKey}
Terminology question:  hotkey and accelerator tend to be used
interchangeably to say "a button I press to avoid having to navigate the
menu" yet we have two types:  the application-wide ones, and the "this
menu only" / "this button-group only" variety (the underlined letter).
Is there a good separate term for these?

> Ok.  When a key binding standard is both available and the
> software is ready for use, we can add information about the
> key binding standard.  However, I personally feel that
> individual applications still have no business changing the
> key binding for a common operation that may be used in other
> places.  Changing that in a global area is fine, but not in
> each program.
> 
Right you are.  *Applications* should not change the binding.  However,
they should read the binding from a user keybinding preference database.
I'm with you now.  We need to get a keybinding standard in place ASAP
before apps have hard-coded keys, though.

I guess I jump on a draft standard and reference implementation for
review.  We can get the implementation great later, the *interface*
should be defined soon.


Paul