From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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