1 Return-Path: <jani@nikula.org>
\r
2 X-Original-To: notmuch@notmuchmail.org
\r
3 Delivered-To: notmuch@notmuchmail.org
\r
4 Received: from localhost (localhost [127.0.0.1])
\r
5 by olra.theworths.org (Postfix) with ESMTP id 16049431FBC
\r
6 for <notmuch@notmuchmail.org>; Fri, 17 Jan 2014 08:12:42 -0800 (PST)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5
\r
12 tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled
\r
13 Received: from olra.theworths.org ([127.0.0.1])
\r
14 by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)
\r
15 with ESMTP id KKyR3rYIGld9 for <notmuch@notmuchmail.org>;
\r
16 Fri, 17 Jan 2014 08:12:34 -0800 (PST)
\r
17 Received: from mail-ee0-f45.google.com (mail-ee0-f45.google.com
\r
18 [74.125.83.45]) (using TLSv1 with cipher RC4-SHA (128/128 bits)) (No client
\r
19 certificate requested) by olra.theworths.org (Postfix) with ESMTPS id
\r
20 50875431FB6 for <notmuch@notmuchmail.org>; Fri, 17 Jan 2014 08:12:34 -0800
\r
22 Received: by mail-ee0-f45.google.com with SMTP id b15so2153433eek.4
\r
23 for <notmuch@notmuchmail.org>; Fri, 17 Jan 2014 08:12:33 -0800 (PST)
\r
24 X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
\r
25 d=1e100.net; s=20130820;
\r
26 h=x-gm-message-state:from:to:cc:subject:in-reply-to:references
\r
27 :user-agent:date:message-id:mime-version:content-type;
\r
28 bh=HbFbb0ElwUCwgCyPkuf8PV/VcyetMI/rULzvuL6e+QU=;
\r
29 b=e9eZM6sGxuvKJ7FYI14NpXRCQbtiR3mXbv0xJCUdEBy4jG24ItDlunN8CiIjgtwx9k
\r
30 muvWvSGNlx7LhV+KVh6bgYVWDz40KuZWRxyfG4oJrTUGzaoDIs+SmX7vcwVt4YWuWHxE
\r
31 61V7sHfmSOoNmTv+efOqSRuulwT7ftJg2d8FoLSA9q+1EhMwiMq4YiAiPAk+6Qrq9xh4
\r
32 G0P2txWG39Hl+qV89k2Xe7sMpgm+gd4bD+wDYdMZmflhb5HEMvd0UvGG4fma2abKEYB0
\r
33 lcK7uciubIQSsDDTxy+LIaPRTgui73bTLtBOfS4dPjGgeIiMJKjACllAGAdFMYhbT8Yp
\r
36 ALoCoQnYc25zjKrh6uDvRmSa0kRD7jOgdINMaNC9hittJXIFBBxenBNy9UPXV0L1LbRiVunNrP/T
\r
37 X-Received: by 10.15.56.132 with SMTP id y4mr3393213eew.61.1389975153157;
\r
38 Fri, 17 Jan 2014 08:12:33 -0800 (PST)
\r
39 Received: from localhost (dsl-hkibrasgw2-58c36f-91.dhcp.inet.fi.
\r
41 by mx.google.com with ESMTPSA id 7sm28033283eee.12.2014.01.17.08.12.31
\r
42 for <multiple recipients>
\r
43 (version=TLSv1.2 cipher=RC4-SHA bits=128/128);
\r
44 Fri, 17 Jan 2014 08:12:32 -0800 (PST)
\r
45 From: Jani Nikula <jani@nikula.org>
\r
46 To: David Bremner <david@tethera.net>, notmuch@notmuchmail.org
\r
47 Subject: Re: [Patch v3 1/3] info: start info documentation.
\r
48 In-Reply-To: <1389791332-21719-2-git-send-email-david@tethera.net>
\r
49 References: <m2bnzeoiij.fsf@guru.guru-group.fi>
\r
50 <1389791332-21719-1-git-send-email-david@tethera.net>
\r
51 <1389791332-21719-2-git-send-email-david@tethera.net>
\r
52 User-Agent: Notmuch/0.17~rc2+18~g39a67a6 (http://notmuchmail.org) Emacs/24.3.1
\r
53 (x86_64-pc-linux-gnu)
\r
54 Date: Fri, 17 Jan 2014 18:12:30 +0200
\r
55 Message-ID: <87iotir3ip.fsf@nikula.org>
\r
57 Content-Type: text/plain
\r
58 Cc: David Bremner <bremner@debian.org>
\r
59 X-BeenThere: notmuch@notmuchmail.org
\r
60 X-Mailman-Version: 2.1.13
\r
62 List-Id: "Use and development of the notmuch mail system."
\r
63 <notmuch.notmuchmail.org>
\r
64 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
65 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
66 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
67 List-Post: <mailto:notmuch@notmuchmail.org>
\r
68 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
69 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
70 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
71 X-List-Received-Date: Fri, 17 Jan 2014 16:12:42 -0000
\r
73 On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote:
\r
74 > From: David Bremner <bremner@debian.org>
\r
76 > Initially, just a skeleton of documentation for the emacs
\r
77 > interface. There are a few dangling references to other info pages;
\r
78 > these are to be generated from the man pages in a following commit.
\r
80 Is it possible to add a link to the info page from notmuch-hello?
\r
87 > As far as actual documentation, so far this contains only a brief
\r
88 > intro to notmuch-hello.
\r
92 > configure | 32 +++++
\r
93 > info/Makefile | 7 ++
\r
94 > info/Makefile.local | 33 +++++
\r
95 > info/notmuch-emacs.texi | 324 ++++++++++++++++++++++++++++++++++++++++++++++++
\r
96 > 6 files changed, 412 insertions(+), 6 deletions(-)
\r
97 > create mode 100644 info/Makefile
\r
98 > create mode 100644 info/Makefile.local
\r
99 > create mode 100644 info/notmuch-emacs.texi
\r
101 > diff --git a/INSTALL b/INSTALL
\r
102 > index fce9352..451bf05 100644
\r
105 > @@ -60,16 +60,24 @@ Talloc which are each described below:
\r
107 > Talloc is available from http://talloc.samba.org/
\r
112 > + To build the info documentation, you need makeinfo and
\r
113 > + pod2texi. To install the info documentation, you need
\r
114 > + install-info; these are all part of the texinfo distribution
\r
115 > + as of version 5.0.
\r
117 > On a modern, package-based operating system you can install all of the
\r
118 > dependencies with a simple simple command line. For example:
\r
120 > For Debian and similar:
\r
122 > - sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev
\r
123 > + sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev makeinfo texinfo
\r
125 > For Fedora and similar:
\r
127 > - sudo yum install xapian-core-devel gmime-devel libtalloc-devel
\r
128 > + sudo yum install xapian-core-devel gmime-devel libtalloc-devel texinfo
\r
130 > On other systems, a similar command can be used, but the details of
\r
131 > the package names may be different.
\r
132 > diff --git a/Makefile b/Makefile
\r
133 > index 0428160..250fbaa 100644
\r
136 > @@ -2,10 +2,12 @@
\r
137 > # given explicitly on the command line) so mention it first.
\r
140 > -# List all subdirectories here. Each contains its own Makefile.local.
\r
141 > -# Use of '=', without '+=', seems to be required for out-of-tree
\r
142 > -# builds to work.
\r
143 > -subdirs = compat completion emacs lib man parse-time-string performance-test util test
\r
144 > +# List all subdirectories here. Each contains its own Makefile.local
\r
145 > +subdirs := compat completion emacs lib man parse-time-string
\r
146 > +subdirs += performance-test util info
\r
147 > +# it seems to be important to keep test last.
\r
151 > # We make all targets depend on the Makefiles themselves.
\r
152 > global_deps = Makefile Makefile.config Makefile.local \
\r
153 > diff --git a/configure b/configure
\r
154 > index 13b6062..e75c1d4 100755
\r
157 > @@ -376,6 +376,10 @@ if [ -z "${EMACSETCDIR}" ]; then
\r
161 > +if [ -z "${INFODIR}" ]; then
\r
162 > + INFODIR='$(prefix)/share/info'
\r
165 > printf "Checking if emacs is available... "
\r
166 > if emacs --quick --batch > /dev/null 2>&1; then
\r
168 > @@ -385,6 +389,24 @@ else
\r
172 > +printf "Checking for makeinfo... "
\r
173 > +if makeinfo --version > /dev/null 2>&1; then
\r
174 > + printf "Yes.\n"
\r
175 > + have_makeinfo=1
\r
177 > + printf "No (so will not info docs)\n"
\r
178 > + have_makeinfo=0
\r
181 > +printf "Checking for install-info... "
\r
182 > +if install-info --version > /dev/null 2>&1; then
\r
183 > + printf "Yes.\n"
\r
184 > + have_installinfo=1
\r
186 > + printf "No (so will not install info docs)\n"
\r
187 > + have_installinfo=0
\r
190 > libdir_in_ldconfig=0
\r
192 > printf "Checking which platform we are on... "
\r
193 > @@ -740,6 +762,16 @@ emacsetcdir=${EMACSETCDIR}
\r
194 > # Whether there's an emacs binary available for byte-compiling
\r
195 > HAVE_EMACS = ${have_emacs}
\r
197 > +# Whether there's a makeinfo binary available to build info docs
\r
198 > +HAVE_MAKEINFO = ${have_makeinfo}
\r
200 > +# Whether there's an install-info binary available
\r
201 > +HAVE_INSTALLINFO = ${have_installinfo}
\r
203 > +# where to install info files
\r
205 > +INFODIR = ${INFODIR}
\r
207 > # The directory to which desktop files should be installed
\r
208 > desktop_dir = \$(prefix)/share/applications
\r
210 > diff --git a/info/Makefile b/info/Makefile
\r
211 > new file mode 100644
\r
212 > index 0000000..de492a7
\r
214 > +++ b/info/Makefile
\r
216 > +# See Makefile.local for the list of files to be compiled in this
\r
219 > + $(MAKE) -C .. all
\r
222 > + $(MAKE) -C .. $@
\r
223 > diff --git a/info/Makefile.local b/info/Makefile.local
\r
224 > new file mode 100644
\r
225 > index 0000000..55e9740
\r
227 > +++ b/info/Makefile.local
\r
229 > +# -*- makefile -*-
\r
233 > +texi_sources := $(dir)/notmuch-emacs.texi
\r
234 > +emacs_info := $(texi_sources:.texi=.info)
\r
236 > +info := $(emacs_info)
\r
238 > +ifeq ($(HAVE_MAKEINFO),1)
\r
242 > +ifeq ($(HAVE_INSTALLINFO),1)
\r
243 > +install: install-info
\r
247 > + makeinfo --no-split -o $@ $<
\r
249 > +$(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi
\r
251 > +.PHONY: $(dir)/version.texi
\r
252 > +$(dir)/version.texi: version
\r
253 > + printf "@set VERSION ${VERSION}\n" > $@
\r
255 > +.PHONY: install-info
\r
256 > +install-info: ${info}
\r
257 > + mkdir -p "$(DESTDIR)$(INFODIR)"
\r
258 > + install -m0644 $(info) "$(DESTDIR)$(INFODIR)"
\r
259 > + install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info)
\r
261 > +CLEAN := $(CLEAN) $(info)
\r
262 > diff --git a/info/notmuch-emacs.texi b/info/notmuch-emacs.texi
\r
263 > new file mode 100644
\r
264 > index 0000000..e19d0ea
\r
266 > +++ b/info/notmuch-emacs.texi
\r
267 > @@ -0,0 +1,324 @@
\r
268 > +\input texinfo @c -*-texinfo-*-
\r
269 > +@comment $Id@w{$}
\r
270 > +@comment %**start of header
\r
271 > +@setfilename notmuch-emacs.info
\r
272 > +@include version.texi
\r
273 > +@settitle Notmuch @value{VERSION}
\r
274 > +@comment %**end of header
\r
276 > +@macro keyindex {NAME}
\r
281 > +@macro funindex {NAME}
\r
286 > +@macro varindex {NAME}
\r
293 > +This manual is for Notmuch (version @value{VERSION})
\r
295 > +Copyright @copyright{} 2013 David Bremner
\r
297 > +This manual is distributed under the same terms as notmuch, which are as follows.
\r
299 > + This program is free software: you can redistribute it and/or modify
\r
300 > + it under the terms of the GNU General Public License as published by
\r
301 > + the Free Software Foundation, either version 3 of the License, or
\r
302 > + (at your option) any later version.
\r
304 > + This program is distributed in the hope that it will be useful,
\r
305 > + but WITHOUT ANY WARRANTY; without even the implied warranty of
\r
306 > + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
\r
307 > + GNU General Public License for more details.
\r
309 > + You should have received a copy of the GNU General Public License
\r
310 > + along with this program. If not, see http://www.gnu.org/licenses/ .
\r
315 > +@dircategory Notmuch
\r
317 > +* notmuch-emacs: (notmuch-emacs). Emacs interface to notmuch
\r
322 > +@subtitle for version @value{VERSION}
\r
323 > +@author David Bremner (@email{david@@tethera.net})
\r
325 > +@vskip 0pt plus 1filll
\r
335 > +This manual is for Notmuch (version @value{VERSION}).
\r
339 > +* About this Manual::
\r
340 > +* notmuch-hello::
\r
341 > +* notmuch-search::
\r
342 > +* notmuch-show::
\r
343 > +* notmuch-tree::
\r
344 > +* Configuration::
\r
345 > +* Function Index::
\r
346 > +* Variable Index::
\r
351 > +@node About this Manual
\r
352 > +@unnumbered About this Manual
\r
354 > +This manual covers only the emacs interface to notmuch. For
\r
355 > +information on the command line interface, see
\r
356 > +@xref{top,the notmuch man page,Description,notmuch,Notmuch Manual Pager}.
\r
358 > +typing, we will sometimes use @emph{notmuch} in this manual to refer
\r
359 > +to the Emacs interface to notmuch. If the distinction should every be
\r
360 > +important, we'll refer to the Emacs inteface as @emph{notmuch-emacs}.
\r
362 > +Notmuch-emacs is highly customizable via the the Emacs customization
\r
363 > +framework (or just by setting the appropriate variables). We try to
\r
364 > +point out relevant variables in this manual, but in order to avoid
\r
365 > +duplication of information, but you can usually find the most detailed
\r
366 > +description in the varables docstring.
\r
368 > +@node notmuch-hello
\r
369 > +@chapter notmuch-hello
\r
371 > +@funindex notmuch-hello
\r
372 > +@funindex notmuch
\r
374 > +@command{notmuch-hello} is the main entry point for notmuch. You can
\r
375 > +start it with @kbd{M-x notmuch} or @kbd{M-x notmuch-hello}. The
\r
376 > +startup screen looks something like the following. There are some
\r
377 > +hints at the bottom of the screen. There are three main parts to the
\r
378 > +notmuch-hello screen, discussed below. The @strong{bold} text
\r
379 > +indicates buttons you can click with a mouse or by positioning the
\r
380 > +cursor and pressing @kbd{<return>}
\r
384 > +----------------------------------------------------------------------------
\r
386 > + Welcome to @strong{notmuch}. You have 52 messages.
\r
388 > +Saved searches: @strong{[edit]}
\r
390 > + 52 @strong{inbox} 52 @strong{unread}
\r
394 > +All tags: @strong{[show]}
\r
396 > + Type a search query and hit RET to view matching threads.
\r
397 > + Edit saved searches with the `edit' button.
\r
398 > + Hit RET or click on a saved search or tag name to view matching threads.
\r
399 > + `=' to refresh this screen. `s' to search messages. `q' to quit.
\r
400 > + @strong{Customize} this page.
\r
402 > +----------------------------------------------------------------------------
\r
406 > +You can change the overall appearence of the notmuch-hello screen by
\r
407 > +customizing the variable @var{notmuch-hello-sections}.
\r
408 > +@varindex{notmuch-hellow-sections}
\r
411 > +* notmuch-hello Key Bindings::
\r
412 > +* Saved Searches::
\r
417 > +@node notmuch-hello Key Bindings
\r
418 > +@section notmuch-hello key bindings
\r
423 > + Move to the next widget (button or text entry field)
\r
425 > + Move to the previous widget.
\r
427 > + Activate the current widget.
\r
429 > +Refresh the buffer; mainly update the counts of messages for various
\r
432 > + Import mail, @xref{Importing Mail}.
\r
434 > + Compose a message
\r
436 > +Search the notmuch database, @xref{notmuch-search}.
\r
438 > + Print notmuch version
\r
444 > +@node Saved Searches
\r
445 > +@section Saved Searches
\r
446 > +@cindex Saved Searches
\r
448 > +@varindex notmuch-saved-searches
\r
449 > +@varindex notmuch-saved-search-sort-function
\r
450 > +@varindex notmuch-column-control
\r
452 > +Notmuch replaces the static assignment of messages with the more
\r
453 > +dynamic notion of searching.
\r
454 > +Notmuch-hello presents the user with a customizable set of saved
\r
455 > +searchs. The initial defaults are @code{tag:inbox} and
\r
456 > +@code{tag:unread}, but you can customize the following variables
\r
460 > +@item notmuch-saved-searches
\r
461 > +A list of cons pairs, the first being the name to display, the second
\r
462 > +being a query string for notmuch. @xref{top,Notmuch Query
\r
463 > +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}.
\r
465 > +@item notmuch-saved-searches-sort-function
\r
466 > + This variable controls how saved searches should be sorted. A value
\r
467 > + of @code{nil} displays the saved searches in the order they are
\r
468 > + stored in `notmuch-saved-searches'.
\r
469 > +@item notmuch-column-control
\r
470 > + Controls the number of columns for displaying saved-searches/tags
\r
473 > +@node Search Box
\r
474 > +@section Search Box
\r
475 > +@cindex Search Box
\r
477 > +@varindex notmuch-hello-recent-searches-max
\r
478 > +The search box lets the user enter an notmuch query. @xref{top,Notmuch
\r
479 > +Query Syntax,Description,notmuch-search-terms,Notmuch Query Syntax},
\r
480 > +for more info on notmuch query syntax. A history of recent searches is
\r
481 > +also displayed by default. The latter is controlled by the variable
\r
482 > +@var{notmuch-hello-recent-searches-max}.
\r
484 > +@node Known Tags
\r
485 > +@section Know Tags
\r
486 > +@cindex Known Tags
\r
487 > +@varindex notmuch-hello-tag-list-make-query
\r
488 > +@varindex notmuch-hello-hide-tags
\r
489 > +@varindex notmuch-column-control
\r
491 > +One special kind of saved search provided by default is for each
\r
492 > +individual tag defined in the database. This can be controlled via the
\r
493 > +following variables.
\r
496 > +@item notmuch-hello-tag-list-make-query
\r
497 > + Control how to construct a search (``virtual folder'') from a given tag.
\r
498 > +@item notmuch-hello-hide-tags
\r
499 > + Which tags not to display at all.
\r
500 > +@item notmuch-column-control
\r
501 > + Controls the number of columns for displaying saved-searches/tags
\r
505 > +@node notmuch-search
\r
506 > +@chapter notmuch-search
\r
509 > +* notmuch-search Key Bindings::
\r
510 > +* notmuch-search Customization::
\r
513 > +@funindex notmuch-search-mode
\r
514 > +@funindex notmuch-search
\r
516 > +@command{notmuch-search-mode} is used to display the results from
\r
517 > +executing a query via @command{notmuch-search}. The syntax for these
\r
518 > +queries is the the same as for @xref{Saved Searches}, namely
\r
519 > +@xref{top,Notmuch Query
\r
520 > +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}.
\r
522 > +By default the output approximates that of the command line
\r
523 > +@xref{top,notmuch search command,Description,notmuch-search,notmuch search command}.
\r
525 > +The main purpose of the @command{notmuch-search-mode} buffer is to act
\r
526 > +as a menu of results that the user can explore further by pressing
\r
527 > +@kbd{<return>} on the appropriate line.
\r
529 > +@node notmuch-search Key Bindings
\r
531 > +@item n,C-n,<down>
\r
532 > + Move to next line
\r
533 > +@item p,C-p,<up>
\r
534 > + Move to previous line
\r
536 > + Open thread on current line in @xref{notmuch-show}
\r
538 > + Display full set of key bindings
\r
541 > +@node notmuch-search Customization
\r
543 > +@varindex notmuch-search-result-format
\r
544 > +@varindex notmuch-search-oldest-first
\r
546 > +The presentation of results can be controlled by the following variables.
\r
548 > +@item notmuch-search-result-format
\r
549 > + Control how each thread of messages is presented in the
\r
550 > + @command{notmuch-show-mode} buffer
\r
551 > +@item notmuch-search-oldest-first
\r
552 > + Display the oldest threads at the top of the buffer
\r
555 > +@node notmuch-show
\r
556 > +@chapter notmuch-show
\r
558 > +@node notmuch-tree
\r
559 > +@chapter notmuch-tree
\r
561 > +@node Configuration
\r
562 > +@chapter Configuration
\r
566 > +* Importing Mail::
\r
569 > +@node Importing Mail
\r
570 > +@section Importing Mail
\r
572 > +@funindex notmuch-poll
\r
573 > +@vindex notmuch-poll-script
\r
575 > +@node Function Index
\r
576 > +@unnumbered Function Index
\r
580 > +@node Variable Index
\r
581 > +@unnumbered Variable Index
\r
586 > +@unnumbered Index
\r
595 > _______________________________________________
\r
596 > notmuch mailing list
\r
597 > notmuch@notmuchmail.org
\r
598 > http://notmuchmail.org/mailman/listinfo/notmuch
\r