X-Git-Url: https://code.delx.au/offlineimap/blobdiff_plain/612e89964f0344744a54ca6bae244cd7675bafb4..d1f5a2827735771dc4d37e9ad22512f4ff0694ed:/offlineimap.sgml

diff --git a/offlineimap.sgml b/offlineimap.sgml
index 960a01a..e164735 100644
--- a/offlineimap.sgml
+++ b/offlineimap.sgml
@@ -32,6 +32,8 @@
 	<arg>-a <replaceable>accountlist</replaceable></arg>
 	<arg>-c <replaceable>configfile</replaceable></arg>
 	<arg>-d <replaceable>debugtype[,...]</replaceable></arg>
+        <arg>-f <replaceable>foldername[,...]</replaceable></arg>
+        <arg>-k <replaceable>[section:]option=value</replaceable></arg>
 	<arg>-l <replaceable>filename</replaceable></arg>
 	<arg>-o</arg>
 	<arg>-u <replaceable>interface</replaceable></arg>
@@ -204,18 +206,19 @@ remoteuser = jgoerzen
 	      and corporate networks do, and most operating systems
 	      have an IMAP
 	      implementation readily available.
+              A special <property>Gmail</property> mailbox type is
+              available to interface with Gmail's IMAP front-end.
 	    </para>
 	  </listitem>
 	  <listitem>
 	    <para>
-	      You must have Python version 2.2.1 or above installed.
+	      You must have Python version 2.4 or above installed.
 	      If you are
 	      running on Debian GNU/Linux, this requirement will automatically be
 	      taken care of for you.  If you do not have Python already, check with
 	      your system administrator or operating system vendor; or, download it from
 	      <ulink url="http://www.python.org/">the Python website</ulink>.
-	      If you intend to use the Tk interface, you must have Tkinter
-		(python-tk) installed.  If you intend to use the SSL interface, your
+		If you intend to use the SSL interface, your
 		Python must have been built with SSL support.
 	    </para>
 	  </listitem>
@@ -231,6 +234,7 @@ remoteuser = jgoerzen
 	      IMAP server and point both &OfflineIMAP; and your mail
 	      reader at it.
 	    </para>
+	  </listitem>
 	</itemizedlist>
       </refsect2>
 
@@ -373,6 +377,26 @@ cd offlineimap-x.y.z</ProgramListing>
 	      will debug the threading model.
 	    </para></listitem>
 	  </varlistentry>
+        <varlistentry><term>-f <replaceable>foldername</replaceable>[,<replaceable>foldername</replaceable>]</term>
+          <listitem><para> Only sync the specified folders.  The
+              <replaceable>foldername</replaceable>s are the
+              untranslated foldernames.  This command-line option
+              overrides any <property>folderfilter</property>
+              and <property>folderincludes</property> options in the
+              configuration file.
+          </para></listitem>
+        </varlistentry>
+        <varlistentry><term>-k [<replaceable>section</replaceable>:]<replaceable>option</replaceable>=<replaceable>value</replaceable>
+          </term>
+          <listitem><para> Override configuration file option.  If
+              "section" is omitted, it defaults
+              to <property>general</property>.  Any underscores "_" in
+              the section name are replaced with spaces: for instance,
+              to override option <property>autorefresh</property> in
+              the "[Account Personal]" section in the config file one
+              would use "-k Account_Personal:autorefresh=30".
+          </para></listitem>
+        </varlistentry>
 	  <varlistentry><term>-l
 	  <replaceable>filename</replaceable></term>
 	    <listitem><para>
@@ -389,6 +413,11 @@ cd offlineimap-x.y.z</ProgramListing>
 	      file.</para>
 	    </listitem>
 	  </varlistentry>
+	  <varlistentry><term>-q</term>
+	    <listitem><para>Run only quick synchronizations.   Ignore any flag
+              updates on IMAP servers.</para>
+	    </listitem>
+	  </varlistentry>
 	  <varlistentry><term>-h</term> <term>--help</term>
 	    <listitem><para>Show summary of options.</para></listitem>
 	  </varlistentry>
@@ -412,27 +441,22 @@ cd offlineimap-x.y.z</ProgramListing>
 	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>Tk.Blinkenlights is an interface designed to be sleek, fun to watch, and
+	<title>Curses.Blinkenlights</title>
+	<para>
+                Curses.Blinkenlights 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
+	  Curses.Blinkenlights contains a row of
+          "LEDs" with command buttons and a log.
+	  The  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;
@@ -538,32 +562,6 @@ cd offlineimap-x.y.z</ProgramListing>
 	</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>
