1 Return-Path: <bremner@unb.ca>
\r
2 X-Original-To: notmuch@notmuchmail.org
\r
3 Delivered-To: notmuch@notmuchmail.org
\r
4 Received: from localhost (localhost [127.0.0.1])
\r
5 by olra.theworths.org (Postfix) with ESMTP id 3403D4196F0
\r
6 for <notmuch@notmuchmail.org>; Wed, 3 Nov 2010 10:20:06 -0700 (PDT)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=-2.6 tagged_above=-999 required=5
\r
12 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7] autolearn=ham
\r
13 Received: from olra.theworths.org ([127.0.0.1])
\r
14 by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)
\r
15 with ESMTP id l4Ha-TNoO0yj for <notmuch@notmuchmail.org>;
\r
16 Wed, 3 Nov 2010 10:19:53 -0700 (PDT)
\r
17 Received: from tempo.its.unb.ca (tempo.its.unb.ca [131.202.1.21])
\r
18 (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
\r
19 (No client certificate requested)
\r
20 by olra.theworths.org (Postfix) with ESMTPS id 12AF340D14D
\r
21 for <notmuch@notmuchmail.org>; Wed, 3 Nov 2010 10:19:36 -0700 (PDT)
\r
22 Received: from rocinante.cs.unb.ca
\r
23 (fctnnbsc30w-142167176217.pppoe-dynamic.High-Speed.nb.bellaliant.net
\r
24 [142.167.176.217]) (authenticated bits=0)
\r
25 by tempo.its.unb.ca (8.13.8/8.13.8) with ESMTP id oA3HJYdT014337
\r
26 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NO);
\r
27 Wed, 3 Nov 2010 14:19:34 -0300
\r
28 Received: from bremner by rocinante.cs.unb.ca with local (Exim 4.72)
\r
29 (envelope-from <bremner@unb.ca>)
\r
30 id 1PDgzm-0001P2-93; Wed, 03 Nov 2010 14:19:34 -0300
\r
31 From: david@tethera.net
\r
32 To: notmuch@notmuchmail.org
\r
33 Subject: [PATCH 3/4] Add rules to build notmuch.1 and notmuch-help.h from the
\r
35 Date: Wed, 3 Nov 2010 14:18:55 -0300
\r
36 Message-Id: <1288804736-5173-4-git-send-email-david@tethera.net>
\r
37 X-Mailer: git-send-email 1.7.1
\r
38 In-Reply-To: <874oc4r4bu.fsf@yoom.home.cworth.org>
\r
39 References: <874oc4r4bu.fsf@yoom.home.cworth.org>
\r
40 Cc: David Bremner <bremner@unb.ca>
\r
41 X-BeenThere: notmuch@notmuchmail.org
\r
42 X-Mailman-Version: 2.1.13
\r
44 List-Id: "Use and development of the notmuch mail system."
\r
45 <notmuch.notmuchmail.org>
\r
46 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
47 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
48 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
49 List-Post: <mailto:notmuch@notmuchmail.org>
\r
50 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
51 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
52 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
53 X-List-Received-Date: Wed, 03 Nov 2010 17:20:06 -0000
\r
55 From: David Bremner <bremner@unb.ca>
\r
57 Add generated files to CLEAN. Remove notmuch.1 from git because we
\r
58 auto generate it now.
\r
60 Makefile.local | 22 ++-
\r
61 notmuch.1 | 609 --------------------------------------------------------
\r
62 2 files changed, 21 insertions(+), 610 deletions(-)
\r
63 delete mode 100644 notmuch.1
\r
65 diff --git a/Makefile.local b/Makefile.local
\r
66 index 490265b..3e20d0c 100644
\r
67 --- a/Makefile.local
\r
68 +++ b/Makefile.local
\r
69 @@ -251,6 +251,18 @@ notmuch_client_srcs = \
\r
73 +notmuch_help_files= \
\r
74 + notmuch-setup-help.h \
\r
75 + notmuch-new-help.h \
\r
76 + notmuch-show-help.h \
\r
77 + notmuch-search-help.h \
\r
78 + notmuch-count-help.h \
\r
79 + notmuch-reply-help.h \
\r
80 + notmuch-tag-help.h \
\r
81 + notmuch-dump-help.h \
\r
82 + notmuch-restore-help.h \
\r
83 + notmuch-part-help.h
\r
85 notmuch_client_modules = $(notmuch_client_srcs:.c=.o)
\r
87 notmuch: $(notmuch_client_modules) lib/libnotmuch.a
\r
88 @@ -259,6 +271,14 @@ notmuch: $(notmuch_client_modules) lib/libnotmuch.a
\r
89 notmuch-shared: $(notmuch_client_modules) lib/$(LINKER_NAME)
\r
90 $(call quiet,$(FINAL_NOTMUCH_LINKER) $(CFLAGS)) $(notmuch_client_modules) $(FINAL_NOTMUCH_LDFLAGS) -o $@
\r
92 +notmuch.1: notmuch.pod
\r
93 + pod2man --stderr --center "User Commands" --release $(VERSION) $^ > $@
\r
95 +notmuch.o: notmuch-help.h
\r
97 +notmuch-help.h: notmuch.pod pod2help_h.pl
\r
98 + perl pod2help_h.pl < notmuch.pod > notmuch-help.h
\r
100 notmuch.1.gz: notmuch.1
\r
101 gzip --stdout $^ > $@
\r
103 @@ -294,4 +314,4 @@ install-desktop:
\r
104 desktop-file-install --mode 0644 --dir $(DESTDIR)$(desktop_dir) notmuch.desktop
\r
106 SRCS := $(SRCS) $(notmuch_client_srcs)
\r
107 -CLEAN := $(CLEAN) notmuch notmuch-shared $(notmuch_client_modules) notmuch.elc notmuch.1.gz
\r
108 +CLEAN := $(CLEAN) notmuch notmuch-shared $(notmuch_client_modules) notmuch.elc notmuch.1.gz notmuch.1 notmuch-help.h
\r
109 diff --git a/notmuch.1 b/notmuch.1
\r
110 deleted file mode 100644
\r
111 index 2c33749..0000000
\r
115 -.\" notmuch - Not much of an email program, (just index, search and tagging)
\r
117 -.\" Copyright © 2009 Carl Worth
\r
119 -.\" Notmuch is free software: you can redistribute it and/or modify
\r
120 -.\" it under the terms of the GNU General Public License as published by
\r
121 -.\" the Free Software Foundation, either version 3 of the License, or
\r
122 -.\" (at your option) any later version.
\r
124 -.\" Notmuch is distributed in the hope that it will be useful,
\r
125 -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
\r
126 -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
\r
127 -.\" GNU General Public License for more details.
\r
129 -.\" You should have received a copy of the GNU General Public License
\r
130 -.\" along with this program. If not, see http://www.gnu.org/licenses/ .
\r
132 -.\" Author: Carl Worth <cworth@cworth.org>
\r
133 -.TH NOTMUCH 1 2009-10-31 "Notmuch 0.1"
\r
135 -notmuch \- thread-based email index, search, and tagging
\r
138 -.IR command " [" args " ...]"
\r
140 -Notmuch is a command-line based program for indexing, searching,
\r
141 -reading, and tagging large collections of email messages.
\r
143 -The quickest way to get started with Notmuch is to simply invoke the
\r
145 -command with no arguments, which will interactively guide you through
\r
146 -the process of indexing your mail.
\r
148 -While the command-line program
\r
150 -provides powerful functionality, it does not provide the most
\r
151 -convenient interface for that functionality. More sophisticated
\r
152 -interfaces are expected to be built on top of either the command-line
\r
153 -interface, or more likely, on top of the notmuch library
\r
154 -interface. See http://notmuchmail.org for more about alternate
\r
155 -interfaces to notmuch.
\r
159 -command is used to configure Notmuch for first use, (or to reconfigure
\r
165 -Interactively sets up notmuch for first use.
\r
167 -The setup command will prompt for your full name, your primary email
\r
168 -address, any alternate email addresses you use, and the directory
\r
169 -containing your email archives. Your answers will be written to a
\r
170 -configuration file in ${NOTMUCH_CONFIG} (if set) or
\r
171 -${HOME}/.notmuch-config . This configuration file will be created with
\r
172 -descriptive comments, making it easy to edit by hand later to change the
\r
173 -configuration. Or you can run
\r
174 -.B "notmuch setup"
\r
175 -again to change the configuration.
\r
177 -The mail directory you specify can contain any number of
\r
178 -sub-directories and should primarily contain only files with individual
\r
179 -email messages (eg. maildir or mh archives are perfect). If there are
\r
180 -other, non-email files (such as indexes maintained by other email
\r
181 -programs) then notmuch will do its best to detect those and ignore
\r
184 -Mail storage that uses mbox format, (where one mbox file contains many
\r
185 -messages), will not work with notmuch. If that's how your mail is
\r
186 -currently stored, it is recommended you first convert it to maildir
\r
187 -format with a utility such as mb2md before running
\r
188 -.B "notmuch setup" .
\r
192 -with no command argument will run
\r
194 -if the setup command has not previously been completed.
\r
199 -command is used to incorporate new mail into the notmuch database.
\r
204 -Find and import any new messages to the database.
\r
208 -command scans all sub-directories of the database, performing
\r
209 -full-text indexing on new messages that are found. Each new message
\r
210 -will automatically be tagged with both the
\r
211 -.BR inbox " and " unread
\r
216 -once after first running
\r
217 -.B "notmuch setup"
\r
218 -to create the initial database. The first run may take a long time if
\r
219 -you have a significant amount of mail (several hundred thousand
\r
220 -messages or more). Subsequently, you should run
\r
222 -whenever new mail is delivered and you wish to incorporate it into the
\r
223 -database. These subsequent runs will be much quicker than the initial
\r
228 -with no command argument will run
\r
231 -.B "notmuch setup"
\r
232 -has previously been completed, but
\r
234 -has not previously been run.
\r
237 -Several of the notmuch commands accept search terms with a common
\r
239 -.B "SEARCH SYNTAX"
\r
240 -section below for more details on the supported syntax.
\r
243 -.BR search ", " show " and " count
\r
244 -commands are used to query the email database.
\r
247 -.BR search " [options...] <search-term>..."
\r
249 -Search for messages matching the given search terms, and display as
\r
250 -results the threads containing the matched messages.
\r
252 -The output consists of one line per thread, giving a thread ID, the
\r
253 -date of the newest (or oldest, depending on the sort option) matched
\r
254 -message in the thread, the number of matched messages and total
\r
255 -messages in the thread, the names of all participants in the thread,
\r
256 -and the subject of the newest (or oldest) message.
\r
258 -Supported options for
\r
263 -.BR \-\-format= ( json | text )
\r
265 -Presents the results in either JSON or plain-text (default).
\r
270 -.B \-\-output=(summary|threads|messages|files|tags)
\r
276 -Output a summary of each thread with any message matching the search
\r
277 -terms. The summary includes the thread ID, date, the number of
\r
278 -messages in the thread (both the number matched and the total number),
\r
279 -the authors of the thread and the subject.
\r
285 -Output the thread IDs of all threads with any message matching the
\r
286 -search terms, either one per line (--format=text) or as a JSON array
\r
293 -Output the message IDs of all messages matching the search terms,
\r
294 -either one per line (--format=text) or as a JSON array
\r
301 -Output the filenames of all messages matching the search terms, either
\r
302 -one per line (--format=text) or as a JSON array (--format=json).
\r
308 -Output all tags that appear on any message matching the search terms,
\r
309 -either one per line (--format=text) or as a JSON array
\r
316 -.BR \-\-sort= ( newest\-first | oldest\-first )
\r
318 -This option can be used to present results in either chronological order
\r
319 -.RB ( oldest\-first )
\r
320 -or reverse chronological order
\r
321 -.RB ( newest\-first ).
\r
323 -Note: The thread order will be distinct between these two options
\r
324 -(beyond being simply reversed). When sorting by
\r
326 -the threads will be sorted by the oldest message in each thread, but
\r
329 -the threads will be sorted by the newest message in each thread.
\r
333 -By default, results will be displayed in reverse chronological order,
\r
334 -(that is, the newest results will be displayed first).
\r
337 -.B "SEARCH SYNTAX"
\r
338 -section below for details of the supported syntax for <search-terms>.
\r
341 -.BR show " [options...] <search-term>..."
\r
343 -Shows all messages matching the search terms.
\r
345 -The messages will be grouped and sorted based on the threading (all
\r
346 -replies to a particular message will appear immediately after that
\r
347 -message in date order). The output is not indented by default, but
\r
348 -depth tags are printed so that proper indentation can be performed by
\r
349 -a post-processor (such as the emacs interface to notmuch).
\r
351 -Supported options for
\r
356 -.B \-\-entire\-thread
\r
358 -By default only those messages that match the search terms will be
\r
359 -displayed. With this option, all messages in the same thread as any
\r
360 -matched message will be displayed.
\r
365 -.B \-\-format=(text|json|mbox)
\r
371 -The default plain-text format has all text-content MIME parts
\r
372 -decoded. Various components in the output,
\r
373 -.RB ( message ", " header ", " body ", " attachment ", and MIME " part ),
\r
374 -will be delimited by easily-parsed markers. Each marker consists of a
\r
375 -Control-L character (ASCII decimal 12), the name of the marker, and
\r
376 -then either an opening or closing brace, ('{' or '}'), to either open
\r
377 -or close the component.
\r
383 -The output is formatted with Javascript Object Notation (JSON). This
\r
384 -format is more robust than the text format for automated
\r
385 -processing. JSON output always includes all messages in a matching
\r
387 -.B \-\-format=json
\r
389 -.B \-\-entire\-thread
\r
396 -All matching messages are output in the traditional, Unix mbox format
\r
397 -with each message being prefixed by a line beginning with "From " and
\r
398 -a blank line separating each message. Lines in the message content
\r
399 -beginning with "From " (preceded by zero or more '>' characters) have
\r
400 -an additional '>' character added. This reversible escaping
\r
401 -is termed "mboxrd" format and described in detail here:
\r
402 -http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
\r
406 -is to display a single thread of email messages. For this, use a
\r
407 -search term of "thread:<thread-id>" as can be seen in the first
\r
408 -column of output from the
\r
413 -.B "SEARCH SYNTAX"
\r
414 -section below for details of the supported syntax for <search-terms>.
\r
417 -.BR count " <search-term>..."
\r
419 -Count messages matching the search terms.
\r
421 -The number of matching messages is output to stdout.
\r
423 -With no search terms, a count of all messages in the database will be
\r
430 -command is useful for preparing a template for an email reply.
\r
433 -.BR reply " [options...] <search-term>..."
\r
435 -Constructs a reply template for a set of messages.
\r
437 -To make replying to email easier,
\r
439 -takes an existing set of messages and constructs a suitable mail
\r
440 -template. The Reply-to header (if any, otherwise From:) is used for
\r
441 -the To: address. Vales from the To: and Cc: headers are copied, but
\r
442 -not including any of the current user's email addresses (as configured
\r
443 -in primary_mail or other_email in the .notmuch\-config file) in the
\r
446 -It also builds a suitable new subject, including Re: at the front (if
\r
447 -not already present), and adding the message IDs of the messages being
\r
448 -replied to to the References list and setting the In\-Reply\-To: field
\r
451 -Finally, the original contents of the emails are quoted by prefixing
\r
452 -each line with '> ' and included in the body.
\r
454 -The resulting message template is output to stdout.
\r
456 -Supported options for
\r
461 -.BR \-\-format= ( default | headers\-only )
\r
465 -Includes subject and quoted message body.
\r
468 -Only produces In\-Reply\-To, References, To, Cc, and Bcc headers.
\r
472 -.B "SEARCH SYNTAX"
\r
473 -section below for details of the supported syntax for <search-terms>.
\r
475 -Note: It is most common to use
\r
476 -.B "notmuch reply"
\r
477 -with a search string matching a single message, (such as
\r
478 -id:<message-id>), but it can be useful to reply to several messages at
\r
479 -once. For example, when a series of patches are sent in a single
\r
480 -thread, replying to the entire thread allows for the reply to comment
\r
481 -on issue found in multiple patches.
\r
487 -command is the only command available for manipulating database
\r
492 -.BR tag " +<tag>|\-<tag> [...] [\-\-] <search-term>..."
\r
494 -Add/remove tags for all messages matching the search terms.
\r
496 -Tags prefixed by '+' are added while those prefixed by '\-' are
\r
497 -removed. For each message, tag removal is performed before tag
\r
500 -The beginning of <search-terms> is recognized by the first
\r
501 -argument that begins with neither '+' nor '\-'. Support for
\r
502 -an initial search term beginning with '+' or '\-' is provided
\r
503 -by allowing the user to specify a "\-\-" argument to separate
\r
504 -the tags from the search terms.
\r
507 -.B "SEARCH SYNTAX"
\r
508 -section below for details of the supported syntax for <search-terms>.
\r
512 -.BR dump " and " restore
\r
513 -commands can be used to create a textual dump of email tags for backup
\r
514 -purposes, and to restore from that dump
\r
518 -.BR dump " [<filename>]"
\r
520 -Creates a plain-text dump of the tags of each message.
\r
522 -The output is to the given filename, if any, or to stdout.
\r
524 -These tags are the only data in the notmuch database that can't be
\r
525 -recreated from the messages themselves. The output of notmuch dump is
\r
526 -therefore the only critical thing to backup (and much more friendly to
\r
527 -incremental backup than the native database files.)
\r
529 -.BR restore " <filename>"
\r
531 -Restores the tags from the given file (see
\r
532 -.BR "notmuch dump" "."
\r
534 -Note: The dump file format is specifically chosen to be
\r
535 -compatible with the format of files produced by sup-dump.
\r
536 -So if you've previously been using sup for mail, then the
\r
537 -.B "notmuch restore"
\r
538 -command provides you a way to import all of your tags (or labels as
\r
544 -command can used to output a single part of a multi-part MIME message.
\r
548 -.BR part " \-\-part=<part-number> <search-term>..."
\r
550 -Output a single MIME part of a message.
\r
552 -A single decoded MIME part, with no encoding or framing, is output to
\r
553 -stdout. The search terms must match only a single message, otherwise
\r
554 -this command will fail.
\r
556 -The part number should match the part "id" field output by the
\r
557 -"\-\-format=json" option of "notmuch show". If the message specified by
\r
558 -the search terms does not include a part with the specified "id" there
\r
559 -will be no output.
\r
562 -.B "SEARCH SYNTAX"
\r
563 -section below for details of the supported syntax for <search-terms>.
\r
568 -command can be used to get or set settings int the notmuch
\r
569 -configuration file.
\r
573 -.BR "config get " <section> . <item>
\r
575 -The value of the specified configuration item is printed to stdout. If
\r
576 -the item has multiple values, each value is separated by a newline
\r
579 -Available configuration items include at least
\r
585 - user.primary_email
\r
594 -.BR "config set " <section> . "<item> [values ...]"
\r
596 -The specified configuration item is set to the given value. To
\r
597 -specify a multiple-value item, provide each value as a separate
\r
598 -command-line argument.
\r
600 -If no values are provided, the specified configuration item will be
\r
601 -removed from the configuration file.
\r
605 -Several notmuch commands accept a common syntax for search terms.
\r
607 -The search terms can consist of free-form text (and quoted phrases)
\r
608 -which will match all messages that contain all of the given
\r
609 -terms/phrases in the body, the subject, or any of the sender or
\r
610 -recipient headers.
\r
612 -As a special case, a search string consisting of exactly a single
\r
613 -asterisk ("*") will match all messages.
\r
615 -In addition to free text, the following prefixes can be used to force
\r
616 -terms to match against specific portions of an email, (where
\r
617 -<brackets> indicate user-supplied values):
\r
619 - from:<name-or-address>
\r
621 - to:<name-or-address>
\r
623 - subject:<word-or-quoted-phrase>
\r
625 - attachment:<word>
\r
627 - tag:<tag> (or is:<tag>)
\r
631 - thread:<thread-id>
\r
635 -prefix is used to match the name or address of the sender of an email
\r
640 -prefix is used to match the names or addresses of any recipient of an
\r
641 -email message, (whether To, Cc, or Bcc).
\r
643 -Any term prefixed with
\r
645 -will match only text from the subject of an email. Searching for a
\r
646 -phrase in the subject is supported by including quotation marks around
\r
647 -the phrase, immediately following
\r
652 -prefix can be used to search for specific filenames (or extensions) of
\r
653 -attachments to email messages.
\r
656 -.BR tag: " and " is:
\r
657 -valid tag values include
\r
658 -.BR inbox " and " unread
\r
659 -by default for new messages added by
\r
661 -as well as any other tag values added manually with
\r
662 -.BR "notmuch tag" .
\r
666 -message ID values are the literal contents of the Message\-ID: header
\r
667 -of email messages, but without the '<', '>' delimiters.
\r
671 -prefix can be used with the thread ID values that are generated
\r
672 -internally by notmuch (and do not appear in email messages). These
\r
673 -thread ID values can be seen in the first column of output from
\r
674 -.B "notmuch search"
\r
676 -In addition to individual terms, multiple terms can be
\r
677 -combined with Boolean operators (
\r
678 -.BR and ", " or ", " not
\r
679 -, etc.). Each term in the query will be implicitly connected by a
\r
680 -logical AND if no explicit operator is provided, (except that terms
\r
681 -with a common prefix will be implicitly combined with OR until we get
\r
682 -Xapian defect #402 fixed).
\r
684 -Parentheses can also be used to control the combination of the Boolean
\r
685 -operators, but will have to be protected from interpretation by the
\r
686 -shell, (such as by putting quotation marks around any parenthesized
\r
689 -Finally, results can be restricted to only messages within a
\r
690 -particular time range, (based on the Date: header) with a syntax of:
\r
692 - <intial-timestamp>..<final-timestamp>
\r
694 -Each timestamp is a number representing the number of seconds since
\r
695 -1970\-01\-01 00:00:00 UTC. This is not the most convenient means of
\r
696 -expressing date ranges, but until notmuch is fixed to accept a more
\r
697 -convenient form, one can use the date program to construct
\r
698 -timestamps. For example, with the bash shell the folowing syntax would
\r
699 -specify a date range to return messages from 2009\-10\-01 until the
\r
702 - $(date +%s \-d 2009\-10\-01)..$(date +%s)
\r
704 -The following environment variables can be used to control the
\r
705 -behavior of notmuch.
\r
708 -Specifies the location of the notmuch configuration file. Notmuch will
\r
709 -use ${HOME}/.notmuch\-config if this variable is not set.
\r
711 -The emacs-based interface to notmuch (available as
\r
713 -in the Notmuch distribution).
\r
715 -The notmuch website:
\r
716 -.B http://notmuchmail.org
\r
718 -Feel free to send questions, comments, or kudos to the notmuch mailing
\r
719 -list <notmuch@notmuchmail.org> . Subscription is not required before
\r
720 -posting, but is available from the notmuchmail.org website.
\r
722 -Real-time interaction with the Notmuch community is available via IRC
\r
723 -(server: irc.freenode.net, channel: #notmuch).
\r
projects / notmuch-archives.git / blob