[Texmacs-dev] Reorganization of the menus

[David Allouche]

On Thu, Jul 25, 2002 at 12:41:24PM +0200, Joris van der Hoeven wrote:
> 
> Yes, please tell me your suggestions, but hurry up...
> I consider the File, Edit, Insert, Text, Paragraph, Document,
> View and Go menus as being quite stable. Just notice that

Well, I would have preferred to do it slowly... but okay, I am
spending a few day making a complete proposal.

First, you pointed out the KDE style guide as a reference. Please see:
http://developer.kde.org/documentation/standards/kde/style/menus/index.html
Here they recommend (verbatim) the following menu layout:

  File  Edit  View  Go  [App. specific]  Bookmarks  Tools  Settings  Help

Personnally, I have no preference for this one layout or the other we
agreed on, but I just wondered.

Now, let us go for my proposal.


  Basic rules
 =============

  Introduction
 --------------

Since I am asked to hurry up, I will drop out some diplomacy to make
my point clear. All those rules are non-negociable. They are first
principles of good user interface design. Some applications can violate
those principles, but then, they are badly designed.

My basic reference here are the Apple User Interface Guidelines.

For MacOS X (Aqua):
http://developer.apple.com/techpubs/macosx/Essentials/AquaHIGuidelines/index.html

For MacOS Classic (7.5):
http://developer.apple.com/techpubs/mac/HIGuidelines/HIGuidelines-75.html#HEADING75-0

That documentation must be taken with a grain of salt because, after
all, we are still only a Unix-only application. But, even though
conventional choices are discutable, the principles are right. Say
what you want about Apple misgivings, there is one sure thing: they
know how to make GUIs.

User interface is not something one can invent out of thin air. There
have been expensive studies made by big corporation on usability
issues, we would be better off leveraging that work. The KDE style
guide tries to synthetise some of this for unix hackers, but why use
the "light" version, while the full documentation is online?

However I also checked the KDE User Interface Guidelines (strange...
they use the same name as Apple...) to make sure there was no
contradiction:

http://developer.kde.org/documentation/standards/kde/style/basics/index.html


  The user
 ----------

The user is right. The internal architecture of the application should
not be a reason for the developper not to provide the user with
expected features and the behaviour. In some cases, however, the user
can be badly educated, so he may appear to be wrong. In such cases we
must find a way to make is easy for the user to re-educate.

Do not forget that the user point of view is always the most
important. Most of us are bad users because we know how things are
working under the hood, and we are used no to expect anything from our
applications GUI, because Unix GUIs are such a mess.


  Menu basics
 -------------

Menus must be stable. They must not appear and disappear. If some
items cannot be used in a certain context, they must be dimmed out. If
all items in a menu are dimmed, the menu title must be dimmed, yet
still allow the user to unroll it.

In principle, all menus items which require further information from
the user, and only these, must be followed by ellipsis ("..."). Menu
items which merely prompt for confirmation must not be followed by
ellipsis.

Currently, most user interaction is done in the minibuffer, which is
non-obvious to the casual user, so ALL menu items which require
additional user interaction must be followed by ellipsis. Eventually,
most of the user interactions will have to be done by default in
pop-up, modeless, dialogs.

All menu items must be capitalized in title style. That means that the
first word and the last word are always capitalized. Other words are
also capitalized excepted if they are:

    * articles (a, an, the)
    * coordinating conjunctions (and, or)
    * prepositions of three or fewer letters, except when the
      preposition is part of a verb phrase, as in "Start Up the
      Computer".


  Hierarchical menus
 --------------------

Hierarchical menus are bad, one level of submenu is acceptable but
best avoided, two levels should only be used if no other reasonable
solution can be found. More than two levels of submenus is a bug.

All submenus with only two non-interactive items will be removed and
replaced by toggled menu items.

http://developer.apple.com/techpubs/macosx/Essentials/AquaHIGuidelines/AHIGMenus/index.html

Some additional hierachical menus will be tolerated if the right way
to do it would involve a dialog window, which we cannot afford at the
moment.


  File menu
 ============

Why "revert buffer" instead of just "revert", or "revert to saved"?
That would be easier to translate, and anyway the term "buffer" is
deprecated in the texmacs GUI.

