mu: implement init, info commands

'init' is for the inital database setup

'info' is for gettting information about the mu database.

6 files changed, 162 insertions, 50 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
index a058c4e..c5ce281 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,4 +1,4 @@
-## Copyright (C) 2008-2019 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
+## Copyright (C) 2008-2020 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 ##
 ## This program is free software; you can redistribute it and/or modify
 ## it under the terms of the GNU General Public License as published by
@@ -25,6 +25,8 @@ dist_man_MANS =		\
 	mu-find.1	\
 	mu-help.1	\
 	mu-index.1	\
+	mu-info.1	\
+	mu-init.1	\
 	mu-mkdir.1	\
 	mu-query.7	\
 	mu-remove.1	\
diff --git a/man/mu-easy.1 b/man/mu-easy.1
index 630fca6..34dce8b 100644
--- a/man/mu-easy.1
+++ b/man/mu-easy.1
@@ -1,4 +1,4 @@
-.TH MU-EASY 1 "December 2012" "User Manuals"
+.TH MU-EASY 1 "February 2020" "User Manuals"
 
 .SH NAME
 
@@ -6,25 +6,35 @@ mu easy \- a quick introduction to mu
 
 .SH DESCRIPTION
 
-\fBmu\fR is a set of tools for dealing with e-mail messages in
-Maildirs. There are many options, which are all described in the man
-pages for the various sub-commands. This man pages jumps over all of
-the details and gives examples of some common use cases. If the use
-cases described here do not precisely do what you want, please check
-the more extensive information in the man page about the sub-command
-you are using -- for example, the \fBmu-index\fR(1) or \fBmu-find\fR(1)
-man pages.
-
-\fBNOTE\fR: the \fBindex\fR command (and therefore, the ones that
-depend on that, such as \fBfind\fR), require that you store your mail
-in the Maildir-format. If you don't do so, you can still use the other
-commands, but you won't be able to index/search your mail.
-
-By default, \fBmu\fR uses colorized output when it thinks your
-terminal is capable of doing so. If you don't like color, you can use
-the \fB--nocolor\fR command-line option, or set either the
-\fBMU_NOCOLOR\fR or the \fBNO_COLOR\fR environment variable to
-non-empty.
+\fBmu\fR is a set of tools for dealing with e-mail messages in Maildirs. There
+are many options, which are all described in the man pages for the various
+sub-commands. This man pages jumps over all of the details and gives examples of
+some common use cases. If the use cases described here do not precisely do what
+you want, please check the more extensive information in the man page about the
+sub-command you are using -- for example, the \fBmu-index\fR(1) or
+\fBmu-find\fR(1) man pages.
+
+\fBNOTE\fR: the \fBindex\fR command (and therefore, the ones that depend on
+that, such as \fBfind\fR), require that you store your mail in the
+Maildir-format. If you don't do so, you can still use the other commands, but
+you won't be able to index/search your mail.
+
+By default, \fBmu\fR uses colorized output when it thinks your terminal is
+capable of doing so. If you don't like color, you can use the \fB--nocolor\fR
+command-line option, or set either the \fBMU_NOCOLOR\fR or the \fBNO_COLOR\fR
+environment variable to non-empty.
+
+.SH SETTING THINGS UP
+
+The first time you run the mu commands, you need to initialize it. This is done
+with the \fBinit\fR command.
+
+.nf
+  \fB$ mu init\fR
+.fi
+
+This uses the defaults (see \fBmu-init(1)\fR for details on how to change that).
+
 
 .SH INDEXING YOUR E-MAIL
 
@@ -294,6 +304,7 @@ Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 
 .SH "SEE ALSO"
 .BR mu (1),
+.BR mu-init (1),
 .BR mu-index (1),
 .BR mu-find (1),
 .BR mu-mfind (1),
diff --git a/man/mu-index.1 b/man/mu-index.1
index 29be1e3..a8a7a80 100644
--- a/man/mu-index.1
+++ b/man/mu-index.1
@@ -1,4 +1,4 @@
-.TH MU-INDEX 1 "July 2016" "User Manuals"
+.TH MU-INDEX 1 "February 2020" "User Manuals"
 
 .SH NAME
 
@@ -15,6 +15,9 @@ directories and storing the results in a Xapian database. The data can then be
 queried using
 .BR mu-find (1)\.
 
+Note that 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
@@ -62,22 +65,6 @@ 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\-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. See the note on mixing sub-maildirs below.
-
-.TP
-\fB\-\-my-address\fR=\fI<my-email-address>\fR
-specifies that some e-mail address is '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.
-
-.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
@@ -190,17 +177,6 @@ case-insensitve/accent-insensitive matching). The profiles are
 dominated by operations in the Xapian database now.
 
 .SH FILES
-By default, \fBmu index\fR stores its message database in \fI~/.mu/xapian\fR;
-the database has an embedded version number, and \fBmu\fR will automatically
-update it when it notices a different version. This allows for automatic
-updating of \fBmu\fR-versions, without the need to clear out any old
-databases.
-
-However, note that versions of \fBmu\fR before 0.7 used a different scheme,
-which puts the database in \fI~/.mu/xapian\-<version>\fR. These older
-databases can safely be deleted. Starting from version 0.7, this manual
-cleanup should no longer be needed.
-
 \fBmu\fR stores logs of its operations and queries in \fI<muhome>/mu.log\fR
 (by default, this is \fI~/.mu/mu.log\fR). Upon startup, \fBmu\fR checks the
 size of this log file. If it exceeds 1 MB, it will be moved to
@@ -232,5 +208,6 @@ Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 
 .BR maildir (5),
 .BR mu (1),
+.BR mu-init (1),
 .BR mu-find (1),
 .BR mu-cfind (1)
diff --git a/man/mu-info.1 b/man/mu-info.1
new file mode 100644
index 0000000..43032be
--- /dev/null
+++ b/man/mu-info.1
@@ -0,0 +1,46 @@
+.TH MU-INFO 1 "February 2020" "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.
+
+.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-init.1 b/man/mu-init.1
new file mode 100644
index 0000000..a270b46
--- /dev/null
+++ b/man/mu-init.1
@@ -0,0 +1,68 @@
+.TH MU-INIT 1 "February 2020" "User Manuals"
+
+.SH NAME
+
+mu init \- initialize the mu message database
+
+.SH SYNOPSIS
+
+.B mu init [options]
+
+.SH DESCRIPTION
+
+\fBmu init\fR is the \fBmu\fR command 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.
+
+.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.
+
+.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.
+
+.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.
+
+.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.1 b/man/mu.1
index 6b4c88c..ecb6122 100644
--- a/man/mu.1
+++ b/man/mu.1
@@ -1,4 +1,4 @@
-.TH MU 1 "July 2019" "User Manuals"
+.TH MU 1 "February 2020" "User Manuals"
 
 .SH NAME
 
@@ -36,6 +36,14 @@ get help for some command. See
 (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)