[HIG] "Desktop Integration" section for the mini-HIG

[Seth Nickell <snickell stanford edu>]

I just wrote a section on desktop integration that I'd like to have
added to the mini-HIG. It covers adding panel menu entries and
registering applications with the MIME database (probably the two most
basic tasks for integrating an application with the rest of GNOME). I
think this is useful for the mini-HIG particularly in light of Nils'
restructuring of the Panel menus. 

It sheds light on the general principals he uses, and hopefully will
prevent the restructured menus from going to hell as quickly once
application developers start adding their own applications (he only did
the restructure for the basic applications installed on Solaris GNOME).

I've attached a patch to the docbook source, but if you'd prefer you can
read the section at:

http://beauty.stanford.edu/hig/desktop-integration.html

Any broad objections to me checking this in? (presumably it would be
revised with the other content at the thursday pow-wow if people have
any objections about specific points)

cheers,

-Seth


? desktop_integration_patch
? docbook2html-dir
? hig_cb.log
? hig_draft1
? hig_draft1.junk
? images/.xvpics
? images/fontsel-suggestion.png
Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/web-devel-2/content/projects/gup/hig/ChangeLog,v
retrieving revision 1.13
diff -u -p -r1.13 ChangeLog
--- ChangeLog	2001/10/08 04:12:07	1.13
+++ ChangeLog	2001/10/08 08:05:20
@@ -1,3 +1,19 @@
+2001-10-08  Seth Nickell  <snickell stanford edu>
+
+	* hig_draft1.sgml:
+
+	Add a section on integrating your application with the desktop environment.
+	
+	* images/abiword-icon.png:
+	* images/evolution-icon.png:
+	* images/fontsel-icon.png:
+	* images/gedit-icon.png:
+	* images/log-icon.png:
+	* images/nautilus-icon.png:
+	* images/shutdown-icon.png:
+
+	Add images linked in the section.
+
 2001-10-07  Gregory Leblanc  <gleblanc linuxweasel com>
 
 	* hig_draft1.sgml: Made this valid SGML, and added a few, slightly
Index: hig_draft1.sgml
===================================================================
RCS file: /cvs/gnome/web-devel-2/content/projects/gup/hig/hig_draft1.sgml,v
retrieving revision 1.3
diff -u -p -r1.3 hig_draft1.sgml
--- hig_draft1.sgml	2001/10/08 04:12:07	1.3
+++ hig_draft1.sgml	2001/10/08 08:05:21
@@ -1560,6 +1560,285 @@ your application respects the settings.<
     
   </sect1>
   
