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 <git@ursliska.de>

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