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>
Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>
This commit is contained in:
Urs Liska 2017-10-02 01:18:41 +02:00 committed by Nicolas Sebrecht
parent 8b398f3aa8
commit f5198794e5

View File

@ -432,6 +432,55 @@ remoterepository = RemoteExample
#proxy = SOCKS5:IP:9999 #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. # TESTING: This option stands in the [Account Test] section.
# #
# Use authproxy connection for this account. Useful to bypass the GFW in China. # Use authproxy connection for this account. Useful to bypass the GFW in China.
@ -1005,7 +1054,7 @@ remoteuser = username
#reference = Mail #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 # IMAP defines an encoding for non-ASCII ("international") characters. Enable
# this option if you want to decode them to the nowadays ubiquitous UTF-8. # 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 # Note that the IMAP 4rev1 specification (RFC 3501) allows both UTF-8 and
# modified UTF-7 folder names. # 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: # WARNING: with this option enabled:
# - compatibility with any other version is NOT GUARANTED (including newer); # - compatibility with any other version is NOT GUARANTED (including newer);
# - no support is provided. # - 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 # 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 # 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 # likely never be marked stable. The approach is: if it works for you, you're