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 DB833431FBF for ; Wed, 24 Apr 2013 18:20:00 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: 0 X-Spam-Level: X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none] autolearn=disabled Received: from olra.theworths.org ([127.0.0.1]) by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id w5XpVVlrd0ez for ; Wed, 24 Apr 2013 18:19:55 -0700 (PDT) Received: from tesseract.cs.unb.ca (tesseract.cs.unb.ca [131.202.240.238]) (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits)) (No client certificate requested) by olra.theworths.org (Postfix) with ESMTPS id 9F0C4431FAF for ; Wed, 24 Apr 2013 18:19:50 -0700 (PDT) Received: from fctnnbsc30w-156034082078.dhcp-dynamic.fibreop.nb.bellaliant.net ([156.34.82.78] helo=zancas.localnet) by tesseract.cs.unb.ca with esmtpsa (TLS1.2:DHE_RSA_AES_128_CBC_SHA1:128) (Exim 4.80) (envelope-from ) id 1UVAqd-0002Tx-9Q; Wed, 24 Apr 2013 22:19:49 -0300 Received: from bremner by zancas.localnet with local (Exim 4.80) (envelope-from ) id 1UVAqX-000144-NH; Wed, 24 Apr 2013 22:19:37 -0300 From: david@tethera.net To: notmuch@notmuchmail.org Subject: [RFC Patch v2 2/3] man: partial conversion to pod. Date: Wed, 24 Apr 2013 22:19:11 -0300 Message-Id: <1366852752-3584-3-git-send-email-david@tethera.net> X-Mailer: git-send-email 1.8.2.rc2 In-Reply-To: <1366852752-3584-1-git-send-email-david@tethera.net> References: <1362882151-14030-1-git-send-email-david@tethera.net> <1366852752-3584-1-git-send-email-david@tethera.net> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam_bar: - 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: Thu, 25 Apr 2013 01:20:01 -0000 From: David Bremner This allows generation of man page and info document from the same source. It is also a bit more friendly to edit for most people. The conversion was done 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 | 184 --------------------------- man/man7/notmuch-search-terms.7 | 266 ---------------------------------------- pod/notmuch-search-terms.pod | 233 +++++++++++++++++++++++++++++++++++ pod/notmuch.pod | 149 ++++++++++++++++++++++ 8 files changed, 440 insertions(+), 454 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 5243f6a..a0c53e2 100755 --- a/configure +++ b/configure @@ -371,6 +371,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" @@ -687,6 +696,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@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@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 72e2a18..ceb5063 100644 --- a/man/Makefile.local +++ b/man/Makefile.local @@ -21,6 +21,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)) @@ -32,6 +34,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) @@ -50,4 +67,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 923fefe..0000000 --- a/man/man1/notmuch.1 +++ /dev/null @@ -1,184 +0,0 @@ -.\" notmuch - Not much of an email program, (just index, search and tagging) -.\" -.\" Copyright © 2009 Carl Worth -.\" -.\" Notmuch is free software: you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License as published by -.\" the Free Software Foundation, either version 3 of the License, or -.\" (at your option) any later version. -.\" -.\" Notmuch is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" along with this program. If not, see http://www.gnu.org/licenses/ . -.\" -.\" Author: Carl Worth -.TH NOTMUCH 1 2013-02-17 "Notmuch 0.15.2" -.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. - -.SH SEE ALSO - -\fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1), -\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), \fBnotmuch-new\fR(1), -\fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1), -\fBnotmuch-search\fR(1), \fBnotmuch-search-terms\fR(7), -\fBnotmuch-show\fR(1), \fBnotmuch-tag\fR(1) - - -The notmuch website: -.B http://notmuchmail.org -.SH CONTACT -Feel free to send questions, comments, or kudos to the notmuch mailing -list . Subscription is not required before -posting, but is available from the notmuchmail.org website. - -Real-time interaction with the Notmuch community is available via IRC -(server: irc.freenode.net, channel: #notmuch). diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7 deleted file mode 100644 index eb417ba..0000000 --- a/man/man7/notmuch-search-terms.7 +++ /dev/null @@ -1,266 +0,0 @@ -.TH NOTMUCH-SEARCH-TERMS 7 2013-02-17 "Notmuch 0.15.2" - -.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. 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-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..d1122b9 --- /dev/null +++ b/pod/notmuch-search-terms.pod @@ -0,0 +1,233 @@ +=head1 Name + +notmuch-search-terms - syntax for notmuch queries + +=head1 Synopsis + +B B [I] >... + +B B [ > ] [--] [ >...] + +B B [I...] >... + +B B [I...] >... + +B B +>|-> [...] [--] >... + +=head1 Description + +Several notmuch commands accept a common syntax for search terms. + +The search terms can consist of free-form text (and quoted phrases) +which will match all messages that contain all of the given +terms/phrases in the body, the subject, or any of the sender or +recipient headers. + +As a special case, a search string consisting of exactly a single +asterisk ("*") will match all messages. + +In addition to free text, the following prefixes can be used to force +terms to match against specific portions of an email, (where +indicate user-supplied values): + +from: + +to: + +subject: + +attachment: + +tag: (or is:) + +id: + +thread: + +folder: + +date:.. + +The B prefix is used to match the name or address of the sender of +an email message. + +The B prefix is used to match the names or addresses of any recipient +of an email message, (whether To, Cc, or Bcc). + +Any term prefixed with B will match only text from the subject +of an email. Searching for a phrase in the subject is supported by +including quotation marks around the phrase, immediately following +B. + +The B prefix can be used to search for specific filenames (or +extensions) of attachments to email messages. + +For B and B valid tag values include B and B by default +for new messages added by B B as well as any other tag values +added manually with B B. + +For B, message ID values are the literal contents of the Message-ID: +header of email messages, but without the `<', `>' delimiters. + +The B prefix can be used with the thread ID values that are +generated internally by notmuch (and do not appear in email messages). +These thread ID values can be seen in the first column of output from +B B + +The B prefix can be used to search for email message files that +are contained within particular directories within the mail store. 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