* [RFC patch] emacs: skeleton of texinfo manual for emacs interface. @ 2013-03-10 2:22 david 2013-04-25 1:19 ` Second draft of info manual david 0 siblings, 1 reply; 27+ messages in thread From: david @ 2013-03-10 2:22 UTC (permalink / raw) To: notmuch; +Cc: David Bremner From: David Bremner <bremner@debian.org> Currently this only attempts to document the notmuch-hello interface. --- I have thought for a long time that we should have some unified documentation for the emacs interface. This is some sketch of a beginning. Building such a document turns out to be a fair amount of work, but I guess it should be possible to have something better than what we have now (i.e. nothing). I did try to avoid duplication with both the docstrings and the man pages. Eventually perhaps we should have some common format to generate the man pages and info pages from, but I didn't want to hold up the whole effort waiting for that. One thing that would make this effort more bearable is being able to re-use material from the wiki. Currently there is no license information at all on that material; I'm not sure exactly how to proceed. To build this, use "makeinfo notmuch.texi" You can then (perversely) view it without emacs with "info -f notmuch.info" or in emacs with C-u C-h i notmuch.info. emacs/notmuch.texi | 274 +++++++++++++++++++++++++++++++++++++++++++++++++++++ emacs/version.texi | 2 + 2 files changed, 276 insertions(+) create mode 100644 emacs/notmuch.texi create mode 100644 emacs/version.texi diff --git a/emacs/notmuch.texi b/emacs/notmuch.texi new file mode 100644 index 0000000..d4f7296 --- /dev/null +++ b/emacs/notmuch.texi @@ -0,0 +1,274 @@ +\input texinfo @c -*-texinfo-*- +@comment $Id@w{$} +@comment %**start of header +@setfilename notmuch.info +@include version.texi +@settitle Notmuch @value{VERSION} +@comment %**end of header + +@macro keyindex {NAME} +@kindex \NAME\ +@cindex \NAME\ +@end macro + +@macro funindex {NAME} +@findex \NAME\ +@cindex \NAME\ +@end macro + +@macro varindex {NAME} +@vindex \NAME\ +@cindex \NAME\ +@end macro + + +@copying +This manual is for Notmuch (version @value{VERSION}, @value{UPDATED}) + +Copyright @copyright{} 2013 David Bremner + +This manual is distributed under the same terms as notmuch, which are as follows. +@quotation + This program 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. + + This program 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/ . + +@end quotation +@end copying + +@dircategory Texinfo documentation system +@direntry +* notmuch: (notmuch)Emacs interface to notmuch +@end direntry + +@titlepage +@title Notmuch +@subtitle for version @value{VERSION}, @value{UPDATED} +@author David Bremner (@email{david@@tethera.net}) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Notmuch + +This manual is for Notmuch (version @value{VERSION}, @value{UPDATED}). +@end ifnottex + +@menu +* About this Manual:: +* notmuch-hello:: +* notmuch-search:: +* Search Syntax:: +* Configuration:: +* Function Index:: +* Variable Index:: +* Index:: +@end menu + + +@node About this Manual +@unnumbered About this Manual + +This manual covers only the emacs interface to notmuch. For +information on the command line interface, see +@url{http://notmuchmail.org/manpages/notmuch-1,the notmuch man page}. +To save +typing, we will sometimes use @emph{notmuch} in this manual to refer +to the Emacs interface to notmuch. If the distinction should every be +important, we'll refer to the Emacs inteface as @emph{notmuch-emacs}. + +Notmuch-emacs is highly customizable via the the Emacs customization +framework (or just by setting the appropriate variables). We try to +point out relevant variables in this manual, but in order to avoid +duplication of information, but you can usually find the most detailed +description in the varables docstring. + +@node notmuch-hello +@chapter notmuch-hello + +@funindex notmuch-hello +@funindex notmuch + +@command{notmuch-hello} is the main entry point for notmuch. You can +start it with @kbd{M-x notmuch} or @kbd{M-x notmuch-hello}. The +startup screen looks something like the following. There are some +hints at the bottom of the screen. There are three main parts to the +notmuch-hello screen, discussed below. The @strong{bold} text +indicates buttons you can click with a mouse or by positioning the +cursor and pressing @kbd{<return>} + +@example +@group +---------------------------------------------------------------------------- + + Welcome to @strong{notmuch}. You have 52 messages. + +Saved searches: @strong{[edit]} + + 52 @strong{inbox} 52 @strong{unread} + +Search: . + +All tags: @strong{[show]} + + Type a search query and hit RET to view matching threads. + Edit saved searches with the `edit' button. + Hit RET or click on a saved search or tag name to view matching threads. + `=' to refresh this screen. `s' to search messages. `q' to quit. + @strong{Customize} this page. + +---------------------------------------------------------------------------- +@end group +@end example + +You can change the overall appearence of the notmuch-hello screen by +customizing the variable @var{notmuch-hello-sections}. +@varindex{notmuch-hellow-sections} + +@menu +* notemuch-hello Key Bindings:: +* Saved Searches:: +* Search Box:: +* Known Tags:: +@end menu + +@node notemuch-hello Key Bindings +@section notmuch-hello key bindings + +@table @kbd + +@item <tab> + Move to the next widget (button or text entry field) +@item <backtab> + Move to the previous widget. +@item <return> + Activate the current widget. +@item = +Refresh the buffer; mainly update the counts of messages for various +saved searches. +@item G + Import mail, @xref{Importing Mail}. +@item m + Compose a message +@item s +Search the notmuch database, @xref{notmuch-search}. +@item v + Print notmuch version +@item q +Quit +@end table + + +@node Saved Searches +@section Saved Searches +@cindex Saved Searches + +@varindex notmuch-saved-searches +@varindex notmuch-saved-search-sort-function +@varindex notmuch-column-control + +Notmuch replaces the static assignment of messages with the more +dynamic notion of searching. +Notmuch-hello presents the user with a customizable set of saved +searchs. The initial defaults are @code{tag:inbox} and +@code{tag:unread}, but you can customize the following variables + + +@table @var +@item notmuch-saved-searches +A list of cons pairs, the first being the name to display, the second being a query string +for notmuch. @xref{Search Syntax}, for more info. +@item notmuch-saved-searches-sort-function + This variable controls how saved searches should be sorted. A value + of @code{nil} displays the saved searches in the order they are + stored in `notmuch-saved-searches'. +@item notmuch-column-control + Controls the number of columns for displaying saved-searches/tags +@end table + +@node Search Box +@section Search Box +@cindex Search Box + +@varindex notmuch-hello-recent-searches-max +The search box lets the user enter an notmuch query. @xref{Search +Syntax}, for more info on notmuch query syntax. A history of recent +searches is also displayed by default. The latter is controlled by +the variable @var{notmuch-hello-recent-searches-max}. + +@node Known Tags +@section Know Tags +@cindex Known Tags +@varindex notmuch-hello-tag-list-make-query +@varindex notmuch-hello-hide-tags +@varindex notmuch-column-control + +One special kind of saved search provided by default is for each +individual tag defined in the database. This can be controlled via the +following variables. + +@table @var +@item notmuch-hello-tag-list-make-query + Control how to construct a search (``virtual folder'') from a given tag. +@item notmuch-hello-hide-tags + Which tags not to display at all. +@item notmuch-column-control + Controls the number of columns for displaying saved-searches/tags +@end table + + +@node notmuch-search +@chapter notmuch-search + + +@node Search Syntax +@chapter Search Syntax + +The canonical reference for notmuch search syntax is +@url{http://notmuchmail.org/manpages/notmuch-search-terms-7,notmuch-search-terms(7)} + +@node Configuration +@chapter Configuration + + +@menu +* Importing Mail:: +@end menu + +@node Importing Mail +@section Importing Mail + +@funindex notmuch-poll +@vindex notmuch-poll-script + +@node Function Index +@unnumbered Function Index + +@printindex fn + +@node Variable Index +@unnumbered Variable Index + +@printindex vr + +@node Index +@unnumbered Index + +@printindex cp + + +@bye diff --git a/emacs/version.texi b/emacs/version.texi new file mode 100644 index 0000000..4de9b21 --- /dev/null +++ b/emacs/version.texi @@ -0,0 +1,2 @@ +@set VERSION 0.15.2 +@set UPDATED April 01, 1970 -- 1.8.2.rc1 ^ permalink raw reply related [flat|nested] 27+ messages in thread
* Second draft of info manual 2013-03-10 2:22 [RFC patch] emacs: skeleton of texinfo manual for emacs interface david @ 2013-04-25 1:19 ` david 2013-04-25 1:19 ` [RFC Patch v2 1/3] info: start info documentation david ` (3 more replies) 0 siblings, 4 replies; 27+ messages in thread From: david @ 2013-04-25 1:19 UTC (permalink / raw) To: notmuch In order to get docs both as man pages and as info docs for reading in emacs, I decided to try converting a couple man pages to pod. There turned out to a painful amount of infrastructure needed to get this working, so I didn't get much done on the notmuch-emacs docs. I think all the infrastructure is in place at this point. I'm probably not going to do much more work into the actual docs until I get some feedback on the basic approach; it's clear that the autoconverted pod files need a bit of tidying. As far as build depends, this needs only perl for the basic docs (pod2man is part of perl since a while). To build the info docs needs pod2texi and makinfo, which are part of recent texinfo releases. ^ permalink raw reply [flat|nested] 27+ messages in thread
* [RFC Patch v2 1/3] info: start info documentation. 2013-04-25 1:19 ` Second draft of info manual david @ 2013-04-25 1:19 ` david 2013-04-25 1:19 ` [RFC Patch v2 2/3] man: partial conversion to pod david ` (2 subsequent siblings) 3 siblings, 0 replies; 27+ messages in thread From: david @ 2013-04-25 1:19 UTC (permalink / raw) To: notmuch; +Cc: David Bremner From: David Bremner <bremner@debian.org> Initially, just a skeleton of documentation for the emacs interface. There are a few dangling references to other info pages; these are to be generated from the man pages in a following commit. As far as actual documentation, so far this contains only a brief intro to notmuch-hello. --- INSTALL | 12 ++- Makefile | 5 +- configure | 32 ++++++ info/Makefile | 7 ++ info/Makefile.local | 33 ++++++ info/notmuch-emacs.texi | 270 ++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 356 insertions(+), 3 deletions(-) create mode 100644 info/Makefile create mode 100644 info/Makefile.local create mode 100644 info/notmuch-emacs.texi diff --git a/INSTALL b/INSTALL index fce9352..451bf05 100644 --- a/INSTALL +++ b/INSTALL @@ -60,16 +60,24 @@ Talloc which are each described below: Talloc is available from http://talloc.samba.org/ + texinfo + ------- + + To build the info documentation, you need makeinfo and + pod2texi. To install the info documentation, you need + install-info; these are all part of the texinfo distribution + as of version 5.0. + On a modern, package-based operating system you can install all of the dependencies with a simple simple command line. For example: For Debian and similar: - sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev + sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev makeinfo texinfo For Fedora and similar: - sudo yum install xapian-core-devel gmime-devel libtalloc-devel + sudo yum install xapian-core-devel gmime-devel libtalloc-devel texinfo On other systems, a similar command can be used, but the details of the package names may be different. diff --git a/Makefile b/Makefile index 73a8554..250fbaa 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,10 @@ all: # List all subdirectories here. Each contains its own Makefile.local subdirs := compat completion emacs lib man parse-time-string -subdirs += performance-test util test +subdirs += performance-test util info +# it seems to be important to keep test last. +subdirs += test + # We make all targets depend on the Makefiles themselves. global_deps = Makefile Makefile.config Makefile.local \ diff --git a/configure b/configure index 460fcfc..5243f6a 100755 --- a/configure +++ b/configure @@ -358,6 +358,10 @@ if [ -z "${EMACSETCDIR}" ]; then fi fi +if [ -z "${INFODIR}" ]; then + INFODIR='$(prefix)/share/info' +fi + printf "Checking if emacs is available... " if emacs --quick --batch > /dev/null 2>&1; then printf "Yes.\n" @@ -367,6 +371,24 @@ else have_emacs=0 fi +printf "Checking for makeinfo... " +if makeinfo --version > /dev/null 2>&1; then + printf "Yes.\n" + have_makeinfo=1 +else + printf "No (so will not info docs)\n" + have_makeinfo=0 +fi + +printf "Checking for install-info... " +if install-info --version > /dev/null 2>&1; then + printf "Yes.\n" + have_installinfo=1 +else + printf "No (so will not install info docs)\n" + have_installinfo=0 +fi + libdir_in_ldconfig=0 printf "Checking which platform we are on... " @@ -659,6 +681,16 @@ emacsetcdir=${EMACSETCDIR} # Whether there's an emacs binary available for byte-compiling HAVE_EMACS = ${have_emacs} +# Whether there's a makeinfo binary available to build info docs +HAVE_MAKEINFO = ${have_makeinfo} + +# Whether there's an install-info binary available +HAVE_INSTALLINFO = ${have_installinfo} + +# where to install info files + +INFODIR = ${INFODIR} + # The directory to which desktop files should be installed desktop_dir = \$(prefix)/share/applications diff --git a/info/Makefile b/info/Makefile new file mode 100644 index 0000000..de492a7 --- /dev/null +++ b/info/Makefile @@ -0,0 +1,7 @@ +# See Makefile.local for the list of files to be compiled in this +# directory. +all: + $(MAKE) -C .. all + +.DEFAULT: + $(MAKE) -C .. $@ diff --git a/info/Makefile.local b/info/Makefile.local new file mode 100644 index 0000000..55e9740 --- /dev/null +++ b/info/Makefile.local @@ -0,0 +1,33 @@ +# -*- makefile -*- + +dir := info + +texi_sources := $(dir)/notmuch-emacs.texi +emacs_info := $(texi_sources:.texi=.info) + +info := $(emacs_info) + +ifeq ($(HAVE_MAKEINFO),1) +all: $(info) +endif + +ifeq ($(HAVE_INSTALLINFO),1) +install: install-info +endif + +%.info: %.texi + makeinfo --no-split -o $@ $< + +$(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi + +.PHONY: $(dir)/version.texi +$(dir)/version.texi: version + printf "@set VERSION ${VERSION}\n" > $@ + +.PHONY: install-info +install-info: ${info} + mkdir -p "$(DESTDIR)$(INFODIR)" + install -m0644 $(info) "$(DESTDIR)$(INFODIR)" + install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info) + +CLEAN := $(CLEAN) $(info) diff --git a/info/notmuch-emacs.texi b/info/notmuch-emacs.texi new file mode 100644 index 0000000..434a360 --- /dev/null +++ b/info/notmuch-emacs.texi @@ -0,0 +1,270 @@ +\input texinfo @c -*-texinfo-*- +@comment $Id@w{$} +@comment %**start of header +@setfilename notmuch-emacs.info +@include version.texi +@settitle Notmuch @value{VERSION} +@comment %**end of header + +@macro keyindex {NAME} +@kindex \NAME\ +@cindex \NAME\ +@end macro + +@macro funindex {NAME} +@findex \NAME\ +@cindex \NAME\ +@end macro + +@macro varindex {NAME} +@vindex \NAME\ +@cindex \NAME\ +@end macro + + +@copying +This manual is for Notmuch (version @value{VERSION}) + +Copyright @copyright{} 2013 David Bremner + +This manual is distributed under the same terms as notmuch, which are as follows. +@quotation + This program 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. + + This program 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/ . + +@end quotation +@end copying + +@dircategory Notmuch +@direntry +* notmuch-emacs: (notmuch-emacs). Emacs interface to notmuch +@end direntry + +@titlepage +@title Notmuch +@subtitle for version @value{VERSION} +@author David Bremner (@email{david@@tethera.net}) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Notmuch + +This manual is for Notmuch (version @value{VERSION}). +@end ifnottex + +@menu +* About this Manual:: +* notmuch-hello:: +* notmuch-search:: +* Configuration:: +* Function Index:: +* Variable Index:: +* Index:: +@end menu + + +@node About this Manual +@unnumbered About this Manual + +This manual covers only the emacs interface to notmuch. For +information on the command line interface, see +@xref{top,the notmuch man page,Description,notmuch,Notmuch Manual Pager}. +To save +typing, we will sometimes use @emph{notmuch} in this manual to refer +to the Emacs interface to notmuch. If the distinction should every be +important, we'll refer to the Emacs inteface as @emph{notmuch-emacs}. + +Notmuch-emacs is highly customizable via the the Emacs customization +framework (or just by setting the appropriate variables). We try to +point out relevant variables in this manual, but in order to avoid +duplication of information, but you can usually find the most detailed +description in the varables docstring. + +@node notmuch-hello +@chapter notmuch-hello + +@funindex notmuch-hello +@funindex notmuch + +@command{notmuch-hello} is the main entry point for notmuch. You can +start it with @kbd{M-x notmuch} or @kbd{M-x notmuch-hello}. The +startup screen looks something like the following. There are some +hints at the bottom of the screen. There are three main parts to the +notmuch-hello screen, discussed below. The @strong{bold} text +indicates buttons you can click with a mouse or by positioning the +cursor and pressing @kbd{<return>} + +@example +@group +---------------------------------------------------------------------------- + + Welcome to @strong{notmuch}. You have 52 messages. + +Saved searches: @strong{[edit]} + + 52 @strong{inbox} 52 @strong{unread} + +Search: . + +All tags: @strong{[show]} + + Type a search query and hit RET to view matching threads. + Edit saved searches with the `edit' button. + Hit RET or click on a saved search or tag name to view matching threads. + `=' to refresh this screen. `s' to search messages. `q' to quit. + @strong{Customize} this page. + +---------------------------------------------------------------------------- +@end group +@end example + +You can change the overall appearence of the notmuch-hello screen by +customizing the variable @var{notmuch-hello-sections}. +@varindex{notmuch-hellow-sections} + +@menu +* notemuch-hello Key Bindings:: +* Saved Searches:: +* Search Box:: +* Known Tags:: +@end menu + +@node notemuch-hello Key Bindings +@section notmuch-hello key bindings + +@table @kbd + +@item <tab> + Move to the next widget (button or text entry field) +@item <backtab> + Move to the previous widget. +@item <return> + Activate the current widget. +@item = +Refresh the buffer; mainly update the counts of messages for various +saved searches. +@item G + Import mail, @xref{Importing Mail}. +@item m + Compose a message +@item s +Search the notmuch database, @xref{notmuch-search}. +@item v + Print notmuch version +@item q +Quit +@end table + + +@node Saved Searches +@section Saved Searches +@cindex Saved Searches + +@varindex notmuch-saved-searches +@varindex notmuch-saved-search-sort-function +@varindex notmuch-column-control + +Notmuch replaces the static assignment of messages with the more +dynamic notion of searching. +Notmuch-hello presents the user with a customizable set of saved +searchs. The initial defaults are @code{tag:inbox} and +@code{tag:unread}, but you can customize the following variables + + +@table @var +@item notmuch-saved-searches +A list of cons pairs, the first being the name to display, the second +being a query string for notmuch. @xref{top,Notmuch Query +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}. + +@item notmuch-saved-searches-sort-function + This variable controls how saved searches should be sorted. A value + of @code{nil} displays the saved searches in the order they are + stored in `notmuch-saved-searches'. +@item notmuch-column-control + Controls the number of columns for displaying saved-searches/tags +@end table + +@node Search Box +@section Search Box +@cindex Search Box + +@varindex notmuch-hello-recent-searches-max +The search box lets the user enter an notmuch query. @xref{top,Notmuch +Query Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}, +for more info on notmuch query syntax. A history of recent searches is +also displayed by default. The latter is controlled by the variable +@var{notmuch-hello-recent-searches-max}. + +@node Known Tags +@section Know Tags +@cindex Known Tags +@varindex notmuch-hello-tag-list-make-query +@varindex notmuch-hello-hide-tags +@varindex notmuch-column-control + +One special kind of saved search provided by default is for each +individual tag defined in the database. This can be controlled via the +following variables. + +@table @var +@item notmuch-hello-tag-list-make-query + Control how to construct a search (``virtual folder'') from a given tag. +@item notmuch-hello-hide-tags + Which tags not to display at all. +@item notmuch-column-control + Controls the number of columns for displaying saved-searches/tags +@end table + + +@node notmuch-search +@chapter notmuch-search + + +@node Configuration +@chapter Configuration + + +@menu +* Importing Mail:: +@end menu + +@node Importing Mail +@section Importing Mail + +@funindex notmuch-poll +@vindex notmuch-poll-script + +@node Function Index +@unnumbered Function Index + +@printindex fn + +@node Variable Index +@unnumbered Variable Index + +@printindex vr + +@node Index +@unnumbered Index + +@printindex cp + + +@bye -- 1.8.2.rc2 ^ permalink raw reply related [flat|nested] 27+ messages in thread
* [RFC Patch v2 2/3] man: partial conversion to pod. 2013-04-25 1:19 ` Second draft of info manual david 2013-04-25 1:19 ` [RFC Patch v2 1/3] info: start info documentation david @ 2013-04-25 1:19 ` david 2013-04-25 1:19 ` [RFC Patch v2 3/3] debian: install info files david 2014-01-05 11:39 ` third draft of info manual David Bremner 3 siblings, 0 replies; 27+ messages in thread From: david @ 2013-04-25 1:19 UTC (permalink / raw) To: notmuch; +Cc: David Bremner From: David Bremner <bremner@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 | 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 <cworth@cworth.org> -.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 <notmuch@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 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 -<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. 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-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<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. 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-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..3407211 --- /dev/null +++ b/pod/notmuch.pod @@ -0,0 +1,149 @@ +=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. + +=back + +=head1 See Also + +L<notmuch-config(1)>, L<notmuch-count(1)>, L<notmuch-dump(1)>, L<notmuch-hooks(5)>, +L<notmuch-new(1)>, L<notmuch-reply(1)>, L<notmuch-restore(1)>, L<notmuchsearch(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@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.2.rc2 ^ permalink raw reply related [flat|nested] 27+ messages in thread
* [RFC Patch v2 3/3] debian: install info files 2013-04-25 1:19 ` Second draft of info manual david 2013-04-25 1:19 ` [RFC Patch v2 1/3] info: start info documentation david 2013-04-25 1:19 ` [RFC Patch v2 2/3] man: partial conversion to pod david @ 2013-04-25 1:19 ` david 2014-01-05 11:39 ` third draft of info manual David Bremner 3 siblings, 0 replies; 27+ messages in thread From: david @ 2013-04-25 1:19 UTC (permalink / raw) To: notmuch; +Cc: David Bremner From: David Bremner <bremner@debian.org> It seems dh_installinfo doesn't understand wildcards or look in debian/tmp --- debian/notmuch-emacs.info | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 debian/notmuch-emacs.info diff --git a/debian/notmuch-emacs.info b/debian/notmuch-emacs.info new file mode 100644 index 0000000..2de46d3 --- /dev/null +++ b/debian/notmuch-emacs.info @@ -0,0 +1,3 @@ +info/notmuch.info +info/notmuch-emacs.info +info/notmuch-search-terms.info -- 1.8.2.rc2 ^ permalink raw reply related [flat|nested] 27+ messages in thread
* third draft of info manual 2013-04-25 1:19 ` Second draft of info manual david ` (2 preceding siblings ...) 2013-04-25 1:19 ` [RFC Patch v2 3/3] debian: install info files david @ 2014-01-05 11:39 ` David Bremner 2014-01-05 11:39 ` [PATCH 1/3] info: start info documentation David Bremner ` (2 more replies) 3 siblings, 3 replies; 27+ messages in thread From: David Bremner @ 2014-01-05 11:39 UTC (permalink / raw) To: notmuch Jani was mentioning how much he loved editing troff, so I decided to dust off these patches, which as a side effect convert (some of) the man pages to pod. As I write this, I realized that the second commit message is sort of a lie, I now use a quick and dirty perl script [1] to do the conversion. I have also updated the converted pages to take into account man page edits since April. Since this is a semi-manual process, I don't want to convert (and therefore have to update) all of the man pages at this stage. An earlier version of the series is at mid:1366852752-3584-1-git-send-email-david@tethera.net [1]: #!/usr/bin/perl open(POD,"groff -e -mandoc -Tascii -rHY=0 | rman -f POD|") || die; LINE: while(<POD>){ my $blank=0; while (m/^\s*$/) { $_=<POD>; $blank++; } print "\n" if ($blank); while(s/^(=head1 .*)B[<]/\1/){}; while(s/^(=head1 .*)[>]/\1/){}; s/ */ /g; print; } ^ permalink raw reply [flat|nested] 27+ messages in thread
* [PATCH 1/3] info: start info documentation. 2014-01-05 11:39 ` third draft of info manual David Bremner @ 2014-01-05 11:39 ` David Bremner 2014-01-05 11:39 ` [PATCH 2/3] man: partial conversion to pod David Bremner 2014-01-05 11:39 ` [PATCH " David Bremner 2 siblings, 0 replies; 27+ messages in thread From: David Bremner @ 2014-01-05 11:39 UTC (permalink / raw) To: notmuch; +Cc: David Bremner From: David Bremner <bremner@debian.org> Initially, just a skeleton of documentation for the emacs interface. There are a few dangling references to other info pages; these are to be generated from the man pages in a following commit. As far as actual documentation, so far this contains only a brief intro to notmuch-hello. --- INSTALL | 12 ++- Makefile | 10 +- configure | 32 ++++++ info/Makefile | 7 ++ info/Makefile.local | 33 ++++++ info/notmuch-emacs.texi | 270 ++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 358 insertions(+), 6 deletions(-) create mode 100644 info/Makefile create mode 100644 info/Makefile.local create mode 100644 info/notmuch-emacs.texi diff --git a/INSTALL b/INSTALL index fce9352..451bf05 100644 --- a/INSTALL +++ b/INSTALL @@ -60,16 +60,24 @@ Talloc which are each described below: Talloc is available from http://talloc.samba.org/ + texinfo + ------- + + To build the info documentation, you need makeinfo and + pod2texi. To install the info documentation, you need + install-info; these are all part of the texinfo distribution + as of version 5.0. + On a modern, package-based operating system you can install all of the dependencies with a simple simple command line. For example: For Debian and similar: - sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev + sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev makeinfo texinfo For Fedora and similar: - sudo yum install xapian-core-devel gmime-devel libtalloc-devel + sudo yum install xapian-core-devel gmime-devel libtalloc-devel texinfo On other systems, a similar command can be used, but the details of the package names may be different. diff --git a/Makefile b/Makefile index 0428160..250fbaa 100644 --- a/Makefile +++ b/Makefile @@ -2,10 +2,12 @@ # given explicitly on the command line) so mention it first. all: -# List all subdirectories here. Each contains its own Makefile.local. -# Use of '=', without '+=', seems to be required for out-of-tree -# builds to work. -subdirs = compat completion emacs lib man parse-time-string performance-test util test +# List all subdirectories here. Each contains its own Makefile.local +subdirs := compat completion emacs lib man parse-time-string +subdirs += performance-test util info +# it seems to be important to keep test last. +subdirs += test + # We make all targets depend on the Makefiles themselves. global_deps = Makefile Makefile.config Makefile.local \ diff --git a/configure b/configure index 13b6062..e75c1d4 100755 --- a/configure +++ b/configure @@ -376,6 +376,10 @@ if [ -z "${EMACSETCDIR}" ]; then fi fi +if [ -z "${INFODIR}" ]; then + INFODIR='$(prefix)/share/info' +fi + printf "Checking if emacs is available... " if emacs --quick --batch > /dev/null 2>&1; then printf "Yes.\n" @@ -385,6 +389,24 @@ else have_emacs=0 fi +printf "Checking for makeinfo... " +if makeinfo --version > /dev/null 2>&1; then + printf "Yes.\n" + have_makeinfo=1 +else + printf "No (so will not info docs)\n" + have_makeinfo=0 +fi + +printf "Checking for install-info... " +if install-info --version > /dev/null 2>&1; then + printf "Yes.\n" + have_installinfo=1 +else + printf "No (so will not install info docs)\n" + have_installinfo=0 +fi + libdir_in_ldconfig=0 printf "Checking which platform we are on... " @@ -740,6 +762,16 @@ emacsetcdir=${EMACSETCDIR} # Whether there's an emacs binary available for byte-compiling HAVE_EMACS = ${have_emacs} +# Whether there's a makeinfo binary available to build info docs +HAVE_MAKEINFO = ${have_makeinfo} + +# Whether there's an install-info binary available +HAVE_INSTALLINFO = ${have_installinfo} + +# where to install info files + +INFODIR = ${INFODIR} + # The directory to which desktop files should be installed desktop_dir = \$(prefix)/share/applications diff --git a/info/Makefile b/info/Makefile new file mode 100644 index 0000000..de492a7 --- /dev/null +++ b/info/Makefile @@ -0,0 +1,7 @@ +# See Makefile.local for the list of files to be compiled in this +# directory. +all: + $(MAKE) -C .. all + +.DEFAULT: + $(MAKE) -C .. $@ diff --git a/info/Makefile.local b/info/Makefile.local new file mode 100644 index 0000000..55e9740 --- /dev/null +++ b/info/Makefile.local @@ -0,0 +1,33 @@ +# -*- makefile -*- + +dir := info + +texi_sources := $(dir)/notmuch-emacs.texi +emacs_info := $(texi_sources:.texi=.info) + +info := $(emacs_info) + +ifeq ($(HAVE_MAKEINFO),1) +all: $(info) +endif + +ifeq ($(HAVE_INSTALLINFO),1) +install: install-info +endif + +%.info: %.texi + makeinfo --no-split -o $@ $< + +$(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi + +.PHONY: $(dir)/version.texi +$(dir)/version.texi: version + printf "@set VERSION ${VERSION}\n" > $@ + +.PHONY: install-info +install-info: ${info} + mkdir -p "$(DESTDIR)$(INFODIR)" + install -m0644 $(info) "$(DESTDIR)$(INFODIR)" + install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info) + +CLEAN := $(CLEAN) $(info) diff --git a/info/notmuch-emacs.texi b/info/notmuch-emacs.texi new file mode 100644 index 0000000..434a360 --- /dev/null +++ b/info/notmuch-emacs.texi @@ -0,0 +1,270 @@ +\input texinfo @c -*-texinfo-*- +@comment $Id@w{$} +@comment %**start of header +@setfilename notmuch-emacs.info +@include version.texi +@settitle Notmuch @value{VERSION} +@comment %**end of header + +@macro keyindex {NAME} +@kindex \NAME\ +@cindex \NAME\ +@end macro + +@macro funindex {NAME} +@findex \NAME\ +@cindex \NAME\ +@end macro + +@macro varindex {NAME} +@vindex \NAME\ +@cindex \NAME\ +@end macro + + +@copying +This manual is for Notmuch (version @value{VERSION}) + +Copyright @copyright{} 2013 David Bremner + +This manual is distributed under the same terms as notmuch, which are as follows. +@quotation + This program 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. + + This program 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/ . + +@end quotation +@end copying + +@dircategory Notmuch +@direntry +* notmuch-emacs: (notmuch-emacs). Emacs interface to notmuch +@end direntry + +@titlepage +@title Notmuch +@subtitle for version @value{VERSION} +@author David Bremner (@email{david@@tethera.net}) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Notmuch + +This manual is for Notmuch (version @value{VERSION}). +@end ifnottex + +@menu +* About this Manual:: +* notmuch-hello:: +* notmuch-search:: +* Configuration:: +* Function Index:: +* Variable Index:: +* Index:: +@end menu + + +@node About this Manual +@unnumbered About this Manual + +This manual covers only the emacs interface to notmuch. For +information on the command line interface, see +@xref{top,the notmuch man page,Description,notmuch,Notmuch Manual Pager}. +To save +typing, we will sometimes use @emph{notmuch} in this manual to refer +to the Emacs interface to notmuch. If the distinction should every be +important, we'll refer to the Emacs inteface as @emph{notmuch-emacs}. + +Notmuch-emacs is highly customizable via the the Emacs customization +framework (or just by setting the appropriate variables). We try to +point out relevant variables in this manual, but in order to avoid +duplication of information, but you can usually find the most detailed +description in the varables docstring. + +@node notmuch-hello +@chapter notmuch-hello + +@funindex notmuch-hello +@funindex notmuch + +@command{notmuch-hello} is the main entry point for notmuch. You can +start it with @kbd{M-x notmuch} or @kbd{M-x notmuch-hello}. The +startup screen looks something like the following. There are some +hints at the bottom of the screen. There are three main parts to the +notmuch-hello screen, discussed below. The @strong{bold} text +indicates buttons you can click with a mouse or by positioning the +cursor and pressing @kbd{<return>} + +@example +@group +---------------------------------------------------------------------------- + + Welcome to @strong{notmuch}. You have 52 messages. + +Saved searches: @strong{[edit]} + + 52 @strong{inbox} 52 @strong{unread} + +Search: . + +All tags: @strong{[show]} + + Type a search query and hit RET to view matching threads. + Edit saved searches with the `edit' button. + Hit RET or click on a saved search or tag name to view matching threads. + `=' to refresh this screen. `s' to search messages. `q' to quit. + @strong{Customize} this page. + +---------------------------------------------------------------------------- +@end group +@end example + +You can change the overall appearence of the notmuch-hello screen by +customizing the variable @var{notmuch-hello-sections}. +@varindex{notmuch-hellow-sections} + +@menu +* notemuch-hello Key Bindings:: +* Saved Searches:: +* Search Box:: +* Known Tags:: +@end menu + +@node notemuch-hello Key Bindings +@section notmuch-hello key bindings + +@table @kbd + +@item <tab> + Move to the next widget (button or text entry field) +@item <backtab> + Move to the previous widget. +@item <return> + Activate the current widget. +@item = +Refresh the buffer; mainly update the counts of messages for various +saved searches. +@item G + Import mail, @xref{Importing Mail}. +@item m + Compose a message +@item s +Search the notmuch database, @xref{notmuch-search}. +@item v + Print notmuch version +@item q +Quit +@end table + + +@node Saved Searches +@section Saved Searches +@cindex Saved Searches + +@varindex notmuch-saved-searches +@varindex notmuch-saved-search-sort-function +@varindex notmuch-column-control + +Notmuch replaces the static assignment of messages with the more +dynamic notion of searching. +Notmuch-hello presents the user with a customizable set of saved +searchs. The initial defaults are @code{tag:inbox} and +@code{tag:unread}, but you can customize the following variables + + +@table @var +@item notmuch-saved-searches +A list of cons pairs, the first being the name to display, the second +being a query string for notmuch. @xref{top,Notmuch Query +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}. + +@item notmuch-saved-searches-sort-function + This variable controls how saved searches should be sorted. A value + of @code{nil} displays the saved searches in the order they are + stored in `notmuch-saved-searches'. +@item notmuch-column-control + Controls the number of columns for displaying saved-searches/tags +@end table + +@node Search Box +@section Search Box +@cindex Search Box + +@varindex notmuch-hello-recent-searches-max +The search box lets the user enter an notmuch query. @xref{top,Notmuch +Query Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}, +for more info on notmuch query syntax. A history of recent searches is +also displayed by default. The latter is controlled by the variable +@var{notmuch-hello-recent-searches-max}. + +@node Known Tags +@section Know Tags +@cindex Known Tags +@varindex notmuch-hello-tag-list-make-query +@varindex notmuch-hello-hide-tags +@varindex notmuch-column-control + +One special kind of saved search provided by default is for each +individual tag defined in the database. This can be controlled via the +following variables. + +@table @var +@item notmuch-hello-tag-list-make-query + Control how to construct a search (``virtual folder'') from a given tag. +@item notmuch-hello-hide-tags + Which tags not to display at all. +@item notmuch-column-control + Controls the number of columns for displaying saved-searches/tags +@end table + + +@node notmuch-search +@chapter notmuch-search + + +@node Configuration +@chapter Configuration + + +@menu +* Importing Mail:: +@end menu + +@node Importing Mail +@section Importing Mail + +@funindex notmuch-poll +@vindex notmuch-poll-script + +@node Function Index +@unnumbered Function Index + +@printindex fn + +@node Variable Index +@unnumbered Variable Index + +@printindex vr + +@node Index +@unnumbered Index + +@printindex cp + + +@bye -- 1.8.5.2 ^ permalink raw reply related [flat|nested] 27+ messages in thread
* [PATCH 2/3] man: partial conversion to pod. 2014-01-05 11:39 ` third draft of info manual David Bremner 2014-01-05 11:39 ` [PATCH 1/3] info: start info documentation David Bremner @ 2014-01-05 11:39 ` David Bremner 2014-01-13 21:06 ` Tomi Ollila 2014-01-05 11:39 ` [PATCH " David Bremner 2 siblings, 1 reply; 27+ messages in thread From: David Bremner @ 2014-01-05 11:39 UTC (permalink / raw) To: notmuch; +Cc: David Bremner From: David Bremner <bremner@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@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 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@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@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@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 ^ permalink raw reply related [flat|nested] 27+ messages in thread
* Re: [PATCH 2/3] man: partial conversion to pod. 2014-01-05 11:39 ` [PATCH 2/3] man: partial conversion to pod David Bremner @ 2014-01-13 21:06 ` Tomi Ollila 2014-01-14 12:06 ` David Bremner 0 siblings, 1 reply; 27+ messages in thread From: Tomi Ollila @ 2014-01-13 21:06 UTC (permalink / raw) To: David Bremner, notmuch; +Cc: David Bremner David Bremner <david@tethera.net> writes: > From: David Bremner <bremner@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. IMHO it is good idea to have common format where to produce man, info & html files. If we're going to need pandoc then the question of source format explodes with choices... > 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@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/' > $@ This usage of pipeline above is problematic as if pod2texi returns nonzero it is shadowed by return value of sed. Therefore a temporary file is needed for this kind of operation. Tomi ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 2/3] man: partial conversion to pod. 2014-01-13 21:06 ` Tomi Ollila @ 2014-01-14 12:06 ` David Bremner 2014-01-14 12:27 ` Tomi Ollila 0 siblings, 1 reply; 27+ messages in thread From: David Bremner @ 2014-01-14 12:06 UTC (permalink / raw) To: Tomi Ollila, notmuch Tomi Ollila <tomi.ollila@iki.fi> writes: > IMHO it is good idea to have common format where to produce man, info & > html files. If we're going to need pandoc then the question of source > format explodes with choices... Hi Tomi; I'm not sure how to interpret this. Are you in favour of using pandoc to produce documentation? As you say we have more choice about source format in that case. We could even try producing all of the notmuch-emacs documentation from the common format (as opposed to just part of it). On the other hand I guess the dependency would be a problem for people using old linux distros, not to mention less common choices like *BSD and OS X. One thing I haven't tried is generating info/notmuch-emacs.texi from pod. I guess that would make sense if people felt strongly that one format for all the docs is a priority. I worry a bit about the two step pod -> texi -> info conversion process, but it's only a hunch. d ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 2/3] man: partial conversion to pod. 2014-01-14 12:06 ` David Bremner @ 2014-01-14 12:27 ` Tomi Ollila 2014-01-15 13:08 ` David Bremner 0 siblings, 1 reply; 27+ messages in thread From: Tomi Ollila @ 2014-01-14 12:27 UTC (permalink / raw) To: David Bremner, notmuch On Tue, Jan 14 2014, David Bremner <david@tethera.net> wrote: > Tomi Ollila <tomi.ollila@iki.fi> writes: > >> IMHO it is good idea to have common format where to produce man, info & >> html files. If we're going to need pandoc then the question of source >> format explodes with choices... > > Hi Tomi; > > I'm not sure how to interpret this. Are you in favour of using pandoc to > produce documentation? No if we can avoid it :D > As you say we have more choice about source > format in that case. We could even try producing all of the > notmuch-emacs documentation from the common format (as opposed to just > part of it). On the other hand I guess the dependency would be a problem > for people using old linux distros, not to mention less common choices > like *BSD and OS X. > > One thing I haven't tried is generating info/notmuch-emacs.texi from > pod. I guess that would make sense if people felt strongly that one > format for all the docs is a priority. I worry a bit about the two step > pod -> texi -> info conversion process, but it's only a hunch. For emacs-only docs IMHO texi/info would suffice. But I quess some docs should be shipped both in info & man formats. for that we'd need such a conversion tools anyway... > d Tomi ^ permalink raw reply [flat|nested] 27+ messages in thread
* (no subject) 2014-01-14 12:27 ` Tomi Ollila @ 2014-01-15 13:08 ` David Bremner 2014-01-15 13:08 ` [Patch v3 1/3] info: start info documentation David Bremner ` (2 more replies) 0 siblings, 3 replies; 27+ messages in thread From: David Bremner @ 2014-01-15 13:08 UTC (permalink / raw) To: notmuch Changes since last round: - rebased to current master - one more converted man page - a bit more actual manual text - fix for Tomi's comment about return valules in pipeline. - commit message of 2/3 no longer lies about the conversion process. ^ permalink raw reply [flat|nested] 27+ messages in thread
* [Patch v3 1/3] info: start info documentation. 2014-01-15 13:08 ` David Bremner @ 2014-01-15 13:08 ` David Bremner 2014-01-17 15:59 ` Jani Nikula 2014-01-17 16:12 ` Jani Nikula 2014-01-15 13:08 ` [Patch v3 2/3] man: partial conversion to pod David Bremner 2014-01-15 13:08 ` [Patch v3 3/3] debian: install info files David Bremner 2 siblings, 2 replies; 27+ messages in thread From: David Bremner @ 2014-01-15 13:08 UTC (permalink / raw) To: notmuch; +Cc: David Bremner From: David Bremner <bremner@debian.org> Initially, just a skeleton of documentation for the emacs interface. There are a few dangling references to other info pages; these are to be generated from the man pages in a following commit. As far as actual documentation, so far this contains only a brief intro to notmuch-hello. --- INSTALL | 12 +- Makefile | 10 +- configure | 32 +++++ info/Makefile | 7 ++ info/Makefile.local | 33 +++++ info/notmuch-emacs.texi | 324 ++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 412 insertions(+), 6 deletions(-) create mode 100644 info/Makefile create mode 100644 info/Makefile.local create mode 100644 info/notmuch-emacs.texi diff --git a/INSTALL b/INSTALL index fce9352..451bf05 100644 --- a/INSTALL +++ b/INSTALL @@ -60,16 +60,24 @@ Talloc which are each described below: Talloc is available from http://talloc.samba.org/ + texinfo + ------- + + To build the info documentation, you need makeinfo and + pod2texi. To install the info documentation, you need + install-info; these are all part of the texinfo distribution + as of version 5.0. + On a modern, package-based operating system you can install all of the dependencies with a simple simple command line. For example: For Debian and similar: - sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev + sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev makeinfo texinfo For Fedora and similar: - sudo yum install xapian-core-devel gmime-devel libtalloc-devel + sudo yum install xapian-core-devel gmime-devel libtalloc-devel texinfo On other systems, a similar command can be used, but the details of the package names may be different. diff --git a/Makefile b/Makefile index 0428160..250fbaa 100644 --- a/Makefile +++ b/Makefile @@ -2,10 +2,12 @@ # given explicitly on the command line) so mention it first. all: -# List all subdirectories here. Each contains its own Makefile.local. -# Use of '=', without '+=', seems to be required for out-of-tree -# builds to work. -subdirs = compat completion emacs lib man parse-time-string performance-test util test +# List all subdirectories here. Each contains its own Makefile.local +subdirs := compat completion emacs lib man parse-time-string +subdirs += performance-test util info +# it seems to be important to keep test last. +subdirs += test + # We make all targets depend on the Makefiles themselves. global_deps = Makefile Makefile.config Makefile.local \ diff --git a/configure b/configure index 13b6062..e75c1d4 100755 --- a/configure +++ b/configure @@ -376,6 +376,10 @@ if [ -z "${EMACSETCDIR}" ]; then fi fi +if [ -z "${INFODIR}" ]; then + INFODIR='$(prefix)/share/info' +fi + printf "Checking if emacs is available... " if emacs --quick --batch > /dev/null 2>&1; then printf "Yes.\n" @@ -385,6 +389,24 @@ else have_emacs=0 fi +printf "Checking for makeinfo... " +if makeinfo --version > /dev/null 2>&1; then + printf "Yes.\n" + have_makeinfo=1 +else + printf "No (so will not info docs)\n" + have_makeinfo=0 +fi + +printf "Checking for install-info... " +if install-info --version > /dev/null 2>&1; then + printf "Yes.\n" + have_installinfo=1 +else + printf "No (so will not install info docs)\n" + have_installinfo=0 +fi + libdir_in_ldconfig=0 printf "Checking which platform we are on... " @@ -740,6 +762,16 @@ emacsetcdir=${EMACSETCDIR} # Whether there's an emacs binary available for byte-compiling HAVE_EMACS = ${have_emacs} +# Whether there's a makeinfo binary available to build info docs +HAVE_MAKEINFO = ${have_makeinfo} + +# Whether there's an install-info binary available +HAVE_INSTALLINFO = ${have_installinfo} + +# where to install info files + +INFODIR = ${INFODIR} + # The directory to which desktop files should be installed desktop_dir = \$(prefix)/share/applications diff --git a/info/Makefile b/info/Makefile new file mode 100644 index 0000000..de492a7 --- /dev/null +++ b/info/Makefile @@ -0,0 +1,7 @@ +# See Makefile.local for the list of files to be compiled in this +# directory. +all: + $(MAKE) -C .. all + +.DEFAULT: + $(MAKE) -C .. $@ diff --git a/info/Makefile.local b/info/Makefile.local new file mode 100644 index 0000000..55e9740 --- /dev/null +++ b/info/Makefile.local @@ -0,0 +1,33 @@ +# -*- makefile -*- + +dir := info + +texi_sources := $(dir)/notmuch-emacs.texi +emacs_info := $(texi_sources:.texi=.info) + +info := $(emacs_info) + +ifeq ($(HAVE_MAKEINFO),1) +all: $(info) +endif + +ifeq ($(HAVE_INSTALLINFO),1) +install: install-info +endif + +%.info: %.texi + makeinfo --no-split -o $@ $< + +$(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi + +.PHONY: $(dir)/version.texi +$(dir)/version.texi: version + printf "@set VERSION ${VERSION}\n" > $@ + +.PHONY: install-info +install-info: ${info} + mkdir -p "$(DESTDIR)$(INFODIR)" + install -m0644 $(info) "$(DESTDIR)$(INFODIR)" + install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info) + +CLEAN := $(CLEAN) $(info) diff --git a/info/notmuch-emacs.texi b/info/notmuch-emacs.texi new file mode 100644 index 0000000..e19d0ea --- /dev/null +++ b/info/notmuch-emacs.texi @@ -0,0 +1,324 @@ +\input texinfo @c -*-texinfo-*- +@comment $Id@w{$} +@comment %**start of header +@setfilename notmuch-emacs.info +@include version.texi +@settitle Notmuch @value{VERSION} +@comment %**end of header + +@macro keyindex {NAME} +@kindex \NAME\ +@cindex \NAME\ +@end macro + +@macro funindex {NAME} +@findex \NAME\ +@cindex \NAME\ +@end macro + +@macro varindex {NAME} +@vindex \NAME\ +@cindex \NAME\ +@end macro + + +@copying +This manual is for Notmuch (version @value{VERSION}) + +Copyright @copyright{} 2013 David Bremner + +This manual is distributed under the same terms as notmuch, which are as follows. +@quotation + This program 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. + + This program 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/ . + +@end quotation +@end copying + +@dircategory Notmuch +@direntry +* notmuch-emacs: (notmuch-emacs). Emacs interface to notmuch +@end direntry + +@titlepage +@title Notmuch +@subtitle for version @value{VERSION} +@author David Bremner (@email{david@@tethera.net}) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Notmuch + +This manual is for Notmuch (version @value{VERSION}). +@end ifnottex + +@menu +* About this Manual:: +* notmuch-hello:: +* notmuch-search:: +* notmuch-show:: +* notmuch-tree:: +* Configuration:: +* Function Index:: +* Variable Index:: +* Index:: +@end menu + + +@node About this Manual +@unnumbered About this Manual + +This manual covers only the emacs interface to notmuch. For +information on the command line interface, see +@xref{top,the notmuch man page,Description,notmuch,Notmuch Manual Pager}. +To save +typing, we will sometimes use @emph{notmuch} in this manual to refer +to the Emacs interface to notmuch. If the distinction should every be +important, we'll refer to the Emacs inteface as @emph{notmuch-emacs}. + +Notmuch-emacs is highly customizable via the the Emacs customization +framework (or just by setting the appropriate variables). We try to +point out relevant variables in this manual, but in order to avoid +duplication of information, but you can usually find the most detailed +description in the varables docstring. + +@node notmuch-hello +@chapter notmuch-hello + +@funindex notmuch-hello +@funindex notmuch + +@command{notmuch-hello} is the main entry point for notmuch. You can +start it with @kbd{M-x notmuch} or @kbd{M-x notmuch-hello}. The +startup screen looks something like the following. There are some +hints at the bottom of the screen. There are three main parts to the +notmuch-hello screen, discussed below. The @strong{bold} text +indicates buttons you can click with a mouse or by positioning the +cursor and pressing @kbd{<return>} + +@example +@group +---------------------------------------------------------------------------- + + Welcome to @strong{notmuch}. You have 52 messages. + +Saved searches: @strong{[edit]} + + 52 @strong{inbox} 52 @strong{unread} + +Search: . + +All tags: @strong{[show]} + + Type a search query and hit RET to view matching threads. + Edit saved searches with the `edit' button. + Hit RET or click on a saved search or tag name to view matching threads. + `=' to refresh this screen. `s' to search messages. `q' to quit. + @strong{Customize} this page. + +---------------------------------------------------------------------------- +@end group +@end example + +You can change the overall appearence of the notmuch-hello screen by +customizing the variable @var{notmuch-hello-sections}. +@varindex{notmuch-hellow-sections} + +@menu +* notmuch-hello Key Bindings:: +* Saved Searches:: +* Search Box:: +* Known Tags:: +@end menu + +@node notmuch-hello Key Bindings +@section notmuch-hello key bindings + +@table @kbd + +@item <tab> + Move to the next widget (button or text entry field) +@item <backtab> + Move to the previous widget. +@item <return> + Activate the current widget. +@item = +Refresh the buffer; mainly update the counts of messages for various +saved searches. +@item G + Import mail, @xref{Importing Mail}. +@item m + Compose a message +@item s +Search the notmuch database, @xref{notmuch-search}. +@item v + Print notmuch version +@item q +Quit +@end table + + +@node Saved Searches +@section Saved Searches +@cindex Saved Searches + +@varindex notmuch-saved-searches +@varindex notmuch-saved-search-sort-function +@varindex notmuch-column-control + +Notmuch replaces the static assignment of messages with the more +dynamic notion of searching. +Notmuch-hello presents the user with a customizable set of saved +searchs. The initial defaults are @code{tag:inbox} and +@code{tag:unread}, but you can customize the following variables + + +@table @var +@item notmuch-saved-searches +A list of cons pairs, the first being the name to display, the second +being a query string for notmuch. @xref{top,Notmuch Query +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}. + +@item notmuch-saved-searches-sort-function + This variable controls how saved searches should be sorted. A value + of @code{nil} displays the saved searches in the order they are + stored in `notmuch-saved-searches'. +@item notmuch-column-control + Controls the number of columns for displaying saved-searches/tags +@end table + +@node Search Box +@section Search Box +@cindex Search Box + +@varindex notmuch-hello-recent-searches-max +The search box lets the user enter an notmuch query. @xref{top,Notmuch +Query Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}, +for more info on notmuch query syntax. A history of recent searches is +also displayed by default. The latter is controlled by the variable +@var{notmuch-hello-recent-searches-max}. + +@node Known Tags +@section Know Tags +@cindex Known Tags +@varindex notmuch-hello-tag-list-make-query +@varindex notmuch-hello-hide-tags +@varindex notmuch-column-control + +One special kind of saved search provided by default is for each +individual tag defined in the database. This can be controlled via the +following variables. + +@table @var +@item notmuch-hello-tag-list-make-query + Control how to construct a search (``virtual folder'') from a given tag. +@item notmuch-hello-hide-tags + Which tags not to display at all. +@item notmuch-column-control + Controls the number of columns for displaying saved-searches/tags +@end table + + +@node notmuch-search +@chapter notmuch-search + +@menu +* notmuch-search Key Bindings:: +* notmuch-search Customization:: +@end menu + +@funindex notmuch-search-mode +@funindex notmuch-search + +@command{notmuch-search-mode} is used to display the results from +executing a query via @command{notmuch-search}. The syntax for these +queries is the the same as for @xref{Saved Searches}, namely +@xref{top,Notmuch Query +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}. + +By default the output approximates that of the command line +@xref{top,notmuch search command,Description,notmuch-search,notmuch search command}. + +The main purpose of the @command{notmuch-search-mode} buffer is to act +as a menu of results that the user can explore further by pressing +@kbd{<return>} on the appropriate line. + +@node notmuch-search Key Bindings +@table @kbd +@item n,C-n,<down> + Move to next line +@item p,C-p,<up> + Move to previous line +@item <return> + Open thread on current line in @xref{notmuch-show} +@item ? + Display full set of key bindings +@end table + +@node notmuch-search Customization + +@varindex notmuch-search-result-format +@varindex notmuch-search-oldest-first + +The presentation of results can be controlled by the following variables. +@table @var +@item notmuch-search-result-format + Control how each thread of messages is presented in the + @command{notmuch-show-mode} buffer +@item notmuch-search-oldest-first + Display the oldest threads at the top of the buffer +@end table + +@node notmuch-show +@chapter notmuch-show + +@node notmuch-tree +@chapter notmuch-tree + +@node Configuration +@chapter Configuration + + +@menu +* Importing Mail:: +@end menu + +@node Importing Mail +@section Importing Mail + +@funindex notmuch-poll +@vindex notmuch-poll-script + +@node Function Index +@unnumbered Function Index + +@printindex fn + +@node Variable Index +@unnumbered Variable Index + +@printindex vr + +@node Index +@unnumbered Index + +@printindex cp + + +@bye -- 1.8.5.2 ^ permalink raw reply related [flat|nested] 27+ messages in thread
* Re: [Patch v3 1/3] info: start info documentation. 2014-01-15 13:08 ` [Patch v3 1/3] info: start info documentation David Bremner @ 2014-01-17 15:59 ` Jani Nikula 2014-01-17 16:12 ` Jani Nikula 1 sibling, 0 replies; 27+ messages in thread From: Jani Nikula @ 2014-01-17 15:59 UTC (permalink / raw) To: David Bremner, notmuch; +Cc: David Bremner On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote: > From: David Bremner <bremner@debian.org> > > Initially, just a skeleton of documentation for the emacs > interface. There are a few dangling references to other info pages; > these are to be generated from the man pages in a following commit. > > As far as actual documentation, so far this contains only a brief > intro to notmuch-hello. > --- > INSTALL | 12 +- > Makefile | 10 +- > configure | 32 +++++ > info/Makefile | 7 ++ > info/Makefile.local | 33 +++++ > info/notmuch-emacs.texi | 324 ++++++++++++++++++++++++++++++++++++++++++++++++ > 6 files changed, 412 insertions(+), 6 deletions(-) > create mode 100644 info/Makefile > create mode 100644 info/Makefile.local > create mode 100644 info/notmuch-emacs.texi > > diff --git a/INSTALL b/INSTALL > index fce9352..451bf05 100644 > --- a/INSTALL > +++ b/INSTALL > @@ -60,16 +60,24 @@ Talloc which are each described below: > > Talloc is available from http://talloc.samba.org/ > > + texinfo > + ------- > + > + To build the info documentation, you need makeinfo and > + pod2texi. To install the info documentation, you need > + install-info; these are all part of the texinfo distribution > + as of version 5.0. > + > On a modern, package-based operating system you can install all of the > dependencies with a simple simple command line. For example: > > For Debian and similar: > > - sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev > + sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev makeinfo texinfo > > For Fedora and similar: > > - sudo yum install xapian-core-devel gmime-devel libtalloc-devel > + sudo yum install xapian-core-devel gmime-devel libtalloc-devel texinfo > > On other systems, a similar command can be used, but the details of > the package names may be different. > diff --git a/Makefile b/Makefile > index 0428160..250fbaa 100644 > --- a/Makefile > +++ b/Makefile > @@ -2,10 +2,12 @@ > # given explicitly on the command line) so mention it first. > all: > > -# List all subdirectories here. Each contains its own Makefile.local. > -# Use of '=', without '+=', seems to be required for out-of-tree > -# builds to work. > -subdirs = compat completion emacs lib man parse-time-string performance-test util test Please read the comment you're removing again! ;) > +# List all subdirectories here. Each contains its own Makefile.local > +subdirs := compat completion emacs lib man parse-time-string > +subdirs += performance-test util info > +# it seems to be important to keep test last. > +subdirs += test > + > > # We make all targets depend on the Makefiles themselves. > global_deps = Makefile Makefile.config Makefile.local \ > diff --git a/configure b/configure > index 13b6062..e75c1d4 100755 > --- a/configure > +++ b/configure > @@ -376,6 +376,10 @@ if [ -z "${EMACSETCDIR}" ]; then > fi > fi > > +if [ -z "${INFODIR}" ]; then > + INFODIR='$(prefix)/share/info' > +fi > + > printf "Checking if emacs is available... " > if emacs --quick --batch > /dev/null 2>&1; then > printf "Yes.\n" > @@ -385,6 +389,24 @@ else > have_emacs=0 > fi > > +printf "Checking for makeinfo... " > +if makeinfo --version > /dev/null 2>&1; then > + printf "Yes.\n" > + have_makeinfo=1 > +else > + printf "No (so will not info docs)\n" Parse error? > + have_makeinfo=0 > +fi > + > +printf "Checking for install-info... " > +if install-info --version > /dev/null 2>&1; then > + printf "Yes.\n" > + have_installinfo=1 > +else > + printf "No (so will not install info docs)\n" > + have_installinfo=0 > +fi > + > libdir_in_ldconfig=0 > > printf "Checking which platform we are on... " > @@ -740,6 +762,16 @@ emacsetcdir=${EMACSETCDIR} > # Whether there's an emacs binary available for byte-compiling > HAVE_EMACS = ${have_emacs} > > +# Whether there's a makeinfo binary available to build info docs > +HAVE_MAKEINFO = ${have_makeinfo} > + > +# Whether there's an install-info binary available > +HAVE_INSTALLINFO = ${have_installinfo} > + > +# where to install info files > + Extra empty line. > +INFODIR = ${INFODIR} > + > # The directory to which desktop files should be installed > desktop_dir = \$(prefix)/share/applications > > diff --git a/info/Makefile b/info/Makefile > new file mode 100644 > index 0000000..de492a7 > --- /dev/null > +++ b/info/Makefile > @@ -0,0 +1,7 @@ > +# See Makefile.local for the list of files to be compiled in this > +# directory. > +all: > + $(MAKE) -C .. all > + > +.DEFAULT: > + $(MAKE) -C .. $@ > diff --git a/info/Makefile.local b/info/Makefile.local > new file mode 100644 > index 0000000..55e9740 > --- /dev/null > +++ b/info/Makefile.local > @@ -0,0 +1,33 @@ > +# -*- makefile -*- > + > +dir := info > + > +texi_sources := $(dir)/notmuch-emacs.texi > +emacs_info := $(texi_sources:.texi=.info) > + > +info := $(emacs_info) > + > +ifeq ($(HAVE_MAKEINFO),1) > +all: $(info) > +endif > + > +ifeq ($(HAVE_INSTALLINFO),1) > +install: install-info > +endif > + > +%.info: %.texi > + makeinfo --no-split -o $@ $< > + > +$(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi > + > +.PHONY: $(dir)/version.texi > +$(dir)/version.texi: version > + printf "@set VERSION ${VERSION}\n" > $@ > + > +.PHONY: install-info > +install-info: ${info} > + mkdir -p "$(DESTDIR)$(INFODIR)" > + install -m0644 $(info) "$(DESTDIR)$(INFODIR)" > + install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info) > + > +CLEAN := $(CLEAN) $(info) > diff --git a/info/notmuch-emacs.texi b/info/notmuch-emacs.texi > new file mode 100644 > index 0000000..e19d0ea > --- /dev/null > +++ b/info/notmuch-emacs.texi > @@ -0,0 +1,324 @@ > +\input texinfo @c -*-texinfo-*- > +@comment $Id@w{$} > +@comment %**start of header > +@setfilename notmuch-emacs.info > +@include version.texi > +@settitle Notmuch @value{VERSION} > +@comment %**end of header > + > +@macro keyindex {NAME} > +@kindex \NAME\ > +@cindex \NAME\ > +@end macro > + > +@macro funindex {NAME} > +@findex \NAME\ > +@cindex \NAME\ > +@end macro > + > +@macro varindex {NAME} > +@vindex \NAME\ > +@cindex \NAME\ > +@end macro > + > + > +@copying > +This manual is for Notmuch (version @value{VERSION}) > + > +Copyright @copyright{} 2013 David Bremner > + > +This manual is distributed under the same terms as notmuch, which are as follows. > +@quotation > + This program 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. > + > + This program 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/ . > + > +@end quotation > +@end copying > + > +@dircategory Notmuch > +@direntry > +* notmuch-emacs: (notmuch-emacs). Emacs interface to notmuch > +@end direntry > + > +@titlepage > +@title Notmuch > +@subtitle for version @value{VERSION} > +@author David Bremner (@email{david@@tethera.net}) > +@page > +@vskip 0pt plus 1filll > +@insertcopying > +@end titlepage > + > +@contents > + > +@ifnottex > +@node Top > +@top Notmuch > + > +This manual is for Notmuch (version @value{VERSION}). > +@end ifnottex > + > +@menu > +* About this Manual:: > +* notmuch-hello:: > +* notmuch-search:: > +* notmuch-show:: > +* notmuch-tree:: > +* Configuration:: > +* Function Index:: > +* Variable Index:: > +* Index:: > +@end menu > + > + > +@node About this Manual > +@unnumbered About this Manual > + > +This manual covers only the emacs interface to notmuch. For > +information on the command line interface, see > +@xref{top,the notmuch man page,Description,notmuch,Notmuch Manual Pager}. > +To save > +typing, we will sometimes use @emph{notmuch} in this manual to refer > +to the Emacs interface to notmuch. If the distinction should every be > +important, we'll refer to the Emacs inteface as @emph{notmuch-emacs}. > + > +Notmuch-emacs is highly customizable via the the Emacs customization > +framework (or just by setting the appropriate variables). We try to > +point out relevant variables in this manual, but in order to avoid > +duplication of information, but you can usually find the most detailed > +description in the varables docstring. Extra "but"? > + > +@node notmuch-hello > +@chapter notmuch-hello > + > +@funindex notmuch-hello > +@funindex notmuch > + > +@command{notmuch-hello} is the main entry point for notmuch. You can > +start it with @kbd{M-x notmuch} or @kbd{M-x notmuch-hello}. The > +startup screen looks something like the following. There are some > +hints at the bottom of the screen. There are three main parts to the > +notmuch-hello screen, discussed below. The @strong{bold} text > +indicates buttons you can click with a mouse or by positioning the > +cursor and pressing @kbd{<return>} > + > +@example > +@group > +---------------------------------------------------------------------------- > + > + Welcome to @strong{notmuch}. You have 52 messages. > + > +Saved searches: @strong{[edit]} > + > + 52 @strong{inbox} 52 @strong{unread} > + > +Search: . > + > +All tags: @strong{[show]} > + > + Type a search query and hit RET to view matching threads. > + Edit saved searches with the `edit' button. > + Hit RET or click on a saved search or tag name to view matching threads. > + `=' to refresh this screen. `s' to search messages. `q' to quit. > + @strong{Customize} this page. > + > +---------------------------------------------------------------------------- > +@end group > +@end example > + > +You can change the overall appearence of the notmuch-hello screen by > +customizing the variable @var{notmuch-hello-sections}. > +@varindex{notmuch-hellow-sections} > + > +@menu > +* notmuch-hello Key Bindings:: > +* Saved Searches:: > +* Search Box:: > +* Known Tags:: > +@end menu > + > +@node notmuch-hello Key Bindings > +@section notmuch-hello key bindings > + > +@table @kbd > + > +@item <tab> > + Move to the next widget (button or text entry field) > +@item <backtab> > + Move to the previous widget. > +@item <return> > + Activate the current widget. > +@item = > +Refresh the buffer; mainly update the counts of messages for various > +saved searches. > +@item G > + Import mail, @xref{Importing Mail}. > +@item m > + Compose a message > +@item s > +Search the notmuch database, @xref{notmuch-search}. > +@item v > + Print notmuch version > +@item q > +Quit > +@end table > + > + > +@node Saved Searches > +@section Saved Searches > +@cindex Saved Searches > + > +@varindex notmuch-saved-searches > +@varindex notmuch-saved-search-sort-function > +@varindex notmuch-column-control > + > +Notmuch replaces the static assignment of messages with the more > +dynamic notion of searching. > +Notmuch-hello presents the user with a customizable set of saved > +searchs. The initial defaults are @code{tag:inbox} and > +@code{tag:unread}, but you can customize the following variables > + > + > +@table @var > +@item notmuch-saved-searches > +A list of cons pairs, the first being the name to display, the second > +being a query string for notmuch. @xref{top,Notmuch Query > +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}. > + > +@item notmuch-saved-searches-sort-function > + This variable controls how saved searches should be sorted. A value > + of @code{nil} displays the saved searches in the order they are > + stored in `notmuch-saved-searches'. > +@item notmuch-column-control > + Controls the number of columns for displaying saved-searches/tags > +@end table > + > +@node Search Box > +@section Search Box > +@cindex Search Box > + > +@varindex notmuch-hello-recent-searches-max > +The search box lets the user enter an notmuch query. @xref{top,Notmuch > +Query Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}, > +for more info on notmuch query syntax. A history of recent searches is > +also displayed by default. The latter is controlled by the variable > +@var{notmuch-hello-recent-searches-max}. > + > +@node Known Tags > +@section Know Tags > +@cindex Known Tags > +@varindex notmuch-hello-tag-list-make-query > +@varindex notmuch-hello-hide-tags > +@varindex notmuch-column-control > + > +One special kind of saved search provided by default is for each > +individual tag defined in the database. This can be controlled via the > +following variables. > + > +@table @var > +@item notmuch-hello-tag-list-make-query > + Control how to construct a search (``virtual folder'') from a given tag. > +@item notmuch-hello-hide-tags > + Which tags not to display at all. > +@item notmuch-column-control > + Controls the number of columns for displaying saved-searches/tags > +@end table > + > + > +@node notmuch-search > +@chapter notmuch-search > + > +@menu > +* notmuch-search Key Bindings:: > +* notmuch-search Customization:: > +@end menu > + > +@funindex notmuch-search-mode > +@funindex notmuch-search > + > +@command{notmuch-search-mode} is used to display the results from > +executing a query via @command{notmuch-search}. The syntax for these > +queries is the the same as for @xref{Saved Searches}, namely > +@xref{top,Notmuch Query > +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}. > + > +By default the output approximates that of the command line > +@xref{top,notmuch search command,Description,notmuch-search,notmuch search command}. > + > +The main purpose of the @command{notmuch-search-mode} buffer is to act > +as a menu of results that the user can explore further by pressing > +@kbd{<return>} on the appropriate line. > + > +@node notmuch-search Key Bindings > +@table @kbd > +@item n,C-n,<down> > + Move to next line > +@item p,C-p,<up> > + Move to previous line > +@item <return> > + Open thread on current line in @xref{notmuch-show} > +@item ? > + Display full set of key bindings > +@end table > + > +@node notmuch-search Customization > + > +@varindex notmuch-search-result-format > +@varindex notmuch-search-oldest-first > + > +The presentation of results can be controlled by the following variables. > +@table @var > +@item notmuch-search-result-format > + Control how each thread of messages is presented in the > + @command{notmuch-show-mode} buffer > +@item notmuch-search-oldest-first > + Display the oldest threads at the top of the buffer > +@end table > + > +@node notmuch-show > +@chapter notmuch-show > + > +@node notmuch-tree > +@chapter notmuch-tree > + > +@node Configuration > +@chapter Configuration > + > + > +@menu > +* Importing Mail:: > +@end menu > + > +@node Importing Mail > +@section Importing Mail > + > +@funindex notmuch-poll > +@vindex notmuch-poll-script > + > +@node Function Index > +@unnumbered Function Index > + > +@printindex fn > + > +@node Variable Index > +@unnumbered Variable Index > + > +@printindex vr > + > +@node Index > +@unnumbered Index > + > +@printindex cp > + > + > +@bye Reading the content, seems like a reasonable start. I ignored the syntax; I don't know anything about it. BR, Jani. ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [Patch v3 1/3] info: start info documentation. 2014-01-15 13:08 ` [Patch v3 1/3] info: start info documentation David Bremner 2014-01-17 15:59 ` Jani Nikula @ 2014-01-17 16:12 ` Jani Nikula 2014-01-17 19:54 ` David Bremner 1 sibling, 1 reply; 27+ messages in thread From: Jani Nikula @ 2014-01-17 16:12 UTC (permalink / raw) To: David Bremner, notmuch; +Cc: David Bremner On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote: > From: David Bremner <bremner@debian.org> > > Initially, just a skeleton of documentation for the emacs > interface. There are a few dangling references to other info pages; > these are to be generated from the man pages in a following commit. Is it possible to add a link to the info page from notmuch-hello? Jani. > > As far as actual documentation, so far this contains only a brief > intro to notmuch-hello. > --- > INSTALL | 12 +- > Makefile | 10 +- > configure | 32 +++++ > info/Makefile | 7 ++ > info/Makefile.local | 33 +++++ > info/notmuch-emacs.texi | 324 ++++++++++++++++++++++++++++++++++++++++++++++++ > 6 files changed, 412 insertions(+), 6 deletions(-) > create mode 100644 info/Makefile > create mode 100644 info/Makefile.local > create mode 100644 info/notmuch-emacs.texi > > diff --git a/INSTALL b/INSTALL > index fce9352..451bf05 100644 > --- a/INSTALL > +++ b/INSTALL > @@ -60,16 +60,24 @@ Talloc which are each described below: > > Talloc is available from http://talloc.samba.org/ > > + texinfo > + ------- > + > + To build the info documentation, you need makeinfo and > + pod2texi. To install the info documentation, you need > + install-info; these are all part of the texinfo distribution > + as of version 5.0. > + > On a modern, package-based operating system you can install all of the > dependencies with a simple simple command line. For example: > > For Debian and similar: > > - sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev > + sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev makeinfo texinfo > > For Fedora and similar: > > - sudo yum install xapian-core-devel gmime-devel libtalloc-devel > + sudo yum install xapian-core-devel gmime-devel libtalloc-devel texinfo > > On other systems, a similar command can be used, but the details of > the package names may be different. > diff --git a/Makefile b/Makefile > index 0428160..250fbaa 100644 > --- a/Makefile > +++ b/Makefile > @@ -2,10 +2,12 @@ > # given explicitly on the command line) so mention it first. > all: > > -# List all subdirectories here. Each contains its own Makefile.local. > -# Use of '=', without '+=', seems to be required for out-of-tree > -# builds to work. > -subdirs = compat completion emacs lib man parse-time-string performance-test util test > +# List all subdirectories here. Each contains its own Makefile.local > +subdirs := compat completion emacs lib man parse-time-string > +subdirs += performance-test util info > +# it seems to be important to keep test last. > +subdirs += test > + > > # We make all targets depend on the Makefiles themselves. > global_deps = Makefile Makefile.config Makefile.local \ > diff --git a/configure b/configure > index 13b6062..e75c1d4 100755 > --- a/configure > +++ b/configure > @@ -376,6 +376,10 @@ if [ -z "${EMACSETCDIR}" ]; then > fi > fi > > +if [ -z "${INFODIR}" ]; then > + INFODIR='$(prefix)/share/info' > +fi > + > printf "Checking if emacs is available... " > if emacs --quick --batch > /dev/null 2>&1; then > printf "Yes.\n" > @@ -385,6 +389,24 @@ else > have_emacs=0 > fi > > +printf "Checking for makeinfo... " > +if makeinfo --version > /dev/null 2>&1; then > + printf "Yes.\n" > + have_makeinfo=1 > +else > + printf "No (so will not info docs)\n" > + have_makeinfo=0 > +fi > + > +printf "Checking for install-info... " > +if install-info --version > /dev/null 2>&1; then > + printf "Yes.\n" > + have_installinfo=1 > +else > + printf "No (so will not install info docs)\n" > + have_installinfo=0 > +fi > + > libdir_in_ldconfig=0 > > printf "Checking which platform we are on... " > @@ -740,6 +762,16 @@ emacsetcdir=${EMACSETCDIR} > # Whether there's an emacs binary available for byte-compiling > HAVE_EMACS = ${have_emacs} > > +# Whether there's a makeinfo binary available to build info docs > +HAVE_MAKEINFO = ${have_makeinfo} > + > +# Whether there's an install-info binary available > +HAVE_INSTALLINFO = ${have_installinfo} > + > +# where to install info files > + > +INFODIR = ${INFODIR} > + > # The directory to which desktop files should be installed > desktop_dir = \$(prefix)/share/applications > > diff --git a/info/Makefile b/info/Makefile > new file mode 100644 > index 0000000..de492a7 > --- /dev/null > +++ b/info/Makefile > @@ -0,0 +1,7 @@ > +# See Makefile.local for the list of files to be compiled in this > +# directory. > +all: > + $(MAKE) -C .. all > + > +.DEFAULT: > + $(MAKE) -C .. $@ > diff --git a/info/Makefile.local b/info/Makefile.local > new file mode 100644 > index 0000000..55e9740 > --- /dev/null > +++ b/info/Makefile.local > @@ -0,0 +1,33 @@ > +# -*- makefile -*- > + > +dir := info > + > +texi_sources := $(dir)/notmuch-emacs.texi > +emacs_info := $(texi_sources:.texi=.info) > + > +info := $(emacs_info) > + > +ifeq ($(HAVE_MAKEINFO),1) > +all: $(info) > +endif > + > +ifeq ($(HAVE_INSTALLINFO),1) > +install: install-info > +endif > + > +%.info: %.texi > + makeinfo --no-split -o $@ $< > + > +$(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi > + > +.PHONY: $(dir)/version.texi > +$(dir)/version.texi: version > + printf "@set VERSION ${VERSION}\n" > $@ > + > +.PHONY: install-info > +install-info: ${info} > + mkdir -p "$(DESTDIR)$(INFODIR)" > + install -m0644 $(info) "$(DESTDIR)$(INFODIR)" > + install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info) > + > +CLEAN := $(CLEAN) $(info) > diff --git a/info/notmuch-emacs.texi b/info/notmuch-emacs.texi > new file mode 100644 > index 0000000..e19d0ea > --- /dev/null > +++ b/info/notmuch-emacs.texi > @@ -0,0 +1,324 @@ > +\input texinfo @c -*-texinfo-*- > +@comment $Id@w{$} > +@comment %**start of header > +@setfilename notmuch-emacs.info > +@include version.texi > +@settitle Notmuch @value{VERSION} > +@comment %**end of header > + > +@macro keyindex {NAME} > +@kindex \NAME\ > +@cindex \NAME\ > +@end macro > + > +@macro funindex {NAME} > +@findex \NAME\ > +@cindex \NAME\ > +@end macro > + > +@macro varindex {NAME} > +@vindex \NAME\ > +@cindex \NAME\ > +@end macro > + > + > +@copying > +This manual is for Notmuch (version @value{VERSION}) > + > +Copyright @copyright{} 2013 David Bremner > + > +This manual is distributed under the same terms as notmuch, which are as follows. > +@quotation > + This program 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. > + > + This program 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/ . > + > +@end quotation > +@end copying > + > +@dircategory Notmuch > +@direntry > +* notmuch-emacs: (notmuch-emacs). Emacs interface to notmuch > +@end direntry > + > +@titlepage > +@title Notmuch > +@subtitle for version @value{VERSION} > +@author David Bremner (@email{david@@tethera.net}) > +@page > +@vskip 0pt plus 1filll > +@insertcopying > +@end titlepage > + > +@contents > + > +@ifnottex > +@node Top > +@top Notmuch > + > +This manual is for Notmuch (version @value{VERSION}). > +@end ifnottex > + > +@menu > +* About this Manual:: > +* notmuch-hello:: > +* notmuch-search:: > +* notmuch-show:: > +* notmuch-tree:: > +* Configuration:: > +* Function Index:: > +* Variable Index:: > +* Index:: > +@end menu > + > + > +@node About this Manual > +@unnumbered About this Manual > + > +This manual covers only the emacs interface to notmuch. For > +information on the command line interface, see > +@xref{top,the notmuch man page,Description,notmuch,Notmuch Manual Pager}. > +To save > +typing, we will sometimes use @emph{notmuch} in this manual to refer > +to the Emacs interface to notmuch. If the distinction should every be > +important, we'll refer to the Emacs inteface as @emph{notmuch-emacs}. > + > +Notmuch-emacs is highly customizable via the the Emacs customization > +framework (or just by setting the appropriate variables). We try to > +point out relevant variables in this manual, but in order to avoid > +duplication of information, but you can usually find the most detailed > +description in the varables docstring. > + > +@node notmuch-hello > +@chapter notmuch-hello > + > +@funindex notmuch-hello > +@funindex notmuch > + > +@command{notmuch-hello} is the main entry point for notmuch. You can > +start it with @kbd{M-x notmuch} or @kbd{M-x notmuch-hello}. The > +startup screen looks something like the following. There are some > +hints at the bottom of the screen. There are three main parts to the > +notmuch-hello screen, discussed below. The @strong{bold} text > +indicates buttons you can click with a mouse or by positioning the > +cursor and pressing @kbd{<return>} > + > +@example > +@group > +---------------------------------------------------------------------------- > + > + Welcome to @strong{notmuch}. You have 52 messages. > + > +Saved searches: @strong{[edit]} > + > + 52 @strong{inbox} 52 @strong{unread} > + > +Search: . > + > +All tags: @strong{[show]} > + > + Type a search query and hit RET to view matching threads. > + Edit saved searches with the `edit' button. > + Hit RET or click on a saved search or tag name to view matching threads. > + `=' to refresh this screen. `s' to search messages. `q' to quit. > + @strong{Customize} this page. > + > +---------------------------------------------------------------------------- > +@end group > +@end example > + > +You can change the overall appearence of the notmuch-hello screen by > +customizing the variable @var{notmuch-hello-sections}. > +@varindex{notmuch-hellow-sections} > + > +@menu > +* notmuch-hello Key Bindings:: > +* Saved Searches:: > +* Search Box:: > +* Known Tags:: > +@end menu > + > +@node notmuch-hello Key Bindings > +@section notmuch-hello key bindings > + > +@table @kbd > + > +@item <tab> > + Move to the next widget (button or text entry field) > +@item <backtab> > + Move to the previous widget. > +@item <return> > + Activate the current widget. > +@item = > +Refresh the buffer; mainly update the counts of messages for various > +saved searches. > +@item G > + Import mail, @xref{Importing Mail}. > +@item m > + Compose a message > +@item s > +Search the notmuch database, @xref{notmuch-search}. > +@item v > + Print notmuch version > +@item q > +Quit > +@end table > + > + > +@node Saved Searches > +@section Saved Searches > +@cindex Saved Searches > + > +@varindex notmuch-saved-searches > +@varindex notmuch-saved-search-sort-function > +@varindex notmuch-column-control > + > +Notmuch replaces the static assignment of messages with the more > +dynamic notion of searching. > +Notmuch-hello presents the user with a customizable set of saved > +searchs. The initial defaults are @code{tag:inbox} and > +@code{tag:unread}, but you can customize the following variables > + > + > +@table @var > +@item notmuch-saved-searches > +A list of cons pairs, the first being the name to display, the second > +being a query string for notmuch. @xref{top,Notmuch Query > +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}. > + > +@item notmuch-saved-searches-sort-function > + This variable controls how saved searches should be sorted. A value > + of @code{nil} displays the saved searches in the order they are > + stored in `notmuch-saved-searches'. > +@item notmuch-column-control > + Controls the number of columns for displaying saved-searches/tags > +@end table > + > +@node Search Box > +@section Search Box > +@cindex Search Box > + > +@varindex notmuch-hello-recent-searches-max > +The search box lets the user enter an notmuch query. @xref{top,Notmuch > +Query Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}, > +for more info on notmuch query syntax. A history of recent searches is > +also displayed by default. The latter is controlled by the variable > +@var{notmuch-hello-recent-searches-max}. > + > +@node Known Tags > +@section Know Tags > +@cindex Known Tags > +@varindex notmuch-hello-tag-list-make-query > +@varindex notmuch-hello-hide-tags > +@varindex notmuch-column-control > + > +One special kind of saved search provided by default is for each > +individual tag defined in the database. This can be controlled via the > +following variables. > + > +@table @var > +@item notmuch-hello-tag-list-make-query > + Control how to construct a search (``virtual folder'') from a given tag. > +@item notmuch-hello-hide-tags > + Which tags not to display at all. > +@item notmuch-column-control > + Controls the number of columns for displaying saved-searches/tags > +@end table > + > + > +@node notmuch-search > +@chapter notmuch-search > + > +@menu > +* notmuch-search Key Bindings:: > +* notmuch-search Customization:: > +@end menu > + > +@funindex notmuch-search-mode > +@funindex notmuch-search > + > +@command{notmuch-search-mode} is used to display the results from > +executing a query via @command{notmuch-search}. The syntax for these > +queries is the the same as for @xref{Saved Searches}, namely > +@xref{top,Notmuch Query > +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}. > + > +By default the output approximates that of the command line > +@xref{top,notmuch search command,Description,notmuch-search,notmuch search command}. > + > +The main purpose of the @command{notmuch-search-mode} buffer is to act > +as a menu of results that the user can explore further by pressing > +@kbd{<return>} on the appropriate line. > + > +@node notmuch-search Key Bindings > +@table @kbd > +@item n,C-n,<down> > + Move to next line > +@item p,C-p,<up> > + Move to previous line > +@item <return> > + Open thread on current line in @xref{notmuch-show} > +@item ? > + Display full set of key bindings > +@end table > + > +@node notmuch-search Customization > + > +@varindex notmuch-search-result-format > +@varindex notmuch-search-oldest-first > + > +The presentation of results can be controlled by the following variables. > +@table @var > +@item notmuch-search-result-format > + Control how each thread of messages is presented in the > + @command{notmuch-show-mode} buffer > +@item notmuch-search-oldest-first > + Display the oldest threads at the top of the buffer > +@end table > + > +@node notmuch-show > +@chapter notmuch-show > + > +@node notmuch-tree > +@chapter notmuch-tree > + > +@node Configuration > +@chapter Configuration > + > + > +@menu > +* Importing Mail:: > +@end menu > + > +@node Importing Mail > +@section Importing Mail > + > +@funindex notmuch-poll > +@vindex notmuch-poll-script > + > +@node Function Index > +@unnumbered Function Index > + > +@printindex fn > + > +@node Variable Index > +@unnumbered Variable Index > + > +@printindex vr > + > +@node Index > +@unnumbered Index > + > +@printindex cp > + > + > +@bye > -- > 1.8.5.2 > > _______________________________________________ > notmuch mailing list > notmuch@notmuchmail.org > http://notmuchmail.org/mailman/listinfo/notmuch ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [Patch v3 1/3] info: start info documentation. 2014-01-17 16:12 ` Jani Nikula @ 2014-01-17 19:54 ` David Bremner 2014-01-18 11:06 ` Mark Walters 0 siblings, 1 reply; 27+ messages in thread From: David Bremner @ 2014-01-17 19:54 UTC (permalink / raw) To: Jani Nikula, notmuch Jani Nikula <jani@nikula.org> writes: > On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote: >> From: David Bremner <bremner@debian.org> >> >> Initially, just a skeleton of documentation for the emacs >> interface. There are a few dangling references to other info pages; >> these are to be generated from the man pages in a following commit. > > Is it possible to add a link to the info page from notmuch-hello? > > Jani. Yep, just need to add a button that calls (info "notmuch-emacs") We could/should also add custom keybindings to other modes to invoke the same help. For example in notmuch-search-mode we can have a binding to call (info "(notmuch-emacs)notmuch-search") Let the bikeshedding over keybindings begin ;). Potentially we could steal '?' if we made sure the key binding info was prominent. d ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [Patch v3 1/3] info: start info documentation. 2014-01-17 19:54 ` David Bremner @ 2014-01-18 11:06 ` Mark Walters 2014-01-18 12:48 ` Tomi Ollila 2014-01-18 14:52 ` [PATCH] emacs: help: add link to info node Mark Walters 0 siblings, 2 replies; 27+ messages in thread From: Mark Walters @ 2014-01-18 11:06 UTC (permalink / raw) To: David Bremner, Jani Nikula, notmuch As you asked for bike shedding... I would guess that ? for looking up a keybinding is more common than wanting to read the info documentation so how about having a button at the top of the current help/key-bindings page which links to the info? Best wishes Mark On Fri, 17 Jan 2014, David Bremner <david@tethera.net> wrote: > Jani Nikula <jani@nikula.org> writes: > >> On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote: >>> From: David Bremner <bremner@debian.org> >>> >>> Initially, just a skeleton of documentation for the emacs >>> interface. There are a few dangling references to other info pages; >>> these are to be generated from the man pages in a following commit. >> >> Is it possible to add a link to the info page from notmuch-hello? >> >> Jani. > > Yep, just need to add a button that calls > > (info "notmuch-emacs") > > We could/should also add custom keybindings to other modes to invoke the > same help. For example in notmuch-search-mode we can have a binding to call > > (info "(notmuch-emacs)notmuch-search") > > Let the bikeshedding over keybindings begin ;). Potentially we could > steal '?' if we made sure the key binding info was prominent. > > d > _______________________________________________ > notmuch mailing list > notmuch@notmuchmail.org > http://notmuchmail.org/mailman/listinfo/notmuch ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [Patch v3 1/3] info: start info documentation. 2014-01-18 11:06 ` Mark Walters @ 2014-01-18 12:48 ` Tomi Ollila 2014-01-18 14:52 ` [PATCH] emacs: help: add link to info node Mark Walters 1 sibling, 0 replies; 27+ messages in thread From: Tomi Ollila @ 2014-01-18 12:48 UTC (permalink / raw) To: Mark Walters, David Bremner, notmuch On Sat, Jan 18 2014, Mark Walters <markwalters1009@gmail.com> wrote: > As you asked for bike shedding... > > I would guess that ? for looking up a keybinding is more common than > wanting to read the info documentation so how about having a button at > the top of the current help/key-bindings page which links to the info? This is better idea than the one I thought of: stealing c-h i... > > Best wishes > > Mark Tomi > > > On Fri, 17 Jan 2014, David Bremner <david@tethera.net> wrote: >> Jani Nikula <jani@nikula.org> writes: >> >>> On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote: >>>> From: David Bremner <bremner@debian.org> >>>> >>>> Initially, just a skeleton of documentation for the emacs >>>> interface. There are a few dangling references to other info pages; >>>> these are to be generated from the man pages in a following commit. >>> >>> Is it possible to add a link to the info page from notmuch-hello? >>> >>> Jani. >> >> Yep, just need to add a button that calls >> >> (info "notmuch-emacs") >> >> We could/should also add custom keybindings to other modes to invoke the >> same help. For example in notmuch-search-mode we can have a binding to call >> >> (info "(notmuch-emacs)notmuch-search") >> >> Let the bikeshedding over keybindings begin ;). Potentially we could >> steal '?' if we made sure the key binding info was prominent. >> >> d >> _______________________________________________ >> notmuch mailing list >> notmuch@notmuchmail.org >> http://notmuchmail.org/mailman/listinfo/notmuch > _______________________________________________ > notmuch mailing list > notmuch@notmuchmail.org > http://notmuchmail.org/mailman/listinfo/notmuch ^ permalink raw reply [flat|nested] 27+ messages in thread
* [PATCH] emacs: help: add link to info node 2014-01-18 11:06 ` Mark Walters 2014-01-18 12:48 ` Tomi Ollila @ 2014-01-18 14:52 ` Mark Walters 1 sibling, 0 replies; 27+ messages in thread From: Mark Walters @ 2014-01-18 14:52 UTC (permalink / raw) To: notmuch Add a link to the info documentation from the keybindings help page. --- For anyone who wants to try this out. (Only works in hello and search mode while there are no other info nodes). Best wishes Mark emacs/notmuch-lib.el | 8 ++++++++ 1 files changed, 8 insertions(+), 0 deletions(-) diff --git a/emacs/notmuch-lib.el b/emacs/notmuch-lib.el index 2be409b..228680b 100644 --- a/emacs/notmuch-lib.el +++ b/emacs/notmuch-lib.el @@ -331,10 +331,18 @@ its prefixed behavior by setting the 'notmuch-prefix-doc property of its command symbol." (interactive) (let* ((mode major-mode) + (parent-mode-name mode-name) + (info-node (concat "(notmuch-emacs)" mode-name)) (doc (substitute-command-keys (notmuch-substitute-command-keys (documentation mode t))))) (with-current-buffer (generate-new-buffer "*notmuch-help*") (insert doc) (goto-char (point-min)) + (forward-line 2) + (insert-button (concat "Info documentation for " parent-mode-name ".") + 'action `(lambda (x) (info ,info-node))) + (insert "\n\n") + (goto-char (point-min)) + (forward-button 1) (set-buffer-modified-p nil) (view-buffer (current-buffer) 'kill-buffer-if-not-modified)))) -- 1.7.9.1 ^ permalink raw reply related [flat|nested] 27+ messages in thread
* [Patch v3 2/3] man: partial conversion to pod. 2014-01-15 13:08 ` David Bremner 2014-01-15 13:08 ` [Patch v3 1/3] info: start info documentation David Bremner @ 2014-01-15 13:08 ` David Bremner 2014-01-17 16:10 ` Jani Nikula 2014-01-15 13:08 ` [Patch v3 3/3] debian: install info files David Bremner 2 siblings, 1 reply; 27+ messages in thread From: David Bremner @ 2014-01-15 13:08 UTC (permalink / raw) To: notmuch; +Cc: David Bremner From: David Bremner <bremner@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 with the following perl script (some small hand-editing of the .pod may be needed afterwards). open(POD,"groff -e -mandoc -Tascii -rHY=0 | rman -f POD|") || die; LINE: while(<POD>){ my $blank=0; while (m/^\s*$/) { $_=<POD>; $blank++; } print "\n" if ($blank); while(s/^(=head1 .*)B[<]/\1/){}; while(s/^(=head1 .*)[>]/\1/){}; s/ */ /g; print; } --- INSTALL | 6 + configure | 12 ++ info/Makefile.local | 28 ++++- man/Makefile.local | 19 ++- man/man1/notmuch-search.1 | 199 ----------------------------- man/man1/notmuch.1 | 190 ---------------------------- man/man7/notmuch-search-terms.7 | 269 ---------------------------------------- pod/notmuch-search-terms.pod | 235 +++++++++++++++++++++++++++++++++++ pod/notmuch-search.pod | 194 +++++++++++++++++++++++++++++ pod/notmuch.pod | 155 +++++++++++++++++++++++ 10 files changed, 645 insertions(+), 662 deletions(-) delete mode 100644 man/man1/notmuch-search.1 delete mode 100644 man/man1/notmuch.1 delete mode 100644 man/man7/notmuch-search-terms.7 create mode 100644 pod/notmuch-search-terms.pod create mode 100644 pod/notmuch-search.pod create mode 100644 pod/notmuch.pod diff --git a/INSTALL b/INSTALL index 451bf05..697b7b2 100644 --- a/INSTALL +++ b/INSTALL @@ -60,6 +60,12 @@ Talloc which are each described below: Talloc is available from http://talloc.samba.org/ + pod2man + ------- + + Some of the documentation is built with pod2man. This is part + of the standard Perl distribution since Perl 5.6.0 + texinfo ------- diff --git a/configure b/configure index e75c1d4..6dadbaa 100755 --- a/configure +++ b/configure @@ -389,6 +389,15 @@ else have_emacs=0 fi +printf "Checking for pod2man... " +if pod2man --help > /dev/null 2>&1; then + printf "Yes.\n" + have_pod2man=1 +else + printf "No (man page install may fail)\n" + have_pod2man=0 +fi + printf "Checking for makeinfo... " if makeinfo --version > /dev/null 2>&1; then printf "Yes.\n" @@ -768,6 +777,9 @@ HAVE_MAKEINFO = ${have_makeinfo} # Whether there's an install-info binary available HAVE_INSTALLINFO = ${have_installinfo} +# Is pod2man in the path? +HAVE_POD2MAN = ${have_pod2man} + # where to install info files INFODIR = ${INFODIR} diff --git a/info/Makefile.local b/info/Makefile.local index 55e9740..26466ae 100644 --- a/info/Makefile.local +++ b/info/Makefile.local @@ -2,10 +2,14 @@ dir := info +man_texi := $(dir)/notmuch.texi $(dir)/notmuch-search.texi $(dir)/notmuch-search-terms.texi +man_info := $(man_texi:.texi=.info) +man_entry := $(man_texi:.texi=.entry) + texi_sources := $(dir)/notmuch-emacs.texi emacs_info := $(texi_sources:.texi=.info) -info := $(emacs_info) +info := $(emacs_info) $(man_info) ifeq ($(HAVE_MAKEINFO),1) all: $(info) @@ -15,11 +19,26 @@ ifeq ($(HAVE_INSTALLINFO),1) install: install-info endif -%.info: %.texi +%.entry: ../pod/%.pod + printf "@dircategory Notmuch\n@direntry\n" > $@ + printf "* %s: (%s). " $(*F) $(*F) >> $@ + podselect -section Name $< | \ + perl -n -e 's/notmuch.* - (.*)/\u\L$$1/ && print' >> $@ + printf "@end direntry\n" >> $@ + +%.info: %.texi %.entry makeinfo --no-split -o $@ $< $(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi + +%.raw-texi: ../pod/%.pod + pod2texi --output $@ $< + +%.texi: %.raw-texi + # a nasty hack, but the nicer ways seem to have bugs. + sed 's/@node Top/@include $(*F).entry\n@node Top/'< $< > $@ + .PHONY: $(dir)/version.texi $(dir)/version.texi: version printf "@set VERSION ${VERSION}\n" > $@ @@ -29,5 +48,8 @@ install-info: ${info} mkdir -p "$(DESTDIR)$(INFODIR)" install -m0644 $(info) "$(DESTDIR)$(INFODIR)" install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info) + for ifile in $(man_info); do \ + install-info --info-dir=${DESTDIR}${INFODIR} $${ifile}; \ + done -CLEAN := $(CLEAN) $(info) +CLEAN := $(CLEAN) $(info) $(man_entry) $(dir)/version.texi diff --git a/man/Makefile.local b/man/Makefile.local index 57910b7..ae4caff 100644 --- a/man/Makefile.local +++ b/man/Makefile.local @@ -23,6 +23,8 @@ MAN1 := \ MAN5 := $(dir)/man5/notmuch-hooks.5 MAN7 := $(dir)/man7/notmuch-search-terms.7 +GENERATED_MAN := $(MAIN_PAGE) $(dir)/man1/notmuch-search.1 $(MAN7) + MAN1_GZ := $(addsuffix .gz,$(MAN1)) MAN5_GZ := $(addsuffix .gz,$(MAN5)) MAN7_GZ := $(addsuffix .gz,$(MAN7)) @@ -34,6 +36,21 @@ COMPRESSED_MAN := $(MAN1_GZ) $(MAN5_GZ) $(MAN7_GZ) %.gz: % gzip --stdout $^ > $@ +POD2MAN_RECIPE = mkdir -p $(@D) && \ + pod2man --section=$(subst .,,$(suffix $@)) \ + --center="Notmuch Documentation" --release=${VERSION} $< > $@ + +$(dir)/man1/%.1: $(dir)/../pod/%.pod + $(POD2MAN_RECIPE) + +$(dir)/man5/%.5: $(dir)/../pod/%.pod + $(POD2MAN_RECIPE) + +$(dir)/man7/%.7: $(dir)/../pod/%.pod + $(POD2MAN_RECIPE) + +CLEAN := $(CLEAN) $(NROFF7) + .PHONY: install-man update-man-versions install-man: $(COMPRESSED_MAN) @@ -52,4 +69,4 @@ update-man-versions: $(MAN_SOURCE) < $$file.bak > $$file; \ done -CLEAN := $(CLEAN) $(COMPRESSED_MAN) $(MAN_BACKUP) +CLEAN := $(CLEAN) $(COMPRESSED_MAN) $(MAN_BACKUP) $(GENERATED_MAN) diff --git a/man/man1/notmuch-search.1 b/man/man1/notmuch-search.1 deleted file mode 100644 index 55a81e7..0000000 --- a/man/man1/notmuch-search.1 +++ /dev/null @@ -1,199 +0,0 @@ -.TH NOTMUCH-SEARCH 1 2013-12-30 "Notmuch 0.17" -.SH NAME -notmuch-search \- search for messages matching the given search terms -.SH SYNOPSIS - -.B notmuch search -.RI [ options "...] <" search-term ">..." - -.SH DESCRIPTION - -Search for messages matching the given search terms, and display as -results the threads containing the matched messages. - -The output consists of one line per thread, giving a thread ID, the -date of the newest (or oldest, depending on the sort option) matched -message in the thread, the number of matched messages and total -messages in the thread, the names of all participants in the thread, -and the subject of the newest (or oldest) message. - -See \fBnotmuch-search-terms\fR(7) -for details of the supported syntax for <search-terms>. - -Supported options for -.B search -include -.RS 4 -.TP 4 -.BR \-\-format= ( json | sexp | text | text0 ) - -Presents the results in either JSON, S-Expressions, newline character -separated plain-text (default), or null character separated plain-text -(compatible with \fBxargs\fR(1) -0 option where available). -.RE - -.RS 4 -.TP 4 -.BR \-\-format-version=N - -Use the specified structured output format version. This is intended -for programs that invoke \fBnotmuch\fR(1) internally. If omitted, the -latest supported version will be used. -.RE - -.RS 4 -.TP 4 -.B \-\-output=(summary|threads|messages|files|tags) - -.RS 4 -.TP 4 -.B summary - -Output a summary of each thread with any message matching the search -terms. The summary includes the thread ID, date, the number of -messages in the thread (both the number matched and the total number), -the authors of the thread and the subject. -.RE -.RS 4 -.TP 4 -.B threads - -Output the thread IDs of all threads with any message matching the -search terms, either one per line (\-\-format=text), separated by null -characters (\-\-format=text0), as a JSON array (\-\-format=json), or -an S-Expression list (\-\-format=sexp). -.RE -.RS 4 -.TP 4 -.B messages - -Output the message IDs of all messages matching the search terms, -either one per line (\-\-format=text), separated by null characters -(\-\-format=text0), as a JSON array (\-\-format=json), or as an -S-Expression list (\-\-format=sexp). -.RE -.RS 4 -.TP 4 -.B files - -Output the filenames of all messages matching the search terms, either -one per line (\-\-format=text), separated by null characters -(\-\-format=text0), as a JSON array (\-\-format=json), or as an -S-Expression list (\-\-format=sexp). - -Note that each message may have multiple filenames associated with it. -All of them are included in the output, unless limited with the -\-\-duplicate=N option. -.RE -.RS 4 -.TP 4 -.B tags - -Output all tags that appear on any message matching the search terms, -either one per line (\-\-format=text), separated by null characters -(\-\-format=text0), as a JSON array (\-\-format=json), or as an -S-Expression list (\-\-format=sexp). -.RE -.RE - -.RS 4 -.TP 4 -.BR \-\-sort= ( newest\-first | oldest\-first ) - -This option can be used to present results in either chronological order -.RB ( oldest\-first ) -or reverse chronological order -.RB ( newest\-first ). - -Note: The thread order will be distinct between these two options -(beyond being simply reversed). When sorting by -.B oldest\-first -the threads will be sorted by the oldest message in each thread, but -when sorting by -.B newest\-first -the threads will be sorted by the newest message in each thread. - -By default, results will be displayed in reverse chronological order, -(that is, the newest results will be displayed first). -.RE - -.RS 4 -.TP 4 -.BR \-\-offset=[\-]N - -Skip displaying the first N results. With the leading '\-', start at the Nth -result from the end. -.RE - -.RS 4 -.TP 4 -.BR \-\-limit=N - -Limit the number of displayed results to N. -.RE - -.RS 4 -.TP 4 -.BR \-\-exclude=(true|false|all|flag) - -A message is called "excluded" if it matches at least one tag in -search.tag_exclude that does not appear explicitly in the search terms. -This option specifies whether to omit excluded messages in the search -process. - -The default value, -.BR true , -prevents excluded messages from matching the search terms. - -.B all -additionally prevents excluded messages from appearing in displayed -results, in effect behaving as though the excluded messages do not exist. - -.B false -allows excluded messages to match search terms and appear in displayed -results. Excluded messages are still marked in the relevant outputs. - -.B flag -only has an effect when -.BR --output=summary . -The output is almost identical to -.BR false , -but the "match count" is the number of matching non-excluded messages in the -thread, rather than the number of matching messages. -.RE - -.RS 4 -.TP 4 -.BR \-\-duplicate=N - -Effective with -.BR --output=files , -output the Nth filename associated with each message matching the -query (N is 1-based). If N is greater than the number of files -associated with the message, don't print anything. - -Note that this option is orthogonal with the -.BR folder: -search prefix. The prefix matches messages based on filenames. This -option filters filenames of the matching messages. -.RE - -.SH EXIT STATUS - -This command supports the following special exit status codes - -.TP -.B 20 -The requested format version is too old. -.TP -.B 21 -The requested format version is too new. - -.SH SEE ALSO - -\fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1), -\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), -\fBnotmuch-insert\fR(1), \fBnotmuch-new\fR(1), -\fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1), -\fBnotmuch-search-terms\fR(7), \fBnotmuch-show\fR(1), -\fBnotmuch-tag\fR(1) diff --git a/man/man1/notmuch.1 b/man/man1/notmuch.1 deleted file mode 100644 index 605b514..0000000 --- a/man/man1/notmuch.1 +++ /dev/null @@ -1,190 +0,0 @@ -.\" notmuch - Not much of an email program, (just index, search and tagging) -.\" -.\" Copyright © 2009 Carl Worth -.\" -.\" Notmuch is free software: you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License as published by -.\" the Free Software Foundation, either version 3 of the License, or -.\" (at your option) any later version. -.\" -.\" Notmuch is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" along with this program. If not, see http://www.gnu.org/licenses/ . -.\" -.\" Author: Carl Worth <cworth@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@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-search.pod b/pod/notmuch-search.pod new file mode 100644 index 0000000..629ac02 --- /dev/null +++ b/pod/notmuch-search.pod @@ -0,0 +1,194 @@ +=head1 Name + +notmuch-search - search for messages matching the given search terms + +=head1 Synopsis + +B<notmuch> B<search> [I<options>...] <I<search-term>>... + +=head1 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 L<notmuch-search-terms(7)> for details of the supported syntax for +<search-terms>. + +Supported options for B<search> include + +=over 5 + +=item B<--format=>(B<json>|B<sexp>|B<text>|B<text0>) + +=back + +Presents the results in either JSON, S-Expressions, newline +character separated plain-text (default), or null character +separated plain-text (compatible with L<xargs(1)> -0 option where +available). + +=over 5 + +=item B<--format-version=N> + +=back + +Use the specified structured output format version. This is +intended for programs that invoke L<notmuch(1)> internally. If +omitted, the latest supported version will be used. + +=over 5 + +=item B<--output=(summary|threads|messages|files|tags)> + +=back + +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. + +B<threads> + +Output the thread IDs of all threads with any message +matching the search terms, either one per line +(--format=text), separated by null characters +(--format=text0), as a JSON array (--format=json), or an S- +Expression list (--format=sexp). + +B<messages> + +Output the message IDs of all messages matching the search +terms, either one per line (--format=text), separated by +null characters (--format=text0), as a JSON array +(--format=json), or as an S-Expression list +(--format=sexp). + +B<files> + +Output the filenames of all messages matching the search +terms, either one per line (--format=text), separated by +null characters (--format=text0), as a JSON array +(--format=json), or as an S-Expression list +(--format=sexp). + +Note that each message may have multiple filenames +associated with it. All of them are included in the +output, unless limited with the --duplicate=N option. + +B<tags> + +Output all tags that appear on any message matching the +search terms, either one per line (--format=text), +separated by null characters (--format=text0), as a JSON +array (--format=json), or as an S-Expression list +(--format=sexp). + +=over 5 + +=item B<--sort=>(B<newest-first>|B<oldest-first>) + +=back + +This option can be used to present results in either +chronological order (B<oldest-first>) or reverse chronological +order (B<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). + +=over 5 + +=item B<--offset=[-]N> + +=back + +Skip displaying the first N results. With the leading `-', +start at the Nth result from the end. + +=over 5 + +=item B<--limit=N> + +=back + +Limit the number of displayed results to N. + +=over 5 + +=item B<--exclude=(true|false|all|flag)> + +=back + +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, B<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 B<--output=summary>. The output is +almost identical to B<false>, but the "match count" is the number +of matching non-excluded messages in the thread, rather than +the number of matching messages. + +=over 5 + +=item B<--duplicate=N> + +=back + +Effective with B<--output=files>, output the Nth filename +associated with each message matching the query (N is 1-based). +If N is greater than the number of files associated with the +message, don't print anything. + +Note that this option is orthogonal with the B<folder:> search +prefix. The prefix matches messages based on filenames. This +option filters filenames of the matching messages. + +=head1 Exit Status + +This command supports the following special exit status codes + +=over 7 + +=item B<20> + + The requested format version is too old. + +=item B<21> + + The requested format version is too new. + +=back + +=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-terms(7)>, L<notmuch-show(1)>, L<notmuchtag(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@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 ^ permalink raw reply related [flat|nested] 27+ messages in thread
* Re: [Patch v3 2/3] man: partial conversion to pod. 2014-01-15 13:08 ` [Patch v3 2/3] man: partial conversion to pod David Bremner @ 2014-01-17 16:10 ` Jani Nikula 2014-01-17 20:09 ` David Bremner 0 siblings, 1 reply; 27+ messages in thread From: Jani Nikula @ 2014-01-17 16:10 UTC (permalink / raw) To: David Bremner, notmuch; +Cc: David Bremner On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote: > From: David Bremner <bremner@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. 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=0 | rman -f POD|") || die; > LINE: > while(<POD>){ > my $blank=0; > while (m/^\s*$/) { > $_=<POD>; > $blank++; > } > print "\n" if ($blank); > > while(s/^(=head1 .*)B[<]/\1/){}; > while(s/^(=head1 .*)[>]/\1/){}; > > s/ */ /g; > print; > } > --- > INSTALL | 6 + > configure | 12 ++ > info/Makefile.local | 28 ++++- > man/Makefile.local | 19 ++- > man/man1/notmuch-search.1 | 199 ----------------------------- > man/man1/notmuch.1 | 190 ---------------------------- > man/man7/notmuch-search-terms.7 | 269 ---------------------------------------- > pod/notmuch-search-terms.pod | 235 +++++++++++++++++++++++++++++++++++ > pod/notmuch-search.pod | 194 +++++++++++++++++++++++++++++ > pod/notmuch.pod | 155 +++++++++++++++++++++++ > 10 files changed, 645 insertions(+), 662 deletions(-) > delete mode 100644 man/man1/notmuch-search.1 > delete mode 100644 man/man1/notmuch.1 > delete mode 100644 man/man7/notmuch-search-terms.7 > create mode 100644 pod/notmuch-search-terms.pod > create mode 100644 pod/notmuch-search.pod > create mode 100644 pod/notmuch.pod > > diff --git a/INSTALL b/INSTALL > index 451bf05..697b7b2 100644 > --- a/INSTALL > +++ b/INSTALL > @@ -60,6 +60,12 @@ Talloc which are each described below: > > Talloc is available from http://talloc.samba.org/ > > + pod2man > + ------- > + > + Some of the documentation is built with pod2man. This is part > + of the standard Perl distribution since Perl 5.6.0 > + > texinfo > ------- > > diff --git a/configure b/configure > index e75c1d4..6dadbaa 100755 > --- a/configure > +++ b/configure > @@ -389,6 +389,15 @@ else > have_emacs=0 > fi > > +printf "Checking for pod2man... " > +if pod2man --help > /dev/null 2>&1; then > + printf "Yes.\n" > + have_pod2man=1 > +else > + printf "No (man page install may fail)\n" > + have_pod2man=0 > +fi > + > printf "Checking for makeinfo... " > if makeinfo --version > /dev/null 2>&1; then > printf "Yes.\n" > @@ -768,6 +777,9 @@ HAVE_MAKEINFO = ${have_makeinfo} > # Whether there's an install-info binary available > HAVE_INSTALLINFO = ${have_installinfo} > > +# Is pod2man in the path? > +HAVE_POD2MAN = ${have_pod2man} > + > # where to install info files > > INFODIR = ${INFODIR} > diff --git a/info/Makefile.local b/info/Makefile.local > index 55e9740..26466ae 100644 > --- a/info/Makefile.local > +++ b/info/Makefile.local > @@ -2,10 +2,14 @@ > > dir := info > > +man_texi := $(dir)/notmuch.texi $(dir)/notmuch-search.texi $(dir)/notmuch-search-terms.texi > +man_info := $(man_texi:.texi=.info) > +man_entry := $(man_texi:.texi=.entry) > + > texi_sources := $(dir)/notmuch-emacs.texi > emacs_info := $(texi_sources:.texi=.info) > > -info := $(emacs_info) > +info := $(emacs_info) $(man_info) > > ifeq ($(HAVE_MAKEINFO),1) > all: $(info) > @@ -15,11 +19,26 @@ ifeq ($(HAVE_INSTALLINFO),1) > install: install-info > endif > > -%.info: %.texi > +%.entry: ../pod/%.pod > + printf "@dircategory Notmuch\n@direntry\n" > $@ > + printf "* %s: (%s). " $(*F) $(*F) >> $@ > + podselect -section Name $< | \ > + perl -n -e 's/notmuch.* - (.*)/\u\L$$1/ && print' >> $@ > + printf "@end direntry\n" >> $@ > + > +%.info: %.texi %.entry > makeinfo --no-split -o $@ $< > > $(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi > > + > +%.raw-texi: ../pod/%.pod > + pod2texi --output $@ $< > + > +%.texi: %.raw-texi > + # a nasty hack, but the nicer ways seem to have bugs. > + sed 's/@node Top/@include $(*F).entry\n@node Top/'< $< > $@ > + > .PHONY: $(dir)/version.texi > $(dir)/version.texi: version > printf "@set VERSION ${VERSION}\n" > $@ > @@ -29,5 +48,8 @@ install-info: ${info} > mkdir -p "$(DESTDIR)$(INFODIR)" > install -m0644 $(info) "$(DESTDIR)$(INFODIR)" > install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info) > + for ifile in $(man_info); do \ > + install-info --info-dir=${DESTDIR}${INFODIR} $${ifile}; \ > + done > > -CLEAN := $(CLEAN) $(info) > +CLEAN := $(CLEAN) $(info) $(man_entry) $(dir)/version.texi > diff --git a/man/Makefile.local b/man/Makefile.local > index 57910b7..ae4caff 100644 > --- a/man/Makefile.local > +++ b/man/Makefile.local > @@ -23,6 +23,8 @@ MAN1 := \ > MAN5 := $(dir)/man5/notmuch-hooks.5 > MAN7 := $(dir)/man7/notmuch-search-terms.7 > > +GENERATED_MAN := $(MAIN_PAGE) $(dir)/man1/notmuch-search.1 $(MAN7) > + > MAN1_GZ := $(addsuffix .gz,$(MAN1)) > MAN5_GZ := $(addsuffix .gz,$(MAN5)) > MAN7_GZ := $(addsuffix .gz,$(MAN7)) > @@ -34,6 +36,21 @@ COMPRESSED_MAN := $(MAN1_GZ) $(MAN5_GZ) $(MAN7_GZ) > %.gz: % > gzip --stdout $^ > $@ > > +POD2MAN_RECIPE = mkdir -p $(@D) && \ > + pod2man --section=$(subst .,,$(suffix $@)) \ > + --center="Notmuch Documentation" --release=${VERSION} $< > $@ > + > +$(dir)/man1/%.1: $(dir)/../pod/%.pod > + $(POD2MAN_RECIPE) > + > +$(dir)/man5/%.5: $(dir)/../pod/%.pod > + $(POD2MAN_RECIPE) > + > +$(dir)/man7/%.7: $(dir)/../pod/%.pod > + $(POD2MAN_RECIPE) > + > +CLEAN := $(CLEAN) $(NROFF7) > + > .PHONY: install-man update-man-versions > > install-man: $(COMPRESSED_MAN) > @@ -52,4 +69,4 @@ update-man-versions: $(MAN_SOURCE) > < $$file.bak > $$file; \ > done > > -CLEAN := $(CLEAN) $(COMPRESSED_MAN) $(MAN_BACKUP) > +CLEAN := $(CLEAN) $(COMPRESSED_MAN) $(MAN_BACKUP) $(GENERATED_MAN) > diff --git a/man/man1/notmuch-search.1 b/man/man1/notmuch-search.1 > deleted file mode 100644 > index 55a81e7..0000000 > --- a/man/man1/notmuch-search.1 > +++ /dev/null > @@ -1,199 +0,0 @@ > -.TH NOTMUCH-SEARCH 1 2013-12-30 "Notmuch 0.17" > -.SH NAME > -notmuch-search \- search for messages matching the given search terms > -.SH SYNOPSIS > - > -.B notmuch search > -.RI [ options "...] <" search-term ">..." > - > -.SH DESCRIPTION > - > -Search for messages matching the given search terms, and display as > -results the threads containing the matched messages. > - > -The output consists of one line per thread, giving a thread ID, the > -date of the newest (or oldest, depending on the sort option) matched > -message in the thread, the number of matched messages and total > -messages in the thread, the names of all participants in the thread, > -and the subject of the newest (or oldest) message. > - > -See \fBnotmuch-search-terms\fR(7) > -for details of the supported syntax for <search-terms>. > - > -Supported options for > -.B search > -include > -.RS 4 > -.TP 4 > -.BR \-\-format= ( json | sexp | text | text0 ) > - > -Presents the results in either JSON, S-Expressions, newline character > -separated plain-text (default), or null character separated plain-text > -(compatible with \fBxargs\fR(1) -0 option where available). > -.RE > - > -.RS 4 > -.TP 4 > -.BR \-\-format-version=N > - > -Use the specified structured output format version. This is intended > -for programs that invoke \fBnotmuch\fR(1) internally. If omitted, the > -latest supported version will be used. > -.RE > - > -.RS 4 > -.TP 4 > -.B \-\-output=(summary|threads|messages|files|tags) > - > -.RS 4 > -.TP 4 > -.B summary > - > -Output a summary of each thread with any message matching the search > -terms. The summary includes the thread ID, date, the number of > -messages in the thread (both the number matched and the total number), > -the authors of the thread and the subject. > -.RE > -.RS 4 > -.TP 4 > -.B threads > - > -Output the thread IDs of all threads with any message matching the > -search terms, either one per line (\-\-format=text), separated by null > -characters (\-\-format=text0), as a JSON array (\-\-format=json), or > -an S-Expression list (\-\-format=sexp). > -.RE > -.RS 4 > -.TP 4 > -.B messages > - > -Output the message IDs of all messages matching the search terms, > -either one per line (\-\-format=text), separated by null characters > -(\-\-format=text0), as a JSON array (\-\-format=json), or as an > -S-Expression list (\-\-format=sexp). > -.RE > -.RS 4 > -.TP 4 > -.B files > - > -Output the filenames of all messages matching the search terms, either > -one per line (\-\-format=text), separated by null characters > -(\-\-format=text0), as a JSON array (\-\-format=json), or as an > -S-Expression list (\-\-format=sexp). > - > -Note that each message may have multiple filenames associated with it. > -All of them are included in the output, unless limited with the > -\-\-duplicate=N option. > -.RE > -.RS 4 > -.TP 4 > -.B tags > - > -Output all tags that appear on any message matching the search terms, > -either one per line (\-\-format=text), separated by null characters > -(\-\-format=text0), as a JSON array (\-\-format=json), or as an > -S-Expression list (\-\-format=sexp). > -.RE > -.RE > - > -.RS 4 > -.TP 4 > -.BR \-\-sort= ( newest\-first | oldest\-first ) > - > -This option can be used to present results in either chronological order > -.RB ( oldest\-first ) > -or reverse chronological order > -.RB ( newest\-first ). > - > -Note: The thread order will be distinct between these two options > -(beyond being simply reversed). When sorting by > -.B oldest\-first > -the threads will be sorted by the oldest message in each thread, but > -when sorting by > -.B newest\-first > -the threads will be sorted by the newest message in each thread. > - > -By default, results will be displayed in reverse chronological order, > -(that is, the newest results will be displayed first). > -.RE > - > -.RS 4 > -.TP 4 > -.BR \-\-offset=[\-]N > - > -Skip displaying the first N results. With the leading '\-', start at the Nth > -result from the end. > -.RE > - > -.RS 4 > -.TP 4 > -.BR \-\-limit=N > - > -Limit the number of displayed results to N. > -.RE > - > -.RS 4 > -.TP 4 > -.BR \-\-exclude=(true|false|all|flag) > - > -A message is called "excluded" if it matches at least one tag in > -search.tag_exclude that does not appear explicitly in the search terms. > -This option specifies whether to omit excluded messages in the search > -process. > - > -The default value, > -.BR true , > -prevents excluded messages from matching the search terms. > - > -.B all > -additionally prevents excluded messages from appearing in displayed > -results, in effect behaving as though the excluded messages do not exist. > - > -.B false > -allows excluded messages to match search terms and appear in displayed > -results. Excluded messages are still marked in the relevant outputs. > - > -.B flag > -only has an effect when > -.BR --output=summary . > -The output is almost identical to > -.BR false , > -but the "match count" is the number of matching non-excluded messages in the > -thread, rather than the number of matching messages. > -.RE > - > -.RS 4 > -.TP 4 > -.BR \-\-duplicate=N > - > -Effective with > -.BR --output=files , > -output the Nth filename associated with each message matching the > -query (N is 1-based). If N is greater than the number of files > -associated with the message, don't print anything. > - > -Note that this option is orthogonal with the > -.BR folder: > -search prefix. The prefix matches messages based on filenames. This > -option filters filenames of the matching messages. > -.RE > - > -.SH EXIT STATUS > - > -This command supports the following special exit status codes > - > -.TP > -.B 20 > -The requested format version is too old. > -.TP > -.B 21 > -The requested format version is too new. > - > -.SH SEE ALSO > - > -\fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1), > -\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), > -\fBnotmuch-insert\fR(1), \fBnotmuch-new\fR(1), > -\fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1), > -\fBnotmuch-search-terms\fR(7), \fBnotmuch-show\fR(1), > -\fBnotmuch-tag\fR(1) > diff --git a/man/man1/notmuch.1 b/man/man1/notmuch.1 > deleted file mode 100644 > index 605b514..0000000 > --- a/man/man1/notmuch.1 > +++ /dev/null > @@ -1,190 +0,0 @@ > -.\" notmuch - Not much of an email program, (just index, search and tagging) > -.\" > -.\" Copyright © 2009 Carl Worth > -.\" > -.\" Notmuch is free software: you can redistribute it and/or modify > -.\" it under the terms of the GNU General Public License as published by > -.\" the Free Software Foundation, either version 3 of the License, or > -.\" (at your option) any later version. > -.\" > -.\" Notmuch is distributed in the hope that it will be useful, > -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of > -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the > -.\" GNU General Public License for more details. > -.\" > -.\" You should have received a copy of the GNU General Public License > -.\" along with this program. If not, see http://www.gnu.org/licenses/ . > -.\" > -.\" Author: Carl Worth <cworth@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@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-search.pod b/pod/notmuch-search.pod > new file mode 100644 > index 0000000..629ac02 > --- /dev/null > +++ b/pod/notmuch-search.pod > @@ -0,0 +1,194 @@ > +=head1 Name > + > +notmuch-search - search for messages matching the given search terms > + > +=head1 Synopsis > + > +B<notmuch> B<search> [I<options>...] <I<search-term>>... > + > +=head1 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 L<notmuch-search-terms(7)> for details of the supported syntax for > +<search-terms>. > + > +Supported options for B<search> include > + > +=over 5 > + > +=item B<--format=>(B<json>|B<sexp>|B<text>|B<text0>) > + > +=back > + > +Presents the results in either JSON, S-Expressions, newline > +character separated plain-text (default), or null character > +separated plain-text (compatible with L<xargs(1)> -0 option where > +available). > + > +=over 5 > + > +=item B<--format-version=N> > + > +=back > + > +Use the specified structured output format version. This is > +intended for programs that invoke L<notmuch(1)> internally. If > +omitted, the latest supported version will be used. > + > +=over 5 > + > +=item B<--output=(summary|threads|messages|files|tags)> > + > +=back > + > +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. > + > +B<threads> > + > +Output the thread IDs of all threads with any message > +matching the search terms, either one per line > +(--format=text), separated by null characters > +(--format=text0), as a JSON array (--format=json), or an S- > +Expression list (--format=sexp). > + > +B<messages> > + > +Output the message IDs of all messages matching the search > +terms, either one per line (--format=text), separated by > +null characters (--format=text0), as a JSON array > +(--format=json), or as an S-Expression list > +(--format=sexp). > + > +B<files> > + > +Output the filenames of all messages matching the search > +terms, either one per line (--format=text), separated by > +null characters (--format=text0), as a JSON array > +(--format=json), or as an S-Expression list > +(--format=sexp). > + > +Note that each message may have multiple filenames > +associated with it. All of them are included in the > +output, unless limited with the --duplicate=N option. > + > +B<tags> > + > +Output all tags that appear on any message matching the > +search terms, either one per line (--format=text), > +separated by null characters (--format=text0), as a JSON > +array (--format=json), or as an S-Expression list > +(--format=sexp). > + > +=over 5 > + > +=item B<--sort=>(B<newest-first>|B<oldest-first>) > + > +=back > + > +This option can be used to present results in either > +chronological order (B<oldest-first>) or reverse chronological > +order (B<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). > + > +=over 5 > + > +=item B<--offset=[-]N> > + > +=back > + > +Skip displaying the first N results. With the leading `-', > +start at the Nth result from the end. > + > +=over 5 > + > +=item B<--limit=N> > + > +=back > + > +Limit the number of displayed results to N. > + > +=over 5 > + > +=item B<--exclude=(true|false|all|flag)> > + > +=back > + > +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, B<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 B<--output=summary>. The output is > +almost identical to B<false>, but the "match count" is the number > +of matching non-excluded messages in the thread, rather than > +the number of matching messages. > + > +=over 5 > + > +=item B<--duplicate=N> > + > +=back > + > +Effective with B<--output=files>, output the Nth filename > +associated with each message matching the query (N is 1-based). > +If N is greater than the number of files associated with the > +message, don't print anything. > + > +Note that this option is orthogonal with the B<folder:> search > +prefix. The prefix matches messages based on filenames. This > +option filters filenames of the matching messages. > + > +=head1 Exit Status > + > +This command supports the following special exit status codes > + > +=over 7 > + > +=item B<20> > + > + The requested format version is too old. > + > +=item B<21> > + > + The requested format version is too new. > + > +=back > + > +=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-terms(7)>, L<notmuch-show(1)>, L<notmuchtag(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@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 > > _______________________________________________ > notmuch mailing list > notmuch@notmuchmail.org > http://notmuchmail.org/mailman/listinfo/notmuch ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [Patch v3 2/3] man: partial conversion to pod. 2014-01-17 16:10 ` Jani Nikula @ 2014-01-17 20:09 ` David Bremner 2014-01-17 23:35 ` Gregor Zattler 2014-01-18 11:11 ` Mark Walters 0 siblings, 2 replies; 27+ messages in thread From: David Bremner @ 2014-01-17 20:09 UTC (permalink / raw) To: Jani Nikula, notmuch Jani Nikula <jani@nikula.org> writes: > On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote: >> From: David Bremner <bremner@debian.org> > 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? To complicate things, if we did decide on something heavyweight I think I'd propose we think about rst instead of markdown. I don't rst as well as markdown, but markdown does feel a little too adhoc to me from time to time (e.g. a verbatim block forcing the end of a list and so on). As far as I can tell, there are many incompatible versions of markdown as soon as you start to want e.g. tables. In any case, rst -> man is supported by python-docutils. sphinx supports both man page generation and texinfo output. So that would be relatively lighter weight alternative (??) to pandoc. A more radical proposal would be to skip generating info and assuming everybody can browse html in emacs. That assumption is supposed to become less ludicrous in emacs24.4 with the inclusion of "eww". d ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [Patch v3 2/3] man: partial conversion to pod. 2014-01-17 20:09 ` David Bremner @ 2014-01-17 23:35 ` Gregor Zattler 2014-01-18 11:11 ` Mark Walters 1 sibling, 0 replies; 27+ messages in thread From: Gregor Zattler @ 2014-01-17 23:35 UTC (permalink / raw) To: notmuch Hi David, notmuch developers, * David Bremner <david@tethera.net> [17. Jan. 2014]: > A more radical proposal would be to skip generating info and assuming > everybody can browse html in emacs. That assumption is supposed to > become less ludicrous in emacs24.4 with the inclusion of "eww". While html-rendering is somewhat more dynamic (I wished I knew how to build emacs info documentation with less width) and at least in graphical environments even provides pictures, it's easier to navigate info documentation (going "up", notion of TOC,). I prefer info docs and do read info manuals more closely than any documentation in any other format. Ciao; Gregor ^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [Patch v3 2/3] man: partial conversion to pod. 2014-01-17 20:09 ` David Bremner 2014-01-17 23:35 ` Gregor Zattler @ 2014-01-18 11:11 ` Mark Walters 1 sibling, 0 replies; 27+ messages in thread From: Mark Walters @ 2014-01-18 11:11 UTC (permalink / raw) To: David Bremner, Jani Nikula, notmuch I don't have strong views on which format we use for docs. Html has the nice feature that most people are happy writing it and making doc writing simple seems a good idea. One negative for the pod2texi approach is that debian stable does not have texinfo 5; to test this series I had to build the package from source. Best wishes Mark (html migh have an advantage that most people are happy writing it; eOn Fri, 17 Jan 2014, David Bremner <david@tethera.net> wrote: > Jani Nikula <jani@nikula.org> writes: > >> On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote: >>> From: David Bremner <bremner@debian.org> > >> 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? > > To complicate things, if we did decide on something heavyweight I think > I'd propose we think about rst instead of markdown. I don't rst as well > as markdown, but markdown does feel a little too adhoc to me from time > to time (e.g. a verbatim block forcing the end of a list and so on). > As far as I can tell, there are many incompatible versions of markdown > as soon as you start to want e.g. tables. > > In any case, rst -> man is supported by python-docutils. sphinx supports > both man page generation and texinfo output. So that would be relatively > lighter weight alternative (??) to pandoc. > > A more radical proposal would be to skip generating info and assuming > everybody can browse html in emacs. That assumption is supposed to > become less ludicrous in emacs24.4 with the inclusion of "eww". > > d > _______________________________________________ > notmuch mailing list > notmuch@notmuchmail.org > http://notmuchmail.org/mailman/listinfo/notmuch ^ permalink raw reply [flat|nested] 27+ messages in thread
* [Patch v3 3/3] debian: install info files 2014-01-15 13:08 ` David Bremner 2014-01-15 13:08 ` [Patch v3 1/3] info: start info documentation David Bremner 2014-01-15 13:08 ` [Patch v3 2/3] man: partial conversion to pod David Bremner @ 2014-01-15 13:08 ` David Bremner 2014-01-15 13:16 ` David Bremner 2 siblings, 1 reply; 27+ messages in thread From: David Bremner @ 2014-01-15 13:08 UTC (permalink / raw) To: notmuch; +Cc: David Bremner From: David Bremner <bremner@debian.org> It seems dh_installinfo doesn't understand wildcards or look in debian/tmp --- debian/notmuch-emacs.info | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 debian/notmuch-emacs.info diff --git a/debian/notmuch-emacs.info b/debian/notmuch-emacs.info new file mode 100644 index 0000000..2de46d3 --- /dev/null +++ b/debian/notmuch-emacs.info @@ -0,0 +1,3 @@ +info/notmuch.info +info/notmuch-emacs.info +info/notmuch-search-terms.info -- 1.8.5.2 ^ permalink raw reply related [flat|nested] 27+ messages in thread
* Re: [Patch v3 3/3] debian: install info files 2014-01-15 13:08 ` [Patch v3 3/3] debian: install info files David Bremner @ 2014-01-15 13:16 ` David Bremner 0 siblings, 0 replies; 27+ messages in thread From: David Bremner @ 2014-01-15 13:16 UTC (permalink / raw) To: notmuch David Bremner <david@tethera.net> writes: > +info/notmuch.info > +info/notmuch-emacs.info > +info/notmuch-search-terms.info > -- > 1.8.5.2 ho hum. forgot to install notmuch-search.info. Fixed in git. d ^ permalink raw reply [flat|nested] 27+ messages in thread
* [PATCH 3/3] debian: install info files 2014-01-05 11:39 ` third draft of info manual David Bremner 2014-01-05 11:39 ` [PATCH 1/3] info: start info documentation David Bremner 2014-01-05 11:39 ` [PATCH 2/3] man: partial conversion to pod David Bremner @ 2014-01-05 11:39 ` David Bremner 2 siblings, 0 replies; 27+ messages in thread From: David Bremner @ 2014-01-05 11:39 UTC (permalink / raw) To: notmuch; +Cc: David Bremner From: David Bremner <bremner@debian.org> It seems dh_installinfo doesn't understand wildcards or look in debian/tmp --- debian/notmuch-emacs.info | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 debian/notmuch-emacs.info diff --git a/debian/notmuch-emacs.info b/debian/notmuch-emacs.info new file mode 100644 index 0000000..2de46d3 --- /dev/null +++ b/debian/notmuch-emacs.info @@ -0,0 +1,3 @@ +info/notmuch.info +info/notmuch-emacs.info +info/notmuch-search-terms.info -- 1.8.5.2 ^ permalink raw reply related [flat|nested] 27+ messages in thread
end of thread, other threads:[~2014-01-18 14:53 UTC | newest] Thread overview: 27+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2013-03-10 2:22 [RFC patch] emacs: skeleton of texinfo manual for emacs interface david 2013-04-25 1:19 ` Second draft of info manual david 2013-04-25 1:19 ` [RFC Patch v2 1/3] info: start info documentation david 2013-04-25 1:19 ` [RFC Patch v2 2/3] man: partial conversion to pod david 2013-04-25 1:19 ` [RFC Patch v2 3/3] debian: install info files david 2014-01-05 11:39 ` third draft of info manual David Bremner 2014-01-05 11:39 ` [PATCH 1/3] info: start info documentation David Bremner 2014-01-05 11:39 ` [PATCH 2/3] man: partial conversion to pod David Bremner 2014-01-13 21:06 ` Tomi Ollila 2014-01-14 12:06 ` David Bremner 2014-01-14 12:27 ` Tomi Ollila 2014-01-15 13:08 ` David Bremner 2014-01-15 13:08 ` [Patch v3 1/3] info: start info documentation David Bremner 2014-01-17 15:59 ` Jani Nikula 2014-01-17 16:12 ` Jani Nikula 2014-01-17 19:54 ` David Bremner 2014-01-18 11:06 ` Mark Walters 2014-01-18 12:48 ` Tomi Ollila 2014-01-18 14:52 ` [PATCH] emacs: help: add link to info node Mark Walters 2014-01-15 13:08 ` [Patch v3 2/3] man: partial conversion to pod David Bremner 2014-01-17 16:10 ` Jani Nikula 2014-01-17 20:09 ` David Bremner 2014-01-17 23:35 ` Gregor Zattler 2014-01-18 11:11 ` Mark Walters 2014-01-15 13:08 ` [Patch v3 3/3] debian: install info files David Bremner 2014-01-15 13:16 ` David Bremner 2014-01-05 11:39 ` [PATCH " David Bremner
Code repositories for project(s) associated with this public inbox https://yhetil.org/notmuch.git/ This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).