diff options
| author | Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> | 2022-12-18 00:21:52 +0200 |
|---|---|---|
| committer | Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> | 2022-12-29 10:41:16 +0200 |
| commit | a259ae41624e0d655160e70fffae7d94468fbef8 (patch) | |
| tree | 8d0142105006f02415dea3c9c9556cc0d8675c01 /man | |
| parent | ba09b8fc2c5ea9f784d79964bdee90b1a51f2d65 (diff) | |
man: generate manpages from .org files
Generate the manpages from org-documents which makes it a bit easier to
keep them update to date since I find org-syntax easier than troff, and
we can use include files.
Diffstat (limited to 'man')
44 files changed, 1659 insertions, 1971 deletions
diff --git a/man/author.inc b/man/author.inc new file mode 100644 index 0000000..db14d93 --- /dev/null +++ b/man/author.inc @@ -0,0 +1,7 @@ +* AUTHOR + +Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> + +# Local Variables: +# mode: org +# End: diff --git a/man/bugs.inc b/man/bugs.inc new file mode 100644 index 0000000..882e6a5 --- /dev/null +++ b/man/bugs.inc @@ -0,0 +1,7 @@ +* REPORTING BUGS + +Please report bugs at <https://github.com/djcb/mu/issues>. + +# Local Variables: +# mode: org +# End: diff --git a/man/common-options.inc b/man/common-options.inc new file mode 100644 index 0000000..ec83e3f --- /dev/null +++ b/man/common-options.inc @@ -0,0 +1,31 @@ +* COMMON OPTIONS + +** -d, --debug +makes mu generate extra debug information, useful for debugging the program +itself. By default, debug information goes to the log file, ~/.cache/mu/mu.log. +It can safely be deleted when mu is not running. When running with --debug +option, the log file can grow rather quickly. See the note on logging below. + +** -q, --quiet +causes mu not to output informational messages and progress information to +standard output, but only to the log file. Error messages will still be sent to +standard error. Note that mu index is much faster with --quiet, so it is +recommended you use this option when using mu from scripts etc. + +** --log-stderr +causes mu to not output log messages to standard error, in addition to sending +them to the log file. + +** --nocolor +do not use ANSI colors. The environment variable ~NO_COLOR~ can be used as an +alternative to ~--nocolor~. + +** -V, --version +prints mu version and copyright information. + +** -h, --help +lists the various command line options. + +# Local Variables: +# mode: org +# End: diff --git a/man/copyright.inc.in b/man/copyright.inc.in new file mode 100644 index 0000000..ba4d8bb --- /dev/null +++ b/man/copyright.inc.in @@ -0,0 +1,12 @@ +* COPYRIGHT + +This manpage is part of ~mu~ @VERSION@. + +Copyright © 2022 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later +<https://gnu.org/licenses/gpl.html>. This is free software: you are free to +change and redistribute it. There is NO WARRANTY, to the extent permitted by +law. + +# Local Variables: +# mode: org +# End: diff --git a/man/exit-code.inc b/man/exit-code.inc new file mode 100644 index 0000000..59bcbdd --- /dev/null +++ b/man/exit-code.inc @@ -0,0 +1,9 @@ +* EXIT CODE + +This command returns 0 upon successful completion, or a non-zero exit code +otherwise. + + +# Local Variables: +# mode: org +# End: diff --git a/man/meson.build b/man/meson.build index 81d7e4c..14aced6 100644 --- a/man/meson.build +++ b/man/meson.build @@ -14,23 +14,81 @@ ## along with this program; if not, write to the Free Software Foundation, ## Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -install_man( - ['mu.1', - 'mu-add.1', - 'mu-bookmarks.5', - 'mu-cfind.1', - 'mu-easy.1', - 'mu-extract.1', - 'mu-fields.1', - 'mu-find.1', - 'mu-help.1', - 'mu-index.1', - 'mu-info.1', - 'mu-init.1', - 'mu-mkdir.1', - 'mu-query.7', - 'mu-remove.1', - 'mu-script.1', - 'mu-server.1', - 'mu-verify.1', - 'mu-view.1']) +# +# generate org include files +# +man_data=configuration_data() +man_data.set('VERSION', meson.project_version()) +incs=[ + 'author.inc', + 'bugs.inc', + 'common-options.inc', + 'copyright.inc.in', + 'exit-code.inc', + 'muhome.inc', + 'prefooter.inc', +] +foreach inc: incs + # configure the .in ones + if inc.substring(-3) == '.in' + configure_file(input: inc, + output: '@BASENAME@', + configuration: man_data) + else # and copy the rest + configure_file(input: inc, output:'@BASENAME@.inc', + copy:true) + endif +endforeach + +# man-pages is org-format. +man_orgs=[ + 'mu.1.org', + 'mu-add.1.org', + 'mu-bookmarks.5.org', + 'mu-cfind.1.org', + 'mu-easy.5.org', + 'mu-extract.1.org', + 'mu-fields.1.org', + 'mu-find.1.org', + 'mu-help.1.org', + 'mu-index.1.org', + 'mu-info.1.org', + 'mu-init.1.org', + 'mu-mkdir.1.org', + 'mu-query.7.org', + 'mu-remove.1.org', + 'mu-server.1.org', + 'mu-verify.1.org', + 'mu-view.1.org' +] + +foreach src : man_orgs + # copy to builddir so org-includes work. + configure_file(input: src, output:'@BASENAME@.org', copy:true) + + # meson makes in tricky to use the results of e.g. configure_file + # in custom_commands..., so this is admittedly a little hacky. + org = join_paths(meson.current_build_dir(), src) + man = '@BASENAME@' + + expr_tmpl = ''.join([ + '(progn', + ' (require \'ox-man)', + ' (org-export-to-file \'man "@0@"))', + ]) + expr = expr_tmpl.format(org.substring(0,-4)) + sectiondir = join_paths(mandir, 'man' + src.substring(-5, -4)) + + custom_target(src + '-to-man', + build_by_default: true, + input: src, + output: '@BASENAME@', + install: true, + install_dir: sectiondir, + depend_files: incs, + command: [emacs, + '--no-init-file', + '--batch', + org, + '--eval', expr]) +endforeach diff --git a/man/mu-add.1 b/man/mu-add.1 deleted file mode 100644 index 1bf1ed9..0000000 --- a/man/mu-add.1 +++ /dev/null @@ -1,47 +0,0 @@ -.TH MU ADD 1 "May 2022" "User Manuals" - -.SH NAME - -mu add\- add one or more messages to the database - -.SH SYNOPSIS - -.B mu add <file> [<files>] - -.SH DESCRIPTION - -\fBmu add\fR is the command to add specific message files to the -database. Each file must be specified with an absolute path. - -.SH OPTIONS - -\fBmu add\fR does not have its own options, but the general options for -determining the location of the database (\fI--muhome\fR) are available. See -\fBmu-index\fR(1) for more information. - -.SH RETURN VALUE - -\fBmu add\fR returns 0 upon success; in general, the following error codes are -returned: - -.nf -| code | meaning | -|------+-----------------------------------| -| 0 | ok | -| 1 | general error | -.fi - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu (1), -.BR mu-index (1), -.BR mu-remove (1) diff --git a/man/mu-add.1.org b/man/mu-add.1.org new file mode 100644 index 0000000..bef1bec --- /dev/null +++ b/man/mu-add.1.org @@ -0,0 +1,28 @@ +#+title: MU ADD + +* NAME + +~mu add~ - add one or more messages to the database + +* SYNOPSIS + +*mu [common-options] add [options] <file> [<files>]* + +* DESCRIPTION + +~mu add~ is the command to add specific message files to the database. Each file +must be specified with an absolute path. + +* ADD OPTIONS + +#+include: "muhome.inc" :minlevel 2 + +#+include: "common-options.inc" :minlevel 1 + +#+include: "exit-code.inc" :minlevel 1 + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO + +*mu(1)*, *mu-index(1)*, *mu-remove(1)* diff --git a/man/mu-bookmarks.5 b/man/mu-bookmarks.5 deleted file mode 100644 index f68a335..0000000 --- a/man/mu-bookmarks.5 +++ /dev/null @@ -1,36 +0,0 @@ -.TH MU-BOOKMARKS 5 "July 2019" "User Manuals" - -.SH NAME - -bookmarks \- file with bookmarks (shortcuts) for mu search expressions - -.SH DESCRIPTION - -Bookmarks are named shortcuts for search queries. They allow using a convenient -name for often-used queries. The bookmarks are also visible as shortcuts in the -mu experimental user interfaces, \fImug\fR and \fImug2\fR. - -The bookmarks file is read from \fI<muhome>/bookmarks\fR. On Unix this would -typically be w be \fI~/.config/mu/bookmarks\fR, but this can be influenced using -the \fB\-\-muhome\fR parameter for \fBmu-find\fR(1) and \fBmug\fR(1). - -The bookmarks file is a typical key=value \fB.ini\fR-file, which is best shown -by means of an example: - -.nf - [mu] - inbox=maildir:/inbox # inbox - oldhat=maildir:/archive subject:hat # archived with subject containing 'hat' -.fi - -The \fB[mu]\fR group header is required. - -For practical uses of bookmarks, see \fBmu-find\fR(1). - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu (1), mu-find (1) diff --git a/man/mu-bookmarks.5.org b/man/mu-bookmarks.5.org new file mode 100644 index 0000000..80e2608 --- /dev/null +++ b/man/mu-bookmarks.5.org @@ -0,0 +1,35 @@ +#+title: MU-BOOKMARKS + +* NAME + +bookmarks - file with bookmarks (shortcuts) for mu search expressions + +* DESCRIPTION + +Bookmarks are named shortcuts for search queries. They allow using a convenient +name for often-used queries. The bookmarks are also visible as shortcuts in the +mu experimental user interfaces, =mug= and =mug2=. + +The bookmarks file is read from =<muhome>/bookmarks=. On Unix this would typically +be w be =~/.config/mu/bookmarks=, but this can be influenced using the ~--muhome~ +parameter for *mu-find(1)*. + +The bookmarks file is a typical key=value *.ini*-file, which is best shown by +means of an example: + +#+begin_example +[mu] +inbox=maildir:/inbox # inbox +oldhat=maildir:/archive subject:hat # archived with subject containing 'hat' +#+end_example + +The *[mu]* group header is required. For practical uses of bookmarks, see +*mu-find(1)*. + +#+include: "author.inc" :minlevel 1 + +#+include: "copyright.inc" :minlevel 1 + +* SEE ALSO + +*mu(1)*, *mu-find(1)* diff --git a/man/mu-cfind.1 b/man/mu-cfind.1 deleted file mode 100644 index a3618e1..0000000 --- a/man/mu-cfind.1 +++ /dev/null @@ -1,133 +0,0 @@ -.TH MU CFIND 1 "April 2019" "User Manuals" - -.SH NAME - -\fBmu cfind\fR is the \fBmu\fR command to find contacts in the \fBmu\fR -database and export them for use in other programs. - -.SH SYNOPSIS - -.B mu cfind [options] [<pattern>] - -.SH DESCRIPTION - -\fBmu cfind\fR is the \fBmu\fR command for finding \fIcontacts\fR (name and -e-mail address of people who were either an e-mail's sender or -receiver). There are different output formats available, for importing the -contacts into other programs. - -.SH SEARCHING CONTACTS - -When you index your messages (see \fBmu index\fR), \fBmu\fR creates a list of -unique e-mail addresses found and the accompanying name, and caches this -list. In case the same e-mail address is used with different names, the most -recent non-empty name is used. - -\fBmu cfind\fR starts a search for contacts that match a \fIregular -expression\fR. For example: - -.nf - $ mu cfind '@gmail\.com' -.fi - -would find all contacts with a gmail-address, while - -.nf - $ mu cfind Mary -.fi - -lists all contacts with Mary in either name or e-mail address. - -If you do not specify a search expression, \fBmu cfind\fR returns the full list -of contacts. Note, \fBmu cfind\fR uses a cache with the e-mail information, -which is populated during the indexing process. - -The regular expressions are Perl-compatible (as per the PCRE-library used by -GRegex). - -.SH OPTIONS - -.TP -\fB\-\-format\fR=\fIplain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv\fR -sets the output format to the given value. The following are available: - -.nf -| --format= | description | -|-------------+-----------------------------------| -| plain | default, simple list | -| mutt-alias | mutt alias-format | -| mutt-ab | mutt external address book format | -| wl | wanderlust addressbook format | -| org-contact | org-mode org-contact format | -| bbdb | BBDB format | -| csv | comma-separated values (*) | -.fi - - -(*) CSV is not fully standardized, but \fBmu cfind\fR follows some common -practices: any double-quote is replaced by a double-double quote (thus, "hello" -become ""hello"", and fields with commas are put in double-quotes. Normally, -this should only apply to name fields. - -.TP -\fB\-\-personal\fR only show addresses seen in messages where one of 'my' e-mail -addresses was seen in one of the address fields; this is to exclude addresses -only seen in mailing-list messages. See the \fB\-\-my-address\fR parameter in -\fBmu index\fR. - -.TP -\fB\-\-after=\fR\fI<timestamp>\fR only show addresses last seen after -\fI<timestamp>\fR. \fI<timestamp>\fR is a UNIX \fBtime_t\fR value, the number of -seconds since 1970-01-01 (in UTC). - -From the command line, you can use the \fBdate\fR command to get this value. For -example, only consider addresses last seen after 2009-06-01, you could specify -.nf - --after=`date +%s --date='2009-06-01'` -.fi - -.SH RETURN VALUE - -\fBmu cfind\fR returns 0 upon successful completion -- that is, at least one -contact was found. Anything else leads to a non-zero return value: - -.nf -| code | meaning | -|------+--------------------------------| -| 0 | ok | -| 1 | general error | -| 2 | no matches (for 'mu cfind') | -.fi - -.SH INTEGRATION WITH MUTT - -You can use \fBmu cfind\fR as an external address book server for \fBmutt\fR. -For this to work, add the following to your \fImuttrc\fR: - -.nf -set query_command = "mu cfind --format=mutt-ab '%s'" -.fi - -Now, in mutt, you can search for e-mail addresses using the \fBquery\fR-command, -which is (by default) accessible by pressing \fBQ\fR. - -.SH ENCODING - -\fBmu cfind\fR output is encoded according to the current locale except for -\fI--format=bbdb\fR. This is hard-coded to UTF-8, and as such specified in the -output-file, so emacs/bbdb can handle things correctly, without guessing. - -.SH BUGS - -Please report bugs if you find them at \fBhttps://github.com/djcb/mu/issues\fR. - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu (1), -.BR mu-index (1), -.BR mu-find (1), -.BR pcrepattern(3) diff --git a/man/mu-cfind.1.org b/man/mu-cfind.1.org new file mode 100644 index 0000000..91aae03 --- /dev/null +++ b/man/mu-cfind.1.org @@ -0,0 +1,116 @@ +#+title: MU CFIND + +* NAME + +*mu cfind* is the *mu* command to find contacts in the *mu* database and export them +for use in other programs. + +* SYNOPSIS + +*mu [common-options] cfind [options] [<pattern>]* + +* DESCRIPTION + +*mu cfind* is the *mu* command for finding =contacts= (name and e-mail address of +people who were either an e-mail's sender or receiver). There are different +output formats available, for importing the contacts into other programs. + +* SEARCHING CONTACTS + +When you index your messages (see *mu index*), *mu* creates a list of unique e-mail +addresses found and the accompanying name, and caches this list. In case the +same e-mail address is used with different names, the most recent non-empty name +is used. + +*mu cfind* starts a search for contacts that match a =regular expression=. For +example: + +#+begin_example +$ mu cfind '@gmail\.com' +#+end_example + +would find all contacts with a gmail-address, while + +#+begin_example +$ mu cfind Mary +#+end_example + +lists all contacts with Mary in either name or e-mail address. + +If you do not specify a search expression, *mu cfind* returns the full list of +contacts. Note, *mu cfind* uses a cache with the e-mail information, which is +populated during the indexing process. + +The regular expressions are Perl-compatible (as per the PCRE-library used by +GRegex). + +* CFIND OPTIONS + +** --format=plain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv +sets the output format to the given value. The following are available: + +| --format= | description | +|-------------+-----------------------------------| +| plain | default, simple list | +| mutt-alias | mutt alias-format | +| mutt-ab | mutt external address book format | +| wl | wanderlust addressbook format | +| org-contact | org-mode org-contact format | +| bbdb | BBDB format | +| csv | comma-separated values [1] | + + +[1] *CSV is not fully standardized, but *mu cfind* follows some common practices: +any double-quote is replaced by a double-double quote (thus, "hello" become +""hello"", and fields with commas are put in double-quotes. Normally, this +should only apply to name fields. + +** --personal,-p only show addresses seen in messages where one of 'my' e-mail +addresses was seen in one of the address fields; this is to exclude addresses +only seen in mailing-list messages. See the ~--my-address~ parameter to *mu init*. + +# ** --after=<timestamp> only show addresses last seen after +# =<timestamp>=. =<timestamp>= is a UNIX *time_t* value, the number of +# seconds since 1970-01-01 (in UTC). + +# From the command line, you can use the *date* command to get this value. For +# example, only consider addresses last seen after 2009-06-01, you could specify +# #+begin_example +# --after=`date +%s --date='2009-06-01'` +# #+end_example + +#+include: "muhome.inc" :minlevel 2 + +#+include: "common-options.inc" :minlevel 1 + +* INTEGRATION WITH MUTT + +You can use *mu cfind* as an external address book server for *mutt*. +For this to work, add the following to your =muttrc=: + +#+begin_example +set query_command = "mu cfind --format=mutt-ab '%s'" +#+end_example + +Now, in mutt, you can search for e-mail addresses using the *query*-command, +which is (by default) accessible by pressing *Q*. + +* ENCODING + +*mu cfind* output is encoded according to the current locale except for +=--format=bbdb=. This is hard-coded to UTF-8, and as such specified in the +output-file, so emacs/bbdb can handle things correctly, without guessing. + +* EXIT CODE + +This command returns 0 upon successful completion, or a non-zero exit code +otherwise: 1 for a generals error and 2 for 'no matches'. + +#+include: "bugs.inc" :minlevel 1 + +#+include: "author.inc" :minlevel 1 + +#+include: "copyright.inc" :minlevel 1 + +* SEE ALSO +*mu(1)*, *mu-index(1)*, *mu-find(1)* diff --git a/man/mu-easy.1 b/man/mu-easy.5.org index 27e9258..27e9258 100644 --- a/man/mu-easy.1 +++ b/man/mu-easy.5.org diff --git a/man/mu-extract.1 b/man/mu-extract.1 deleted file mode 100644 index 35d96ce..0000000 --- a/man/mu-extract.1 +++ /dev/null @@ -1,100 +0,0 @@ -.TH MU EXTRACT 1 "July 2012" "User Manuals" - -.SH NAME - -\fBmu extract\fR is the \fBmu\fR command to display and save message parts -(attachments), and open them with other tools. - -.SH SYNOPSIS - -.B mu extract [options] <file> - -.B mu extract [options] <file> <pattern> - -.SH DESCRIPTION - -\fBmu extract\fR is the \fBmu\fR sub-command for extracting MIME-parts (e.g., -attachments) from mail messages. The sub-command works on message files, and -does not require the message to be indexed in the database. - -For attachments, the file name used when saving it is the name of the -attachment in the message. If there is no such name, or when saving -non-attachment MIME-parts, a name is derived from the message-id of the -message. - -If you specify a pattern (a case-insensitive regular expression) as the second -argument, all attachments with filenames matching that pattern will be -extracted. The regular expressions are Perl-compatible (as per the -PCRE-library). - -Without any options, \fBmu extract\fR simply outputs the list of leaf -MIME-parts in the message. Only 'leaf' MIME-parts (including RFC822 -attachments) are considered, \fBmultipart/*\fR etc. are ignored. - -.SH OPTIONS - -.TP -\fB\-a\fR, \fB\-\-save\-attachments\fR -save all MIME-parts that look like attachments. - -.TP -\fB\-\-save\-all\fR -save all non-multipart MIME-parts. - -.TP -\fB\-\-parts\fR=<parts> -only consider the following numbered parts -(comma-separated list). The numbers for the parts can be seen from running -\fBmu extract\fR without any options but only the message file. - -.TP -\fB\-\-target\-dir\fR=<dir> -save the parts in the target directory rather than -the current working directory. - -.TP -\fB\-\-overwrite\fR -overwrite existing files with the same name; by default overwriting is not -allowed. - -.TP -\fB\-\-play\fR Try to 'play' (open) the attachment with the default -application for the particular file type. On MacOS, this uses the \fBopen\fR -program, on other platforms it uses \fBxdg-open\fR. You can choose a different -program by setting the \fBMU_PLAY_PROGRAM\fR environment variable. - -.SH EXAMPLES - -To display information about all the MIME-parts in a message file: -.nf - $ mu extract msgfile -.fi - -To extract MIME-part 3 and 4 from this message, overwriting existing files -with the same name: -.nf - $ mu extract --parts=3,4 --overwrite msgfile -.fi - -To extract all files ending in '.jpg' (case-insensitive): -.nf - $ mu extract msgfile '.*\.jpg' -.fi - -To extract an mp3-file, and play it in the default mp3-playing application: -.nf - $ mu extract --play msgfile 'whoopsididitagain.mp3' -.fi - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu (1) diff --git a/man/mu-extract.1.org b/man/mu-extract.1.org new file mode 100644 index 0000000..ceade67 --- /dev/null +++ b/man/mu-extract.1.org @@ -0,0 +1,89 @@ +#+title: MU EXTRACT + +* NAME + +*mu extract* is the *mu* command to display and save message parts +(attachments), and open them with other tools. + +* SYNOPSIS + +*mu [common-options] extract [options] <file>* + +*mu [common-options] extract [options] <file> <pattern>* + +* DESCRIPTION + +*mu extract* is the *mu* sub-command for extracting MIME-parts (e.g., attachments) +from mail messages. The sub-command works on message files, and does not require +the message to be indexed in the database. + +For attachments, the file name used when saving it is the name of the attachment +in the message. If there is no such name, or when saving non-attachment +MIME-parts, a name is derived from the message-id of the message. + +If you specify a pattern (a case-insensitive regular expression) as the second +argument, all attachments with filenames matching that pattern will be +extracted. The regular expressions are Perl-compatible (as per the +PCRE-library). + +Without any options, *mu extract* simply outputs the list of leaf MIME-parts in +the message. Only 'leaf' MIME-parts (including RFC822 attachments) are +considered, *multipart/** etc. are ignored. + +* EXTRACT OPTIONS + +** -a, --save-attachments +save all MIME-parts that look like attachments. + +** --save-all +save all non-multipart MIME-parts. + +** --parts=<parts> +only consider the following numbered parts (comma-separated list). The numbers +for the parts can be seen from running *mu extract* without any options but only +the message file. + +** --target-dir=<dir> +save the parts in the target directory rather than the current working +directory. + +** --overwrite +overwrite existing files with the same name; by default overwriting is not +allowed. + +** --play +Try to 'play' (open) the attachment with the default application for the +particular file type. On MacOS, this uses the *open* program, on other platforms +it uses *xdg-open*. You can choose a different program by setting the +*MU_PLAY_PROGRAM* environment variable. + +#+include: "common-options.inc" :minlevel 1 + +* EXAMPLES + +To display information about all the MIME-parts in a message file: +#+begin_example +$ mu extract msgfile +#+end_example + +To extract MIME-part 3 and 4 from this message, overwriting existing files with +the same name: +#+begin_example +$ mu extract --parts=3,4 --overwrite msgfile +#+end_example + +To extract all files ending in '.jpg' (case-insensitive): +#+begin_example +$ mu extract msgfile '.*\.jpg' +#+end_example + +To extract an mp3-file, and play it in the default mp3-playing application: +#+begin_example +$ mu extract --play msgfile 'whoopsididitagain.mp3' +#+end_example + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO + +*mu(1)* diff --git a/man/mu-fields.1 b/man/mu-fields.1 deleted file mode 100644 index e86c22a..0000000 --- a/man/mu-fields.1 +++ /dev/null @@ -1,32 +0,0 @@ -.TH MU FIELDS 1 "April 2022" "User Manuals" - -.SH NAME - -mu fields\- list all message fields - -.SH SYNOPSIS - -.B mu fields [options] - -.SH DESCRIPTION - -\fBmu fields\fR is the \fBmu\fR command for showing a table of message fields -and their properties. - -.SH OPTIONS - -Inherits common options from -.BR mu(1) - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu (1) diff --git a/man/mu-fields.1.org b/man/mu-fields.1.org new file mode 100644 index 0000000..79e78e9 --- /dev/null +++ b/man/mu-fields.1.org @@ -0,0 +1,22 @@ +#+title: MU FIELDS + +* NAME + +*mu fields* - list all message fields + +* SYNOPSIS + +*mu [common-options] fields + +* DESCRIPTION + +*mu fields* is the *mu* command for showing a table of message fields and their +properties. + +#+include: "common-options.inc" :minlevel 1 + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO + +*mu(1)* diff --git a/man/mu-find.1 b/man/mu-find.1 deleted file mode 100644 index df2f4d8..0000000 --- a/man/mu-find.1 +++ /dev/null @@ -1,338 +0,0 @@ -.TH MU FIND 1 "29 April 2022" "User Manuals" - -.SH NAME - -mu find \- find e-mail messages in the \fBmu\fR database. - -.SH SYNOPSIS - -.B mu find [options] <search expression> - -.SH DESCRIPTION - -\fBmu find\fR is the \fBmu\fR command for searching e-mail message -that were stored earlier using \fBmu index\fR(1). - -.SH SEARCHING MAIL - -\fBmu find\fR starts a search for messages in the database that match -some search pattern. The search patterns are described in detail in -.BR mu-query (7). -. - -For example: - -.nf - $ mu find subject:snow and date:2009.. -.fi - -would find all messages in 2009 with 'snow' in the subject field, e.g: - -.nf - 2009-03-05 17:57:33 EET Lucia <lucia@example.com> running in the snow - 2009-03-05 18:38:24 EET Marius <marius@foobar.com> Re: running in the snow -.fi - -Note, this the default, plain-text output, which is the default, so you don't -have to use \fB--format=plain\fR. For other types of output (such as symlinks, -XML or s-expressions), see the discussion in the \fBOPTIONS\fR-section below -about \fB--format\fR. - -The search pattern is taken as a command-line parameter. If the search -parameter consists of multiple parts (as in the example) they are -treated as if there were a logical \fBand\fR between them. - -For details on the possible queries, see -.BR mu-query (7). - -.SH OPTIONS - -Note, some of the important options are described in the \fBmu\fR(1) man-page -and not here, as they apply to multiple mu-commands. - -The \fBfind\fR-command has various options that influence the way \fBmu\fR -displays the results. If you don't specify anything, the defaults are -\fI\-\-fields="d f s"\fR, \fI\-\-sortfield=date\fR and \fI\-\-reverse\fR. - -.TP -\fB\-f\fR, \fB\-\-fields\fR=\fI<fields>\fR -specifies a string that determines which fields are shown in the output. This -string consists of a number of characters (such as 's' for subject or 'f' for -from), which will replace with the actual field in the output. Fields that are -not known will be output as-is, allowing for some simple formatting. - -For example: - -.nf - $ mu find subject:snow --fields "d f s" -.fi - -would list the date, subject and sender of all messages with 'snow' in the -their subject. - -The table of replacement characters is superset of the list mentions for -search parameters, such as: -.nf - t \fBt\fRo: recipient - d Sent \fBd\fRate of the message - f Message sender (\fBf\fRrom:) - g Message flags (fla\fBg\fRs) - l Full path to the message (\fBl\fRocation) - s Message \fBs\fRubject - i Message-\fBi\fRd - m \fBm\fRaildir -.fi - -For the complete, up-to-date list, see: -.BR mu-fields(1) - -The message flags are described in \fBmu-query\fR(7). As an example, a -message which is 'seen', has an attachment and is signed would -have 'asz' as its corresponding output string, while an encrypted new -message would have 'nx'. - -.TP -\fB\-s\fR, \fB\-\-sortfield\fR \fR=\fI<field>\fR and \fB\-z\fR, -\fB\-\-reverse\fR specifies the field to sort the search results by, and the -direction (i.e., 'reverse' means that the sort should be reverted - Z-A). Examples include: - -.nf - cc,c Cc (carbon-copy) recipient(s) - date,d Message sent date - from,f Message sender - maildir,m Maildir - msgid,i Message id - prio,p Nessage priority - subject,s Message subject - to,t To:-recipient(s) -.fi - -For the complete list use can use the \fBmu fields\fR command; see: -.BR mu-fields(1) - -Thus, for example, to sort messages by date, you could specify: - -.nf - $ mu find fahrrad --fields "d f s" --sortfield=date --reverse -.fi - -Note, if you specify a sortfield, by default, messages are sorted in reverse -(descending) order (e.g., from lowest to highest). This is usually a good -choice, but for dates it may be more useful to sort in the opposite direction. - -.TP -\fB\-n\fR, \fB\-\-maxnum=<number>\fR -If > 0, display maximally that number of entries. If not specified, all matching entries are displayed. - -.TP -\fB\-\-summary-len=<number>\fR -If > 0, use that number of lines of the message to provide a summary. - -.TP -\fB\-\-format\fR=\fIplain|links|xquery|xml|sexp\fR -output results in the specified format. - -The default is \fBplain\fR, i.e normal output with one line per message. - -\fBlinks\fR outputs the results as a maildir with symbolic links to the found -messages. This enables easy integration with mail-clients (see below for more -information). - -\fBxml\fR formats the search results as XML. - -\fBsexp\fR formats the search results as an s-expression as used in Lisp -programming environments. - -\fBxquery\fR shows the Xapian query corresponding to your search terms. This -is meant for for debugging purposes. - -.TP -\fB\-\-linksdir\fR \fR=\fI<dir>\fR and \fB\-c\fR, \fB\-\-clearlinks\fR -output the results as a maildir with symbolic links to the found -messages. This enables easy integration with mail-clients (see below -for more information). \fBmu\fR will create the maildir if it does not -exist yet. - -If you specify \fB\-\-clearlinks\fR, all existing symlinks will be -cleared from the target directories; this allows for re-use of the -same maildir. However, this option will delete any symlink it finds, -so be careful. - -.nf - $ mu find grolsch --format=links --linksdir=~/Maildir/search --clearlinks -.fi - -will store links to found messages in \fI~/Maildir/search\fR. If the directory -does not exist yet, it will be created. - -Note: when \fBmu\fR creates a Maildir for these links, it automatically -inserts a \fI.noindex\fR file, to exclude the directory from \fBmu -index\fR. - -.TP -\fB\-\-after=\fR\fI<timestamp>\fR only show messages whose message files were -last modified (\fBmtime\fR) after \fI<timestamp>\fR. \fI<timestamp>\fR is a -UNIX \fBtime_t\fR value, the number of seconds since 1970-01-01 (in UTC). - -From the command line, you can use the \fBdate\fR command to get this -value. For example, only consider messages modified (or created) in the last 5 -minutes, you could specify -.nf - --after=`date +%s --date='5 min ago'` -.fi -This is assuming the GNU \fBdate\fR command. - - -.TP -\fB\-\-exec\fR=\fI<command>\fR -the \fB\-\-exec\fR command causes the \fIcommand\fR to be executed on each -matched message; for example, to see the raw text of all messages -matching 'milkshake', you could use: -.nf - $ mu find milkshake --exec='less' -.fi -which is roughly equivalent to: -.nf - $ mu find milkshake --fields="l" | xargs less -.fi - - -.TP -\fB\-b\fR, \fB\-\-bookmark\fR=\fI<bookmark>\fR -use a bookmarked search query. Using this option, a query from your bookmark -file will be prepended to other search queries. See \fBmu-bookmarks\fR(1) for the -details of the bookmarks file. - - -.TP -\fB\-\-skip\-dups\fR,\fB-u\fR whenever there are multiple messages with the -same name, only show the first one. This is useful if you have copies of the -same message, which is a common occurrence when using e.g. Gmail together with -\fBofflineimap\fR. - -.TP -\fB\-\-include\-related\fR,\fB-r\fR also include messages being referred to by -the matched messages -- i.e.. include messages that are part of the same -message thread as some matched messages. This is useful if you want -Gmail-style 'conversations'. Note, finding these related messages make -searches slower. - -.TP -\fB\-t\fR, \fB\-\-threads\fR show messages in a 'threaded' format -- -that is, with indentation and arrows showing the conversation threads -in the list of matching messages. When using this, sorting is -chronological (by date), based on the newest message in a thread. - -Messages in the threaded list are indented based on the depth in the -discussion, and are prefix with a kind of arrow with thread-related -information about the message, as in the following table: - -.nf -| | normal | orphan | duplicate | -|-------------+--------+--------+-----------| -| first child | `-> | `*> | `=> | -| other | |-> | |*> | |=> | -.fi - -Here, an 'orphan' is a message without a parent message (in the list of -matches), and a duplicate is a message whose message-id was already seen -before; not this may not really be the same message, if the message-id was -copied. - -The algorithm used for determining the threads is based on Jamie Zawinksi's -description: -.BR http://www.jwz.org/doc/threading.html - - -.SS Integrating mu find with mail clients - -.TP - -\fBmutt\fR - -For \fBmutt\fR you can use the following in your \fImuttrc\fR; pressing the F8 -key will start a search, and F9 will take you to the results. - -.nf -# mutt macros for mu -macro index <F8> "<shell-escape>mu find --clearlinks --format=links --linksdir=~/Maildir/search " \\ - "mu find" -macro index <F9> "<change-folder-readonly>~/Maildir/search" \\ - "mu find results" -.fi - - -.TP - -\fBWanderlust\fR - -\fBSam B\fR suggested the following on the \fBmu\fR-mailing list. First add -the following to your Wanderlust configuration file: - -.nf -(require 'elmo-search) -(elmo-search-register-engine - 'mu 'local-file - :prog "/usr/local/bin/mu" ;; or wherever you've installed it - :args '("find" pattern "--fields" "l") :charset 'utf-8) - -(setq elmo-search-default-engine 'mu) -;; for when you type "g" in folder or summary. -(setq wl-default-spec "[") -.fi - -Now, you can search using the \fBg\fR key binding; you can also create -permanent virtual folders when the messages matching some expression by adding -something like the following to your \fIfolders\fR file. - -.nf -VFolders { - [date:today..now]!mu "Today" - - [size:1m..100m]!mu "Big" - - [flag:unread]!mu "Unread" -} -.fi - -After restarting Wanderlust, the virtual folders should appear. - -.SH RETURN VALUE - -\fBmu find\fR returns 0 upon successful completion; if the search was -performed, there needs to be a least one match. Anything else leads to a -non-zero return value, for example: - -.nf -| code | meaning | -|------+--------------------------------| -| 0 | ok | -| 1 | general error | -| 4 | no matches (for 'mu find') | -.fi - - -.SH ENCODING - -\fBmu find\fR output is encoded according the locale for \fI--format=plain\fR -(the default), and UTF-8 for all other formats (\fIsexp\fR, -\fIxml\fR). - - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues -If you have specific messages which are not matched correctly, please attach -them (appropriately censored if needed). - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu (1), -.BR mu-index (1), -.BR mu-query (7) -.BR mu-fields (1) diff --git a/man/mu-find.1.org b/man/mu-find.1.org new file mode 100644 index 0000000..79d4720 --- /dev/null +++ b/man/mu-find.1.org @@ -0,0 +1,288 @@ +#+title: MU FIND + +* NAME + +*mu find* - find e-mail messages in the *mu* database. + +* SYNOPSIS + +*mu [common-options] find [options] <search expression>* + +* DESCRIPTION + +*mu find* is the *mu* command for searching e-mail message that were stored earlier +using *mu index(1)*. + +* SEARCHING MAIL + +*mu find* starts a search for messages in the database that match some search +pattern. The search patterns are described in detail in *mu-query(7)*. + +For example: + +#+begin_example +$ mu find subject:snow and date:2009.. +#+end_example + +would find all messages in 2009 with 'snow' in the subject field, e.g: + +#+begin_example +2009-03-05 17:57:33 EET Lucia <lucia@example.com> running in the snow +2009-03-05 18:38:24 EET Marius <marius@foobar.com> Re: running in the snow +#+end_example + +Note, this the default, plain-text output, which is the default, so you don't +have to use *--format=plain*. For other types of output (such as symlinks, XML or +s-expressions), see the discussion in the *OPTIONS*-section below about *--format*. + +The search pattern is taken as a command-line parameter. If the search +parameter consists of multiple parts (as in the example) they are +treated as if there were a logical *and* between them. + +For details on the possible queries, see *mu-query(7)*. + +* FIND OPTIONS + +Note, some of the important options are described in the *mu*(1) man-page +and not here, as they apply to multiple mu-commands. + +The *find*-command has various options that influence the way *mu* displays the +results. If you don't specify anything, the defaults are ~fields="d f s"~, +~--sortfield=date~ and ~--reverse~. + +** -f, --fields=<fields> +specifies a string that determines which fields are shown in the output. This +string consists of a number of characters (such as 's' for subject or 'f' for +from), which will replace with the actual field in the output. Fields that are +not known will be output as-is, allowing for some simple formatting. + +For example: + +#+begin_example +$ mu find subject:snow --fields "d f s" +#+end_example + +lists the date, subject and sender of all messages with 'snow' in the their +subject. + +The table of replacement characters is superset of the list mentions for search +parameters, such as: +#+begin_example + t *t*o: recipient + d Sent *d*ate of the message + f Message sender (*f*rom:) + g Message flags (fla*g*s) + l Full path to the message (*l*ocation) + s Message *s*ubject + i Message-*i*d + m *m*aildir +#+end_example + +For the complate list, see *mu-fields(1)*. + +The message flags are described in *mu-query(7)*. As an example, a message which +is 'seen', has an attachment and is signed would have 'asz' as its corresponding +output string, while an encrypted new message would have 'nx'. + +** -s, --sortfield=<field> and -z,--reverse +specify the field to sort the search results by and the direction (i.e., +'reverse' means that the sort should be reverted - Z-A). Examples include: + +#+begin_example + cc,c Cc (carbon-copy) recipient(s) + date,d Message sent date + from,f Message sender + maildir,m Maildir + msgid,i Message id + prio,p Nessage priority + subject,s Message subject + to,t To:-recipient(s) +#+end_example + +For the complete list use can use the *mu fields* command; see *mu-fields(1)*. + +Thus, for example, to sort messages by date, you could specify: + +#+begin_example +$ mu find fahrrad --fields "d f s" --sortfield=date --reverse +#+end_example + +Note, if you specify a sortfield, by default, messages are sorted in reverse +(descending) order (e.g., from lowest to highest). This is usually a good +choice, but for dates it may be more useful to sort in the opposite direction. + +** -n, --maxnum=<number> +If > 0, display maximally that number of entries. If not specified, all matching +entries are displayed. + +** --summary-len=<number> +If > 0, use that number of lines of the message to provide a summary. + +** --format=<plain|links|xquery|xml|sexp> + +output results in the specified format: + +- The default is *plain*, i.e normal output with one line per message. +- *links* outputs the results as a maildir with symbolic links to the found + messages. This enables easy integration with mail-clients (see below for more + information). +- *xml* formats the search results as XML. +- *sexp* formats the search results as an s-expression as used in Lisp programming + environments. +- *xquery* shows the Xapian query corresponding to your search terms. This is + meant for for debugging purposes. + +** --linksdir=<dir> and -c, --clearlinks +when using ~-format=links~, output the results as a maildir with symbolic links to +the found messages. This enables easy integration with mail-clients (see below +for more information). *mu* will create the maildir if it does not exist yet. + +If you specify ~--clearlinks~, existing symlinks will be cleared from the target +directories; this allows for re-use of the same maildir. However, this option +will delete any symlink it finds, so be careful. + +#+begin_example +$ mu find grolsch --format=links --linksdir=~/Maildir/search --clearlinks +#+end_example + +stores links to found messages in =~/Maildir/search=. If the directory does not +exist yet, it will be created. Note: when *mu* creates a Maildir for these links, +it automatically inserts a =.noindex= file, to exclude the directory from *mu +index*. + +** --after=<timestamp> +only show messages whose message files were last modified (*mtime*) after +=<timestamp>=. =<timestamp>= is a UNIX *time_t* value, the number of seconds since +1970-01-01 (in UTC). + +From the command line, you can use the *date* command to get this value. For +example, only consider messages modified (or created) in the last 5 minutes, you +could specify +#+begin_example + --after=`date +%s --date='5 min ago'` +#+end_example +This is assuming the GNU *date* command. + +** --exec=<command> +the ~--exec~ coption causes the =command= to be executed on each matched message; +for example, to see the raw text of all messages matching 'milkshake', you could +use: +#+begin_example +$ mu find milkshake --exec='less' +#+end_example +which is roughly equivalent to: +#+begin_example +$ mu find milkshake --fields="l" | xargs less +#+end_example + +** -b, --bookmark=<bookmark> +use a bookmarked search query. Using this option, a query from your bookmark +file will be prepended to other search queries. See *mu-bookmarks(5)* for the +details of the bookmarks file. + + +** -u, --skip-dups +whenever there are multiple messages with the same message-id field, only show +the first one. This is useful if you have copies of the same message, which is a +common occurrence when using e.g. Gmail together with *offlineimap*. + +** -r, --include-related +include messages being referred to by the matched messages -- i.e.. include +messages that are part of the same message thread as some matched messages. This +is useful if you want Gmail-style 'conversations'. + +** -t, --threads +show messages in a 'threaded' format -- that is, with indentation and arrows +showing the conversation threads in the list of matching messages. When using +this, sorting is chronological (by date), based on the newest message in a +thread. + +Messages in the threaded list are indented based on the depth in the discussion, +and are prefix with a kind of arrow with thread-related information about the +message, as in the following table: +#+begin_example +| | normal | orphan | duplicate | +|-------------+--------+--------+-----------| +| first child | `-> | `*> | `=> | +| other | |-> | |*> | |=> | +#+end_example + +Here, an 'orphan' is a message without a parent message (in the list of +matches), and a duplicate is a message whose message-id was already seen before; +not this may not really be the same message, if the message-id was copied. + +The algorithm used for determining the threads is based on Jamie Zawinksi's +description: http://www.jwz.org/doc/threading.html + +#+include: "muhome.inc" :minlevel 2 + +#+include: "common-options.inc" :minlevel 1 + +* Integrating mu find with mail clients + +** *mutt* + +For *mutt* you can use the following in your =muttrc=; pressing the F8 key will +start a search, and F9 will take you to the results. + +#+begin_example +# mutt macros for mu +macro index <F8> "<shell-escape>mu find --clearlinks --format=links --linksdir=~/Maildir/search " \\ + "mu find" +macro index <F9> "<change-folder-readonly>~/Maildir/search" \\ + "mu find results" +#+end_example + + +** *Wanderlust* + +*Sam B* suggested the following on the *mu*-mailing list. First add the following to +your Wanderlust configuration file: + +#+begin_example +(require 'elmo-search) +(elmo-search-register-engine + 'mu 'local-file + :prog "/usr/local/bin/mu" ;; or wherever you've installed it + :args '("find" pattern "--fields" "l") :charset 'utf-8) + +(setq elmo-search-default-engine 'mu) +;; for when you type "g" in folder or summary. +(setq wl-default-spec "[") +#+end_example + +Now, you can search using the *g* key binding; you can also create permanent +virtual folders when the messages matching some expression by adding something +like the following to your =folders= file. + +#+begin_example +VFolders { + [date:today..now]!mu "Today" + [size:1m..100m]!mu "Big" + [flag:unread]!mu "Unread" +} +#+end_example + +After restarting Wanderlust, the virtual folders should appear. + +* ENCODING + +*mu find* output is encoded according the locale for =--format=plain= +(the default), and UTF-8 for all other formats (=sexp=, +=xml=). + + +* EXIT CODE + +This command returns 0 upon successful completion, or a non-zero exit code +otherwise: 1 for a generals error and 2 for 'no matches'. + +#+include: "bugs.inc" :minlevel 1 + +#+include: "author.inc" :minlevel 1 + +#+include: "copyright.inc" :minlevel 1 + +* SEE ALSO + +*mu(1)*, *mu-index(1)*, *mu-query(7)*, *mu-fields(1)* diff --git a/man/mu-help.1 b/man/mu-help.1 deleted file mode 100644 index 80ba090..0000000 --- a/man/mu-help.1 +++ /dev/null @@ -1,34 +0,0 @@ -.TH MU HELP 1 "July 2012" "User Manuals" - -.SH NAME - -\fBmu help\fR is a \fBmu\fR command that gives help information about mu -commands. - -.SH SYNOPSIS - -.B mu help <command> - -.SH DESCRIPTION - -\fBmu help\fR provides help information about mu commands. - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu-index (1), -.BR mu-find (1), -.BR mu-cfind (1), -.BR mu-mkdir (1), -.BR mu-view (1), -.BR mu-extract (1), -.BR mu-easy (1), -.BR mu-bookmarks (5) diff --git a/man/mu-help.1.org b/man/mu-help.1.org new file mode 100644 index 0000000..7144722 --- /dev/null +++ b/man/mu-help.1.org @@ -0,0 +1,19 @@ +#+title: MU HELP + +* NAME + +*mu help* is a *mu* command that gives help information about mu commands. + +* SYNOPSIS + +*mu [common-options] help [<command>]* + +* DESCRIPTION + +*mu help* provides help information about mu commands. + +#+include: "common-options.inc" :minlevel 1 + +#+include: "exit-code.inc" :minlevel 1 + +#+include: "prefooter.inc" :minlevel 1 diff --git a/man/mu-index.1 b/man/mu-index.1 deleted file mode 100644 index d9e9ea3..0000000 --- a/man/mu-index.1 +++ /dev/null @@ -1,196 +0,0 @@ -.TH MU-INDEX 1 "June 2022" "User Manuals" - -.SH NAME - -mu index \- index e-mail messages stored in Maildirs - -.SH SYNOPSIS - -.B mu index [options] - -.SH DESCRIPTION - -\fBmu index\fR is the \fBmu\fR command for scanning the contents of Maildir -directories and storing the results in a Xapian database. The data can then be -queried using -.BR mu-find (1)\. - -Before the first time you run \fBmu index\fR, you must run \fBmu init\fR to -initialize the database. - -\fBindex\fR understands Maildirs as defined by Daniel Bernstein for -\fBqmail\fR(7). In addition, it understands recursive Maildirs (Maildirs within -Maildirs), Maildir++. It can also deal with VFAT-based Maildirs which use '!' -or ';' as the separators instead of ':'. - -E-mail messages which are not stored in something resembling a maildir -leaf-directory (\fIcur\fR and \fInew\fR) are ignored, as are the cache -directories for \fInotmuch\fR and \fIgnus\fR, and any dot-directory. - -Starting with mu 1.5.x, symlinks are followed, and can be spread over multiple -filesystems; however note that moving files around is much faster when multiple -filesystems are not involved. - -If there is a file called \fI.noindex\fR in a directory, the contents of that -directory and all of its subdirectories will be ignored. This can be useful to -exclude certain directories from the indexing process, for example directories -with spam-messages. - -If there is a file called \fI.noupdate\fR in a directory, the contents of that -directory and all of its subdirectories will be ignored, unless we do a full -rebuild (with \fBmu init\fR). This can be useful to speed up things you have -some maildirs that never change. Note that you can still search for these -messages, this only affects updating the database. \fI.noupdate\fR is ignored -when you start indexing with an empty database (such as directly after \fImu -init\fR. - -There also the \fB--lazy-check\fR which can greatly speed up indexing; see below -for details. - -The first run of \fBmu index\fR may take a few minutes if you have a lot of mail -(tens of thousands of messages). Fortunately, such a full scan needs to be done -only once; after that it suffices to index the changes, which goes much faster. -See the 'Note on performance (i,ii,iii)' below for more information. - -The optional 'phase two' of the indexing-process is the removal of messages from -the database for which there is no longer a corresponding file in the Maildir. -If you do not want this, you can use \fB\-n\fR, \fB\-\-nocleanup\fR. - -When \fBmu index\fR catches one of the signals \fBSIGINT\fR, \fBSIGHUP\fR or -\fBSIGTERM\fR (e.g., when you press Ctrl-C during the indexing process), it -tries to shutdown gracefully; it tries to save and commit data, and close the -database etc. If it receives another signal (e.g., when pressing Ctrl-C once -more), \fBmu index\fR will terminate immediately. - -.SH OPTIONS - -Some of the general options are described in the \fBmu(1)\fR man-page and not -here, as they apply to multiple mu commands. - -.TP -\fB\-\-lazy-check\fR -in lazy-check mode, \fBmu\fR does not consider messages for which the -time-stamp (ctime) of the directory they reside in has not changed -since the previous indexing run. This is much faster than the non-lazy -check, but won't update messages that have change (rather than having -been added or removed), since merely editing a message does not update -the directory time-stamp. Of course, you can run \fBmu-index\fR -occasionally without \fB\-\-lazy-check\fR, to pick up such messages. - -.TP -\fB\-\-nocleanup\fR -disables the database cleanup that \fBmu\fR does by default after indexing. - -.SS A note on performance (i) -As a non-scientific benchmark, a simple test on the author's machine (a -Thinkpad X61s laptop using Linux 2.6.35 and an ext3 file system) with no -existing database, and a maildir with 27273 messages: - -.nf - $ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' - $ time mu index --quiet - 66,65s user 6,05s system 27% cpu 4:24,20 total -.fi -(about 103 messages per second) - -A second run, which is the more typical use case when there is a database -already, goes much faster: - -.nf - $ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' - $ time mu index --quiet - 0,48s user 0,76s system 10% cpu 11,796 total -.fi -(more than 56818 messages per second) - -Note that each test flushes the caches first; a more common use case might -be to run \fBmu index\fR when new mail has arrived; the cache may stay -quite 'warm' in that case: - -.nf - $ time mu index --quiet - 0,33s user 0,40s system 80% cpu 0,905 total -.fi -which is more than 30000 messages per second. - - -.SS A note on performance (ii) -As per June 2012, we did the same non-scientific benchmark, this time with an -Intel i5-2500 CPU @ 3.30GHz, an ext4 file system and a maildir with 22589 -messages. We start without an existing database. - -.nf - $ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' - $ time mu index --quiet - 27,79s user 2,17s system 48% cpu 1:01,47 total -.fi -(about 813 messages per second) - -A second run, which is the more typical use case when there is a database -already, goes much faster: - -.nf - $ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' - $ time mu index --quiet - 0,13s user 0,30s system 19% cpu 2,162 total -.fi -(more than 173000 messages per second) - - -.SS A note on performance (iii) -As per July 2016, we did the same non-scientific benchmark, again with -the Intel i5-2500 CPU @ 3.30GHz, an ext4 file system. This time, the -maildir contains 72525 messages. - -.nf - $ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' - $ time mu index --quiet - 40,34s user 2,56s system 64% cpu 1:06,17 total -.fi -(about 1099 messages per second). - -.SS A note on performance (iv) -A few years later and its June 2022. There's a lot more happening during indexing, but indexing became multi-threaded and machines are faster; e.g. this -is with an AMD Ryzen Threadripper 1950X (32) @ 3.399GHz. - -The instructions are a little different since we have a proper repeatable -benchmark now. After building, - -.nf - $ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' -% THREAD_NUM=4 build/lib/tests/bench-indexer -m perf -# random seed: R02Sf5c50e4851ec51adaf301e0e054bd52b -1..1 -# Start of bench tests -# Start of indexer tests -indexed 5000 messages in 20 maildirs in 3763ms; 752 μs/message; 1328 messages/s (4 thread(s)) -ok 1 /bench/indexer/4-cores -# End of indexer tests -# End of bench tests -.fi - -Things are again a little faster, even though the index does a lot more now -(text-normalizatian, and pre-generating message-sexps). A faster machine helps, -too! - -.SH RETURN VALUE - -\fBmu index\fR return 0 upon successful completion; any other number signals an -error. - -.SH BUGS - -Please report bugs if you find any: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR maildir (5), -.BR mu (1), -.BR mu-init (1), -.BR mu-find (1), -.BR mu-cfind (1) diff --git a/man/mu-index.1.org b/man/mu-index.1.org new file mode 100644 index 0000000..1db1e5f --- /dev/null +++ b/man/mu-index.1.org @@ -0,0 +1,182 @@ +#+title: MU-INDEX + +* NAME + +*mu index* -- index e-mail messages stored in Maildirs + +* SYNOPSIS + +*mu [common-options] index* + +* DESCRIPTION + +*mu index* is the *mu* command for scanning the contents of Maildir directories and +storing the results in a Xapian database. The data can then be queried using +*mu-find(1)*. + +Before the first time you run *mu index*, you must run *mu init* to initialize the +database. + +*index* understands Maildirs as defined by Daniel Bernstein for *qmail(7)*. In +addition, it understands recursive Maildirs (Maildirs within Maildirs), +Maildir++. It also supports VFAT-based Maildirs which use '!' or ';' as the +separators instead of ':'. + +E-mail messages which are not stored in something resembling a maildir +leaf-directory (=cur= and =new=) are ignored, as are the cache directories for +=notmuch= and =gnus=, and any dot-directory. + +Starting with mu 1.5.x, symlinks are followed, and can be spread over multiple +filesystems; however note that moving files around is much faster when multiple +filesystems are not involved. + +If there is a file called =.noindex= in a directory, the contents of that +directory and all of its subdirectories will be ignored. This can be useful to +exclude certain directories from the indexing process, for example directories +with spam-messages. + +If there is a file called =.noupdate= in a directory, the contents of that +directory and all of its subdirectories will be ignored, unless we do a full +rebuild (with *mu init*). This can be useful to speed up things you have some +maildirs that never change. Note that you can still search for these messages, +this only affects updating the database. =.noupdate= is ignored when you start +indexing with an empty database (such as directly after =mu init=. + +There also the *--lazy-check* which can greatly speed up indexing; see below for +details. + +The first run of *mu index* may take a few minutes if you have a lot of mail (tens +of thousands of messages). Fortunately, such a full scan needs to be done only +once; after that it suffices to index the changes, which goes much faster. See +the 'Note on performance (i,ii,iii)' below for more information. + +The optional 'phase two' of the indexing-process is the removal of messages from +the database for which there is no longer a corresponding file in the Maildir. +If you do not want this, you can use ~-n~, ~--nocleanup~. + +When *mu index* catches one of the signals *SIGINT*, *SIGHUP* or *SIGTERM* (e.g., when +you press Ctrl-C during the indexing process), it attempts to shutdown +gracefully; it tries to save and commit data, and close the database etc. If it +receives another signal (e.g., when pressing Ctrl-C once more), *mu index* will +terminate immediately. + +* INDEX OPTIONS + +** --lazy-check +in lazy-check mode, *mu* does not consider messages for which the time-stamp +(ctime) of the directory they reside in has not changed since the previous +indexing run. This is much faster than the non-lazy check, but won't update +messages that have change (rather than having been added or removed), since +merely editing a message does not update the directory time-stamp. Of course, +you can run *mu-index* occasionally without ~--lazy-check~, to pick up such +messages. + +** --nocleanup +disable the database cleanup that *mu* does by default after indexing. + +#+include: "muhome.inc" :minlevel 2 + +#+include: "common-options.inc" :minlevel 1 + +* PERFORMANCE + +** indexing in ancient times (2009?) + +As a non-scientific benchmark, a simple test on the author's machine (a Thinkpad +X61s laptop using Linux 2.6.35 and an ext3 file system) with no existing +database, and a maildir with 27273 messages: + +#+begin_example +$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' +$ time mu index --quiet +66,65s user 6,05s system 27% cpu 4:24,20 total +#+end_example +(about 103 messages per second) + +A second run, which is the more typical use case when there is a database +already, goes much faster: + +#+begin_example +$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' +$ time mu index --quiet +0,48s user 0,76s system 10% cpu 11,796 total +#+end_example +(more than 56818 messages per second) + +Note that each test flushes the caches first; a more common use case might be to +run *mu index* when new mail has arrived; the cache may stay quite 'warm' in that +case: + +#+begin_example + $ time mu index --quiet + 0,33s user 0,40s system 80% cpu 0,905 total +#+end_example +which is more than 30000 messages per second. + +** indexing in 2012 + +As per June 2012, we did the same non-scientific benchmark, this time with an +Intel i5-2500 CPU @ 3.30GHz, an ext4 file system and a maildir with 22589 +messages. We start without an existing database. + +#+begin_example + $ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' + $ time mu index --quiet + 27,79s user 2,17s system 48% cpu 1:01,47 total +#+end_example +(about 813 messages per second) + +A second run, which is the more typical use case when there is a database +already, goes much faster: + +#+begin_example +$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' +$ time mu index --quiet +0,13s user 0,30s system 19% cpu 2,162 total +#+end_example +(more than 173000 messages per second) + +** indexing in 2016 + +As per July 2016, we did the same non-scientific benchmark, again with the Intel +i5-2500 CPU @ 3.30GHz, an ext4 file system. This time, the maildir contains +72525 messages. + +#+begin_example +$ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' +$ time mu index --quiet +40,34s user 2,56s system 64% cpu 1:06,17 total +#+end_example +(about 1099 messages per second). + +** indexing in 2022 + +A few years later and it is June 2022. There's a lot more happening during +indexing, but indexing became multi-threaded and machines are faster; e.g. this +is with an AMD Ryzen Threadripper 1950X (16 cores) @ 3.399GHz. + +The instructions are a little different since we have a proper repeatable +benchmark now. After building, + +#+begin_example + $ sudo sh -c 'sync && echo 3 > /proc/sys/vm/drop_caches' +% THREAD_NUM=4 build/lib/tests/bench-indexer -m perf +# random seed: R02Sf5c50e4851ec51adaf301e0e054bd52b +1..1 +# Start of bench tests +# Start of indexer tests +indexed 5000 messages in 20 maildirs in 3763ms; 752 μs/message; 1328 messages/s (4 thread(s)) +ok 1 /bench/indexer/4-cores +# End of indexer tests +# End of bench tests +#+end_example + +Things are again a little faster, even though the index does a lot more now +(text-normalizatian, and pre-generating message-sexps). A faster machine helps, +too! + +#+include: "prefooter.inc" + +* SEE ALSO + +*maildir(5)*, *mu(1)*, *mu-init(1)*, *mu-find(1)*, *mu-cfind(1)* diff --git a/man/mu-info.1 b/man/mu-info.1 deleted file mode 100644 index ea8e703..0000000 --- a/man/mu-info.1 +++ /dev/null @@ -1,47 +0,0 @@ -.TH MU-INFO 1 "May 2022" "User Manuals" - -.SH NAME - -mu info \- show information about the mu database - -.SH SYNOPSIS - -.B mu info [options] - -.SH DESCRIPTION - -\fBmu info\fR is the \fBmu\fR command for getting information about the mu -database. Note that while running (e.g. \fBmu4e\fR), some of the information -may be slightly delayed due to database caching. - -.SH OPTIONS - -Note, some of the general options are described in the \fBmu(1)\fR man-page and -not here, as they apply to multiple mu commands. - -.TP -\fB\-\-muhome\fR -use an alternative directory to store and read the database, write the logs, -etc. By default, \fBmu\fR uses XDG Base Directory Specification (e.g. on Linux -this defaults to \fI~/.cache/mu\fR, \fI~/.config/mu\fR). Earlier versions of -\fBmu\fR defaulted to \fI~/.mu\fR, which now requires \fI\-\-muhome=~/.mu\fR. - -.SH RETURN VALUE - -\fBmu init\fR returns 0 upon successful completion, or a non-zero exit code if -there was some error. - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR maildir (5), -.BR mu (1), -.BR mu-index (1) diff --git a/man/mu-info.1.org b/man/mu-info.1.org new file mode 100644 index 0000000..36f92f9 --- /dev/null +++ b/man/mu-info.1.org @@ -0,0 +1,25 @@ +#+title: MU-INFO + +* NAME + +~mu info~ - show information about the mu database + +* SYNOPSIS + +*mu [common options] info* + +* DESCRIPTION + +~mu info~ is the ~mu~ command for getting information about the mu database. Note +that while running (e.g. ~mu4e~), some of the information may be slightly delayed +due to database caching. + +#+include: "common-options.inc" :minlevel 1 + +#+include: "exit-code.inc" :minlevel 1 + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO + +*maildir(5)*, *mu(1)* diff --git a/man/mu-init.1 b/man/mu-init.1 deleted file mode 100644 index e5697d4..0000000 --- a/man/mu-init.1 +++ /dev/null @@ -1,79 +0,0 @@ -.TH MU-INIT 1 "May 2022" "User Manuals" - -.SH NAME - -mu init \- initialize the mu message database - -.SH SYNOPSIS - -.B mu init [options] - -.SH DESCRIPTION - -\fBmu init\fR is the subcommand for setting up the mu message -database. After \fBmu init\fR has completed, you can run \fBmu -index\fR - -.SH OPTIONS - -Note, some of the general options are described in the \fBmu(1)\fR -man-page and not here, as they apply to multiple mu commands. - -.TP -\fB\-\-muhome\fR -use an alternative directory to store and read the database, write the logs, -etc. By default, \fBmu\fR uses XDG Base Directory Specification (e.g. on Linux -this defaults to \fI~/.cache/mu\fR, \fI~/.config/mu\fR). - -Earlier versions of \fBmu\fR defaulted to \fI~/.mu\fR, which now requires -\fI\-\-muhome=~/.mu\fR. - -Alternatively, use can use the \fBMUHOME\fR environment variable (the command-line takes precedence). - -.TP -\fB\-m\fR, \fB\-\-maildir\fR=\fI<maildir>\fR -starts searching at \fI<maildir>\fR. By default, \fBmu\fR uses whatever the -\fBMAILDIR\fR environment variable is set to; if it is not set, it tries -\fI~/Maildir\fR if it already exists. - -.TP -\fB\-\-my-address\fR=\fI<my-email-address>\fR -specifies that some e-mail addresses are 'my-address' (\fB\-\-my-address\fR can -be used multiple times). This is used by \fBmu cfind\fR -- any e-mail address -found in the address fields of a message which also has \fI<my-email-address>\fR -in one of its address fields is considered a \fIpersonal\fR e-mail address. This -allows you, for example, to filter out (\fBmu cfind --personal\fR) addresses -which were merely seen in mailing list messages. - -\fI<my-email-address>\fR can be either a plain e-mail address (such as -\fBfoo@example.com\fR), or a regular-expression (of the 'Basic POSIX' flavor), -wrapped in \fB/\fR (such as \fB/foo-.*@example\\.com/\fR). Depending on your -shell program, the argument may need to b quoted. - -.SH ENVIRONMENT - -\fBmu init\fR uses \fBMAILDIR\fR to find the user's Maildir if it has not been -specified explicitly with \fB\-\-maildir\fR=\fI<maildir>\fR. If \fBMAILDIR\fR is -not set, \fBmu init\fR uses \fI~/Maildir\fR. - -\fBMUHOME\fR can be used as an alternative to \fB\-\-muhome\fR. - -.SH RETURN VALUE - -\fBmu init\fR returns 0 upon successful completion, or a non-zero exit code if -there was some error. - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR maildir (5), -.BR mu (1), -.BR mu-index (1) diff --git a/man/mu-init.1.org b/man/mu-init.1.org new file mode 100644 index 0000000..5fc9ace --- /dev/null +++ b/man/mu-init.1.org @@ -0,0 +1,42 @@ +#+title: MU-INIT + +* NAME + +mu init -- initialize the mu message database + +* SYNOPSIS + +*mu [common-options] init [options]* + +* DESCRIPTION + +*mu init* is the subcommand for setting up the mu message database. After *mu init* +has completed, you can run *mu index* + +* INIT OPTIONS + +** -m, --maildir=<maildir> +starts searching at =<maildir>=. By default, *mu* uses whatever the *MAILDIR* +environment variable is set to; if it is not set, it tries =~/Maildir= if it +already exists. + +** --my-address=<my-email-address> + +specifies that some e-mail addresses are 'my-address' (the option can be used +multiple times). Any message in which at least one of the contact fields +contains such an address is considered a 'personal' messages; this can then be +used for filtering in *mu-find(1)*, *mu-cfind(1)* and *mu4e*, e.g. to filter-out +mailing list messages. + +=<my-email-address>= can be either a plain e-mail address (such as +*foo@example.com*), or a regular-expression (of the 'Basic POSIX' flavor), wrapped +in */* (such as =/foo-.*@example\\.com/=). Depending on your shell, the argument may +need to b quoted. + +#+include: "muhome.inc" :minlevel 2 + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO + +*mu-index(1)*, *mu-find(1)*, *mu-cfind(1)* diff --git a/man/mu-mkdir.1 b/man/mu-mkdir.1 deleted file mode 100644 index 6f9ddd2..0000000 --- a/man/mu-mkdir.1 +++ /dev/null @@ -1,45 +0,0 @@ -.TH MU MKDIR 1 "July 2012" "User Manuals" - -.SH NAME - -mu mkdir\- create a new Maildir - -.SH SYNOPSIS - -.B mu mkdir [options] <dir> [<dirs>] - -.SH DESCRIPTION - -\fBmu mkdir\fR is the \fBmu\fR command for creating Maildirs. It does -\fBnot\fR use the mu database. With the \fBmkdir\fR command, you can create -new Maildirs with permissions 0755. For example, - -.nf - mu mkdir tom dick harry -.fi - -creates three maildirs, \fItom\fR, \fIdick\fR and \fIharry\fR. - -If creation fails for any reason, \fBno\fR attempt is made to remove any parts -that were created. This is for safety reasons. - -.SH OPTIONS - -.TP -\fB\-\-mode\fR=<mode> -set the file access mode for the new maildir(s) as in \fBchmod(1)\fR. - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR maildir (5), -.BR mu (1), -.BR chmod (1) diff --git a/man/mu-mkdir.1.org b/man/mu-mkdir.1.org new file mode 100644 index 0000000..c2e9edf --- /dev/null +++ b/man/mu-mkdir.1.org @@ -0,0 +1,37 @@ +#+title: MU MKDIR + +* NAME + +*mu mkdir* - create a new Maildir + +* SYNOPSIS + +*mu [common-options] mkdir [options] <dir> [<dirs>]* + +* DESCRIPTION + +*mu mkdir* is the *mu* command for creating Maildirs. It does not* use the mu +*database. With the *mkdir* command, you can create new Maildirs with +*permissions 0755. For example, + +#+begin_example +$ mu mkdir tom dick harry +#+end_example + +creates three maildirs, =tom=, =dick= and =harry=. + +If creation fails for any reason, *no* attempt is made to remove any parts that +were created. This is for safety reasons. + +* MKDIR OPTIONS + +** --mode=<mode> +set the file access mode for the new maildir(s) as in *chmod(1)*. + +#+include: "common-options.inc" :minlevel 1 + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO + +*maildir(5)*, *chmod(1)* diff --git a/man/mu-query.7 b/man/mu-query.7 deleted file mode 100644 index ca1800a..0000000 --- a/man/mu-query.7 +++ /dev/null @@ -1,361 +0,0 @@ -.TH MU QUERY 7 "22 April 2022" "User Manuals" - -.SH NAME - -mu query language \- a language for finding messages in \fBmu\fR databases. - -.SH DESCRIPTION - -The mu query language is a language used by \fBmu find\fR and \fBmu4e\fR to find -messages in \fBmu\fR's Xapian databases. The language is quite similar to -Xapian's default query-parser, but is an independent implementation that is -customized for the mu/mu4e use-case. - -In this article, we give a structured but informal overview of the query -language and provide examples. - -As a companion to this, we recommend the \fBmu fields\fR and \fBmu flags\fR -commands to get an up-to-date list of the available fields and flags. - -\fBNOTE:\fR if you use queries on the command-line (say, for \fBmu find\fR), you -need to quote any characters that would otherwise be interpreted by the shell, -such as \fB""\fR, \fB(\fR and \fB)\fR and whitespace. - -.de EX1 -.nf -.RS -.. - -.de EX2 -.RE -.fi -.. - -.SH TERMS - -The basic building blocks of a query are \fBterms\fR; these are just -normal words like 'banana' or 'hello', or words prefixed with a -field-name which make them apply to just that field. See -\fBmu find\fR -for all the available fields. - -Some example queries: -.EX1 -vacation -subject:capybara -maildir:/inbox -.EX2 - -Terms without an explicit field-prefix, (like 'vacation' above) are -interpreted like: -.EX1 -to:vacation or subject:vacation or body:vacation or ... -.EX2 - -The language is case-insensitive for terms and attempts to 'flatten' -any diacritics, so \fIangtrom\fR matches \fIÅngström\fR. - -.PP -If terms contain whitespace, they need to be quoted: -.EX1 -subject:"hi there" -.EX2 -This is a so-called \fIphrase query\fR, which means that we match -against subjects that contain the literal phrase "hi there". - -Remember that you need to escape those quotes when using this from the -command-line: -.EX1 -mu find subject:\\"hi there\\" -.EX2 - -.SH LOGICAL OPERATORS - -We can combine terms with logical operators -- binary ones: \fBand\fR, -\fBor\fR, \fBxor\fR and the unary \fBnot\fR, with the conventional -rules for precedence and association, and are case-insensitive. - -.PP -You can also group things with \fB(\fR and \fB)\fR, so you can do -things like: -.EX1 -(subject:beethoven or subject:bach) and not body:elvis -.EX2 - -If you do not explicitly specify an operator between terms, \fBand\fR -is implied, so the queries -.EX1 -subject:chip subject:dale -.EX2 -.EX1 -subject:chip AND subject:dale -.EX2 -are equivalent. For readability, we recommend the second version. - -Note that a \fIpure not\fR - e.g. searching for \fBnot apples\fR is -quite a 'heavy' query. - -.SH REGULAR EXPRESSIONS AND WILDCARDS - -The language supports matching regular expressions that follow -ECMAScript; for details, see - -.BR http://www.cplusplus.com/reference/regex/ECMAScript/ - -Regular expressions must be enclosed in \fB//\fR. Some examples: -.EX1 -subject:/h.llo/ # match hallo, hello, ... -subject:/ -.EX2 - -Note the difference between 'maildir:/foo' and 'maildir:/foo/'; the -former matches messages in the '/foo' maildir, while the latter -matches all messages in all maildirs that match 'foo', such -as '/foo', '/bar/cuux/foo', '/fooishbar' etc. - -Wildcards are an older mechanism for matching where a term with a -rightmost \fB*\fR (and \fIonly\fR in that position) matches any term -that starts with the part before the \fB*\fR; they are supported for -backward compatibility and \fBmu\fR translates them to regular -expressions internally: -.EX1 -foo* -.EX2 -is equivalent to -.EX1 -/foo.*/ -.EX2 - -As a note of caution, certain wild-cards and regular expression can -take quite a bit longer than 'normal' queries. - -.SH FIELDS - -We already saw a number of search fields, such as \fBsubject:\fR and -\fBbody:\fR. For the full table, see \fBmu fields\fR. -.EX1 - bcc,h Bcc (blind-carbon-copy) recipient(s) - body,b Message body - cc,c Cc (carbon-copy) recipient(s) - changed,k Last change to message file (range) - date,d Send date (range) - embed,e Search inside embedded text parts - file,j Attachment filename - flag,g Message Flags - from,f Message sender - list,v Mailing list (e.g. the List-Id value) - maildir,m Maildir - mime,y MIME-type of one or more message parts - msgid,i Message-ID - prio,p Message priority (\fIlow\fR, \fInormal\fR or \fIhigh\fR) - size,z Message size range - subject,s Message subject - tag,x Tags for the message - thread,w Thread a message belongs to - to,t To: recipient(s) - -The \fBmu fields\fR command is recommended to get the latest version. -.EX2 -The shortcut character can be used instead of the full name: -.EX1 -f:foo@bar -.EX2 -is the same as -.EX1 -from:foo@bar -.EX2 -For queries that are not one-off, we would recommend the longer name -for readability. - -There are also the special fields \fBcontact:\fR, which matches all -contact-fields (\fIfrom\fR, \fIto\fR, \fIcc\fR and \fIbcc\fR), and -\fBrecip\fR, which matches all recipient-fields (\fIto\fR, \fIcc\fR -and \fIbcc\fR). Hence, for instance, -.EX1 -contact:fnorb@example.com -.EX2 -is equivalent to -.EX1 -(from:fnorb@example.com or to:fnorb@example.com or - cc:from:fnorb@example.com or bcc:fnorb@example.com) -.EX2 - -.SH DATE RANGES - -The \fBdate:\fR field takes a date-range, expressed as the lower and -upper bound, separated by \fB..\fR. Either lower or upper (but not -both) can be omitted to create an open range. - -Dates are expressed in local time and using ISO-8601 format -(YYYY-MM-DD HH:MM:SS); you can leave out the right part, and \fBmu\fR -adds the rest, depending on whether this is the beginning or end of -the range (e.g., as a lower bound, '2015' would be interpreted as the -start of that year; as an upper bound as the end of the year). - -You can use '/' , '.', '-' and 'T' to make dates more human readable. - -Some examples: -.EX1 -date:20170505..20170602 -date:2017-05-05..2017-06-02 -date:..2017-10-01T12:00 -date:2015-06-01.. -date:2016..2016 -.EX2 - -You can also use the special 'dates' \fBnow\fR and \fBtoday\fR: -.EX1 -date:20170505..now -date:today.. -.EX2 - -Finally, you can use relative 'ago' times which express some time -before now and consist of a number followed by a unit, with units -\fBs\fR for seconds, \fBM\fR for minutes, \fBh\fR for hours, \fBd\fR -for days, \fBw\fR for week, \fBm\fR for months and \fBy\fR for years. -Some examples: - -.EX1 -date:3m.. -date:2017.01.01..5w -.EX2 - -.SH SIZE RANGES - -The \fBsize\fR or \fBz\fR field allows you to match \fIsize ranges\fR --- that is, match messages that have a byte-size within a certain -range. Units (b (for bytes), K (for 1000 bytes) and M (for 1000 * 1000 -bytes) are supported). Some examples: - -.EX1 -size:10k..2m -size:10m.. -.EX2 - -.SH FLAG FIELDS - -The \fBflag\fR/\fBg\fR field allows you to match message flags. The -following fields are available: -.EX1 - a,attach Message with attachment - d,draft Draft Message - f,flagged Flagged - l,list Mailing-list message - n,new New message (in new/ Maildir) - p,passed Passed ('Handled') - r,replied Replied - s,seen Seen - t,trashed Marked for deletion - u,unread new OR NOT seen - x,encrypted Encrypted message - z,signed Signed message -.EX2 - -Some examples: -.EX1 -flag:attach -flag:replied -g:x -.EX2 - -Encrypted messages may be signed as well, but this is only visible -after decrypting and thus, invisible to \fBmu\fR. - -.SH PRIORITY FIELD - -The message priority field (\fBprio:\fR) has three possible values: -\fBlow\fR, \fBnormal\fR or \fBhigh\fR. For instance, to match -high-priority messages: -.EX1 - prio:high -.EX2 - -.SH MAILDIR - -The Maildir field describes the directory path starting \fBafter\fR -the Maildir-base path, and before the \fI/cur/\fR or \fI/new/\fR part. -So for example, if there's a message with the file name -\fI~/Maildir/lists/running/cur/1234.213:2,\fR, you could find it (and -all the other messages in the same maildir) with: -.EX1 -maildir:/lists/running -.EX2 - -Note the starting '/'. If you want to match mails in the 'root' -maildir, you can do with a single '/': -.EX1 -maildir:/ -.EX2 - -If you have maildirs (or any fields) that include spaces, you need to -quote them, ie. -.EX1 -maildir:"/Sent Items" -.EX2 - -Note that from the command-line, such queries must be quoted: -.EX1 -mu find 'maildir:"/Sent Items"' -.EX2 - -.SH MORE EXAMPLES - -Here are some simple examples of \fBmu\fR queries; you can make many -more complicated queries using various logical operators, parentheses -and so on, but in the author's experience, it's usually faster to find -a message with a simple query just searching for some words. - -Find all messages with both 'bee' and 'bird' (in any field) -.EX1 -bee AND bird -.EX2 - -Find all messages with either Frodo or Sam: -.EX1 -Frodo OR Sam -.EX2 - -Find all messages with the 'wombat' as subject, and 'capybara' anywhere: -.EX1 -subject:wombat and capybara -.EX2 - -Find all messages in the 'Archive' folder from Fred: -.EX1 -from:fred and maildir:/Archive -.EX2 - -Find all unread messages with attachments: -.EX1 -flag:attach and flag:unread -.EX2 - - -Find all messages with PDF-attachments: -.EX1 -mime:application/pdf -.EX2 - -Find all messages with attached images: -.EX1 -mime:image/* -.EX2 - -.SH CAVEATS - -With current Xapian versions, the apostroph character is considered part of a -word. Thus, you cannot find \fID'Artagnan\fR by searching for \fIArtagnan\fR. -So, include the apostroph in search or use a regexp search. - -Matching on spaces has changed compared to the old query-parser; this applies -e.g. to Maildirs that have spaces in their name, such as \fISent Items\fR. See -\fBMAILDIR\fR above. - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu-find (1) -.BR mu-fields (1) diff --git a/man/mu-query.7.org b/man/mu-query.7.org new file mode 100644 index 0000000..ff3d896 --- /dev/null +++ b/man/mu-query.7.org @@ -0,0 +1,334 @@ +#+title: MU QUERY + +* NAME + +mu query language -- a language for finding messages in *mu* databases. + +* DESCRIPTION + +The mu query language is a language used by *mu find* and *mu4e* to find messages in +*mu*'s Xapian databases. The language is quite similar to Xapian's default +query-parser, but is an independent implementation that is customized for the +mu/mu4e use-case. + +In this article, we give a structured but informal overview of the query +language and provide examples. + +As a companion to this, we recommend the *mu fields* and *mu flags* commands to get +an up-to-date list of the available fields and flags. + +*NOTE:* if you use queries on the command-line (say, for *mu find*), you need to +quote any characters that would otherwise be interpreted by the shell, such as +*""*, *(* and *)* and whitespace. + +* TERMS + +The basic building blocks of a query are *terms*; these are just normal words like +'banana' or 'hello', or words prefixed with a field-name which make them apply +to just that field. See *mu find* for all the available fields. + +Some example queries: +#+begin_example +vacation +subject:capybara +maildir:/inbox +#+end_example + +Terms without an explicit field-prefix, (like 'vacation' above) are interpreted +like: +#+begin_example +to:vacation or subject:vacation or body:vacation or ... +#+end_example + +The language is case-insensitive for terms and attempts to 'flatten' any +diacritics, so =angtrom= matches =Ångström=. + +If terms contain whitespace, they need to be quoted: +#+begin_example +subject:"hi there" +#+end_example +This is a so-called =phrase query=, which means that we match against subjects +that contain the literal phrase "hi there". + +Remember that you need to escape those quotes when using this from the +command-line: +#+begin_example +mu find subject:\\"hi there\\" +#+end_example + +* LOGICAL OPERATORS + +We can combine terms with logical operators -- binary ones: *and*, *or*, *xor* and the +unary *not*, with the conventional rules for precedence and association, and are +case-insensitive. + + +You can also group things with *(* and *)*, so you can do things like: +#+begin_example +(subject:beethoven or subject:bach) and not body:elvis +#+end_example + +If you do not explicitly specify an operator between terms, *and* is implied, so +the queries +#+begin_example +subject:chip subject:dale +#+end_example +#+begin_example +subject:chip AND subject:dale +#+end_example +are equivalent. For readability, we recommend the second version. + +Note that a =pure not= - e.g. searching for *not apples* is quite a 'heavy' query. + +* REGULAR EXPRESSIONS AND WILDCARDS + +The language supports matching regular expressions that follow ECMAScript; for +details, see http://www.cplusplus.com/reference/regex/ECMAScript/ + +Regular expressions are enclosed in *//*. Some examples: +#+begin_example +subject:/h.llo/ # match hallo, hello, ... +subject:/ +#+end_example + +Note the difference between 'maildir:/foo' and 'maildir:/foo/'; the former +matches messages in the '/foo' maildir, while the latter matches all messages in +all maildirs that match 'foo', such as '/foo', '/bar/cuux/foo', '/fooishbar' +etc. + +Wildcards are an older mechanism for matching where a term with a rightmost *** +(and =only= in that position) matches any term that starts with the part before +the ***; they are supported for backward compatibility and *mu* translates them to +regular expressions internally: +#+begin_example +foo* +#+end_example +is equivalent to +#+begin_example +/foo.*/ +#+end_example + +As a note of caution, certain wild-cards and regular expression can take quite a +bit longer than 'normal' queries. + +* FIELDS + +We already saw a number of search fields, such as *subject:* and *body:*. For the +full table, see *mu-fields(1)*. +#+begin_example + bcc,h Bcc (blind-carbon-copy) recipient(s) + body,b Message body + cc,c Cc (carbon-copy) recipient(s) + changed,k Last change to message file (range) + date,d Send date (range) + embed,e Search inside embedded text parts + file,j Attachment filename + flag,g Message Flags + from,f Message sender + list,v Mailing list (e.g. the List-Id value) + maildir,m Maildir + mime,y MIME-type of one or more message parts + msgid,i Message-ID + prio,p Message priority (=low=, =normal= or =high=) + size,z Message size range + subject,s Message subject + tag,x Tags for the message + thread,w Thread a message belongs to + to,t To: recipient(s) +#+end_example + +The shortcut character can be used instead of the full name: +#+begin_example +f:foo@bar +#+end_example +is the same as +#+begin_example +from:foo@bar +#+end_example +For queries that are not one-off, we would recommend the longer name +for readability. + +There are also the special fields *contact:*, which matches all contact-fields +(=from=, =to=, =cc= and =bcc=), and *recip*, which matches all recipient-fields (=to=, =cc= +and =bcc=). Hence, for instance, +#+begin_example +contact:fnorb@example.com +#+end_example +is equivalent to +#+begin_example +(from:fnorb@example.com or to:fnorb@example.com or + cc:from:fnorb@example.com or bcc:fnorb@example.com) +#+end_example + +* DATE RANGES + +The *date:* field takes a date-range, expressed as the lower and upper bound, +separated by *..*. Either lower or upper (but not both) can be omitted to create +an open range. + +Dates are expressed in local time and using ISO-8601 format (YYYY-MM-DD +HH:MM:SS); you can leave out the right part, and *mu* adds the rest, depending on +whether this is the beginning or end of the range (e.g., as a lower bound, +'2015' would be interpreted as the start of that year; as an upper bound as the +end of the year). + +You can use '/' , '.', '-' and 'T' to make dates more human readable. + +Some examples: +#+begin_example +date:20170505..20170602 +date:2017-05-05..2017-06-02 +date:..2017-10-01T12:00 +date:2015-06-01.. +date:2016..2016 +#+end_example + +You can also use the special 'dates' *now* and *today*: +#+begin_example +date:20170505..now +date:today.. +#+end_example + +Finally, you can use relative 'ago' times which express some time before now and +consist of a number followed by a unit, with units *s* for seconds, *M* for minutes, +*h* for hours, *d* for days, *w* for week, *m* for months and *y* for years. Some +examples: + +#+begin_example +date:3m.. +date:2017.01.01..5w +#+end_example + +* SIZE RANGES + +The *size* or *z* field allows you to match =size ranges= -- that is, match messages +that have a byte-size within a certain range. Units (b (for bytes), K (for 1000 +bytes) and M (for 1000 * 1000 bytes) are supported). Some examples: + +#+begin_example +size:10k..2m +size:10m.. +#+end_example + +* FLAG FIELD + +The *flag/g* field allows you to match message flags. The following fields are +available: +#+begin_example + a,attach Message with attachment + d,draft Draft Message + f,flagged Flagged + l,list Mailing-list message + n,new New message (in new/ Maildir) + p,passed Passed ('Handled') + r,replied Replied + s,seen Seen + t,trashed Marked for deletion + u,unread new OR NOT seen + x,encrypted Encrypted message + z,signed Signed message +#+end_example + +Some examples: +#+begin_example +flag:attach +flag:replied +g:x +#+end_example + +Encrypted messages may be signed as well, but this is only visible after +decrypting and thus invisible to *mu*. + +* PRIORITY FIELD + +The message priority field (*prio:*) has three possible values: *low*, *normal* or +*high*. For instance, to match high-priority messages: +#+begin_example +prio:high +#+end_example + +* MAILDIR + +The Maildir field describes the directory path starting *after* the Maildir-base +path, and before the =/cur/= or =/new/= part. So for example, if there's a message +with the file name =~/Maildir/lists/running/cur/1234.213:2,=, you could find it +(and all the other messages in the same maildir) with: +#+begin_example +maildir:/lists/running +#+end_example + +Note the starting '/'. If you want to match mails in the 'root' maildir, you can +do with a single '/': +#+begin_example +maildir:/ +#+end_example + +If you have maildirs (or any fields) that include spaces, you need to quote +them, ie. +#+begin_example +maildir:"/Sent Items" +#+end_example + +Note that from the command-line, such queries must be quoted: +#+begin_example +mu find 'maildir:"/Sent Items"' +#+end_example + +* MORE EXAMPLES + +Here are some simple examples of *mu* queries; you can make many more complicated +queries using various logical operators, parentheses and so on, but in the +author's experience, it's usually faster to find a message with a simple query +just searching for some words. + +Find all messages with both 'bee' and 'bird' (in any field) +#+begin_example +bee AND bird +#+end_example + +Find all messages with either Frodo or Sam: +#+begin_example +Frodo OR Sam +#+end_example + +Find all messages with the 'wombat' as subject, and 'capybara' anywhere: +#+begin_example +subject:wombat and capybara +#+end_example + +Find all messages in the 'Archive' folder from Fred: +#+begin_example +from:fred and maildir:/Archive +#+end_example + +Find all unread messages with attachments: +#+begin_example +flag:attach and flag:unread +#+end_example + + +Find all messages with PDF-attachments: +#+begin_example +mime:application/pdf +#+end_example + +Find all messages with attached images: +#+begin_example +mime:image/* +#+end_example + +* CAVEATS + +With current Xapian versions, the apostroph character is considered part of a +word. Thus, you cannot find =D'Artagnan= by searching for =Artagnan=. So, include +the apostroph in search or use a regexp search. + +Matching on spaces has changed compared to the old query-parser; this applies +e.g. to Maildirs that have spaces in their name, such as =Sent Items=. See *MAILDIR* +above. + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO + +*mu-find(1)*, *mu-fields(1)* diff --git a/man/mu-remove.1 b/man/mu-remove.1 deleted file mode 100644 index e0aa212..0000000 --- a/man/mu-remove.1 +++ /dev/null @@ -1,48 +0,0 @@ -.TH MU REMOVE 1 "May 2022" "User Manuals" - -.SH NAME - -\fBmu remove\fR is the \fBmu\fR command to remove messages from the database. - -.SH SYNOPSIS - -.B mu remove [options] <file> [<files>] - -.SH DESCRIPTION - -\fBmu remove\fR removes specific messages from the database, each of them -specified by their filename. The files do not have to exist in the file -system. - -.SH OPTIONS - -\fBmu remove\fR does not have its own options, but the general options for -determining the location of the database (\fI--muhome\fR) are available. See -\fBmu-index(1)\fR for more information. - -.SH RETURN VALUE - -\fBmu remove\fR returns 0 upon success; in general, the following error codes are -returned: - -.nf -| code | meaning | -|------+-----------------------------------| -| 0 | ok | -| 1 | general error | -.fi - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu (1), -.BR mu-index (1), -.BR mu-add (1) diff --git a/man/mu-remove.1.org b/man/mu-remove.1.org new file mode 100644 index 0000000..1b6b099 --- /dev/null +++ b/man/mu-remove.1.org @@ -0,0 +1,26 @@ +#+title: MU REMOVE + +* NAME + +*mu remove* - command to remove messages from the database. + +* SYNOPSIS + +*mu [common-options] remove [options] <file> [<files>]* + +* DESCRIPTION + +*mu remove* removes specific messages from the database, each of them specified by +their filename. The files do not have to exist in the file system. + +* REMOVE OPTIONS + +#+include: "muhome.inc" :minlevel 2 + +#+include: "common-options.inc" :minlevel 1 + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO + +*mu(1)*, *mu-index(1)*, *mu-add(1)* diff --git a/man/mu-script.1 b/man/mu-script.1 deleted file mode 100644 index ec3f032..0000000 --- a/man/mu-script.1 +++ /dev/null @@ -1,84 +0,0 @@ -.TH MU SCRIPT 1 "October 2021" "User Manuals" - -.SH NAME - -mu script\- show the available mu scripts, and/or run them. - -.SH SYNOPSIS - -.B mu script [options] [<pattern>] - -.B mu <script-name> [<script-options>] - -.SH DESCRIPTION - -\fBmu script\fR is the \fBmu\fR command to list available \fBmu\fR scripts. -The scripts are to be implemented in the Guile programming language, and -therefore only work if your \fBmu\fR is built with support for Guile. In -addition, many scripts require you to have \fBgnuplot\fR installed. - -Without any parameters, \fBmu script\fR lists the available scripts. If you -provide a pattern (a regular expression), only the scripts whose name or -one-line description match this pattern are listed. See the examples below. - -\fBmu\fR ships with a number of scripts. - -.SH OPTIONS - -.TP -\fB\-\-verbose\fR,\fB\-v\fR -when listing the available scripts, show the long descriptions. - -\fB\-\-\fR -all options on the right side of the \fB\-\-\fR are passed to the script. - -.SH EXAMPLES - -List all available scripts (one-line descriptions): -.nf - $ mu script -.fi - -List all available scripts matching \fImonth\fR (long descriptions): -.nf - $ mu script -v month -.fi - -Run the \fImsgs-per-month\fR script for messages matching 'hello', and pass it -the \fI--textonly\fR parameter: -.nf - $ mu msgs-per-month --query=hello --textonly -.fi - -.SH RETURN VALUE - -\fBmu script\fR returns 0 when all went well, and returns some non-zero error -code when this is not the case. - -.SH FILES - -You can make your own Scheme scripts accessible through \fBmu script\fR by -putting them in either \fI<XDG_DATA_HOME>/mu/scripts\fR (e.g., \fI~/.local/share/mu/scripts\fR) or, if \fImuhome\fR is specified, in - -It is a good idea to document the scripts by using some -special comments in the source code: -.nf -;; INFO: this is my script -- one-line description -;; INFO: (longer description) -;; INFO: --option1=<foo> (describe option1) -;; INFO: etc. -.fi - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu (1), -.BR guile (1) diff --git a/man/mu-server.1 b/man/mu-server.1 deleted file mode 100644 index 087483c..0000000 --- a/man/mu-server.1 +++ /dev/null @@ -1,61 +0,0 @@ -.TH MU-SERVER 1 "January 2020" "User Manuals" - -.SH NAME - -mu server \- the mu backend for the mu4e e-mail client - -.SH SYNOPSIS - -.B mu server [options] - -.SH DESCRIPTION - -\fBmu server\fR starts a simple shell in which one can query and manipulate the -mu database. The output uses s-expressions. \fBmu server\fR is not meant for use -by humans, except for debugging purposes. Instead, it is designed specifically -for the \fBmu4e\fR e-mail client. - -In this man-page, we document the commands \fBmu server\fR accepts, as well as -their responses. In general, the commands sent to the server are s-expressions -of the form: - -.nf - (<command-name> :param1 value1 :param2 value2) -.fi - -For example, to view a certain message, the command would be: - -.nf - (view :docid 12345) -.fi - -Parameters can be sent in any order; they must be of the correct type though. -See \fBlib/utils/mu-sexp-parser.hh\fR and \fBlib/utils/mu-sexp-parser.cc\fR in -source-tree for the details. - - -.SH OUTPUT FORMAT - -\fBmu server\fR accepts a number of commands, and delivers its results in -the form: - -.nf - \\376<length>\\377<s-expr> -.fi - -\\376 (one byte 0xfe), followed by the length of the s-expression expressed as -an hexadecimal number, followed by another \\377 (one byte 0xff), followed by -the actual s-expression. - -By prefixing the expression with its length, it can be processed more -efficiently. The \\376 and \\377 were chosen since they never occur in valid -UTF-8 (in which the s-expressions are encoded). - -.sh COMMANDS - - -.SH AUTHOR -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" -.BR mu (1) diff --git a/man/mu-server.1.org b/man/mu-server.1.org new file mode 100644 index 0000000..65d0d69 --- /dev/null +++ b/man/mu-server.1.org @@ -0,0 +1,69 @@ +#+title: MU-SERVER + +* NAME + +mu server - the mu backend for the mu4e e-mail client + +* SYNOPSIS + +mu [common-options] server + +* DESCRIPTION + +*mu server* starts a simple shell in which one can query and manipulate the mu +database. The output uses s-expressions. *mu server* is not meant for use by +humans, except for debugging purposes. Instead, it is designed specifically for +the *mu4e* e-mail client. + +In this man-page, we document the commands *mu server* accepts, as well as their +responses. In general, the commands sent to the server are s-expressions of the +form: + +#+begin_example + (<command-name> :param1 value1 :param2 value2) +#+end_example + +For example, to view a certain message, the command would be: + +#+begin_example + (view :docid 12345) +#+end_example + +Parameters can be sent in any order; they must be of the correct type though. +See *lib/utils/mu-sexp-parser.hh* and *lib/utils/mu-sexp-parser.cc* in source-tree +for the details. + +* OUTPUT FORMAT + +*mu server* accepts a number of commands, and delivers its results in the form: + +#+begin_example + \\376<length>\\377<s-expr> +#+end_example + +\\376 (one byte 0xfe), followed by the length of the s-expression expressed as +an hexadecimal number, followed by another \\377 (one byte 0xff), followed by +the actual s-expression. + +By prefixing the expression with its length, it can be processed more +efficiently. The \\376 and \\377 were chosen since they never occur in valid +UTF-8 (in which the s-expressions are encoded). + +* SERVER OPTIONS + +** --commands + +List available commands (and try with ~--verbose~) + +** --eval <expression> + +Evaluate a mu4e server s-expression + +#+include: "muhome.inc" :minlevel 2 + +#+include: "common-options.inc" :minlevel 1 + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO +*mu(1)* diff --git a/man/mu-verify.1 b/man/mu-verify.1 deleted file mode 100644 index 652db95..0000000 --- a/man/mu-verify.1 +++ /dev/null @@ -1,69 +0,0 @@ -.TH MU VERIFY 1 "April 2022" "User Manuals" - -.SH NAME - -mu verify\- verify message signatures and display information about them - -.SH SYNOPSIS - -.B mu verify [options] <msgfile> - -.SH DESCRIPTION - -\fBmu verify\fR is the \fBmu\fR command for verifying message signatures (such -as PGP/GPG signatures) and displaying information about them. The sub-command -works on message files, and does not require the message to be indexed in the -database. - -.SH OPTIONS - -.TP -\fB\-r\fR, \fB\-\-auto\-retrieve\fR -attempt to find keys online (see the \fBauto-key-retrieve\fR option in the -\fBgnupg(1)\fR documentation). - -.SH EXAMPLES - -To display aggregated (one-line) information about the verification status in a -message: -.nf - $ mu verify msgfile -.fi - -To display information about all the signatures: -.nf - $ mu verify --verbose msgfile -.fi - -If you only want to use the exit code, you can use: -.nf - $ mu verify --quiet msgfile -.fi -which does not give any output unless there is an error. - -.SH RETURN VALUE - -\fBmu verify\fR returns 0 when all signatures could be verified to be good, and -returns some non-zero error code when this is not the case. - -When there are no signatures, returns 0 as well. - -.nf -| code | meaning | -|------+--------------------------------| -| 0 | ok | -| 1 | some non-verified signature(s) | -.fi - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu (1) diff --git a/man/mu-verify.1.org b/man/mu-verify.1.org new file mode 100644 index 0000000..1a321e8 --- /dev/null +++ b/man/mu-verify.1.org @@ -0,0 +1,51 @@ +#+title: MU VERIFY + +* NAME + +mu verify - verify message signatures and display information about them + +* SYNOPSIS + +*mu [common-options] verify [options] <msgfile>* + +* DESCRIPTION + +*mu verify* is the *mu* command for verifying message signatures (such as PGP/GPG +signatures) and displaying information about them. The sub-command works on +message files, and does not require the message to be indexed in the database. + +* VERIFY OPTIONS + +** -r, --auto-retrieve +attempt to find keys online (see the *auto-key-retrieve* option in the *gnupg(1)* +documentation). + +** decrypt +attempt to decrypt the message + +#+include: "common-options.inc" :minlevel 1 + +* EXAMPLES + +To display aggregated (one-line) information about the verification status in a +message: +#+begin_example +$ mu verify msgfile +#+end_example + +To display information about all the signatures: +#+begin_example +$ mu verify --verbose msgfile +#+end_example + +If you only want to use the exit code, you can use: +#+begin_example +$ mu verify --quiet msgfile +#+end_example +which does not give any output unless there is an error. + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO + +*mu(1)* diff --git a/man/mu-view.1 b/man/mu-view.1 deleted file mode 100644 index 8dc746d..0000000 --- a/man/mu-view.1 +++ /dev/null @@ -1,53 +0,0 @@ -.TH MU VIEW 1 "April 2022" "User Manuals" - -.SH NAME - -mu view\- display an e-mail message file - -.SH SYNOPSIS - -.B mu view [options] <file> [<files>] - -.SH DESCRIPTION - -\fBmu view\fR is the \fBmu\fR command for displaying e-mail message files. It -works on message files and does \fInot\fR require the message to be indexed in -the database. - -The command shows some common headers (From:, To:, Cc:, Bcc:, Subject: and -Date:), the list of attachments and the plain-text body of the message (if -any). - -.SH OPTIONS - -.TP -\fB\-\-summary-len\fR=\fI<number>\fR -instead of displaying the full message, output a summary based upon the first -\fI<number>\fR lines of the message. - -.TP -\fB\-\-terminate\fR -terminate messages with \\f (\fIform-feed\fR) characters when displaying -them. This is useful when you want to further process them. - -.TP -\fB\-\-decrypt\fR -attempt to decrypt encrypted message bodies. This is only possible if \fBmu\fR -was built with crypto-support. - -.TP -\fB\-\-auto-retrieve\fR -attempt to retrieve crypto-keys automatically from the network, when needed. - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" - -.BR mu (1) diff --git a/man/mu-view.1.org b/man/mu-view.1.org new file mode 100644 index 0000000..391b3bb --- /dev/null +++ b/man/mu-view.1.org @@ -0,0 +1,42 @@ +#+title: MU VIEW + +* NAME + +mu view - display an e-mail message file + +* SYNOPSIS + +mu [common options] view [options] <file> [<files>] + +* DESCRIPTION + +*mu view* is the *mu* command for displaying e-mail message files. It works on +message files and does =not= require the message to be indexed in the database. + +The command shows some common headers (From:, To:, Cc:, Bcc:, Subject: and +Date:), the list of attachments and the plain-text body of the message (if any). + +* VIEW OPTIONS + +** --summary-len=<number> +instead of displaying the full message, output a summary based upon the first +=<number>= lines of the message. + +** --terminate +terminate messages with \\f (=form-feed=) characters when displaying them. This is +useful when you want to further process them. + +** --decrypt +attempt to decrypt encrypted message bodies. This is only possible if *mu* +was built with crypto-support. + +** --auto-retrieve +attempt to retrieve crypto-keys automatically from the network, when needed. + +#+include: "common-options.inc" :minlevel 1 + +* BUGS + +* SEE ALSO + +*mu(1)* diff --git a/man/mu.1 b/man/mu.1 deleted file mode 100644 index 95469e9..0000000 --- a/man/mu.1 +++ /dev/null @@ -1,188 +0,0 @@ -.TH MU 1 "May 2022" "User Manuals" - -.SH NAME - -mu \- a set of tools to deal with Maildirs and message files, in particular to -index and search e-mail messages. - -.SH SYNOPSIS - -In alphabetical order: - -.B mu [options] -general mu command. - -.B mu add -add specific messages to the database. See -.BR mu-add(1) - -.B mu cfind [options] [<regexp>] -find contacts. See -.BR mu-cfind(1) - -.B mu extract [options] <file> [<parts>] [<regexp>] -extract attachments and other MIME-parts. See -.BR mu-extract(1) - -.B mu find [options] <search expression> -find messages. See -.BR mu-find(1) - -.B mu help [command] -get help for some command. See -.BR mu-help(1) - -.B mu index [options] -(re)index the messages in a Maildir. See -.BR mu-index(1) - -.B mu info [options] -show information about the mu database -.BR mu-info(1) - -.B mu init [options] -initialize the mu database -.BR mu-init(1) - -.B mu mkdir [options] <dir> [<dirs>] -create a new Maildir. See -.BR mu-mkdir(1) - -.B mu remove [options] -remove specific messages from the database. See -.BR mu-remove(1) - -.B mu script [options] -run a mu (Guile) script. See -.BR mu-script(1) - -.B mu server [options] -start a server process (for \fBmu4e\fR-internal use). See -.BR mu-server(1) - -.B mu view <file> [<files>] -view a specific message. See -.BR mu-view(1) - -.SH DESCRIPTION - -\fBmu\fR is a set of tools for dealing with Maildirs and the e-mail messages -in them. - -\fBmu\fR's main purpose is to enable searching of e-mail messages. It -does so by periodically scanning a Maildir directory tree and -analyzing the e-mail messages found (this is called 'indexing'). The -results of this analysis are stored in a database, which can then be -queried. - -In addition to indexing and searching, \fBmu\fR also offers -functionality for viewing messages, extracting attachments and -creating maildirs, and searching and exporting contact information. - -\fBmu\fR can be used from the command line or can be integrated with various -e-mail clients. - -This manpage gives a general overview of the available commands -(\fBindex\fR, \fBfind\fR, etc.); each \fBmu\fR command has its own -man-page as well. - -.SH COLORS - -Some \fBmu\fR sub-commands support colorized output, and do so by -default. If you don't want colors, you can use \fI--nocolor\fR. - -Currently, \fBmu find\fR, \fBmu view\fR, \fBmu cfind\fR and \fBmu extract\fR -support colors. - -.SH ENCODING - -\fBmu\fR's output is in the current locale, with the exceptions of the output -specifically meant for output to UTF8-encoded files. In practice, this means -that the output of commands \fBindex\fR, \fBview\fR, -\fBextract\fR is always encoded according to the current locale. - -The same is true for \fBfind\fR and \fBcfind\fR, with some exceptions, where -the output is always UTF-8, regardless of the locale. - -For \fBcfind\fR the exception is \fI--format=bbdb\fR. This is hard-coded to -UTF-8, and as such specified in the output-file, so emacs/bbdb can handle it -correctly without guessing. - -For \fBfind\fR the output is encoded according the locale for -\fI--format=plain\fR (the default), and UTF-8 for all other formats -(\fIjson\fR, \fIsexp\fR, \fIxml\fR). - -.SH DATABASE AND FILE - -Commands \fBmu index\fR and \fBfind\fR and \fBcfind\fR work with the database, -while the other ones work on individual mail files. Hence, running \fBview\fR, -\fBmkdir\fR and \fBextract\fR does not require the mu database. - -The various commands are discussed in more detail in their own separate -man-pages; here the general options are discussed. - -.SH OPTIONS - -\fBmu\fR offers several general options that apply to all commands, -including \fBmu\fR without any command. - -.TP -\fB\-\-muhome\fR -use an alternative directory to store and read the database, write the logs, -etc. By default, \fBmu\fR uses XDG Base Directory Specification (e.g. on Linux -by default \fI~/.cache/mu\fR, \fI~/.config/mu\fR). Earlier versions of \fBmu\fR defaulted -to \fI~/.mu\fR, which now requires \fI\-\-muhome=~/.mu\fR. - -.TP -\fB\-d\fR, \fB\-\-debug\fR -makes \fBmu\fR generate extra debug information, -useful for debugging the program itself. By default, debug information goes to -the log file, \fI~/.cache/mu/mu.log\fR. It can safely be deleted when \fBmu\fR is -not running. When running with \fB--debug\fR option, the log file can grow -rather quickly. See the note on logging below. - -.TP -\fB\-q\fR, \fB\-\-quiet\fR -causes \fBmu\fR not to output informational -messages and progress information to standard output, but only to the log -file. Error messages will still be sent to standard error. Note that \fBmu -index\fR is \fBmuch\fR faster with \fB\-\-quiet\fR, so it is recommended you -use this option when using \fBmu\fR from scripts etc. - -.TP -\fB\-\-log-stderr\fR -causes \fBmu\fR to \fBnot\fR output log messages to standard error, in -addition to sending them to the log file. - -.TP -\fB\-V\fR, \fB\-\-version\fR -prints \fBmu\fR version and copyright information. - -.TP -\fB\-h\fR, \fB\-\-help\fR -lists the various command line options. - -.SH ENVIRONMENT - -\fBMUHOME\fR can be used as an alternative to \fB\-\-muhome\fR. The latter has precedence. - -\fBNO_COLOR\fR can be used as an alternative to \fB\-\-nocolor\fR. - -.SH ERROR CODES - -The various mu subcommands typically exit with 0 (zero) upon success, and -non-zero when some error occurred. - -.SH BUGS - -Please report bugs if you find them: -.BR https://github.com/djcb/mu/issues - -.SH AUTHOR - -Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> - -.SH "SEE ALSO" -.BR mu-index (1), mu-find (1), mu-cfind (1), mu-mkdir (1), mu-view (1), -.BR mu-extract (1), mu-easy (1), mu-bookmarks (5), mu-query (7) -.BR https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html diff --git a/man/mu.1.org b/man/mu.1.org new file mode 100644 index 0000000..c4c3f69 --- /dev/null +++ b/man/mu.1.org @@ -0,0 +1,89 @@ +#+title: MU + +* NAME + +~mu~ - a set of tools to deal with Maildirs and message files, in particular to +index and search e-mail messages. + +* SYNOPSIS + +~mu~ [COMMON-OPTIONS] [[COMMAND] [COMMAND-OPTIONS]] + +For information about the commmon options, see *COMMON OPTIONS*. + +* DESCRIPTION + +~mu~ is the general command shows help about the specific commands: + +- ~add~: add specific messages to the database. +- ~cfind~: find contacts +- ~extract~: extract attachments and other MIME-parts +- ~find~: find messages in the database +- ~help~: get help for some command +- ~index~: (re)index the messages in a Maildir +- ~info~: show information about the mu database +- ~init~: initialize the mu database +- ~mkdir~: create a new Maildir +- ~remove~: remove specific messages from the database +- ~server~: start a server process (for ~mu4e~-internal use) +- ~view~: view a specific message + +Each of the commands have their own manpage ~mu-<command~>~. + +~mu~ is a set of tools for dealing with Maildirs and the e-mail messages +in them. + +~mu~'s main purpose is to enable searching of e-mail messages. It +does so by periodically scanning a Maildir directory tree and +analyzing the e-mail messages found (this is called 'indexing'). The +results of this analysis are stored in a database, which can then be +queried. + +In addition to indexing and searching, ~mu~ also offers +functionality for viewing messages, extracting attachments and +creating maildirs, and searching and exporting contact information. + +~mu~ can be used from the command line or can be integrated with various +e-mail clients. + +This manpage gives a general overview of the available commands +(~index~, ~find~, etc.); each ~mu~ command has its own +man-page as well. + +* COLORS + +Some ~mu~ commands support colorized output, and do so by default. If you don't +want colors, you can use ~--nocolor~. + +* ENCODING + +~mu~'s output is in the current locale, with the exceptions of the output +specifically meant for output to UTF8-encoded files. In practice, this means +that the output of commands ~index~, ~view~, ~extract~ is always encoded according to +the current locale. + +The same is true for ~find~ and ~cfind~, with some exceptions, where +the output is always UTF-8, regardless of the locale: + +- For ~cfind~ the exception is ~--format=bbdb~. This is hard-coded to UTF-8, and as + such specified in the output-file, so emacs/bbdb can handle it correctly + without guessing. +- For ~find~ the output is encoded according the locale for ~--format=plain~ (the + default), and UTF-8 for all other formats. + +* DATABASE AND FILE + +Commands ~mu index~ and ~find~ and ~cfind~ work with the database, while the other +ones work on individual mail files. Hence, running ~view~, ~mkdir~ and ~extract~ does +not require the mu database. + +#+include: "common-options.inc" :minlevel 1 + +#+include: "exit-code.inc" :minlevel 1 + +#+include: "prefooter.inc" :minlevel 1 + +* SEE ALSO +~mu-add(1)~, ~mu-cfind(1)~, ~mu-extract(1)~, ~mu-find(1)~, ~mu-help(1)~, ~mu-index(1)~, +~mu-info(1)~, ~mu-init(1)~, ~mu-mkdir(1)~, ~mu-remove(1)~, ~mu-server(1)~, ~mu-view(1)~, +~mu-query(7)~, ~mu-easy(1)~ diff --git a/man/muhome.inc b/man/muhome.inc new file mode 100644 index 0000000..8b312a2 --- /dev/null +++ b/man/muhome.inc @@ -0,0 +1,12 @@ +** --muhome +use a non-default directory to store and read the database, write the logs, etc. +By default, ~mu~ uses the XDG Base Directory Specification (e.g. on GNU/Linux this +defaults to =~/.cache/mu= and =~/.config/mu=). Earlier versions of ~mu~ defaulted to +=~/.mu=, which now requires =--muhome=~/.mu=. + +The environment variable ~MUHOME~ can be used as an alternative to ~--muhome~. The +latter has precedence. + +# Local Variables: +# mode: org +# End: diff --git a/man/prefooter.inc b/man/prefooter.inc new file mode 100644 index 0000000..79c6e40 --- /dev/null +++ b/man/prefooter.inc @@ -0,0 +1,9 @@ +#+include: "bugs.inc" :minlevel 1 + +#+include: "author.inc" :minlevel 1 + +#+include: "copyright.inc" :minlevel 1 + +# Local Variables: +# mode: org +# End: |