From f5198794e5e2c110156f6731353a06ae2ee15e42 Mon Sep 17 00:00:00 2001 From: Urs Liska Date: Mon, 2 Oct 2017 01:18:41 +0200 Subject: [PATCH] utf8: document new feature, deprecate old one - Document the new utf8foldernames config option - Deprecate the old decodefoldernames option Update its documentation, discussing the limitations. Signed-off-by: Urs Liska Signed-off-by: Nicolas Sebrecht --- offlineimap.conf | 67 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 66 insertions(+), 1 deletion(-) diff --git a/offlineimap.conf b/offlineimap.conf index b7c9fbd..f6b5438 100644 --- a/offlineimap.conf +++ b/offlineimap.conf @@ -432,6 +432,55 @@ remoterepository = RemoteExample #proxy = SOCKS5:IP:9999 +# EXPERIMENTAL: This option stands in the [Account Test] section. +# +# IMAP defines an encoding for non-ASCII ("international") characters, and most +# IMAP servers store folder names in this encoding. Note that the IMAP 4rev1 +# specification (RFC 3501) allows both UTF-8 and modified UTF-7 folder names +# so it is *possible* that an IMAP server already uses UTF-8 encoded folder +# names. But usually Folders that are shown as, say, "Gäste" will be represented +# as "G&AOQ-ste", and by default will be synchronized like this by offlineIMAP. +# +# This option converts IMAP folder names from IMAP4-UTF-7 to UTF-8 and back +# in order to have nicely readable UTF-8 folder names in the local copy. +# +# WARNING: with this option enabled: +# - compatibility with any other version is NOT GUARANTED (including newer); +# - existing set-ups will probably break. +# - no support is provided. +# +# IMPORTANT: READ THIS SECTION if you intend to enable this feature for an +# EXISTING ACCOUNT that has already been synchronized! +# Enabling UTF-8 encoded folder names will change many things on the local +# repository of an account, so you really have to create a new local repository +# and review the configuration. The least that would happen otherwise is a +# duplication of all folders containing non-ASCII characters. +# But also the following functionality may change, so the configuration in the +# remote repository configuration has to be reviewed/updated: +# - decodefoldernames +# This option is replaced by utf8foldernames and must be removed +# If both utf8foldernames and decodefoldernames are enabled the synchronization +# for the given account is aborted before doing any changes. +# - nametrans +# With utf8foldernames enabled any nametrans function will operate on the +# UTF-8 encoded folder names, while even with decodefoldernames enabled they +# operate on the original IMAP4-UTF-7 encoded names. +# - folderfilter +# Folder filters still work on the untranslated names before applying a +# nametrans function, but still this operates on the UTF-8 encoded names. +# - folderincludes +# With utf8foldernames enabled this function expects UTF-8 encoded folder +# names. +# - foldersort +# With utf8foldernames enabled the folder names passed to the sorting routine +# will be the UTF encoded names. +# - idlefolders +# With utf8foldernames enabled folders passed to this function are expected to +# be UTF-8 encoded. +# +#utf8foldernames = no + + # TESTING: This option stands in the [Account Test] section. # # Use authproxy connection for this account. Useful to bypass the GFW in China. @@ -1005,7 +1054,7 @@ remoteuser = username #reference = Mail -# This option stands in the [Repository RemoteExample] section. +# DEPRECATED: This option stands in the [Repository RemoteExample] section. # # IMAP defines an encoding for non-ASCII ("international") characters. Enable # this option if you want to decode them to the nowadays ubiquitous UTF-8. @@ -1013,10 +1062,26 @@ remoteuser = username # Note that the IMAP 4rev1 specification (RFC 3501) allows both UTF-8 and # modified UTF-7 folder names. # +# This option converts IMAP folder names from IMAP4-UTF-7 to UTF-8. +# +# NOTE/LIMITATION: +# - The reencoding is applied *after* a nametrans function that may be given, +# so it is important to note that nametrans will work on the undecoded +# UTF-7 names. +# - This option only works from a remote IMAP to a local Maildir repository +# - It only works *once*, so it can only be used for one-off backups +# (see https://github.com/OfflineIMAP/offlineimap/issues/299 and especially +# https://github.com/OfflineIMAP/offlineimap/issues/299#issuecomment-331243827) +# # WARNING: with this option enabled: # - compatibility with any other version is NOT GUARANTED (including newer); # - no support is provided. # +# DEPRECATION: +# This option is only there for backward compatibility with existing set-ups. +# For newly created accounts please use the utf8foldernames option on account +# level. +# # This feature was merged because it's small changes in the code. However, this # might seriously decrease the stability of the program. That's why it will # likely never be marked stable. The approach is: if it works for you, you're