notmuch config: Add more documentation for maildir.synchronize_flags

[notmuch] / notmuch-config.c

diff --git a/notmuch-config.c b/notmuch-config.c
index 483d5c638e0e68d4a991aca9904c7336c8cc1a8a..bace8e567fb465251f4213988e464ff705b423c9 100644 (file)
--- a/notmuch-config.c
+++ b/notmuch-config.c
@@ -64,10 +64,24 @@ static const char user_config_comment[] =
 static const char maildir_config_comment[] =
     " Maildir compatibility configuration\n"
     "\n"
-    " Here you can configure whether notmuch will synchronize its tags with\n"
-    " maildir flags."
+    " The following option is supported here:\n"
     "\n"
-    "\tsynchronize_flags      Valid values are true and false.\n";
+    "\tsynchronize_flags      Valid values are true and false.\n"
+    "\n"
+    "\tIf true, then the following maildir flags (in message filenames)\n"
+    "\twill be syncrhonized with the corresponding notmuch tags:\n"
+    "\n"
+    "\t\tFlag  Tag\n"
+    "\t\t----  -------\n"
+    "\t\tD     draft\n"
+    "\t\tF     flagged\n"
+    "\t\tP     passed\n"
+    "\t\tR     replied\n"
+    "\t\tS     unread (added when 'S' tag is not present)\n"
+    "\n"
+    "\tThe \"notmuch new\" command will notice flag changes in filenames\n"
+    "\tand update tags, while the \"notmuch tag\" and \"notmuch restore\"\n"
+    "\tcommands will notice tag changes and update flags in filenames\n";
 
 struct _notmuch_config {
     char *filename;
@@ -80,7 +94,7 @@ struct _notmuch_config {
     size_t user_other_email_length;
     const char **new_tags;
     size_t new_tags_length;
-    notmuch_bool_t maildir_sync;
+    notmuch_bool_t maildir_synchronize_flags;
 };
 
 #define MAILDIR_SYNC_UNDEF ((notmuch_bool_t)-1)
@@ -233,7 +247,7 @@ notmuch_config_open (void *ctx,
     config->user_other_email_length = 0;
     config->new_tags = NULL;
     config->new_tags_length = 0;
-    config->maildir_sync = MAILDIR_SYNC_UNDEF;
+    config->maildir_synchronize_flags = MAILDIR_SYNC_UNDEF;
 
     if (! g_key_file_load_from_file (config->key_file,
                                     config->filename,
@@ -327,8 +341,8 @@ notmuch_config_open (void *ctx,
        notmuch_config_set_new_tags (config, tags, 2);
     }
 
-    if (notmuch_config_get_maildir_sync (config) == MAILDIR_SYNC_UNDEF) {
-       notmuch_config_set_maildir_sync (config, FALSE);
+    if (notmuch_config_get_maildir_synchronize_flags (config) == MAILDIR_SYNC_UNDEF) {
+       notmuch_config_set_maildir_synchronize_flags (config, FALSE);
     }
 
     /* Whenever we know of configuration sections that don't appear in
@@ -729,26 +743,26 @@ notmuch_config_command (void *ctx, int argc, char *argv[])
 }
 
 notmuch_bool_t
-notmuch_config_get_maildir_sync (notmuch_config_t *config)
+notmuch_config_get_maildir_synchronize_flags (notmuch_config_t *config)
 {
     GError *err = NULL;
-    if (config->maildir_sync == MAILDIR_SYNC_UNDEF) {
-       config->maildir_sync =
+    if (config->maildir_synchronize_flags == MAILDIR_SYNC_UNDEF) {
+       config->maildir_synchronize_flags =
            g_key_file_get_boolean (config->key_file,
                                    "maildir", "synchronize_flags", &err);
        if (err) {
-           config->maildir_sync = MAILDIR_SYNC_UNDEF;
+           config->maildir_synchronize_flags = MAILDIR_SYNC_UNDEF;
            g_error_free (err);
        }
     }
-    return config->maildir_sync;
+    return config->maildir_synchronize_flags;
 }
 
 void
-notmuch_config_set_maildir_sync (notmuch_config_t *config,
-                                notmuch_bool_t maildir_sync)
+notmuch_config_set_maildir_synchronize_flags (notmuch_config_t *config,
+                                             notmuch_bool_t synchronize_flags)
 {
     g_key_file_set_boolean (config->key_file,
-                           "maildir", "synchronize_flags", maildir_sync);
-    config->maildir_sync = maildir_sync;
+                           "maildir", "synchronize_flags", synchronize_flags);
+    config->maildir_synchronize_flags = synchronize_flags;
 }