The import and export menus items are only useful if they perform
importation in the current document, or exportation of the current
selection.

The print menu should use a dialog. So we keep on with the same
hierarchic menu.

There should be a "Page Setup..." menu items allowing to configure
page parameters through a dialog. Instead we would use a hierarchical
menu with items taken from the Settings and Document menu hierarchies.
The "Page Setup" items set the page size and margins.

  -- "Document->page->size" should be moved to "File->Page
      Setup->Size" and keeped as is.

  -- "Document->page->orientation" should become a toggled menu item
     associated to the actions "Use Landscape Orientation" (initially)
     and "Use Portrait Orientation" (when the current orientation is
     landscape).

  -- "Document->page->layout" should be replace by two items in the
     "Page Setup" submenu. "Customize margins" would allow the user to
     set the left, right, top and bottom margins, and "Restore
     margins" would revert to the built-in default. If margins have no
     been customized, the "Restore Default Margins" item must be dimmed.

     WARNING: the "Document->page->layout->set margins" is broken,
       since it sets the "page right margin" which is no longer
       meaningful. Instead it should set the "paragraph width" by
       substracting the requested left and right margins from the page
       width.

  -- The predefined paper types should use a "odd page margin"
     bigger than the "even page margin" if and only if the document is
     being printed recto-verso. We should control this option with
     toggled menu items "Constant Margins" and "Recto-Verso Margins".
     
  -- For the sake of simplicity, I propose we do not allow the user to
     use "Recto Verso Margins" with customized values. So, when the
     margins are customized the "Constant/Recto Verso Margins" items
     must be dimmed and the "Constant Margins" item must be checked.
     If the user then decide to "Restore Default Margins", "Constant
     Margins" will be left checked.

The "File->import" menu item is redundant with open. The open dialog
should provide a popup menu to allow choosing between TeXmacs format
(.tm .ts .tp), LaTeX (.ltx .tex), HTML (.htm .html), verbatim or
scheme; and the "File->import" item should be removed.

Moreover, there is still a bug around regarding the autosaving of
imported documents, but that is irrelevant to menus.

"File->export->postcript" is redundand with "File->print->print all to
file" and should be removed.

The "File->export" submenu should be moved to the "Export" dialog in
the form of a pop-up menu.


Proposed layout:
----------------

  File              File->Page Setup
    New               Size >                      
    Open...         x Portrait 
    --                Landscape
    Close             --
    Save            x Constant Margins
    Save as...        Recto Verso Margins
    Export...         --
    Revert            Customize Margins...
    --                Restore Default Margins
    Page Setup >      
    Print      >
    --
    Quit
    

Edit menu:
==========

First, a bit of terminology. Xlib has brain damaged terminology
regarding copy and paste. What Xlib calls the "selection", is the
"clipboard" to the rest of the world. For the civilized world (not
Xlib) the selection is only what emacs calls the "region".

"Undo" and "Redo" are universally the first items of the "Edit" menu.
It should be so in TeXmacs too.

Clear is broken. In any sane application "Edit->clear" removes the
contents of the selection without putting a copy of it in the
clipboard (as opposed to Cut, which removes the contents of the
selection and put a copy of it in the clipboard). In TeXmacs, "clear"
only clears the clipbord, which is an action I see no use for. So,
"Clear" must be fixed to properly clear the selection without
affecting the clipboard.

Also, the "Edit->clear selection" submenu must be removed.

The two menus "Tools->selection->import" and
"Tools->selection->export" should be moved back to the Edit menu where
they really belong and be renamed "Pasting imports >" and "Copying
exports >". This phrasing make it clear that these menu are only meant
to change the behaviour of the copy and paste command when relating to
external applications.

The "cancel" command is not really an edition command, and its
presence in the Edit menu is absolutely not informative. Emacs users
instinctively use C-g when they want cancel. Other users may use
various tricks. I guess all non-emacs user get out of incremental
search by moving the caret (either by clicking or with the arrows).

