diff --git a/docs/MANUAL.rst b/docs/MANUAL.rst index 8d7a8b7..9715cb8 100644 --- a/docs/MANUAL.rst +++ b/docs/MANUAL.rst @@ -43,6 +43,10 @@ Most configuration is done via the configuration file. However, any setting can OfflineImap is well suited to be frequently invoked by cron jobs, or can run in daemon mode to periodically check your email (however, it will exit in some error situations). +The documentation is included in the git repository and can be created by +issueing `make dev-doc` in the `doc` folder (python-sphinx required), or it can +be viewed online at `http://docs.offlineimap.org`_. + .. _configuration: Configuration @@ -66,96 +70,9 @@ Check out the `Use Cases`_ section for some example configurations. OPTIONS ======= - --1 Disable most multithreading operations - - Use solely a single-connection sync. This effectively sets the - maxsyncaccounts and all maxconnections configuration file variables to 1. - - --P profiledir - - Sets OfflineIMAP into profile mode. The program will create profiledir (it - must not already exist). As it runs, Python profiling information about each - thread is logged into profiledir. Please note: This option is present for - debugging and optimization only, and should NOT be used unless you have a - specific reason to do so. It will significantly slow program performance, may - reduce reliability, and can generate huge amounts of data. You must use the - -1 option when you use -P. - - --a accountlist - - Overrides the accounts option in the general section of the configuration - file. You might use this to exclude certain accounts, or to sync some - accounts that you normally prefer not to. Separate the accounts by commas, - and use no embedded spaces. - - --c configfile - - Specifies a configuration file to use in lieu of the default, - ``~/.offlineimaprc``. - - --d debugtype[,...] - - Enables debugging for OfflineIMAP. This is useful if you are trying to track - down a malfunction or figure out what is going on under the hood. I suggest - that you use this with -1 to make the results more sensible. - - -d requires one or more debugtypes, separated by commas. These define what - exactly will be debugged, and include three options: imap, maildir, and - thread. The imap option will enable IMAP protocol stream and parsing - debugging. Note that the output may contain passwords, so take care to remove - that from the debugging output before sending it to anyone else. The maildir - option will enable debugging for certain Maildir operations. And thread will - debug the threading model. - - --f foldername[,foldername] - - Only sync the specified folders. The foldernames are the untranslated - foldernames. This command-line option overrides any folderfilter and - folderincludes options in the configuration file. - - --k [section:]option=value - - Override configuration file option. If "section" is omitted, it defaults to - general. Any underscores "_" in the section name are replaced with spaces: - for instance, to override option autorefresh in the "[Account Personal]" - section in the config file one would use "-k Account_Personal:autorefresh=30". - You may give more than one -k on the command line if you wish. - - --l filename - - Enables logging to filename. This will log everything that goes to the screen - to the specified file. Additionally, if any debugging is specified with -d, - then debug messages will not go to the screen, but instead to the logfile - only. - - --o Run only once, - - ignoring all autorefresh settings in the configuration file. - - --q Run only quick synchronizations. - - Ignore any flag updates on IMAP servers. - - --h|--help Show summary of options. - - --u interface - - Specifies an alternative user interface module to use. This overrides the - default specified in the configuration file. The pre-defined options are - listed in the User Interfaces section. The interface name is case insensitive. - +The command line options are described by issueing `offlineimap --help`. +Details on their use can be found either in the sample offlineimap.conf file or +in the user docs at `http://docs.offlineimap.org`_. User Interfaces =============== diff --git a/docs/dev-doc-src/offlineimap.rst b/docs/dev-doc-src/offlineimap.rst index bc98c16..37d78dc 100644 --- a/docs/dev-doc-src/offlineimap.rst +++ b/docs/dev-doc-src/offlineimap.rst @@ -6,6 +6,15 @@ Offlineimap is invoked with the following pattern: `offlineimap [args...]`. Where [args...] are as follows: Options: + --dry-run This mode protects us from performing any actual action. + It will not precisely give the exact information what + will happen. If e.g. it would need to create a folder, + it merely outputs "Would create folder X", but not how + many and which mails it would transfer. + --info Output information on the configured email + repositories. Useful for debugging and bug reporting. + Use in conjunction with the -a option to limit the + output to a single account. --version show program's version number and exit -h, --help show this help message and exit -1 Disable all multithreading operations and use solely a diff --git a/offlineimap/init.py b/offlineimap/init.py index d381a65..8668cc1 100644 --- a/offlineimap/init.py +++ b/offlineimap/init.py @@ -57,7 +57,19 @@ class OfflineImap: default=False, help="Do not actually modify any store but check and print " "what synchronization actions would be taken if a sync would be" - " performed.") + " performed. It will not precisely give the exact information w" + "hat will happen. If e.g. we need to create a folder, it merely" + " outputs 'Would create folder X', but not how many and which m" + "ails it would transfer.") + + parser.add_option("--info", + action="store_true", dest="diagnostics", + default=False, + help="Output information on the configured email repositories" + ". Useful for debugging and bug reporting. Use in conjunction wit" + "h the -a option to limit the output to a single account. This mo" + "de will prevent any actual sync to occur and exits after it outp" + "ut the debug information.") parser.add_option("-1", action="store_true", dest="singlethreading", @@ -80,11 +92,11 @@ class OfflineImap: "implies the -1 option.") parser.add_option("-a", dest="accounts", metavar="ACCOUNTS", - help="""Overrides the accounts section in the config file. - Lets you specify a particular account or set of - accounts to sync without having to edit the config - file. You might use this to exclude certain accounts, - or to sync some accounts that you normally prefer not to.""") + help="Overrides the accounts section in the config file. " + "Lets you specify a particular account or set of " + "accounts to sync without having to edit the config " + "file. You might use this to exclude certain accounts, " + "or to sync some accounts that you normally prefer not to.") parser.add_option("-c", dest="configfile", metavar="FILE", default="~/.offlineimaprc", @@ -92,18 +104,18 @@ class OfflineImap: "%default.") parser.add_option("-d", dest="debugtype", metavar="type1,[type2...]", - help="""Enables debugging for OfflineIMAP. This is useful - if you are to track down a malfunction or figure out what is - going on under the hood. This option requires one or more - debugtypes, separated by commas. These define what exactly - will be debugged, and so far include two options: imap, thread, - maildir or ALL. The imap option will enable IMAP protocol - stream and parsing debugging. Note that the output may contain - passwords, so take care to remove that from the debugging - output before sending it to anyone else. The maildir option - will enable debugging for certain Maildir operations. - The use of any debug option (unless 'thread' is included), - implies the single-thread option -1.""") + help="Enables debugging for OfflineIMAP. This is useful " + "if you are to track down a malfunction or figure out what is " + "going on under the hood. This option requires one or more " + "debugtypes, separated by commas. These define what exactly " + "will be debugged, and so far include two options: imap, thread, " + "maildir or ALL. The imap option will enable IMAP protocol " + "stream and parsing debugging. Note that the output may contain " + "passwords, so take care to remove that from the debugging " + "output before sending it to anyone else. The maildir option " + "will enable debugging for certain Maildir operations. " + "The use of any debug option (unless 'thread' is included), " + "implies the single-thread option -1.") parser.add_option("-l", dest="logfile", metavar="FILE", help="Log to FILE") @@ -149,13 +161,6 @@ class OfflineImap: "not usable. Possible interface choices are: %s " % ", ".join(UI_LIST.keys())) - parser.add_option("--info", - action="store_true", dest="diagnostics", - default=False, - help="Output information on the configured email repositories" - ". Useful for debugging and bug reporting. Use in conjunction wit" - "h the -a option to limit the output to a single account") - (options, args) = parser.parse_args() #read in configuration file