rename 'mu label' -> 'mu labels'

Update names, docs etc.

man/mu-labels.1.org

@@ -0,0 +1,182 @@
+#+TITLE: MU LABELS
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
+#+include: macros.inc
+
+* NAME
+
+mu-labels - attach labels to messages. Export labels to file, and import them.
+
+* SYNOPSIS
+
+*mu* [​_COMMON-OPTIONS_​] labels update [​UPDATE-OPTIONS​] "<query>" --labels [{+,-}<label>]...
+
+*mu* [​_COMMON-OPTIONS_​] labels list
+
+*mu* [​_COMMON-OPTIONS_​] labels list-restore
+
+*mu* [​_COMMON-OPTIONS_​] labels clear [CLEAR-OPTIONS] "<query>"
+
+*mu* [​_COMMON-OPTIONS_​] labels export [<file>]
+
+*mu* [​_COMMON-OPTIONS_​] labels import <file>
+
+* DESCRIPTION
+
+*mu labels* is the sub-command for adding and removing and listing message labels.
+
+A label is a string associated with a message.
+
+*mu labels* has five sub-commands (i.e., 'sub-sub-commands'):
+
+- *update* for changing the labels for the messages matching some query
+- *clear* for clearing all labels from messages matching some query
+- *list* to list all labels that are used in the store
+- *list-restore* to restore the list of labels from the store
+- *export* to write the label information to a file
+- *import* the read label information from a file
+
+Important: unlike other message metadata stored by *mu*, labels _cannot_ be restored
+by merely re-indexing messages. Hence, to avoid loosing label information, you
+must *export* it before re-indexing, and *import* afterwards.
+
+* UPDATE OPTIONS
+
+The *update* command changes the labels for messages that match some query. The
+query must be recognized as a single parameter; hence, it must be quoted when
+using from a shell.
+
+** --labels
+
+  a comma-separated list of labels, each prefixed with either *+* to add that
+  label, or *-* to remove it. See *VALID LABELS*.
+
+  *mu4e* users: note the difference, in *mu4e* the label expressions are
+  _space_-separated, here they are _comma_-separated.
+
+** --dry-run
+
+  only print what /would/ change, but do not change anything
+
+#+include: "muhome.inc" :minlevel 2
+
+* CLEAR OPTIONS
+
+The *clear* command removes all labels from messages that match some query. As
+with *update*, the query must be recognized as a single parameter, i.e., quote it
+when using a shell.
+
+** --dry-run
+
+  only print what /would/ change, but do not change anything
+
+  #+include: "muhome.inc" :minlevel 2
+
+* LIST OPTIONS
+
+The *list* command lists all the labels that are currently in use in the store.
+This is the information is used for auto-completion in *mu4e*.
+
+With the (global, directly after *mu) *--verbose* option, this also includes the
+counts.
+
+* LIST-RESTORE OPTIONS
+
+It is possible that the list of labels (as per the *list* sub-command) gets
+outdated for various reasons. With *list-restore*, this list get refreshed with
+the actual labels as seen in the store.
+
+* EXPORT OPTIONS
+
+The *export* command takes the labels in the store and the messages they apply to,
+and writes this information to a file. You can *import* this file later, to
+restore the labels. The command takes a path to a file or a directory (ending in
+'/') as its argument.
+
+If a file is specified, *mu* writes the export to it.
+
+If a directory is specified, *mu* writes to a file in that directory. The
+directory must already exist.
+
+When neither is specified, *mu* writes to a file in the current directory.
+
+See *EXPORT FORMAT* below for details about the format.
+
+* IMPORT OPTIONS
+
+The *import* command is for restoring the labels from a file created through
+*export* earlier. The command takes a path to a file as its argument.
+
+See *EXPORT FORMAT* below for details on the format.
+
+** --dry-run
+
+  only print what would change, but do not change anything
+
+#+include: "muhome.inc" :minlevel 2
+
+* VALID LABELS
+
+*mu* does not wish to limit your creativity, but nevertheless puts a few
+restrictions on what is accepted as a label.
+
+- a *valid label character* is any character that is not a control-character, a
+  blank, or any of *'*, *"*, *`*, */*, *\*, *$*
+- a *valid label* consists of one or more valid label characters, the first of
+  which must *not* be either *+* or *-*
+
+Hence, some valid labels are: ~project-x~, ~c@pybara~, ~fn😃rb~, while some _invalid_
+ones are: ~holiday plan~ and ~+fancy$/dinner~.
+
+* EXPORT FORMAT
+
+The formats for import/export are UTF8-encoded text. The first line starts with
+~;;~ and some internal data. Empty lines are ignored.
+
+Each entry represents the labels for a message. Messages without labels are not
+included.
+
+An entry consists of three lines:
+1. The first line starts with ~path:~ followed by the file-system path to the
+   message.
+2. The second line starts with ~message-id:~ followed by the message-id for the
+   message.
+3. Finally, the third line starts with ~labels:~ followed by the space-separated
+   labels for the message
+
+#+begin_example
+path:/home/user/Maildir/inbox/cur/1720645394.99f64f5d81f42ba4.hyperion:2,S
+message-id:669338009127192q7821feh1t826d0c4c90bd8fdf@mail.gmail.com
+labels:foo,bar,cuux
+#+end_example
+
+The ~message-id:~ is only used if the message cannot be found using ~path:~.
+
+This adds some fault-tolerance for the case where the precise file-system
+positions have changed since the labels were exported. The upshot of that is
+that if there are _duplicate_ messages (messages with the same message-id), the
+tags are applied to all of them.
+
+#+include: "exit-code.inc" :minlevel 1
+
+* EXAMPLES
+
+Some examples. For the query parameter, make sure to quote the query to ensure
+it is recognized as a single parameter.
+
+Remove the label "planet" and add the label "dwarf-planet" to all messages that
+have "pluto" in their subject:
+#+begin_export
+$ mu labels update "subject:pluto" --labels -planet,+dwarf-planet
+#+end_export
+
+Clear all labels from messages with the label "boring":
+#+begin_export
+$ mu labels clear "label:boring"
+#+end_export
+
+#+include: "prefooter.inc" :minlevel 1
+
+* SEE ALSO
+
+{{{man-link(mu-query,1)}}},
+{{{man-link(mu-find,1)}}},