For the cancel command to be of any use, it must be extended with the
name of the action to cancel (e.g. "Cancel Search" or "Cancel
Customize Margins"). Actually, I think that "Interrupt" would be much
more meaningful.

"Spell" is a bit a shorthand. "Spell Check..." is much more
informative.

Questions: What is the use of Edit->move?


Proposed layout:

  Edit
    Undo
    Redo
    --
    Cut
    Copy
    Paste
    Clear
    --
    Interrupt
    --
    Search...
    Replace...
    Spell Check...
    --
    Pasting Imports >
    Copying Exports >
    --
    Cut To          >
    Copy To         >
    Paste From      >
    


Insert menu:
============

This menu should be broken in three separate menus: Structure, Math,
and Insert.

Structure and Mathematics menus should have the contents of the first part of
the current Insert menu, respectively in text and math modes. From now
on, we will talk of those menu items as the contents of the Structure
and Math menus.

Items of "Structure->mathematics" should be moved as the first
top-level group of the Mathematics menu. These items should be enable
only when the cursor is in a text context. Other items of the
Mathematics menus should be enabled only in a mathematic context.

The item "Structure->Description" must not be hierarchic when it
contains only one item.

The Mathematics->symbols menus are three levels deep, but since I
think everybody in his right mind use the toolbar menus or the
keybinding to insert those, we can make an exception.

The transient Table menu should be made permanent. The contents of the
Structure->table and Mathematics->table menus should be moved as the
first groups of the Table menus. The enable state of the items of the
Table menu should match their current visible state.

The submenu Insert->image should be moved to the Structure menu. Its
items should be made permanent. Of course the "Small Figure" and "Big
Figure" items should only be enable in text context.

The submenu "Insert->page insertion" should be moved to the Structure
menu and enabled only in text context.

Menus items relating to vertical space insertion and indentation flags
should be moved to the Paragraph menu since they only work on
paragraph blocks. Menus items from "Insert->space" not related to
vertical spaces should be moved to the top-level of the Insert menu.

Header and footer insertion commands should be moved out of the
Document->page menu and to the Insert menu.

The submenus "citation", "index entry" and "glossary entry" of the
"Insert->link" submenus must be moved to the "Structure" menu, since
they are only relevant in text context.

The items of "Insert->executable" must be moved in a new group at the
top-level of the "Insert" menu. The submenu
"Insert->executable->programming" has a too generic name, "Control"
(as in flow control, or execution control) would be a better name.

Structure
  Section        >
  Environment    >
  Automatic      >
  Session        >
  --
  Itemize        >
  Enumerate      >
  Description
  --
  Citation       >
  Index Entry    >
  Glossary Entry >
  --
  Image          >
  Page Insertion >


Mathematics
  Formula
  Equation
  Equations
  Numbered Equations
  --
  Fraction
  Square Root
  N-th Root
  Negation
  Tree
  Text
  --
  Script       >
  Accent Above >
  Accent Below >
  Symbol       >

Insert
  Rigid Space
  Horizontal Space
  Break             >
  Header and Footer >
  ---
  Link              >
  Switch            >
  Specific          >
  Special           >
  ---
  Arithmetic        >
  Text              >
  Tuple             >
  Condition         >
  Control           >

Insert->Header and Footer
  This Page Header
  This Page Footer
  --
  Permanent Header
  Permanent Footer
  --
  Odd Page Header
  Odd Page Footer
  Even Page Header
  Even Page Footer
  --
  Odd Page Text
  Even Page Text


  Paragraph Menu
 ================

Indentation switches like "disable/enable indentation before/after"
should be made more smart. For example, in normal mode, they should
insert a tag at the beginning (ident. before) or a the end (indent.
after) of the current paragraph. Before displaying the menu texmacs
should check the current environment and the tags in the current
paragraph to display the appropriate "disable/enable" prefix.


  And so on...
 ==============

I am a bit tired to make this long enumeration. There would still have
a lot of things to change in the other menus, but I think I already
gave the idea of it.

Most of it is only moving menus around and renaming them, but there is
also a need for some support from the editor, esp. regarding Insert
cammands which should be moved to Paragraph.

I strongly believe we can avoid almost all hierachical menus of more
than just one level of depth. However the introduction of the
Structure, Mathematics and Table menus may make us lack some room.
Maybe we could get some room back by scaterring the items of the
Settings menu in the appropriate semantic categories, or all in the
Edit menu where the Preference menu item (displaying a dialog) should
be.

-- 

                             -- David --