+  <sect1 id="desktop-integration">
+
+    <title>Integrating Applications with the Desktop</title>
+    <para>Basic integration with the user environment of the GNOME Desktop requires two general steps. First, applications should place an entry in the panel menu. This is the mechanism by which users discover your application in order to execute it. Secondly, your application should add itself to the application registry, and if it supports any documents add those to the document type (MIME) registry. This allows the desktop and other applications to automatically launch your application when they encounter a document it can display or edit, forming a more document centered interface.</para>
+    <sect2 id="menuentries">
+      <title>Placing Entries in the Panel Menu</title>
+
+      <para>Applications should place entries in the GNOME panel menu. The panel menu provides a convenient way for users to survey the available applications and select one to perform their next task. </para>
+      <para>The panel menu is arranged into a set of broad categories, an application should place an entry in one of these categories. Creation of new categories should be done cautiously to avoid the confusing proliferation of menu items, and should be discussed with the community first. The temptation to over-estimate the importance of your application to users could easily lead to the justification for creating a new category. Just remember that users would probably rather have a simple menu system than to have your one application in a precisely defined category.</para>
+      <para>Menu categories are:
+	<itemizedlist>
+	  <listitem><para>Internet</para></listitem>
+	  <listitem><para>Multimedia</para></listitem>
+	  <listitem><para>Productivity</para></listitem>
+	  <listitem><para>Graphics</para></listitem>
+	  <listitem><para>Utilities</para></listitem>
+	  <listitem><para>Development Tools</para></listitem>
+	  <listitem><para>Games</para></listitem>
+	  <listitem><para>System</para></listitem>
+	</itemizedlist>
+      </para>
+      <sect3 id="menu-entry-icons">
+        <title>Menu Entry Icons</title>
+	<para>Icons assist the user in rapidly scanning a large number of entries and choosing the correct one. They are easier to identify quickly, particularly after becoming accostumed to the icon's appearance, than text labelling. Additionally, icons can assist the text in communicating the purpose of the program (by providing visual suggestions to accompany the descriptive text). Good icons suggest to the user the sort of application they are associated with. Icons are fundamentally about metaphor, presenting a visual image that the user associates with a particular aspect of functionality.</para>
+	<tip><title>Rule of Thumb for Icon Metaphors</title><para>"If you have to think about an icon to understand it, the metaphor is too complex"</para></tip>
+	<para><emphasis role="bold">Icons tend to fall into one of three categories</emphasis></para>
+	<itemizedlist>
+	    <listitem><para><emphasis role="bold">Functionally Suggestive Icons</emphasis></para>
+	    <para>Icons should be, if possible, suggestive of the functionality of the program. The best icon will suggest to the user the primary purpose of the program without having to read the accompanying catpion.</para>
+	    <figure>
+	      <title>A functionally suggestive icon for a word processor (AbiWord)</title>
+	      <mediaobject><imageobject>
+		  <imagedata fileref="images/abiword-icon.png" format="PNG">
+		</imageobject>
+		<textobject>
+		  <phrase>The AbiWord icon</phrase>
+		</textobject>
+	      </mediaobject>
+	    </figure>
+	  </listitem>
+	  <listitem><para><emphasis role="bold">Name Suggestive Icons</emphasis>
+	    <para>Some icons, such as the Nautilus icon, do not suggest the program's purpose, but instead suggest the program's name. This is less desirable than a functionally suggestive icon, because an extra layer of abstraction is added (rather than associating file management with an icon representing files, they have to represent file management with nautilus with an image of a nautilus shell). Additionally it makes it difficult for new users because, for example, may not know what "Nautilus" is, and hence will not look for a shell when they want to manage files.</para>
+	    <figure>
+	      <title>A name suggestive icon for Nautilus</title>
+	      <mediaobject><imageobject>
+		  <imagedata fileref="images/nautilus-icon.png" format="PNG">
+		</imageobject>
+		<textobject>
+		  <phrase>A picture of a nautilus shell</phrase>
+		</textobject>
+	      </mediaobject>
+	    </figure>
+	  </listitem>
+	    <listitem><para><emphasis role="bold">"Text Icons"</emphasis></para>
+	    <para>Icons which contain the text of the program name in the icon. They effectively contain no metaphor or picture for the user to identify with, and are probably harder to read than the accompanying caption. Since icons draw the eyes, an icon that is harder to identify than text is potentially worse than no icon at all. Hence "text icons" should not be used.</para>
+	    <figure>
+	      <title>A "text icon" for GEdit</title>
+	      <mediaobject><imageobject>
+		  <imagedata fileref="images/gedit-icon.png" format="PNG">
+		</imageobject>
+		<textobject>
+		  <phrase>The GEdit icon</phrase>
+		</textobject>
+	      </mediaobject>
+	    </figure>
+	  </listitem>
+	</itemizedlist>
+	<para>If at all possible, a functionally suggestive icon should be used. Failing that a name suggestive icon is appropriate. "Text Icons" or other desperate substitutes should not be used.</para>
+	<para><emphasis role="bold">Icon Problems to Avoid</emphasis></para>
+	<itemizedlist>
+	  <listitem><para><emphasis role="bold">Excessive information</emphasis></para>
+	    <para>Remember that icons will often be viewed in a smaller form. Too much information may render the icon unintelligable when it is shrunk in size (e.g. to be placed on a panel, or in the tasklist). Also, too much information makes it easier to confuse the purpose of the application. For example, in user testing many users thought the Evolution icon would launch a word processor. They were thrown off by the pencil and the paper, which could be seen as extraneous information; it is implicit that the mail program will allow you to write messages as well as receive them. A better icon might have been a simple envelope. Foremost in the icon designer's mind should be a consideration of the minimal visual element necessary to differentiate the purpose of the program from other programs/icons.</para>
+	    <figure>
+	      <title>The Evolution icon</title>
+	      <mediaobject><imageobject>
+		  <imagedata fileref="images/evolution-icon.png" format="PNG">
+		</imageobject>
+		<textobject>
+		  <phrase>The Evolution icon</phrase>
+		</textobject>
+	      </mediaobject>
+	    </figure>
+	  </listitem>
+	  <listitem><para><emphasis role="bold">Use of body parts</emphasis></para>
+	    <para> Because GNOME aims to be an international desktop, it needs to avoid imagery that is potentially offensive or crass imagery to other cultures. A prime source of offensive imagery is various body parts in a number of different configurations. Aside from offensive gestures with the hands, arms or fingers; body parts that are considered "clean" in one culture (such as eyes), will be considered tasteless or gross to another (such as a nose). Based on a survey of icons in GNOME, body parts frequently appear in the least communicative icons (often "pointing" at some element in the icon); they are being used as a largely ineffective crutch for poor metaphors. In these situations body parts should certainely not be used. In situations where the metaphor is appropriate (for example an eye representing the sawfish appearance capplet) it is probably still best to avoid using a body part in order to avoid possible offense. Often body parts have been used in GNOME to suggest!
 a human "choosing" or "using" something. In general this is an unnecessary point to make, people will instinctively associate themselves as using the object in question. For example, the font selector shows a finger pointing to an "F" suggesting the user choosing between a series of fonts. A better icon would be the text "Aa" done in an ornate font. The user doesn't need to be told that they are "choosing" the font, they can infer that easily.</para>
