From: David Bremner Date: Wed, 15 Jan 2014 13:08:51 +0000 (+2000) Subject: [Patch v3 2/3] man: partial conversion to pod. X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=1ed4e2c10f08545399fc959fe166690e4685cadf;p=notmuch-archives.git [Patch v3 2/3] man: partial conversion to pod. --- diff --git a/fd/d0109b866a042b8915276ff61e5975b4b53f54 b/fd/d0109b866a042b8915276ff61e5975b4b53f54 new file mode 100644 index 000000000..419366a83 --- /dev/null +++ b/fd/d0109b866a042b8915276ff61e5975b4b53f54 @@ -0,0 +1,1523 @@ +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 9FAAF431FAF + for ; Wed, 15 Jan 2014 05:09:21 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: 0 +X-Spam-Level: +X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none] + autolearn=disabled +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 QDlE30l4Br5P for ; + Wed, 15 Jan 2014 05:09:12 -0800 (PST) +Received: from yantan.tethera.net (yantan.tethera.net [199.188.72.155]) + (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id 33CAC431FB6 + for ; Wed, 15 Jan 2014 05:09:12 -0800 (PST) +Received: from remotemail by yantan.tethera.net with local (Exim 4.80) + (envelope-from ) + id 1W3QDW-0005UU-07; Wed, 15 Jan 2014 09:09:10 -0400 +Received: (nullmailer pid 21894 invoked by uid 1000); Wed, 15 Jan 2014 + 13:08:59 -0000 +From: David Bremner +To: notmuch@notmuchmail.org +Subject: [Patch v3 2/3] man: partial conversion to pod. +Date: Wed, 15 Jan 2014 09:08:51 -0400 +Message-Id: <1389791332-21719-3-git-send-email-david@tethera.net> +X-Mailer: git-send-email 1.8.5.2 +In-Reply-To: <1389791332-21719-1-git-send-email-david@tethera.net> +References: + <1389791332-21719-1-git-send-email-david@tethera.net> +MIME-Version: 1.0 +Content-Type: text/plain; charset=UTF-8 +Content-Transfer-Encoding: 8bit +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, 15 Jan 2014 13:09:21 -0000 + +From: David Bremner + +This allows generation of man page and info document from the same source. +It is also a bit more friendly to edit for most people. + +The conversion was done with the following perl script (some small +hand-editing of the .pod may be needed afterwards). + +open(POD,"groff -e -mandoc -Tascii -rHY=0 | rman -f POD|") || die; +LINE: +while(){ + my $blank=0; + while (m/^\s*$/) { + $_=; + $blank++; + } + print "\n" if ($blank); + + while(s/^(=head1 .*)B[<]/\1/){}; + while(s/^(=head1 .*)[>]/\1/){}; + + s/ */ /g; + print; +} +--- + INSTALL | 6 + + configure | 12 ++ + info/Makefile.local | 28 ++++- + man/Makefile.local | 19 ++- + man/man1/notmuch-search.1 | 199 ----------------------------- + man/man1/notmuch.1 | 190 ---------------------------- + man/man7/notmuch-search-terms.7 | 269 ---------------------------------------- + pod/notmuch-search-terms.pod | 235 +++++++++++++++++++++++++++++++++++ + pod/notmuch-search.pod | 194 +++++++++++++++++++++++++++++ + pod/notmuch.pod | 155 +++++++++++++++++++++++ + 10 files changed, 645 insertions(+), 662 deletions(-) + delete mode 100644 man/man1/notmuch-search.1 + delete mode 100644 man/man1/notmuch.1 + delete mode 100644 man/man7/notmuch-search-terms.7 + create mode 100644 pod/notmuch-search-terms.pod + create mode 100644 pod/notmuch-search.pod + create mode 100644 pod/notmuch.pod + +diff --git a/INSTALL b/INSTALL +index 451bf05..697b7b2 100644 +--- a/INSTALL ++++ b/INSTALL +@@ -60,6 +60,12 @@ Talloc which are each described below: + + Talloc is available from http://talloc.samba.org/ + ++ pod2man ++ ------- ++ ++ Some of the documentation is built with pod2man. This is part ++ of the standard Perl distribution since Perl 5.6.0 ++ + texinfo + ------- + +diff --git a/configure b/configure +index e75c1d4..6dadbaa 100755 +--- a/configure ++++ b/configure +@@ -389,6 +389,15 @@ else + have_emacs=0 + fi + ++printf "Checking for pod2man... " ++if pod2man --help > /dev/null 2>&1; then ++ printf "Yes.\n" ++ have_pod2man=1 ++else ++ printf "No (man page install may fail)\n" ++ have_pod2man=0 ++fi ++ + printf "Checking for makeinfo... " + if makeinfo --version > /dev/null 2>&1; then + printf "Yes.\n" +@@ -768,6 +777,9 @@ HAVE_MAKEINFO = ${have_makeinfo} + # Whether there's an install-info binary available + HAVE_INSTALLINFO = ${have_installinfo} + ++# Is pod2man in the path? ++HAVE_POD2MAN = ${have_pod2man} ++ + # where to install info files + + INFODIR = ${INFODIR} +diff --git a/info/Makefile.local b/info/Makefile.local +index 55e9740..26466ae 100644 +--- a/info/Makefile.local ++++ b/info/Makefile.local +@@ -2,10 +2,14 @@ + + dir := info + ++man_texi := $(dir)/notmuch.texi $(dir)/notmuch-search.texi $(dir)/notmuch-search-terms.texi ++man_info := $(man_texi:.texi=.info) ++man_entry := $(man_texi:.texi=.entry) ++ + texi_sources := $(dir)/notmuch-emacs.texi + emacs_info := $(texi_sources:.texi=.info) + +-info := $(emacs_info) ++info := $(emacs_info) $(man_info) + + ifeq ($(HAVE_MAKEINFO),1) + all: $(info) +@@ -15,11 +19,26 @@ ifeq ($(HAVE_INSTALLINFO),1) + install: install-info + endif + +-%.info: %.texi ++%.entry: ../pod/%.pod ++ printf "@dircategory Notmuch\n@direntry\n" > $@ ++ printf "* %s: (%s). " $(*F) $(*F) >> $@ ++ podselect -section Name $< | \ ++ perl -n -e 's/notmuch.* - (.*)/\u\L$$1/ && print' >> $@ ++ printf "@end direntry\n" >> $@ ++ ++%.info: %.texi %.entry + makeinfo --no-split -o $@ $< + + $(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi + ++ ++%.raw-texi: ../pod/%.pod ++ pod2texi --output $@ $< ++ ++%.texi: %.raw-texi ++ # a nasty hack, but the nicer ways seem to have bugs. ++ sed 's/@node Top/@include $(*F).entry\n@node Top/'< $< > $@ ++ + .PHONY: $(dir)/version.texi + $(dir)/version.texi: version + printf "@set VERSION ${VERSION}\n" > $@ +@@ -29,5 +48,8 @@ install-info: ${info} + mkdir -p "$(DESTDIR)$(INFODIR)" + install -m0644 $(info) "$(DESTDIR)$(INFODIR)" + install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info) ++ for ifile in $(man_info); do \ ++ install-info --info-dir=${DESTDIR}${INFODIR} $${ifile}; \ ++ done + +-CLEAN := $(CLEAN) $(info) ++CLEAN := $(CLEAN) $(info) $(man_entry) $(dir)/version.texi +diff --git a/man/Makefile.local b/man/Makefile.local +index 57910b7..ae4caff 100644 +--- a/man/Makefile.local ++++ b/man/Makefile.local +@@ -23,6 +23,8 @@ MAN1 := \ + MAN5 := $(dir)/man5/notmuch-hooks.5 + MAN7 := $(dir)/man7/notmuch-search-terms.7 + ++GENERATED_MAN := $(MAIN_PAGE) $(dir)/man1/notmuch-search.1 $(MAN7) ++ + MAN1_GZ := $(addsuffix .gz,$(MAN1)) + MAN5_GZ := $(addsuffix .gz,$(MAN5)) + MAN7_GZ := $(addsuffix .gz,$(MAN7)) +@@ -34,6 +36,21 @@ COMPRESSED_MAN := $(MAN1_GZ) $(MAN5_GZ) $(MAN7_GZ) + %.gz: % + gzip --stdout $^ > $@ + ++POD2MAN_RECIPE = mkdir -p $(@D) && \ ++ pod2man --section=$(subst .,,$(suffix $@)) \ ++ --center="Notmuch Documentation" --release=${VERSION} $< > $@ ++ ++$(dir)/man1/%.1: $(dir)/../pod/%.pod ++ $(POD2MAN_RECIPE) ++ ++$(dir)/man5/%.5: $(dir)/../pod/%.pod ++ $(POD2MAN_RECIPE) ++ ++$(dir)/man7/%.7: $(dir)/../pod/%.pod ++ $(POD2MAN_RECIPE) ++ ++CLEAN := $(CLEAN) $(NROFF7) ++ + .PHONY: install-man update-man-versions + + install-man: $(COMPRESSED_MAN) +@@ -52,4 +69,4 @@ update-man-versions: $(MAN_SOURCE) + < $$file.bak > $$file; \ + done + +-CLEAN := $(CLEAN) $(COMPRESSED_MAN) $(MAN_BACKUP) ++CLEAN := $(CLEAN) $(COMPRESSED_MAN) $(MAN_BACKUP) $(GENERATED_MAN) +diff --git a/man/man1/notmuch-search.1 b/man/man1/notmuch-search.1 +deleted file mode 100644 +index 55a81e7..0000000 +--- a/man/man1/notmuch-search.1 ++++ /dev/null +@@ -1,199 +0,0 @@ +-.TH NOTMUCH-SEARCH 1 2013-12-30 "Notmuch 0.17" +-.SH NAME +-notmuch-search \- search for messages matching the given search terms +-.SH SYNOPSIS +- +-.B notmuch search +-.RI [ options "...] <" search-term ">..." +- +-.SH DESCRIPTION +- +-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. +- +-See \fBnotmuch-search-terms\fR(7) +-for details of the supported syntax for . +- +-Supported options for +-.B search +-include +-.RS 4 +-.TP 4 +-.BR \-\-format= ( json | sexp | text | text0 ) +- +-Presents the results in either JSON, S-Expressions, newline character +-separated plain-text (default), or null character separated plain-text +-(compatible with \fBxargs\fR(1) -0 option where available). +-.RE +- +-.RS 4 +-.TP 4 +-.BR \-\-format-version=N +- +-Use the specified structured output format version. This is intended +-for programs that invoke \fBnotmuch\fR(1) internally. If omitted, the +-latest supported version will be used. +-.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), separated by null +-characters (\-\-format=text0), as a JSON array (\-\-format=json), or +-an S-Expression list (\-\-format=sexp). +-.RE +-.RS 4 +-.TP 4 +-.B messages +- +-Output the message IDs of all messages matching the search terms, +-either one per line (\-\-format=text), separated by null characters +-(\-\-format=text0), as a JSON array (\-\-format=json), or as an +-S-Expression list (\-\-format=sexp). +-.RE +-.RS 4 +-.TP 4 +-.B files +- +-Output the filenames of all messages matching the search terms, either +-one per line (\-\-format=text), separated by null characters +-(\-\-format=text0), as a JSON array (\-\-format=json), or as an +-S-Expression list (\-\-format=sexp). +- +-Note that each message may have multiple filenames associated with it. +-All of them are included in the output, unless limited with the +-\-\-duplicate=N option. +-.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), separated by null characters +-(\-\-format=text0), as a JSON array (\-\-format=json), or as an +-S-Expression list (\-\-format=sexp). +-.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. +- +-By default, results will be displayed in reverse chronological order, +-(that is, the newest results will be displayed first). +-.RE +- +-.RS 4 +-.TP 4 +-.BR \-\-offset=[\-]N +- +-Skip displaying the first N results. With the leading '\-', start at the Nth +-result from the end. +-.RE +- +-.RS 4 +-.TP 4 +-.BR \-\-limit=N +- +-Limit the number of displayed results to N. +-.RE +- +-.RS 4 +-.TP 4 +-.BR \-\-exclude=(true|false|all|flag) +- +-A message is called "excluded" if it matches at least one tag in +-search.tag_exclude that does not appear explicitly in the search terms. +-This option specifies whether to omit excluded messages in the search +-process. +- +-The default value, +-.BR true , +-prevents excluded messages from matching the search terms. +- +-.B all +-additionally prevents excluded messages from appearing in displayed +-results, in effect behaving as though the excluded messages do not exist. +- +-.B false +-allows excluded messages to match search terms and appear in displayed +-results. Excluded messages are still marked in the relevant outputs. +- +-.B flag +-only has an effect when +-.BR --output=summary . +-The output is almost identical to +-.BR false , +-but the "match count" is the number of matching non-excluded messages in the +-thread, rather than the number of matching messages. +-.RE +- +-.RS 4 +-.TP 4 +-.BR \-\-duplicate=N +- +-Effective with +-.BR --output=files , +-output the Nth filename associated with each message matching the +-query (N is 1-based). If N is greater than the number of files +-associated with the message, don't print anything. +- +-Note that this option is orthogonal with the +-.BR folder: +-search prefix. The prefix matches messages based on filenames. This +-option filters filenames of the matching messages. +-.RE +- +-.SH EXIT STATUS +- +-This command supports the following special exit status codes +- +-.TP +-.B 20 +-The requested format version is too old. +-.TP +-.B 21 +-The requested format version is too new. +- +-.SH SEE ALSO +- +-\fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1), +-\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), +-\fBnotmuch-insert\fR(1), \fBnotmuch-new\fR(1), +-\fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1), +-\fBnotmuch-search-terms\fR(7), \fBnotmuch-show\fR(1), +-\fBnotmuch-tag\fR(1) +diff --git a/man/man1/notmuch.1 b/man/man1/notmuch.1 +deleted file mode 100644 +index 605b514..0000000 +--- a/man/man1/notmuch.1 ++++ /dev/null +@@ -1,190 +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 2013-12-30 "Notmuch 0.17" +-.SH NAME +-notmuch \- thread-based email index, search, and tagging +-.SH SYNOPSIS +-.B notmuch +-.RI "[" option " ...] " command " [" arg " ...]" +-.SH 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. +-.B notmuch show +-consult the \fBnotmuch-show\fR(1) man page, also accessible via +-.B notmuch help show +- +-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. The emacs-based interface to notmuch (available under +-.B emacs/ +-in the Notmuch source distribution) is probably the most widely used at +-this time. +- +-.SH OPTIONS +- +-Supported global options for +-.B notmuch +-include +- +-.RS 4 +-.TP 4 +-.B \-\-help +- +-Print a synopsis of available commands and exit. +-.RE +- +-.RS 4 +-.TP 4 +-.B \-\-version +- +-Print the installed version of notmuch, and exit. +-.RE +- +-.RS 4 +-.TP 4 +-.B \-\-config=FILE +- +-Specify the configuration file to use. This overrides any +-configuration file specified by ${NOTMUCH_CONFIG}. +- +-.RE +- +-.SH COMMANDS +- +- +-.SS SETUP +- +-The +-.B 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 +-.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 +- +-.SS OTHER COMMANDS +- +-Several of the notmuch commands accept search terms with a common +-syntax. See \fNnotmuch-search-terms\fR(7) +-for more details on the supported syntax. +- +-The +-.BR search ", " show " and " count +-commands are used to query the email database. +- +-The +-.B reply +-command is useful for preparing a template for an email reply. +- +-The +-.B tag +-command is the only command available for manipulating database +-contents. +- +- +-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. +- +-The +-.B config +-command can be used to get or set settings int the notmuch +-configuration file. +- +-.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. +- +-.TP +-.B NOTMUCH_TALLOC_REPORT +-Location to write a talloc memory usage report. See +-.B talloc_enable_leak_report_full +-in \fBtalloc\fR(3) +-for more information. +- +-.TP +-.B NOTMUCH_DEBUG_QUERY +-If set to a non-empty value, the notmuch library will print (to stderr) Xapian +-queries it constructs. +- +-.SH SEE ALSO +- +-\fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1), +-\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), +-\fBnotmuch-insert\fR(1), \fBnotmuch-new\fR(1), +-\fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1), +-\fBnotmuch-search\fR(1), \fBnotmuch-search-terms\fR(7), +-\fBnotmuch-show\fR(1), \fBnotmuch-tag\fR(1) +- +- +-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). +diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7 +deleted file mode 100644 +index a768b63..0000000 +--- a/man/man7/notmuch-search-terms.7 ++++ /dev/null +@@ -1,269 +0,0 @@ +-.TH NOTMUCH-SEARCH-TERMS 7 2013-12-30 "Notmuch 0.17" +- +-.SH NAME +-notmuch-search-terms \- syntax for notmuch queries +- +-.SH SYNOPSIS +- +-.B notmuch count +-.RI [ options... ] +-.RI < search-term ">..." +- +-.B "notmuch dump" +-.RI "[ <" filename "> ] [--]" +-.RI "[ <" search-term ">...]" +- +-.B notmuch search +-.RI [ options "...] <" search-term ">..." +- +-.B notmuch show +-.RI "[" options "...] <" search-term ">..." +- +-.B notmuch tag +-.RI "+<" tag> "|\-<" tag "> [...] [\-\-] <" search-term ">..." +- +- +-.SH DESCRIPTION +-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: +- +- folder: +- +- date:.. +- +-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" +- +-The +-.B folder: +-prefix can be used to search for email message files that are +-contained within particular directories within the mail store. If the +-same email message has multiple message files associated with it, it's +-sufficient for a match that at least one of the files is contained +-within a matching directory. Only the directory components below the +-top-level mail database path are available to be searched. +- +-The +-.B date: +-prefix can be used to restrict the results to only messages within a +-particular time range (based on the Date: header) with a range syntax +-of: +- +- date:.. +- +-See \fBDATE AND TIME SEARCH\fR below for details on the range +-expression, and supported syntax for and date and time +-expressions. +- +-The time range can also be specified using timestamps with a syntax +-of: +- +- .. +- +-Each timestamp is a number representing the number of seconds since +-1970\-01\-01 00:00:00 UTC. +- +-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). +- +-.SH DATE AND TIME SEARCH +- +-notmuch understands a variety of standard and natural ways of +-expressing dates and times, both in absolute terms ("2012-10-24") and +-in relative terms ("yesterday"). Any number of relative terms can be +-combined ("1 hour 25 minutes") and an absolute date/time can be +-combined with relative terms to further adjust it. A non-exhaustive +-description of the syntax supported for absolute and relative terms is +-given below. +- +-.RS 4 +-.TP 4 +-.B The range expression +- +-date:.. +- +-The above expression restricts the results to only messages from +- to , based on the Date: header. +- +- and can describe imprecise times, such as "yesterday". +-In this case, is taken as the earliest time it could describe +-(the beginning of yesterday) and is taken as the latest time +-it could describe (the end of yesterday). Similarly, +-date:january..february matches from the beginning of January to the +-end of February. +- +-Currently, we do not support spaces in range expressions. You can +-replace the spaces with '_', or (in most cases) '-', or (in some +-cases) leave the spaces out altogether. Examples in this man page use +-spaces for clarity. +- +-Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's +-possible to specify date:.. or date:.. to not limit the +-start or end time, respectively. Pre-1.2.1 Xapian does not report an +-error on open ended ranges, but it does not work as expected either. +- +-Entering date:expr without ".." (for example date:yesterday) won't +-work, as it's not interpreted as a range expression at all. You can +-achieve the expected result by duplicating the expr both sides of ".." +-(for example date:yesterday..yesterday). +-.RE +- +-.RS 4 +-.TP 4 +-.B Relative date and time +-[N|number] (years|months|weeks|days|hours|hrs|minutes|mins|seconds|secs) [...] +- +-All refer to past, can be repeated and will be accumulated. +- +-Units can be abbreviated to any length, with the otherwise ambiguous +-single m being m for minutes and M for months. +- +-Number can also be written out one, two, ..., ten, dozen, +-hundred. Additionally, the unit may be preceded by "last" or "this" +-(e.g., "last week" or "this month"). +- +-When combined with absolute date and time, the relative date and time +-specification will be relative from the specified absolute date and +-time. +- +-Examples: 5M2d, two weeks +-.RE +- +-.RS 4 +-.TP 4 +-.B Supported absolute time formats +-H[H]:MM[:SS] [(am|a.m.|pm|p.m.)] +- +-H[H] (am|a.m.|pm|p.m.) +- +-HHMMSS +- +-now +- +-noon +- +-midnight +- +-Examples: 17:05, 5pm +-.RE +- +-.RS 4 +-.TP 4 +-.B Supported absolute date formats +-YYYY-MM[-DD] +- +-DD-MM[-[YY]YY] +- +-MM-YYYY +- +-M[M]/D[D][/[YY]YY] +- +-M[M]/YYYY +- +-D[D].M[M][.[YY]YY] +- +-D[D][(st|nd|rd|th)] Mon[thname] [YYYY] +- +-Mon[thname] D[D][(st|nd|rd|th)] [YYYY] +- +-Wee[kday] +- +-Month names can be abbreviated at three or more characters. +- +-Weekday names can be abbreviated at three or more characters. +- +-Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3 +-.RE +- +-.RS 4 +-.TP 4 +-.B Time zones +-(+|-)HH:MM +- +-(+|-)HH[MM] +- +-Some time zone codes, e.g. UTC, EET. +-.RE +- +-.SH SEE ALSO +- +-\fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1), +-\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), +-\fBnotmuch-insert\fR(1), \fBnotmuch-new\fR(1), +-\fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1), +-\fBnotmuch-search\fR(1), \fBnotmuch-show\fR(1), \fBnotmuch-tag\fR(1) +diff --git a/pod/notmuch-search-terms.pod b/pod/notmuch-search-terms.pod +new file mode 100644 +index 0000000..47b9c20 +--- /dev/null ++++ b/pod/notmuch-search-terms.pod +@@ -0,0 +1,235 @@ ++=head1 Name ++ ++notmuch-search-terms - syntax for notmuch queries ++ ++=head1 Synopsis ++ ++B B [I] >... ++ ++B B [ > ] [--] [ >...] ++ ++B B [I...] >... ++ ++B B [I...] >... ++ ++B B +>|-> [...] [--] >... ++ ++=head1 Description ++ ++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: ++ ++folder: ++ ++date:.. ++ ++The B prefix is used to match the name or address of the sender of ++an email message. ++ ++The B 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 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 ++B. ++ ++The B prefix can be used to search for specific filenames (or ++extensions) of attachments to email messages. ++ ++For B and B valid tag values include B and B by default ++for new messages added by B B as well as any other tag values ++added manually with B B. ++ ++For B, message ID values are the literal contents of the Message-ID: ++header of email messages, but without the `<', `>' delimiters. ++ ++The B 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 B ++ ++The B prefix can be used to search for email message files that ++are contained within particular directories within the mail store. If ++the same email message has multiple message files associated with it, ++it's sufficient for a match that at least one of the files is contained ++within a matching directory. Only the directory components below the ++top-level mail database path are available to be searched. ++ ++The B prefix can be used to restrict the results to only messages ++within a particular time range (based on the Date: header) with a range ++syntax of: ++ ++date:.. ++ ++See B B B