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 C303F431FB6 for ; Fri, 17 Jan 2014 08:11:10 -0800 (PST) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: -0.7 X-Spam-Level: X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5 tests=[RCVD_IN_DNSWL_LOW=-0.7] 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 wVruVB5w1CyN for ; Fri, 17 Jan 2014 08:10:59 -0800 (PST) Received: from mail-ee0-f42.google.com (mail-ee0-f42.google.com [74.125.83.42]) (using TLSv1 with cipher RC4-SHA (128/128 bits)) (No client certificate requested) by olra.theworths.org (Postfix) with ESMTPS id F1F2F431FBC for ; Fri, 17 Jan 2014 08:10:58 -0800 (PST) Received: by mail-ee0-f42.google.com with SMTP id e49so2194904eek.15 for ; Fri, 17 Jan 2014 08:10:57 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:in-reply-to:references :user-agent:date:message-id:mime-version:content-type :content-transfer-encoding; bh=jK5i0FMqNoFutoz5zd1ozx4t4f5Uyx8Ymo1hbxGkuV8=; b=bl6RDkMkSBvega6BbYvhjk0FytPPL6isohk7UEnU3vlwrv7WGQ7zih2UPjpq6Aew+s GMjIvEF4H3a3EyevMTfhKUN2OlkmU7lKCa87bvgU77oCOloP2q7wt6KxybnZkEK9iSGq +uYTAIyN4OPXCiI5ptmgsU6tlwjimfZ/VRpWxnZd1t+NxyfQfoBtryLhBFdyRLplMFkQ 1pGt6P09eLlxX2qFolYGwgsaR1Bm9i7dGDA3bFKmr0ks50sopJdqEITvPkkEmIqrQdZb Z0IitlX2SN00hRT6U3yihUqSIr+L6DtTtQufX/TF2Wu62eBZ/rmRk8Kc8zgyy5Hb02H3 7z2w== X-Gm-Message-State: ALoCoQmp2FZE4J4E8yARQD9b5QXQaQs1vw66EYHqYXMRSifYP6lx78Jrg/v2XYYoRzgYHfh39j7w X-Received: by 10.14.111.73 with SMTP id v49mr3383813eeg.94.1389975056563; Fri, 17 Jan 2014 08:10:56 -0800 (PST) Received: from localhost (dsl-hkibrasgw2-58c36f-91.dhcp.inet.fi. [88.195.111.91]) by mx.google.com with ESMTPSA id 4sm28025886eed.14.2014.01.17.08.10.53 for (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Fri, 17 Jan 2014 08:10:55 -0800 (PST) From: Jani Nikula To: David Bremner , notmuch@notmuchmail.org Subject: Re: [Patch v3 2/3] man: partial conversion to pod. In-Reply-To: <1389791332-21719-3-git-send-email-david@tethera.net> References: <1389791332-21719-1-git-send-email-david@tethera.net> <1389791332-21719-3-git-send-email-david@tethera.net> User-Agent: Notmuch/0.17~rc2+18~g39a67a6 (http://notmuchmail.org) Emacs/24.3.1 (x86_64-pc-linux-gnu) Date: Fri, 17 Jan 2014 18:10:52 +0200 Message-ID: <87lhyer3lf.fsf@nikula.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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: Fri, 17 Jan 2014 16:11:11 -0000 On Wed, 15 Jan 2014, David Bremner wrote: > 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. Before plunging into reviewing this, I'd like to have some more views on the choice of the format. Also on the mailing list and not just IRC. In short, I'm really tempted by using markdown as the format, not least because it's what we use for the web pages. The big (also literally) downside is pandoc (http://johnmacfarlane.net/pandoc/), the tool for converting markdown to man. I don't mind its dependencies, others may disagree. Are there any sensible alternatives to pandoc? That said, I do like pod better than *roff, and if people oppose to requiring pandoc for building and installing the man pages, I'm okay with that too. BR, Jani. > > 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=3D0 | rman -f POD|") || die; > LINE: > while(){ > my $blank=3D0; > while (m/^\s*$/) { > $_=3D; > $blank++; > } > print "\n" if ($blank); > > while(s/^(=3Dhead1 .*)B[<]/\1/){}; > while(s/^(=3Dhead1 .*)[>]/\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: >=20=20 > Talloc is available from http://talloc.samba.org/ >=20=20 > + pod2man > + ------- > + > + Some of the documentation is built with pod2man. This is part > + of the standard Perl distribution since Perl 5.6.0 > + > texinfo > ------- >=20=20 > diff --git a/configure b/configure > index e75c1d4..6dadbaa 100755 > --- a/configure > +++ b/configure > @@ -389,6 +389,15 @@ else > have_emacs=3D0 > fi >=20=20 > +printf "Checking for pod2man... " > +if pod2man --help > /dev/null 2>&1; then > + printf "Yes.\n" > + have_pod2man=3D1 > +else > + printf "No (man page install may fail)\n" > + have_pod2man=3D0 > +fi > + > printf "Checking for makeinfo... " > if makeinfo --version > /dev/null 2>&1; then > printf "Yes.\n" > @@ -768,6 +777,9 @@ HAVE_MAKEINFO =3D ${have_makeinfo} > # Whether there's an install-info binary available > HAVE_INSTALLINFO =3D ${have_installinfo} >=20=20 > +# Is pod2man in the path? > +HAVE_POD2MAN =3D ${have_pod2man} > + > # where to install info files >=20=20 > INFODIR =3D ${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 @@ >=20=20 > dir :=3D info >=20=20 > +man_texi :=3D $(dir)/notmuch.texi $(dir)/notmuch-search.texi $(dir)/not= much-search-terms.texi > +man_info :=3D $(man_texi:.texi=3D.info) > +man_entry :=3D $(man_texi:.texi=3D.entry) > + > texi_sources :=3D $(dir)/notmuch-emacs.texi > emacs_info :=3D $(texi_sources:.texi=3D.info) >=20=20 > -info :=3D $(emacs_info) > +info :=3D $(emacs_info) $(man_info) >=20=20 > ifeq ($(HAVE_MAKEINFO),1) > all: $(info) > @@ -15,11 +19,26 @@ ifeq ($(HAVE_INSTALLINFO),1) > install: install-info > endif >=20=20 > -%.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 $@ $< >=20=20 > $(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi >=20=20 > + > +%.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=3DNotmuch --info-dir=3D${DESTDIR}${INFODIR} $(em= acs_info) > + for ifile in $(man_info); do \ > + install-info --info-dir=3D${DESTDIR}${INFODIR} $${ifile}; \ > + done >=20=20 > -CLEAN :=3D $(CLEAN) $(info) > +CLEAN :=3D $(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 :=3D \ > MAN5 :=3D $(dir)/man5/notmuch-hooks.5 > MAN7 :=3D $(dir)/man7/notmuch-search-terms.7 >=20=20 > +GENERATED_MAN :=3D $(MAIN_PAGE) $(dir)/man1/notmuch-search.1 $(MAN7) > + > MAN1_GZ :=3D $(addsuffix .gz,$(MAN1)) > MAN5_GZ :=3D $(addsuffix .gz,$(MAN5)) > MAN7_GZ :=3D $(addsuffix .gz,$(MAN7)) > @@ -34,6 +36,21 @@ COMPRESSED_MAN :=3D $(MAN1_GZ) $(MAN5_GZ) $(MAN7_GZ) > %.gz: % > gzip --stdout $^ > $@ >=20=20 > +POD2MAN_RECIPE =3D mkdir -p $(@D) && \ > + pod2man --section=3D$(subst .,,$(suffix $@)) \ > + --center=3D"Notmuch Documentation" --release=3D${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 :=3D $(CLEAN) $(NROFF7) > + > .PHONY: install-man update-man-versions >=20=20 > install-man: $(COMPRESSED_MAN) > @@ -52,4 +69,4 @@ update-man-versions: $(MAN_SOURCE) > < $$file.bak > $$file; \ > done >=20=20 > -CLEAN :=3D $(CLEAN) $(COMPRESSED_MAN) $(MAN_BACKUP) > +CLEAN :=3D $(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=3D ( 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=3DN > - > -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=3D(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=3Dtext), separated by null > -characters (\-\-format=3Dtext0), as a JSON array (\-\-format=3Djson), or > -an S-Expression list (\-\-format=3Dsexp). > -.RE > -.RS 4 > -.TP 4 > -.B messages > - > -Output the message IDs of all messages matching the search terms, > -either one per line (\-\-format=3Dtext), separated by null characters > -(\-\-format=3Dtext0), as a JSON array (\-\-format=3Djson), or as an > -S-Expression list (\-\-format=3Dsexp). > -.RE > -.RS 4 > -.TP 4 > -.B files > - > -Output the filenames of all messages matching the search terms, either > -one per line (\-\-format=3Dtext), separated by null characters > -(\-\-format=3Dtext0), as a JSON array (\-\-format=3Djson), or as an > -S-Expression list (\-\-format=3Dsexp). > - > -Note that each message may have multiple filenames associated with it. > -All of them are included in the output, unless limited with the > -\-\-duplicate=3DN 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=3Dtext), separated by null characters > -(\-\-format=3Dtext0), as a JSON array (\-\-format=3Djson), or as an > -S-Expression list (\-\-format=3Dsexp). > -.RE > -.RE > - > -.RS 4 > -.TP 4 > -.BR \-\-sort=3D ( 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=3D[\-]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=3DN > - > -Limit the number of displayed results to N. > -.RE > - > -.RS 4 > -.TP 4 > -.BR \-\-exclude=3D(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=3Dsummary . > -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=3DN > - > -Effective with > -.BR --output=3Dfiles , > -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 tagg= ing) > -.\" > -.\" Copyright =C2=A9 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 u= nder > -.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=3DFILE > - > -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-te= rms.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 @@ > +=3Dhead1 Name > + > +notmuch-search-terms - syntax for notmuch queries > + > +=3Dhead1 Synopsis > + > +B B [I] >... > + > +B B [ > ] [--] [ >...] > + > +B B [I...] >... > + > +B B [I...] >... > + > +B B +>|-> [...] [--] >... > + > +=3Dhead1 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 recipie= nt > +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 b= y default > +for new messages added by B B as well as any other tag val= ues > +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