Return-Path: X-Original-To: notmuch@notmuchmail.org Delivered-To: notmuch@notmuchmail.org Received: from localhost (localhost [127.0.0.1]) by olra.theworths.org (Postfix) with ESMTP id 3403D4196F0 for ; Wed, 3 Nov 2010 10:20:06 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: -2.6 X-Spam-Level: X-Spam-Status: No, score=-2.6 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7] autolearn=ham Received: from olra.theworths.org ([127.0.0.1]) by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id l4Ha-TNoO0yj for ; Wed, 3 Nov 2010 10:19:53 -0700 (PDT) Received: from tempo.its.unb.ca (tempo.its.unb.ca [131.202.1.21]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by olra.theworths.org (Postfix) with ESMTPS id 12AF340D14D for ; Wed, 3 Nov 2010 10:19:36 -0700 (PDT) Received: from rocinante.cs.unb.ca (fctnnbsc30w-142167176217.pppoe-dynamic.High-Speed.nb.bellaliant.net [142.167.176.217]) (authenticated bits=0) by tempo.its.unb.ca (8.13.8/8.13.8) with ESMTP id oA3HJYdT014337 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NO); Wed, 3 Nov 2010 14:19:34 -0300 Received: from bremner by rocinante.cs.unb.ca with local (Exim 4.72) (envelope-from ) id 1PDgzm-0001P2-93; Wed, 03 Nov 2010 14:19:34 -0300 From: david@tethera.net To: notmuch@notmuchmail.org Subject: [PATCH 3/4] Add rules to build notmuch.1 and notmuch-help.h from the pod file. Date: Wed, 3 Nov 2010 14:18:55 -0300 Message-Id: <1288804736-5173-4-git-send-email-david@tethera.net> X-Mailer: git-send-email 1.7.1 In-Reply-To: <874oc4r4bu.fsf@yoom.home.cworth.org> References: <874oc4r4bu.fsf@yoom.home.cworth.org> Cc: David Bremner X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 03 Nov 2010 17:20:06 -0000 From: David Bremner Add generated files to CLEAN. Remove notmuch.1 from git because we auto generate it now. --- Makefile.local | 22 ++- notmuch.1 | 609 -------------------------------------------------------- 2 files changed, 21 insertions(+), 610 deletions(-) delete mode 100644 notmuch.1 diff --git a/Makefile.local b/Makefile.local index 490265b..3e20d0c 100644 --- a/Makefile.local +++ b/Makefile.local @@ -251,6 +251,18 @@ notmuch_client_srcs = \ show-message.c \ json.c +notmuch_help_files= \ + notmuch-setup-help.h \ + notmuch-new-help.h \ + notmuch-show-help.h \ + notmuch-search-help.h \ + notmuch-count-help.h \ + notmuch-reply-help.h \ + notmuch-tag-help.h \ + notmuch-dump-help.h \ + notmuch-restore-help.h \ + notmuch-part-help.h + notmuch_client_modules = $(notmuch_client_srcs:.c=.o) notmuch: $(notmuch_client_modules) lib/libnotmuch.a @@ -259,6 +271,14 @@ notmuch: $(notmuch_client_modules) lib/libnotmuch.a notmuch-shared: $(notmuch_client_modules) lib/$(LINKER_NAME) $(call quiet,$(FINAL_NOTMUCH_LINKER) $(CFLAGS)) $(notmuch_client_modules) $(FINAL_NOTMUCH_LDFLAGS) -o $@ +notmuch.1: notmuch.pod + pod2man --stderr --center "User Commands" --release $(VERSION) $^ > $@ + +notmuch.o: notmuch-help.h + +notmuch-help.h: notmuch.pod pod2help_h.pl + perl pod2help_h.pl < notmuch.pod > notmuch-help.h + notmuch.1.gz: notmuch.1 gzip --stdout $^ > $@ @@ -294,4 +314,4 @@ install-desktop: desktop-file-install --mode 0644 --dir $(DESTDIR)$(desktop_dir) notmuch.desktop SRCS := $(SRCS) $(notmuch_client_srcs) -CLEAN := $(CLEAN) notmuch notmuch-shared $(notmuch_client_modules) notmuch.elc notmuch.1.gz +CLEAN := $(CLEAN) notmuch notmuch-shared $(notmuch_client_modules) notmuch.elc notmuch.1.gz notmuch.1 notmuch-help.h diff --git a/notmuch.1 b/notmuch.1 deleted file mode 100644 index 2c33749..0000000 --- a/notmuch.1 +++ /dev/null @@ -1,609 +0,0 @@ -.\" notmuch - Not much of an email program, (just index, search and tagging) -.\" -.\" Copyright © 2009 Carl Worth -.\" -.\" Notmuch is free software: you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License as published by -.\" the Free Software Foundation, either version 3 of the License, or -.\" (at your option) any later version. -.\" -.\" Notmuch is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" along with this program. If not, see http://www.gnu.org/licenses/ . -.\" -.\" Author: Carl Worth -.TH NOTMUCH 1 2009-10-31 "Notmuch 0.1" -.SH NAME -notmuch \- thread-based email index, search, and tagging -.SH SYNOPSIS -.B notmuch -.IR command " [" args " ...]" -.SH DESCRIPTION -Notmuch is a command-line based program for indexing, searching, -reading, and tagging large collections of email messages. - -The quickest way to get started with Notmuch is to simply invoke the -.B notmuch -command with no arguments, which will interactively guide you through -the process of indexing your mail. -.SH NOTE -While the command-line program -.B 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. -.SH COMMANDS -The -.BR setup -command is used to configure Notmuch for first use, (or to reconfigure -it later). -.RS 4 -.TP 4 -.B setup - -Interactively sets up notmuch for first use. - -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 -.B "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 -.B "notmuch setup" . - -Invoking -.B notmuch -with no command argument will run -.B setup -if the setup command has not previously been completed. -.RE - -The -.B new -command is used to incorporate new mail into the notmuch database. -.RS 4 -.TP 4 -.B new - -Find and import any new messages to the database. - -The -.B new -command scans all sub-directories of the database, performing -full-text indexing on new messages that are found. Each new message -will automatically be tagged with both the -.BR inbox " and " unread -tags. - -You should run -.B "notmuch new" -once after first running -.B "notmuch setup" -to create the initial database. The first run may take a long time if -you have a significant amount of mail (several hundred thousand -messages or more). Subsequently, you should run -.B "notmuch new" -whenever new mail is delivered and you wish to incorporate it into the -database. These subsequent runs will be much quicker than the initial -run. - -Invoking -.B notmuch -with no command argument will run -.B new -if -.B "notmuch setup" -has previously been completed, but -.B "notmuch new" -has not previously been run. -.RE - -Several of the notmuch commands accept search terms with a common -syntax. See the -.B "SEARCH SYNTAX" -section below for more details on the supported syntax. - -The -.BR search ", " show " and " count -commands are used to query the email database. -.RS 4 -.TP 4 -.BR search " [options...] ..." - -Search for messages matching the given search terms, and display as -results the threads containing the matched messages. - -The output consists of one line per thread, giving a thread ID, the -date of the newest (or oldest, depending on the sort option) matched -message in the thread, the number of matched messages and total -messages in the thread, the names of all participants in the thread, -and the subject of the newest (or oldest) message. - -Supported options for -.B search -include -.RS 4 -.TP 4 -.BR \-\-format= ( json | text ) - -Presents the results in either JSON or plain-text (default). -.RE - -.RS 4 -.TP 4 -.B \-\-output=(summary|threads|messages|files|tags) - -.RS 4 -.TP 4 -.B summary - -Output a summary of each thread with any message matching the search -terms. The summary includes the thread ID, date, the number of -messages in the thread (both the number matched and the total number), -the authors of the thread and the subject. -.RE -.RS 4 -.TP 4 -.B threads - -Output the thread IDs of all threads with any message matching the -search terms, either one per line (--format=text) or as a JSON array -(--format=json). -.RE -.RS 4 -.TP 4 -.B messages - -Output the message IDs of all messages matching the search terms, -either one per line (--format=text) or as a JSON array -(--format=json). -.RE -.RS 4 -.TP 4 -.B files - -Output the filenames of all messages matching the search terms, either -one per line (--format=text) or as a JSON array (--format=json). -.RE -.RS 4 -.TP 4 -.B tags - -Output all tags that appear on any message matching the search terms, -either one per line (--format=text) or as a JSON array -(--format=json). -.RE -.RE - -.RS 4 -.TP 4 -.BR \-\-sort= ( newest\-first | oldest\-first ) - -This option can be used to present results in either chronological order -.RB ( oldest\-first ) -or reverse chronological order -.RB ( newest\-first ). - -Note: The thread order will be distinct between these two options -(beyond being simply reversed). When sorting by -.B oldest\-first -the threads will be sorted by the oldest message in each thread, but -when sorting by -.B newest\-first -the threads will be sorted by the newest message in each thread. - -.RE -.RS 4 -By default, results will be displayed in reverse chronological order, -(that is, the newest results will be displayed first). - -See the -.B "SEARCH SYNTAX" -section below for details of the supported syntax for . -.RE -.TP -.BR show " [options...] ..." - -Shows all messages matching the search terms. - -The messages will be grouped and sorted based on the threading (all -replies to a particular message will appear immediately after that -message in date order). The output is not indented by default, but -depth tags are printed so that proper indentation can be performed by -a post-processor (such as the emacs interface to notmuch). - -Supported options for -.B show -include -.RS 4 -.TP 4 -.B \-\-entire\-thread - -By default only those messages that match the search terms will be -displayed. With this option, all messages in the same thread as any -matched message will be displayed. -.RE - -.RS 4 -.TP 4 -.B \-\-format=(text|json|mbox) - -.RS 4 -.TP 4 -.B text - -The default plain-text format has all text-content MIME parts -decoded. Various components in the output, -.RB ( message ", " header ", " body ", " attachment ", and MIME " part ), -will be delimited by easily-parsed markers. Each marker consists of a -Control-L character (ASCII decimal 12), the name of the marker, and -then either an opening or closing brace, ('{' or '}'), to either open -or close the component. -.RE -.RS 4 -.TP 4 -.B json - -The output is formatted with Javascript Object Notation (JSON). This -format is more robust than the text format for automated -processing. JSON output always includes all messages in a matching -thread; in effect -.B \-\-format=json -implies -.B \-\-entire\-thread - -.RE -.RS 4 -.TP 4 -.B mbox - -All matching messages are output in the traditional, Unix mbox format -with each message being prefixed by a line beginning with "From " and -a blank line separating each message. Lines in the message content -beginning with "From " (preceded by zero or more '>' characters) have -an additional '>' character added. This reversible escaping -is termed "mboxrd" format and described in detail here: -http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html -.RE -A common use of -.B notmuch show -is to display a single thread of email messages. For this, use a -search term of "thread:" as can be seen in the first -column of output from the -.B notmuch search -command. - -See the -.B "SEARCH SYNTAX" -section below for details of the supported syntax for . -.RE -.TP -.BR count " ..." - -Count messages matching the search terms. - -The number of matching messages is output to stdout. - -With no search terms, a count of all messages in the database will be -displayed. -.RE -.RE - -The -.B reply -command is useful for preparing a template for an email reply. -.RS 4 -.TP 4 -.BR reply " [options...] ..." - -Constructs a reply template for a set of messages. - -To make replying to email easier, -.B notmuch reply -takes an existing set of messages and constructs a suitable mail -template. The Reply-to header (if any, otherwise From:) is used for -the To: address. Vales from the To: and Cc: headers are copied, but -not including any of the current user's email addresses (as configured -in primary_mail or other_email in the .notmuch\-config file) in the -recipient list - -It also builds a suitable new subject, including Re: at the front (if -not already present), and adding the message IDs of the messages being -replied to to the References list and setting the In\-Reply\-To: field -correctly. - -Finally, the original contents of the emails are quoted by prefixing -each line with '> ' and included in the body. - -The resulting message template is output to stdout. - -Supported options for -.B reply -include -.RS -.TP 4 -.BR \-\-format= ( default | headers\-only ) -.RS -.TP 4 -.BR default -Includes subject and quoted message body. -.TP -.BR headers\-only -Only produces In\-Reply\-To, References, To, Cc, and Bcc headers. -.RE - -See the -.B "SEARCH SYNTAX" -section below for details of the supported syntax for . - -Note: It is most common to use -.B "notmuch reply" -with a search string matching a single message, (such as -id:), but it can be useful to reply to several messages at -once. For example, when a series of patches are sent in a single -thread, replying to the entire thread allows for the reply to comment -on issue found in multiple patches. -.RE -.RE - -The -.B tag -command is the only command available for manipulating database -contents. - -.RS 4 -.TP 4 -.BR tag " +|\- [...] [\-\-] ..." - -Add/remove tags for all messages matching the search terms. - -Tags prefixed by '+' are added while those prefixed by '\-' are -removed. For each message, tag removal is performed before tag -addition. - -The beginning of is recognized by the first -argument that begins with neither '+' nor '\-'. Support for -an initial search term beginning with '+' or '\-' is provided -by allowing the user to specify a "\-\-" argument to separate -the tags from the search terms. - -See the -.B "SEARCH SYNTAX" -section below for details of the supported syntax for . -.RE - -The -.BR dump " and " restore -commands can be used to create a textual dump of email tags for backup -purposes, and to restore from that dump - -.RS 4 -.TP 4 -.BR dump " []" - -Creates a plain-text dump of the tags of each message. - -The output is to the given filename, if any, or to stdout. - -These tags are the only data in the notmuch database that can't be -recreated from the messages themselves. The output of notmuch dump is -therefore the only critical thing to backup (and much more friendly to -incremental backup than the native database files.) -.TP -.BR restore " " - -Restores the tags from the given file (see -.BR "notmuch dump" "." - -Note: The dump file format is specifically chosen to be -compatible with the format of files produced by sup-dump. -So if you've previously been using sup for mail, then the -.B "notmuch restore" -command provides you a way to import all of your tags (or labels as -sup calls them). -.RE - -The -.B part -command can used to output a single part of a multi-part MIME message. - -.RS 4 -.TP 4 -.BR part " \-\-part= ..." - -Output a single MIME part of a message. - -A single decoded MIME part, with no encoding or framing, is output to -stdout. The search terms must match only a single message, otherwise -this command will fail. - -The part number should match the part "id" field output by the -"\-\-format=json" option of "notmuch show". If the message specified by -the search terms does not include a part with the specified "id" there -will be no output. - -See the -.B "SEARCH SYNTAX" -section below for details of the supported syntax for . -.RE - -The -.B config -command can be used to get or set settings int the notmuch -configuration file. - -.RS 4 -.TP 4 -.BR "config get "
. - -The value of the specified configuration item is printed to stdout. If -the item has multiple values, each value is separated by a newline -character. - -Available configuration items include at least - - database.path - - user.name - - user.primary_email - - user.other_email - - new.tags -.RE - -.RS 4 -.TP 4 -.BR "config set "
. " [values ...]" - -The specified configuration item is set to the given value. To -specify a multiple-value item, provide each value as a separate -command-line argument. - -If no values are provided, the specified configuration item will be -removed from the configuration file. -.RE - -.SH SEARCH SYNTAX -Several notmuch commands accept a common syntax for search terms. - -The search terms can consist of free-form text (and quoted phrases) -which will match all messages that contain all of the given -terms/phrases in the body, the subject, or any of the sender or -recipient headers. - -As a special case, a search string consisting of exactly a single -asterisk ("*") will match all messages. - -In addition to free text, the following prefixes can be used to force -terms to match against specific portions of an email, (where - indicate user-supplied values): - - from: - - to: - - subject: - - attachment: - - tag: (or is:) - - id: - - thread: - -The -.B from: -prefix is used to match the name or address of the sender of an email -message. - -The -.B to: -prefix is used to match the names or addresses of any recipient of an -email message, (whether To, Cc, or Bcc). - -Any term prefixed with -.B subject: -will match only text from the subject of an email. Searching for a -phrase in the subject is supported by including quotation marks around -the phrase, immediately following -.BR subject: . - -The -.B attachment: -prefix can be used to search for specific filenames (or extensions) of -attachments to email messages. - -For -.BR tag: " and " is: -valid tag values include -.BR inbox " and " unread -by default for new messages added by -.B notmuch new -as well as any other tag values added manually with -.BR "notmuch tag" . - -For -.BR id: , -message ID values are the literal contents of the Message\-ID: header -of email messages, but without the '<', '>' delimiters. - -The -.B thread: -prefix can be used with the thread ID values that are generated -internally by notmuch (and do not appear in email messages). These -thread ID values can be seen in the first column of output from -.B "notmuch search" - -In addition to individual terms, multiple terms can be -combined with Boolean operators ( -.BR and ", " or ", " not -, etc.). Each term in the query will be implicitly connected by a -logical AND if no explicit operator is provided, (except that terms -with a common prefix will be implicitly combined with OR until we get -Xapian defect #402 fixed). - -Parentheses can also be used to control the combination of the Boolean -operators, but will have to be protected from interpretation by the -shell, (such as by putting quotation marks around any parenthesized -expression). - -Finally, results can be restricted to only messages within a -particular time range, (based on the Date: header) with a syntax of: - - .. - -Each timestamp is a number representing the number of seconds since -1970\-01\-01 00:00:00 UTC. This is not the most convenient means of -expressing date ranges, but until notmuch is fixed to accept a more -convenient form, one can use the date program to construct -timestamps. For example, with the bash shell the folowing syntax would -specify a date range to return messages from 2009\-10\-01 until the -current time: - - $(date +%s \-d 2009\-10\-01)..$(date +%s) -.SH ENVIRONMENT -The following environment variables can be used to control the -behavior of notmuch. -.TP -.B NOTMUCH_CONFIG -Specifies the location of the notmuch configuration file. Notmuch will -use ${HOME}/.notmuch\-config if this variable is not set. -.SH SEE ALSO -The emacs-based interface to notmuch (available as -.B notmuch.el -in the Notmuch distribution). - -The notmuch website: -.B http://notmuchmail.org -.SH 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). -- 1.7.1