+	    <figure>
+	      <title>The font selector icon and a simple potential replacement</title>
+	      <mediaobject><imageobject>
+		  <imagedata fileref="images/fontsel-icon.png" format="PNG">
+		</imageobject>
+		<textobject>
+		  <phrase>The Font Selector Icon</phrase>
+		</textobject>
+	      </mediaobject>
+	      <mediaobject><imageobject>
+		  <imagedata fileref="images/fontsel-suggestion.png" format="PNG">
+		</imageobject>
+		<textobject>
+		  <phrase>A Simple Replacement Icon showing an ornate "Aa"</phrase>
+		</textobject>
+	      </mediaobject>
+	      </figure>	    
+	  </listitem>
+	  <listitem><para><emphasis role="bold">Icons based off word games</emphasis></para>
+	    <para>These should be avoided for a couple reasons. The most obvious is that they do not translate well. For example, representing the "system log monitor" as a log will likely be uncommunicative in languages other than English. Additionally, most users do not understand the word play until it is too late for the icon to assist them. Even after being familiar with the "system log monitor" being represented as a log, users do not form the association fast enough for the icon to assist through in scanning through menu entries. A popular instance of this problem was in proliferation of icons representing the "World Wide Web" as a spider web in the mid 1990s. Part of the value of icons is that they bypass linguistic comprehension and hence are complementary to captions, allowing users to utilize more areas of comprehension than words when they hunt for items.</para>
+	      <figure>
+	      <title>System Log Monitor Icon</title>
+	      <mediaobject><imageobject>
+		  <imagedata fileref="images/log-icon.png" format="PNG">
+		</imageobject>
+		<textobject>
+		  <phrase>A tree log</phrase>
+		</textobject>
+	      </mediaobject>
+	    </figure>	    
+	  </listitem>
+	  <listitem><para><emphasis role="bold">Violent Imagery</emphasis></para>
+	    <para>Just as words like "kill" and "slay" are inappropriate in interfaces, violent or destructive icons should be avoided. The "shut down" icon uses the image of an explosive detonation switch, presumably trying to convey the idea of ending something abruptly. However, this icon is likely to intimidate many users of the computer who will not want to click on the icon for fear of breaking something.</para>
+	    <figure>
+	      <title>Destructive looking Shutdown Icon</title>
+	      <mediaobject><imageobject>
+		  <imagedata fileref="images/shutdown-icon.png" format="PNG">
+		</imageobject>
+		<textobject>
+		  <phrase>An explosive detonation button</phrase>
+		</textobject>
+	      </mediaobject>
+	    </figure>	    
+	  </listitem>
+	</itemizedlist>
+      </sect3>
+      <sect3 id="menu-entry-captions">
+        <title>Menu Entry Captions</title>
+	<para>Menu entries require captions (or "names") to textually describe the application. If an application falls into a general class of applications (for example, "Email Client" or "Word Processor") they should follow the format <emphasis>APPLICATION TYPE (APPLICATION NAME)</emphasis>. Rather than focusing on branding the menu system tries to encourage listing based on functionality. Users are more likely to be able to discover your application when they need it if it is listed by functionality rather than by name. This is particularly important on systems where numerous applications are installed by default, so the user is less aware of the mapping between names and functionality. Try to think of what information users will have when they look for your application when choosing a general class, and try to copy similar applications if they have already chosen a general class.</para>
+	<para>In user testing of MIT's Athena system, users had a difficult time finding the file manager because they had never heard the name Nautilus before, and hence did not register the word when they looked for an application to fufill the concept "file manager". Unless the name of the program is very obvious (for example, "Font Selector"), it is preferable to describe the application in the caption by functionality rather than by name. The application name is retained both because it is important to give specific instances recognition, and because it clarifies the situation where multiple applications are installed filling the same general purpose.</para>
+	<itemizedlist>
+	  <listitem>
+	    <example>
+	      <title>A caption for Nautilus</title>
+	      <para>File Manager (Nautilus)</para>
+	    </example>
+	  </listitem>
+	  <listitem>
+	    <example>
+	      <title>A caption for the GIMP</title>
+	      <para>Image Editor (GIMP)</para>
+	    </example>
+	  </listitem>
+	  <listitem>
+	    <example>
+	      <title>A caption for GnomeMines</title>
+	      <para>Minesweeper (GnomeMines)</para>
+	    </example>
+	  </listitem>
+	</itemizedlist>
+	
+	<para>If no appropriate general class exists, applications may reasonably follow the format <emphasis>APPLICATION NAME</emphasis>. It is important to apply common sense in choosing which format to use. While it is generally preferable to list a general class, do not try to force a class where the information is not useful to the user. For example, listing all the entries in the Games section as <emphasis>Game (GAME NAME)</emphasis> is awkward and also redundant since the category they are contained in is already labled as Games.</para>
+	<tip>
+	  <para>If you can think of another application that could be viewed as a competitor to your application (if not in number of features or quality at least in general area of use), your application probably belongs to some general class and should use the first format.</para>
+	</tip>
+	
+	<itemizedlist>
+	  <listitem>
+	    <example>
+	      <title>A caption for AisleRiot</title>
+	      <para>Aisle Riot</para>
+	    </example>
+	  </listitem>
+	  <listitem>
+	    <example>
+	      <title>A caption for Time Tracking Tool</title>
+	      <para>Time Tracking Tool</para>
+	    </example>
+	  </listitem>
+	</itemizedlist>
+	<para>If possible, it is better to remove explicit mention of GNOME or X-Windows or other platform details from menu entry captions. The user probably already knows what platform they are using, and if they don't, application names aren't the right place to inform them. Menu captions are there to assist in finding the correct application to accomplish the user's tasks and should not burden them with technical details, especially when they are implicit from context. Other technical details should also be avoided when the user does not need to know them or can infer them from context. For example, when both a client and a server for something are listed in the menus, drop the word "Client" from the caption for the client. Try not to clutter titles with unnecessary information, but be sure to retain enough information that similar applications are distinct from eachother.</para>
+	<itemizedlist>
+	  <listitem>
+	    <example>
+	      <title>A caption for Same Gnome</title>
+	      <para>Same Game</para>
+	    </example>
+	  </listitem>
+	  <listitem>
+	    <example>
+	      <title>A caption for GNOME VideoLAN Client</title>
+	      <para>Movie Player (VideoLAN)</para>
+	    </example>
+	  </listitem>
+	</itemizedlist>
+      </sect3>
+      <sect3 id="menu-entry-tooltips">
+	<title>Menu Entry Tooltips</title>
+	<para>Tooltips should be provided to give the user some information on the tasks they can perform with the tool. Tooltips should not be overly verbose, but should go beyond the simple description given by the caption to help users decide if a given entry is really the application they want. Users often view tooltips when they suspect they have found the right tool for a job, but aren't entirely sure and want more confirmation before they begin the potentially slow operation of launching the program. Because they describe the user actions to be performed with the tool, tooltips should usually be phrased in verb form. It is particularly important to have a good tooltip when a short functional description isn't found, or when the <emphasis>APPLICATION NAME</emphasis> form of caption is used (and hence little information is provided to the user about the application in the caption).</para>
+	<itemizedlist>
+	  <listitem>
+	    <example>
+	      <title>A tooltip for Character Map</title>
+	      <para>Insert special characters into documents</para>
+	    </example>
+	  </listitem>
+	  <listitem>
+	    <example>
+	      <title>A tooltip for Memprof</title>
+	      <para>Check your application for memory leaks</para>
+	    </example>
+	  </listitem>
+	  <listitem>
+	    <example>
+	      <title>A tooltip for Same Gnome</title>
+	      <para>Arrange long chains of similarly coloured balls up and eliminate them</para>
+	    </example>
+	  </listitem>
+	  <listitem>
+	    <example>
+	      <title>A tooltip for Gnome Batalla Naval Client</title>
+	      <para>Find and sink enemy ships in this networked rendition of Battleship</para>
+	    </example>
+	  </listitem>
+	</itemizedlist>
+      </sect3>
+    </sect2>
+
+    <sect2 id="mimedatabase">
+      <title>Providing a Connection between Documents & Applications</title>
+
+      <para>The Application & MIME database provides a mapping between document types (as defined by their MIME type) and applications. This is the mechanism by which Nautilus, Evolution and other applications decide what to launch when they encounter a document of a type they cannot handle. Users can edit the association between types & applications in the "File Types & Applications" capplet in the Control Center. Upon installation applications should associate themselves with any types they can handle, registering those types as necessary if they are not already present on the system. Technical details on performing this operation or other operations on the MIME database described in this section should be consulted in the <ulink url="http://developer.gnome.org/doc/API/gnome-vfs";><citetitle>GnomeVFS API reference</citetitle></ulink>.</para>
+      <para>The preferred list for a particular document type defines applications which are considered first class handlers for that data type. The decision whether to appear in the preferred list or not is left to the discretion of the application developer, but you should generally only list your application in the preferred list if you think a majority of users manipulating that document will want to see your application in the <guimenu>Open With...</guimenu> menu in Nautilus. For example, while a text editor such as GEdit may be capable of editing all files of type text/*, it probably should not add itself to the preferred list for files of type text/html. While it is <emphasis>capable</emphasis> of editing and viewing these files, users will generally not prefer GEdit for HTML files. On the other hand, GEdit should register itself as being capable of handling these files, so if some user wishes to frequently use it to edit HTML files it is easy for them to add GEdit t!
o the preferred list.</para>
+      <para>To provide a connection to document types an application should:
+	<itemizedlist>
+	  <listitem><para>Install a <filename>.applications</filename> file in <filename>$PREFIX/share/application-registry</filename> describing the abilities of your application.</para>
+	    <example>
+	      <title>A mozilla.applications file for Mozilla</title>
+	      <programlisting>
+mozilla
+        command=mozilla
+        name=Mozilla
+        can_open_multiple_files=true
+        expects_uris=true
+        requires_terminal=false
+        supported_uri_schemes=file,http,ftp,telnet,gopher
+        mime_types=text/html,text/mathml,x-directory/webdav,x-directory/webdav-prefer-directory,image/gif,image/jpeg,text/xml,text/*
+	      </programlisting>
+	    </example>
+	  </listitem>
+	  <listitem><para>Install a <filename>.mime</filename> file in <filename>$PREFIX/share/mime-info</filename> describing the MIME types you can handle.</para>
+	    <example>
+	      <title>Part of a mozilla.mime file for Mozilla</title>
+	      <programlisting>
+text/html
+        ext: html htm HTML
+text/xml
+        ext: xml
+image/jpeg
+        ext: jpe jpeg jpg
+	      </programlisting>
+	      </example>
+	  </listitem>
+	  <listitem><para>Install a <filename>.keys</filename> file in <filename>$PREFIX/share/mime-info</filename> describing the MIME types you handle in greater detail (optional). Also install a default icon for any new filetypes you add.</para>
+	    <example>
+	      <title>One entry in a mozilla.keys file for Mozilla</title>
+	      <programlisting>
+text/mathml
+        description=MathML document
+           ...
+        [es]description=documento de MathML
+	   ...
+	icon_filename=mathml.png
+	default_action_type=application
+	short_list_application_ids_for_novice_user_level=mozilla
+	short_list_application_ids_for_intermediate_user_level=mozilla
+	short_list_application_ids_for_advanced_user_level=mozilla
+	      </programlisting>
+	    </example>
+	  </listitem>
+	</itemizedlist>
+      </para>
+    </sect2>
+  </sect1>
 
   <sect1 id="terminology">