[PATCH 2/3] man: partial conversion to pod.
David Bremner
david at tethera.net
Sun Jan 5 03:39:09 PST 2014
From: David Bremner <bremner at debian.org>
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 as follows:
% groff -e -mandoc -Tascii -rHY=0 $* | rman -f POD | sed -e '/./,/^$/!d' -e 's/
Some small hand-editing of the .pod may be needed afterwards.
---
INSTALL | 6 +
configure | 12 ++
info/Makefile.local | 25 +++-
man/Makefile.local | 19 ++-
man/man1/notmuch.1 | 190 ----------------------------
man/man7/notmuch-search-terms.7 | 269 ----------------------------------------
pod/notmuch-search-terms.pod | 235 +++++++++++++++++++++++++++++++++++
pod/notmuch.pod | 155 +++++++++++++++++++++++
8 files changed, 448 insertions(+), 463 deletions(-)
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.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..cca891a 100644
--- a/info/Makefile.local
+++ b/info/Makefile.local
@@ -2,10 +2,14 @@
dir := info
+man_texi := $(dir)/notmuch.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,23 @@ ifeq ($(HAVE_INSTALLINFO),1)
install: install-info
endif
-%.info: %.texi
+%.entry: ../pod/%.pod
+ printf "@dircategory Notmuch\n at 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
+%.texi: ../pod/%.pod
+ # a nasty hack, but the nicer ways seem to have bugs.
+ pod2texi $< | \
+ sed 's/@node Top/@include $(*F).entry\n at node Top/' > $@
+
.PHONY: $(dir)/version.texi
$(dir)/version.texi: version
printf "@set VERSION ${VERSION}\n" > $@
@@ -29,5 +45,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..91bef04 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) $(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.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 <cworth at cworth.org>
-.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 <notmuch at notmuchmail.org> . 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
-<brackets> indicate user-supplied values):
-
- from:<name-or-address>
-
- to:<name-or-address>
-
- subject:<word-or-quoted-phrase>
-
- attachment:<word>
-
- tag:<tag> (or is:<tag>)
-
- id:<message-id>
-
- thread:<thread-id>
-
- folder:<directory-path>
-
- date:<since>..<until>
-
-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:<since>..<until>
-
-See \fBDATE AND TIME SEARCH\fR below for details on the range
-expression, and supported syntax for <since> and <until> date and time
-expressions.
-
-The time range can also be specified using timestamps with a syntax
-of:
-
- <initial-timestamp>..<final-timestamp>
-
-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:<since>..<until>
-
-The above expression restricts the results to only messages from
-<since> to <until>, based on the Date: header.
-
-<since> and <until> can describe imprecise times, such as "yesterday".
-In this case, <since> is taken as the earliest time it could describe
-(the beginning of yesterday) and <until> 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:..<until> or date:<since>.. 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<notmuch> B<count> [I<options...>] <I<search-term>>...
+
+B<notmuch> B<dump> [ <I<filename>> ] [--] [ <I<search-term>>...]
+
+B<notmuch> B<search> [I<options>...] <I<search-term>>...
+
+B<notmuch> B<show> [I<options>...] <I<search-term>>...
+
+B<notmuch> B<tag> +<I<tag>>|-<I<tag>> [...] [--] <I<search-term>>...
+
+=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 <brackets>
+indicate user-supplied values):
+
+from:<name-or-address>
+
+to:<name-or-address>
+
+subject:<word-or-quoted-phrase>
+
+attachment:<word>
+
+tag:<tag> (or is:<tag>)
+
+id:<message-id>
+
+thread:<thread-id>
+
+folder:<directory-path>
+
+date:<since>..<until>
+
+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
+B<subject:>.
+
+The B<attachment:> prefix can be used to search for specific filenames (or
+extensions) of attachments to email messages.
+
+For B<tag:> and B<is:> valid tag values include B<inbox> and B<unread> by default
+for new messages added by B<notmuch> B<new> as well as any other tag values
+added manually with B<notmuch> B<tag>.
+
+For B<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> B<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:<since>..<until>
+
+See B<DATE> B<AND> B<TIME> B<SEARCH> below for details on the range expression, and
+supported syntax for <since> and <until> date and time expressions.
+
+The time range can also be specified using timestamps with a syntax of:
+
+<initial-timestamp>..<final-timestamp>
+
+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 ( B<and>, B<or>, B<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).
+
+=head1 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.
+
+B<The> B<range> B<expression>
+
+date:<since>..<until>
+
+The above expression restricts the results to only messages
+from <since> to <until>, based on the Date: header.
+
+<since> and <until> can describe imprecise times, such as
+"yesterday". In this case, <since> is taken as the earliest
+time it could describe (the beginning of yesterday) and <until>
+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:..<until> or date:<since>.. 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).
+
+B<Relative> B<date> B<and> B<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
+
+B<Supported> B<absolute> B<time> B<formats>
+H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]
+
+H[H] (am|a.m.|pm|p.m.)
+
+=over 5
+
+=item HHMMSS
+
+=back
+
+now
+
+noon
+
+midnight
+
+Examples: 17:05, 5pm
+
+B<Supported> B<absolute> B<date> B<formats>
+YYYY-MM[-DD]
+
+=over 5
+
+=item DD-MM[-[YY]YY]
+
+=item MM-YYYY
+
+=item M[M]/D[D][/[YY]YY]
+
+=item M[M]/YYYY
+
+=item D[D].M[M][.[YY]YY]
+
+=back
+
+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
+
+B<Time> B<zones>
+(+|-)HH:MM
+
+=over 5
+
+=item (+|-)HH[MM]
+
+=back
+
+Some time zone codes, e.g. UTC, EET.
+
+=head1 See Also
+
+L<notmuch(1)>, L<notmuch-config(1)>, L<notmuch-count(1)>, L<notmuch-dump(1)>,
+L<notmuch-hooks(5)>, L<notmuch-insert(1)>, L<notmuch-new(1)>, L<notmuch-reply(1)>,
+L<notmuch-restore(1)>, L<notmuch-search(1)>, L<notmuch-show(1)>, L<notmuch-tag(1)>
diff --git a/pod/notmuch.pod b/pod/notmuch.pod
new file mode 100644
index 0000000..5b11967
--- /dev/null
+++ b/pod/notmuch.pod
@@ -0,0 +1,155 @@
+=head1 Name
+
+notmuch - thread-based email index, search, and tagging
+
+=head1 Synopsis
+
+B<notmuch> [I<option> ...] I<command> [I<arg> ...]
+
+=head1 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> B<show> consult the L<notmuch-show(1)> man page,
+also accessible via B<notmuch> B<help> B<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.
+
+=head1 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.
+
+=head1 Options
+
+Supported global options for B<notmuch> include
+
+=over 5
+
+=item B<--help>
+
+=back
+
+Print a synopsis of available commands and exit.
+
+=over 5
+
+=item B<--version>
+
+=back
+
+Print the installed version of notmuch, and exit.
+
+=over 5
+
+=item B<--config=FILE>
+
+=back
+
+Specify the configuration file to use. This overrides any
+configuration file specified by ${NOTMUCH_CONFIG}.
+
+=head1 Commands
+
+B<SETUP>
+The B<notmuch> B<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> B<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> B<setup> B<.>
+
+Invoking B<notmuch> with no command argument will run B<setup> if the setup
+command has not previously been completed.
+
+B<OTHER> B<COMMANDS>
+Several of the notmuch commands accept search terms with a common
+syntax. See L<notmuch-search-terms(7)> for more details on the supported
+syntax.
+
+The B<search>, B<show> and B<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 B<dump> and B<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.
+
+=head1 Environment
+
+The following environment variables can be used to control the behavior
+of notmuch.
+
+=over 5
+
+=item B<NOTMUCH_CONFIG>
+
+Specifies the location of the notmuch configuration file.
+Notmuch will use ${HOME}/.notmuch-config if this variable is not
+set.
+
+=item B<NOTMUCH_TALLOC_REPORT>
+
+Location to write a talloc memory usage report. See
+B<talloc_enable_leak_report_full> in L<talloc(3)> for more
+information.
+
+=item B<NOTMUCH_DEBUG_QUERY>
+
+If set to a non-empty value, the notmuch library will print (to
+stderr) Xapian queries it constructs.
+
+=back
+
+=head1 See Also
+
+L<notmuch-config(1)>, L<notmuch-count(1)>, L<notmuch-dump(1)>, L<notmuch-hooks(5)>,
+L<notmuch-insert(1)>, L<notmuch-new(1)>, L<notmuch-reply(1)>, L<notmuch-restore(1)>,
+L<notmuch-search(1)>, L<notmuch-search-terms(7)>, L<notmuch-show(1)>,
+L<notmuch-tag(1)>
+
+The notmuch website: B<http://notmuchmail.org>
+
+=head1 Contact
+
+Feel free to send questions, comments, or kudos to the notmuch mailing
+list <notmuch at notmuchmail.org> . Subscription is not required before
+posting, but is available from the notmuchmail.org website.
+
+Real-time interaction with the Notmuch community is available via IRC
+(server: irc.freenode.net, channel: #notmuch).
--
1.8.5.2
More information about the notmuch
mailing list