-	  Tk.VerboseUI (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>
@@ -598,6 +596,15 @@ cd offlineimap-x.y.z</ProgramListing>
 	</para>
       </refsect2>
 
+      <refsect2>
+        <title>Machine.MachineUI</title>
+        <para>
+           Machine.MachineUI generates output in a machine-parsable format.
+           It is designed for other programs that will interface
+           to OfflineIMAP.
+        </para>
+      </refsect2>
+
     </refsect1>
 
     <refsect1>
@@ -694,7 +701,7 @@ holdconnectionopen = no</programlisting>
 	  is based on one supplied by Tommi Virtanen for this feature.
 	</para>
 	<para>
-	  In <filename>~/.offlineimap.rc</filename>, he adds these options:
+	  In <filename>~/.offlineimaprc</filename>, he adds these options:
 	</para>
 	<programlisting>[general]
 pythonfile=~/.offlineimap.py
@@ -731,6 +738,24 @@ def test_mycmp():
 	</para>
       </refsect2>
     </refsect1>
+
+    <refsect1>
+            <title>Signals</title>
+            <para>
+                    OfflineIMAP writes its current PID into
+                    <filename>~/.offlineimap/pid</filename> when it is
+                    running.  It is not guaranteed that this file will
+                    not exist when OfflineIMAP is not running.
+            </para>
+            <!-- not done yet 
+            <para>
+                    You can send SIGINT to OfflineIMAP using this file to
+                    kill it.  SIGUSR1 will force an immediate resync of
+                    all accounts.  This will be ignored for all accounts
+                    for which a resync is already in progress.
+            </para>
+            -->
+    </refsect1>
       
     <refsect1>
       <title>Errors</title>
@@ -766,11 +791,11 @@ def test_mycmp():
 	</para>
 
 	<programlisting>rm -r ~/Folders/INBOX
-rm -r ~/.offlineimap/Account-<replaceable>AccountName</>
-rm -r ~/.offlineimap/Repository-<replaceable>RepositoryName</></programlisting>
+rm -r ~/.offlineimap/Account-<replaceable>AccountName</>/LocalStatus/INBOX
+rm -r ~/.offlineimap/Repository-<replaceable>RemoteRepositoryName</>/FolderValidity/INBOX</programlisting>
 
 	<para>
-	  (Of course, replace AccountName and RepositoryName 
+	  (Of course, replace AccountName and RemoteRepositoryName 
 	  with the names as specified
 	  in <filename>~/.offlineimaprc</filename>).
 	</para>
@@ -827,7 +852,7 @@ rm -r ~/.offlineimap/Repository-<replaceable>RepositoryName</></programlisting>
 	  this as an intentional deletion of many messages and will interpret
 	  your action as requesting them to be deleted from the server as well.
 	  (If you don't understand this, don't worry; you probably won't
-	  encounter this situation)
+	  encounter this situation.)
 	</para>
       </refsect2>
 
@@ -836,8 +861,8 @@ rm -r ~/.offlineimap/Repository-<replaceable>RepositoryName</></programlisting>
 	<para>&OfflineIMAP; is not designed to have several instances (for instance, a cron job and an interactive invocation) run over the same
 	  mailbox simultaneously.  It will perform a check on startup and
 	  abort if another &OfflineIMAP; is already running.  If you need
-	  to schedule synchronizations, please use the
-	  <property>autorefresh</property> settings rather than cron.
+	  to schedule synchronizations, you'll probably find
+	  <property>autorefresh</property> settings more convenient than cron.
 	  Alternatively, you can set a separate <property>metadata</property>
 	  directory for each instance.
 	</para>
@@ -873,9 +898,10 @@ rm -r ~/.offlineimap/Repository-<replaceable>RepositoryName</></programlisting>
 
       <refsect2>
 	<title>Bugs</title>
-	<para>Reports of bugs should be sent via e-mail to the
-	  &OfflineIMAP; mailing list at offlineimap at complete
-          dot org.  Debian users are encouraged to instead use the
+	<para>
+          Reports of bugs should be reported online at the
+          &OfflineIMAP; homepage.
+          Debian users are encouraged to instead use the
 	Debian
           bug-tracking system.
 	</para>
@@ -960,14 +986,6 @@ rm -r ~/.offlineimap/Repository-<replaceable>RepositoryName</></programlisting>
 	<ulink url="http://software.complete.org/offlineimap">homepage</ulink>.
       </para>
 
-      <para>
-	&OfflineIMAP; may also be downloaded using Subversion.  Additionally,
-	the distributed tar.gz may be updated with a simple "svn update"
-	command; it is ready to go.  For information on getting OfflineIMAP
-	with Subversion, please visit the
-	<ulink url="http://svn.complete.org/">complete.org Subversion page</ulink>.
-      </para>
-
     </refsect1>
 
     <refsect1>