Changed "OS X" to "macOS"

[notmuch-wiki] / getting-started.mdwn

diff --git a/getting-started.mdwn b/getting-started.mdwn
index 0482abd6cfce823d31a17c944e319150dc982e87..7cc7c31f4181225b67a4fb5598a08a07f3856828 100644 (file)
--- a/getting-started.mdwn
+++ b/getting-started.mdwn
@@ -8,6 +8,9 @@
 This is your friendly guide and tutorial to getting started with Notmuch. It
 will help you through the first steps of setting up Notmuch.
 
+All Notmuch commands have [[manual pages|manpages]]. Please refer to them for
+details.
+
 ## Prerequisites
 
 In order to use Notmuch, you will need to have your email messages stored in
@@ -24,9 +27,9 @@ already have messages in this format.
 
 On Linux, the easiest way to install Notmuch is through your distribution's
 package repository. If you're installing Notmuch from a [git
-checkout](http://git.notmuchmail.org/git/notmuch) or a [source
-release](http://notmuchmail.org/releases/), please refer to the
-[INSTALL](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/INSTALL) document.
+checkout](https://git.notmuchmail.org/git/notmuch) or a [source
+release](https://notmuchmail.org/releases/), please refer to the
+[INSTALL](https://git.notmuchmail.org/git/notmuch/blob/HEAD:/INSTALL) document.
 
 ## Configuration
 
@@ -66,10 +69,59 @@ interface|manpages]], or [[Notmuch Emacs interface|notmuch-emacs]].
 
 ## Converting Existing mbox to Maildir
 
+The [`mb2md`](http://batleth.sapienti-sat.org/projects/mb2md/) tool can be used
+to convert existing mbox files to Maildir.
+
+Beware that the source and destination directory options to `mb2md` are relative
+to the user's home directory, not relative to the current working directory.
+
 ## Delivering New Messages
 
+Notmuch itself does not receive messages. There is no IMAP or POP support. You
+will need to set up other tools, such as fetchmail, offlineimap, or mbsync, to
+receive the messages.
+
+There are two ways to deliver and index messages:
+
+* Use an external tool (such as offlineimap or mbsync) to deliver the messages
+  to your mail store, and run `notmuch new` to discover and index the newly
+  delivered messages (and any other changes in the mail store).
+
+* Use an external tool (such as fetchmail) receive the messages, and configure
+  the tool to use `notmuch insert` as a Mail Delivery Agent to deliver the
+  messages to your mail store and index them.
+
 ## Automation Via Hooks
 
-## Backing up and Restoring the Database
+Notmuch supports running [[user defined hooks|manpages/notmuch-hooks-5]] before
+or after certain commands. Hooks can be arbitrary executable programs or
+scripts. For example, if you always run your mail delivery tool first and
+`notmuch new` after that, you can run the tool from Notmuch `pre-new` hook, and
+simply run `notmuch new` to do both. If you always do some tagging after
+indexing of new messages, you may want to set up a `post-new` or `post-insert`
+hook to do that automatically.
+
+## Backing Up and Restoring the Database
+
+The Notmuch database contains a search index of your messages, along with all
+the tags you've added to your messages. The search index can be regenerated by
+indexing the messages again, but the tags will be lost if the database is
+lost. (If you have `maildir.synchronize_flags` configuration option enabled,
+also some of the tags can be regenerated from maildir flags.)
+
+To create a plain-text dump of the tags, run
+
+        notmuch dump --output=dump.txt
+
+To restore the tags from the dump, run
+
+        notmuch restore --input=dump.txt
 
 ## Removing Notmuch
+
+Did not like it after all? All you need to do is remove the database and the
+configuration file. The database is stored in the `.notmuch` directory under
+your mail store. And your mail store is at `notmuch config get database.path`.
+
+You may want to use the `notmuch dump` command to create a backup of any tags
+you've added before removing the database.