rev 341 - offlineimap/head

Author: jgoerzen
Date: 2003-01-08 08:40:39 -0600 (Wed, 08 Jan 2003)
New Revision: 341

Modified:
   offlineimap/head/offlineimap.sgml
Log:


Modified: offlineimap/head/offlineimap.sgml
==============================================================================
--- offlineimap/head/offlineimap.sgml	(original)
+++ offlineimap/head/offlineimap.sgml	Wed Jan  8 08:40:39 2003
@@ -342,7 +342,224 @@
 	      certain Maildir operations.
 	    </para></listitem>
 	  </varlistentry>
+	  <varlistentry><term>-o</term>
+	    <listitem><para>Run only once, ignoring all
+	      <property>autorefresh</property> settings in the configuration
+	      file.</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term>-h</term> <term>--help</term>
+	    <listitem><para>Show summary of options.</para></listitem>
+	  </varlistentry>
+	  <varlistentry><term>-u <replaceable>interface</replaceable></term>
+	    <listitem><para>Specifies an alternative user interface module
+	      to use.  This overrides the defailt specified in the
+	      configuration file.  The pre-defined options are listed in
+	      the User Interfaces section.</para>
+	    </listitem>
+	  </varlistentry>
       </variablelist>
+    </refsect1>
+    <refsect1>
+      <title>User Interfaces</title>
+      <para>&OfflineIMAP; has a pluggable user interface system that lets you choose how the
+	program communicates information to you.  There are two graphical
+	interfaces, two terminal interfaces, and two noninteractive interfaces
+	suitable for scripting or logging purposes.  The
+	<property>ui</property> option in the configuration file specifies
+	user interface preferences.  The <option>-u</option> command-line
+	option can override the configuration file setting.  The available
+	values for the configuration file or command-line are described
+	in this section.</para>
+      <refsect2>
+	<title>Tk.Blinkenlights</title>
+	<para>This is an interface designed to be sleek, fun to watch, and
+	  informative of the overall picture of what &OfflineIMAP;
+	  is doing.  I consider it to be the best general-purpose interface in
+	  &OfflineIMAP;.
+	</para>
+	<para>
+	  Tk.Blinkenlights contains, by default, a small window with a row of
+	  LEDs, a small log, and a row of command buttons.
+	  The total size of the window is
+	  very small, so it uses little desktop space, yet it is quite
+	  functional.  The optional, toggleable, log shows more
+	  detail about what is happening and is color-coded to match the color
+	  of the lights.
+	</para>
+	<para>
+	  Tk.Blinkenlights is the only user interface that has configurable
+	  parameters; see the example <filename>offlineimap.conf</filename>
+	  for more details.
+	</para>
+	<para>
+	  Each light in the Blinkenlights interface represents a thread
+	  of execution -- that is, a particular task that &OfflineIMAP;
+	  is performing right now.  The colors indicate what task
+	  the particular thread is performing, and are as follows:
+	</para>
+	<variablelist><title>Blinkenlights Colors</title>
+	  <varlistentry>
+	    <term>Black</term>
+	    <para>indicates that this light's thread has terminated; it will light up
+	      again later when new threads start up.  So, black indicates no
+	      activity.
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Red (Meaning 1)</term>
+	    <para>is the color of the main program's thread, which basically does
+	      nothing but monitor the others.  It might remind you of HAL 9000 in
+	      <citation>2001</citation>.
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Gray</term>
+	    <para>indicates that the thread is establishing a new connection to the IMAP
+	      server.
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Purple</term>
+	    <para>is the color of an account synchronization thread that is monitoring
+	      the progress of the folders in that account (not generating any I/O).
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Cyan</term>
+	    <para>indicates that the thread is syncing a folder.
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Green</term>
+	    <para>means that a folder's message list is being loaded.
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Blue</term>
+	    <para>is the color of a message synchronization controller thread.
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Orange</term>
+	    <para>indicates that an actual message is being copied.
+	      (We use fuschia for fake messages.)
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Red (meaning 2)</term>
+	    <para>indicates that a message is being deleted.
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Yellow / bright orange</term>
+	    <para>indicates that message flags are being added.
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Pink / bright red</term>
+	    <para>indicates that message flags are being removed.
+	    </para>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>Red / Black Flashing</term>
+	    <para>corresponds to the countdown timer that runs between
+	      synchronizations.
+	    </para>
+	  </varlistentry>
+	</variablelist>
+	<para>The name of this interfaces derives from a bit of computer
+	  history.  Eric Raymond's <citation>Jargon File</citation> defines
+	  <term>blinkenlights</term>, in part, as:
+	</para>
+	<blockquote>
+	  <para>Front-panel diagnostic
+	    lights on a computer, esp. a dinosaur. Now that dinosaurs are rare,
+	    this term usually refers to status lights on a modem, network hub, or
+	    the like.
+	  </para>
+	  <para>
+	    This term derives from the last word of the famous blackletter-Gothic
+	    sign in mangled pseudo-German that once graced about half the computer
+	    rooms in the English-speaking world. One version ran in its entirety as
+	    follows:
+	  </para>
+	  <para>
+	    <emphasis>ACHTUNG!  ALLES LOOKENSPEEPERS!</emphasis>
+	  </para>
+	  <para>
+	    Das computermachine ist nicht fuer gefingerpoken und mittengrabben.
+	    Ist easy schnappen der springenwerk, blowenfusen und poppencorken
+	    mit spitzensparken.  Ist nicht fuer gewerken bei das dumpkopfen.
+	    Das rubbernecken sichtseeren keepen das cotten-pickenen hans in das
+	    pockets muss; relaxen und watchen das blinkenlichten.
+	  </para>
+	</blockquote>
+      </refsect2>
+
+      <refsect2>
+	<title>Curses.Blinkenlights</title>
+	<para>
+	  Curses.Blinkenlights is an interface very similar to Tk.Blinkenlights,
+	  but is designed to be run in a console window (an xterm, Linux virtual
+	  terminal, etc.)  Since it doesn't have access to graphics, it isn't
+	  quite as pretty, but it still gets the job done.
+	</para>
+	<para>Please see the Tk.Blinkenlights section above for more
+	  information about the colors used in this interface.
+	</para>
+      </refsect2>
+
+      <refsect2>
+	<title>Tk.VerboseUI</title>
+	<para>
+	  This interface (formerly known as Tk.TkUI) is a graphical interface
+	  that presents a variable-sized window.  In the window, each
+	  currently-executing thread has a section where its name and current
+	  status are displayed.  This interface is best suited to people running
+	  on slower connections, as you get a lot of detail, but for fast
+	  connections, the detail may go by too quickly to be useful.  People
+	  with fast connections may wish to use Tk.Blinkenlights instead.
+	</para>
+      </refsect2>
+
+      <refsect2>
+	<title>TTY.TTYUI</title>
+	<para>
+	  This interface is for people running in basic, non-color terminals.  It
+	  prints out basic status messages and is generally friendly to use on a console
+	  or xterm.
+	</para>
+      </refsect2>
+
+      <refsect2>
+	<title>Noninteractive.Basic</title>
+	<para>
+	  This interface is designed for situations in which &OfflineIMAP;
+	  will be run non-attended and the status of its execution will be
+	  logged.  You might use it, for instance, to have the system run
+	  automatically and
+	  e-mail you the results of the synchronization.  This user interface
+	  is not capable of reading a password from the keyboard; account
+	  passwords must be specified using one of the configuration file options.
+	</para>
+      </refsect2>
+
+      <refsect2>
+	<title>Noninteractive.Quiet</title>
+	<para>
+	  This interface is designed for non-attended running in situations
+	  where normal status messages are not desired.  It will output nothing
+	  except errors and serious warnings.  Like Noninteractive.Basic,
+	  this user interface
+	  is not capable of reading a password from the keyboard; account
+	  passwords must be specified using one of the configuration file options.
+	</para>
+      </refsect2>
+
+    </refsect1>
+
+
     <refsect1>
       <title>See Also</title>
       <para>This is also a test.  Foo bar.</para>