improve documentation

3 files changed, 47 insertions, 13 deletions

diff --git a/README.org b/README.org
index 3eeeacb..41ba1ed 100644
--- a/README.org
+++ b/README.org
@@ -13,6 +13,7 @@
 
 Welcome to ~mu~!
 
+
 Latest development news: [[NEWS.org]].
 
 With the enormous amounts of e-mail many people gather and the importance of
@@ -22,15 +23,15 @@ now, and quickly file away message for later use.
 
 ~mu~ is a set of command-line tools for dealing with e-mail messages stored in the
 Maildir-format. ~mu~'s goal is to help you to quickly find the messages you need,
-view them, extract attachments, create new maildirs, and so on.
+view them, extract attachments, and so on.
 
 After indexing your messages into a [[http://www.xapian.org][Xapian]]-database, you can search them through
 a query language. You can use various message fields or words in the body text
 to find the right messages.
 
-Built on top of ~mu~ are some extensions (included in this package):
+Built on top of ~mu~ are some other tools (included in this package):
 
-- ~mu4e~: a full-featured e-mail client that runs inside emacs
+- ~mu4e~: a full-featured e-mail client that runs inside emacs (more below)
 
 - ~mu-scm~: bindings for the Guile/Scheme programming language (version 3.0 and
   later)
@@ -48,19 +49,19 @@ version 3]] (or higher).
 *mu* attempts to balance development speed and stability.
 
 Active development takes place on ~master~ (the 1.14 series), and we maintain
-~release/1.12~ as well. When possible, fixes (but not features) from ~master~ are
-back-ported to ~release/1.12~.
+~release/1.12~ as well, for any critical fixes.
 
 Every few months, we release a stable version (e.g. ~1.14.0~); development then
 continues in ~master~, with ~-pre<n>~ (e.g. ~1.14.1-pre1~): ~-pre~-suffixed versions
 refer to the current _development_ code, until it is released (and then looses its
 ~-pre~ suffix, i.e., becomes the ~1.14.1~ release).
 
-Hence, if you want to track active development, use ~master~; if you want to avoid
-any changes except bug-fixes, use a 1.12 [[https://github.com/djcb/mu/releases/][release]]; otherwise, track ~master~.
+Hence, generally we recommend the latest 1.14 release; if you want to avoid any
+changes except critical bug-fixes, use the latest 1.12 [[https://github.com/djcb/mu/releases/][release]]; and finally, if
+you want to track active development, use ~master~.
 
 Overall, we try to avoid incompatible changes, but sometimes this is necessary,
-for example to update the versions of required libraries
+for example to update the versions of required libraries.
 
 * Installation
 
@@ -112,6 +113,37 @@ $ meson compile -C build
 $ meson install -C build
 #+end_example
 
-** Contributing
+* Initial setup
+
+Most ~mu~ commands and ~mu4e~ require setting up the database, which is needed only
+once. For this, there is the ~mu init~ command. See its manpage for all the
+details, but could look something like:
+
+#+begin_example
+$ mu init --maildir=~/Maildir          \
+    --personal-address=jim@example.com \
+    --personal-address=bob@example.com \
+    --ignored-address='.*reply*.'
+#+end_example
+
+This creates your database, specifies some of your personal addresses, and some
+addresses (a regular expression) that should be ignored from the contacts-cache
+used for address-autocompletion in ~mu4e~.
+
+After this step, we can index our maildir:
+#+begin_example
+$ mu index
+#+end_example
+The first time you do this, it can take a few minutes, depending on how many
+messages you have. Afterwards, you can run ~mu index~ e.g., after retrieving
+messages from a remote server.
+
+After that has completed you can try to find some messages with some simple
+queries:
+#+begin_example
+$ mu find hello
+#+end_example
+
+* Contributing
 
 Contributions are welcome! See the Github issue list and [[IDEAS.org]].
diff --git a/man/mu-init.1.org b/man/mu-init.1.org
index 945964a..92760e7 100644
--- a/man/mu-init.1.org
+++ b/man/mu-init.1.org
@@ -26,7 +26,6 @@ can be used, the *--maildir* option is required; it must be an absolute path (bu
 ~~/~ expansion is performed).
 
 ** --personal-address _email-address-or-regex_
-** --my-address _email-address-or-regex_  (alias)
 Specifies that some e-mail address is a /personal/ address. The option can be used
 multiple times, to specify all your addresses.
 
@@ -49,6 +48,9 @@ The good news is that *mu4e* can automatically translate the regular-expressions
 if you allow it to, by installing the *pcre2el* Elisp package. See the *mu4e*
 documentation for further details.
 
+** --my-address _email-address-or-regex_
+Obsolete alias for ~--personal-address~
+
 ** --ignored-address _email-address-or-regex_
 Specifies that some e-mail address is to be ignored from the contacts-cache (the
 option can be used multiple times). Such addresses then cannot be found with
diff --git a/mu4e/mu4e.texi b/mu4e/mu4e.texi
index e0920a4..7f61002 100644
--- a/mu4e/mu4e.texi
+++ b/mu4e/mu4e.texi
@@ -236,7 +236,7 @@ After these steps, @code{mu4e} should be ready to go!
 * Versions:: Available stable and development versions
 * Installation:: How to install @code{mu} and @code{mu4e}
 * Getting mail:: Getting mail from a server
-* Initializing the message store:: Settings things up
+* Initializing the message store:: Setting things up
 * Indexing your messages:: Creating and maintaining the index
 * Basic configuration:: Settings for @code{mu4e}
 * Folders::  Setting up standard folders
@@ -397,13 +397,13 @@ environment variable @env{MUHOME}.
 Assuming that your maildir is at @file{~/Maildir}, we issue the
 following command:
 @example
-  $ mu init --maildir=~/Maildir
+$ mu init --maildir=~/Maildir
 @end example
 
 You can add some e-mail addresses, so @code{mu} recognizes them as yours:
 
 @example
-  $ mu init --maildir=~/Maildir --personal-address=jim@@example.com \
+$ mu init --maildir=~/Maildir --personal-address=jim@@example.com \
     --personal-address=bob@@example.com
 @end example