commit 043a8b583570c6d946373cd1c00acc4573cadd75
parent 16db3498b383ccc38ff74202fa758fca44a5d8e2
Author: Oswald Buddenhagen <ossi@users.sf.net>
Date: Thu, 9 Dec 2021 19:05:06 +0100
documentation tweaks
manual:
- explain what "rename on move" really means
- reword "remote" to "opposite" to make it less confusing
(possibly renaming TrashRemoteNew left as an exercise for later)
- mention example mbsyncrc
- consistently capitalize Store/Channel/Group where they refer to the
respective configuration entities
- emphasize that SyncState may need a trailing slash (as we do for Path)
- fix missing mention of global usage/default for some options
example mbsyncrc:
- add big fat note that empty lines matter
- stop demoing deprecated options
- point out that CertificateFile is optional
REFMAIL: 877dd11jb3.fsf@angela.anarc.at
Diffstat:
2 files changed, 39 insertions(+), 26 deletions(-)
diff --git a/src/mbsync.1 b/src/mbsync.1
@@ -50,11 +50,11 @@ Read configuration from \fIfile\fR.
By default, the configuration is read from ~/.mbsyncrc.
.TP
\fB-a\fR, \fB--all\fR
-Select all configured channels. Any channel/group specifications on the command
-line are ignored.
+Select all configured Channels. Any Channel/Group specifications on the
+command line are ignored.
.TP
\fB-l\fR, \fB--list\fR
-Don't synchronize anything, but list all mailboxes in the selected channels
+Don't synchronize anything, but list all mailboxes in the selected Channels
and exit.
.TP
\fB-C\fR[\fBf\fR][\fBn\fR], \fB--create\fR[\fB-far\fR|\fB-near\fR]
@@ -144,8 +144,7 @@ Unix-like forward slashes.
.SS All Stores
These options can be used in all supported Store types.
.br
-In this context, the term "remote" describes the second Store within a Channel,
-and not necessarily a remote server.
+The term "opposite Store" refers to the other Store within a Channel.
.br
The special mailbox \fBINBOX\fR exists in every Store; its physical location
in the file system is Store type specific.
@@ -208,14 +207,15 @@ See \fBRECOMMENDATIONS\fR and \fBINHERENT PROBLEMS\fR below.
.TP
\fBTrashNewOnly\fR \fByes\fR|\fBno\fR
When trashing, copy only not yet propagated messages. This makes sense if the
-remote Store has a \fBTrash\fR as well (with \fBTrashNewOnly\fR \fBno\fR).
+opposite Store has a \fBTrash\fR as well (with \fBTrashNewOnly\fR \fBno\fR).
(Default: \fBno\fR)
.
.TP
\fBTrashRemoteNew\fR \fByes\fR|\fBno\fR
-When expunging the remote Store, copy not yet propagated messages to this
-Store's \fBTrash\fR. When using this, the remote Store does not need an own
-\fBTrash\fR at all, yet all messages are archived.
+When expunging the opposite Store, copy not yet propagated messages to this
+Store's \fBTrash\fR.
+When using this, the opposite Store does not need an own \fBTrash\fR at all,
+yet all messages are archived.
(Default: \fBno\fR)
.
.SS Maildir Stores
@@ -540,7 +540,7 @@ Note that \fBINBOX\fR is not matched by wildcards, unless it lives under
\fBPath\fR.
.br
The mailbox list selected by \fBPatterns\fR can be overridden by a mailbox
-list in a channel reference (a \fBGroup\fR specification or the command line).
+list in a Channel reference (a \fBGroup\fR specification or the command line).
.br
Example: "\fBPatterns\fR\ \fI%\ !Trash\fR"
.
@@ -560,7 +560,7 @@ the actual date of the message) will be deleted first.
Messages that are flagged (marked as important) and (by default) unread
messages will not be automatically deleted.
If \fIcount\fR is 0, the maximum number of messages is \fBunlimited\fR
-(Default: \fI0\fR).
+(Global default: \fI0\fR).
.
.TP
\fBExpireUnread\fR \fByes\fR|\fBno\fR
@@ -570,7 +570,7 @@ This ensures that you never miss new messages even after an extended absence.
However, if your archive contains large amounts of unread messages by design,
treating them as important would practically defeat \fBMaxMessages\fR. In this
case you need to enable this option.
-(Default: \fBno\fR).
+(Global default: \fBno\fR).
.
.TP
\fBSync\fR {\fBNone\fR|[\fBPull\fR] [\fBPush\fR] [\fBNew\fR] [\fBReNew\fR] [\fBDelete\fR] [\fBFlags\fR]|\fBAll\fR}
@@ -586,7 +586,7 @@ Select the synchronization operation(s) to perform:
a configured \fBMaxSize\fR.
.br
\fBDelete\fR - propagate message deletions. This applies only to messages that
-are actually gone, i.e., were expunged. The affected messages in the remote
+are actually gone, i.e., were expunged. The affected messages in the opposite
Store are marked as deleted only, i.e., they won't be really deleted until
that Store is expunged.
.br
@@ -622,6 +622,7 @@ row/column. For example,
"\fBSync\fR\ \fBPullNew\fR\ \fBPullDelete\fR\ \fBPush\fR" will propagate
message arrivals and deletions from the far side to the near side and any
changes from the near side to the far side.
+.br
Note that it is not allowed to assert a cell in two ways, e.g.
"\fBSync\fR\ \fBPullNew\fR\ \fBPull\fR" and
"\fBSync\fR\ \fBPullNew\fR\ \fBDelete\fR\ \fBPush\fR" induce error messages.
@@ -648,7 +649,8 @@ Note that for safety, non-empty mailboxes are never deleted.
.
.TP
\fBExpunge\fR {\fBNone\fR|\fBFar\fR|\fBNear\fR|\fBBoth\fR}
-Permanently remove all messages [on the far/near side] marked for deletion.
+Permanently remove all messages [on the far/near side] which are marked
+for deletion.
See \fBRECOMMENDATIONS\fR below.
(Global default: \fBNone\fR)
.
@@ -660,11 +662,11 @@ Enabling this makes sense in order to keep the time stamp based message
sorting intact.
Note that IMAP does not guarantee that the time stamp (termed \fBinternal
date\fR) is actually the arrival time, but it is usually close enough.
-(Default: \fBno\fR)
+(Global default: \fBno\fR)
.
.P
\fBSync\fR, \fBCreate\fR, \fBRemove\fR, \fBExpunge\fR,
-\fBMaxMessages\fR, and \fBCopyArrivalDate\fR
+\fBMaxMessages\fR, \fBExpireUnread\fR, and \fBCopyArrivalDate\fR
can be used before any section for a global effect.
The global settings are overridden by Channel-specific options,
which in turn are overridden by command line switches.
@@ -677,7 +679,8 @@ in the near side mailbox itself; this has the advantage that you do not need
to handle the state file separately if you delete the mailbox, but it works
only with Maildir mailboxes, obviously.
Otherwise this is interpreted as a string to prepend to the near side mailbox
-name to make up a complete path.
+name to make up a complete path. Note that you \fBmust\fR append a slash if
+you want to specify a directory.
.br
This option can be used outside any section for a global effect. In this case
the appended string is made up according to the pattern
@@ -702,7 +705,7 @@ used as mailbox name separators as well.
.
.TP
\fBChannel\fR[\fBs\fR] \fIchannel\fR[\fB:\fIbox\fR[\fB,\fR...]] ...
-Add the specified channels to the group. This option can be specified multiple
+Add the specified Channels to the Group. This option can be specified multiple
times within a Group.
.
.SS Global Options
@@ -744,7 +747,7 @@ counters by default. The output will look like this:
C: 1/2 B: 3/4 F: +13/13 *23/42 #0/0 N: +0/7 *0/0 #0/0
.in -4
.P
-This represents the cumulative progress over channels, boxes, and messages
+This represents the cumulative progress over Channels, boxes, and messages
affected on the far and near side, respectively.
The message counts represent added messages, messages with updated flags,
and trashed messages, respectively.
@@ -757,14 +760,14 @@ slow, and semantically somewhat questionable. Specifically, Gmail needs to
be configured not to do it.
.P
By default, \fBmbsync\fR will not delete any messages - deletions are
-propagated by marking the messages as deleted on the remote store.
+propagated by marking the messages as deleted in the opposite Store.
Once you have verified that your setup works, you will typically want to
set \fBExpunge\fR to \fBBoth\fR, so that deletions become effective.
.P
\fBmbsync\fR's built-in trash functionality relies on \fBmbsync\fR doing
the expunging of deleted messages. This is the case when it propagates
deletions of previously propagated messages, and the trash is on the target
-store (typically your IMAP server).
+Store (typically your IMAP server).
.br
However, when you intend \fBmbsync\fR to trash messages which were not
propagated yet, the MUA must mark the messages as deleted without expunging
@@ -789,6 +792,10 @@ Mutt always does that, while mu4e needs to be configured to do it:
.in +4
(setq mu4e-change-filenames-when-moving t)
.in -4
+.br
+The general expectation is that a completely new filename is generated
+as if the message was new, but stripping the \fB,U=\fIxxx\fR infix is
+sufficient as well.
.
.SH INHERENT PROBLEMS
Changes done after \fBmbsync\fR has retrieved the message list will not be
@@ -804,7 +811,8 @@ There is no risk as long as the IMAP mailbox is accessed by only one client
.SH FILES
.TP
.B ~/.mbsyncrc
-Default configuration file
+Default configuration file.
+See also the example file in the documentation directory.
.TP
.B ~/.mbsync/
Directory containing synchronization state files
diff --git a/src/mbsyncrc.sample b/src/mbsyncrc.sample
@@ -4,6 +4,10 @@
Expunge None
Create Both
+# More sections follow
+#
+# !!!! Note that empty lines delimit sections !!!!
+
MaildirStore local
Path ~/Mail/
Trash Trash
@@ -32,7 +36,7 @@ Sync PullNew Push
IMAPStore personal
Host host.play.com
Port 6789
-RequireSSL no
+SSLType None
Channel personal
Far :personal:
@@ -55,14 +59,14 @@ Channels work personal remote
IMAPStore st1
Host st1.domain.com
-RequireCRAM yes
+AuthMech CRAM-MD5
+# Omit if you want to use the system certificate store.
CertificateFile ~/.st1-certificate.crt
IMAPStore st2
Host imap.another-domain.com
Path non-standard/
-RequireSSL no
-UseTLSv1 no
+SSLVersions TLSv1.3
Channel rst
Far :st1:somebox
@@ -71,6 +75,7 @@ Near :st2:
IMAPAccount server
Host imaps:foo.bar.com
+# Omit if you want to use the system certificate store.
CertificateFile ~/.server-certificate.crt
IMAPStore server
