From: Jani Nikula Date: Fri, 17 Jan 2014 16:10:52 +0000 (+0200) Subject: Re: [Patch v3 2/3] man: partial conversion to pod. X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=979bfb19f5b6922b56e74f873e8d568cea27bcfc;p=notmuch-archives.git Re: [Patch v3 2/3] man: partial conversion to pod. --- diff --git a/82/c2b142852ea3d8b2d9085bb20927aa2c0b80b4 b/82/c2b142852ea3d8b2d9085bb20927aa2c0b80b4 new file mode 100644 index 000000000..0bf0bd936 --- /dev/null +++ b/82/c2b142852ea3d8b2d9085bb20927aa2c0b80b4 @@ -0,0 +1,1599 @@ +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 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