Rework threadutil to use Queue for simplification and power-friendliness

[offlineimap] / offlineimap.sgml

diff --git a/offlineimap.sgml b/offlineimap.sgml
index f0481f713dec2833245f1f996c5af5fddd475a7a..e1647351ce3105b7ea9731ddcae39fbce6d05c6d 100644 (file)
--- 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,11 +206,13 @@ 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
@@ -230,6 +234,7 @@ remoteuser = jgoerzen
              IMAP server and point both &OfflineIMAP; and your mail
              reader at it.
            </para>
+         </listitem>
        </itemizedlist>
       </refsect2>
 
@@ -372,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>
@@ -388,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>
@@ -566,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>
@@ -662,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
@@ -699,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>
@@ -734,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>
@@ -795,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>
 
@@ -804,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>