From d736260385a689b5c77d8121f48e29440e3adfa4 Mon Sep 17 00:00:00 2001 From: David Bremner Date: Tue, 28 Jan 2014 12:12:37 -0400 Subject: doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet. --- doc/man1/notmuch.rst | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 doc/man1/notmuch.rst (limited to 'doc/man1/notmuch.rst') diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst new file mode 100644 index 00000000..97102943 --- /dev/null +++ b/doc/man1/notmuch.rst @@ -0,0 +1,143 @@ +======= +notmuch +======= + +SYNOPSIS +======== + +**notmuch** [option ...] **command** [arg ...] + +DESCRIPTION +=========== + +Notmuch is a command-line based program for indexing, searching, +reading, and tagging large collections of email messages. + +This page describes how to get started using notmuch from the command +line, and gives a brief overview of the commands available. For more +information on e.g. **notmuch show** consult the **notmuch-show(1)** man +page, also accessible via **notmuch help show** + +The quickest way to get started with Notmuch is to simply invoke the +``notmuch`` command with no arguments, which will interactively guide +you through the process of indexing your mail. + +NOTE +==== + +While the command-line program ``notmuch`` provides powerful +functionality, it does not provide the most convenient interface for +that functionality. More sophisticated interfaces are expected to be +built on top of either the command-line interface, or more likely, on +top of the notmuch library interface. See http://notmuchmail.org for +more about alternate interfaces to notmuch. The emacs-based interface to +notmuch (available under **emacs/** in the Notmuch source distribution) +is probably the most widely used at this time. + +OPTIONS +======= + +Supported global options for ``notmuch`` include + + ``--help`` + Print a synopsis of available commands and exit. + + ``--version`` + Print the installed version of notmuch, and exit. + + ``--config=FILE`` + Specify the configuration file to use. This overrides any + configuration file specified by ${NOTMUCH\_CONFIG}. + +COMMANDS +======== + +SETUP +----- + +The **notmuch setup** command is used to configure Notmuch for first +use, (or to reconfigure it later). + +The setup command will prompt for your full name, your primary email +address, any alternate email addresses you use, and the directory +containing your email archives. Your answers will be written to a +configuration file in ${NOTMUCH\_CONFIG} (if set) or +${HOME}/.notmuch-config . This configuration file will be created with +descriptive comments, making it easy to edit by hand later to change the +configuration. Or you can run **notmuch setup** again to change the +configuration. + +The mail directory you specify can contain any number of sub-directories +and should primarily contain only files with individual email messages +(eg. maildir or mh archives are perfect). If there are other, non-email +files (such as indexes maintained by other email programs) then notmuch +will do its best to detect those and ignore them. + +Mail storage that uses mbox format, (where one mbox file contains many +messages), will not work with notmuch. If that's how your mail is +currently stored, it is recommended you first convert it to maildir +format with a utility such as mb2md before running **notmuch setup .** + +Invoking ``notmuch`` with no command argument will run **setup** if the +setup command has not previously been completed. + +OTHER COMMANDS +-------------- + +Several of the notmuch commands accept search terms with a common +syntax. See **notmuch-search-terms**\ (7) for more details on the +supported syntax. + +The **search**, **show** and **count** commands are used to query the +email database. + +The **reply** command is useful for preparing a template for an email +reply. + +The **tag** command is the only command available for manipulating +database contents. + +The **dump** and **restore** commands can be used to create a textual +dump of email tags for backup purposes, and to restore from that dump. + +The **config** command can be used to get or set settings in the notmuch +configuration file. + +ENVIRONMENT +=========== + +The following environment variables can be used to control the behavior +of notmuch. + +**NOTMUCH\_CONFIG** + Specifies the location of the notmuch configuration file. Notmuch + will use ${HOME}/.notmuch-config if this variable is not set. + +**NOTMUCH\_TALLOC\_REPORT** + Location to write a talloc memory usage report. See + **talloc\_enable\_leak\_report\_full** in **talloc(3)** for more + information. + +**NOTMUCH\_DEBUG\_QUERY** + If set to a non-empty value, the notmuch library will print (to + stderr) Xapian queries it constructs. + +SEE ALSO +======== + +**notmuch-config(1)**, **notmuch-count(1)**, **notmuch-dump(1)**, +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**, +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**, +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)** + +The notmuch website: **http://notmuchmail.org** + +CONTACT +======= + +Feel free to send questions, comments, or kudos to the notmuch mailing +list . Subscription is not required before +posting, but is available from the notmuchmail.org website. + +Real-time interaction with the Notmuch community is available via IRC +(server: irc.freenode.net, channel: #notmuch). -- cgit v1.2.3