From 9787cd6bcc8eff6ebf0dd79d9e0211a126495c47 Mon Sep 17 00:00:00 2001 From: david Date: Thu, 4 Nov 2010 14:18:55 +2100 Subject: [PATCH] [PATCH 3/4] Add rules to build notmuch.1 and notmuch-help.h from the pod file. --- 94/a79434d00f2a7d27378b8ca957adcc514e6d6d | 726 ++++++++++++++++++++++ 1 file changed, 726 insertions(+) create mode 100644 94/a79434d00f2a7d27378b8ca957adcc514e6d6d diff --git a/94/a79434d00f2a7d27378b8ca957adcc514e6d6d b/94/a79434d00f2a7d27378b8ca957adcc514e6d6d new file mode 100644 index 000000000..dc5d53597 --- /dev/null +++ b/94/a79434d00f2a7d27378b8ca957adcc514e6d6d @@ -0,0 +1,726 @@ +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 + -- 2.26.2