1 Return-Path: <bremner@tethera.net>
\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 16248431FC3
\r
6 for <notmuch@notmuchmail.org>; Sun, 5 Jan 2014 03:39:37 -0800 (PST)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]
\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 bZ5WbTmwXiSX for <notmuch@notmuchmail.org>;
\r
16 Sun, 5 Jan 2014 03:39:27 -0800 (PST)
\r
17 Received: from yantan.tethera.net (yantan.tethera.net [199.188.72.155])
\r
18 (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits))
\r
19 (No client certificate requested)
\r
20 by olra.theworths.org (Postfix) with ESMTPS id BA6E4431FC2
\r
21 for <notmuch@notmuchmail.org>; Sun, 5 Jan 2014 03:39:27 -0800 (PST)
\r
22 Received: from remotemail by yantan.tethera.net with local (Exim 4.80)
\r
23 (envelope-from <bremner@tethera.net>)
\r
24 id 1Vzm3B-0001YF-1x; Sun, 05 Jan 2014 07:39:25 -0400
\r
25 Received: (nullmailer pid 5366 invoked by uid 1000); Sun, 05 Jan 2014
\r
27 From: David Bremner <david@tethera.net>
\r
28 To: notmuch@notmuchmail.org
\r
29 Subject: [PATCH 1/3] info: start info documentation.
\r
30 Date: Sun, 5 Jan 2014 07:39:08 -0400
\r
31 Message-Id: <1388921950-5017-2-git-send-email-david@tethera.net>
\r
32 X-Mailer: git-send-email 1.8.5.2
\r
33 In-Reply-To: <1388921950-5017-1-git-send-email-david@tethera.net>
\r
34 References: <1366852752-3584-1-git-send-email-david@tethera.net>
\r
35 <1388921950-5017-1-git-send-email-david@tethera.net>
\r
36 Cc: David Bremner <bremner@debian.org>
\r
37 X-BeenThere: notmuch@notmuchmail.org
\r
38 X-Mailman-Version: 2.1.13
\r
40 List-Id: "Use and development of the notmuch mail system."
\r
41 <notmuch.notmuchmail.org>
\r
42 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
43 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
44 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
45 List-Post: <mailto:notmuch@notmuchmail.org>
\r
46 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
47 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
48 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
49 X-List-Received-Date: Sun, 05 Jan 2014 11:39:37 -0000
\r
51 From: David Bremner <bremner@debian.org>
\r
53 Initially, just a skeleton of documentation for the emacs
\r
54 interface. There are a few dangling references to other info pages;
\r
55 these are to be generated from the man pages in a following commit.
\r
57 As far as actual documentation, so far this contains only a brief
\r
58 intro to notmuch-hello.
\r
62 configure | 32 ++++++
\r
63 info/Makefile | 7 ++
\r
64 info/Makefile.local | 33 ++++++
\r
65 info/notmuch-emacs.texi | 270 ++++++++++++++++++++++++++++++++++++++++++++++++
\r
66 6 files changed, 358 insertions(+), 6 deletions(-)
\r
67 create mode 100644 info/Makefile
\r
68 create mode 100644 info/Makefile.local
\r
69 create mode 100644 info/notmuch-emacs.texi
\r
71 diff --git a/INSTALL b/INSTALL
\r
72 index fce9352..451bf05 100644
\r
75 @@ -60,16 +60,24 @@ Talloc which are each described below:
\r
77 Talloc is available from http://talloc.samba.org/
\r
82 + To build the info documentation, you need makeinfo and
\r
83 + pod2texi. To install the info documentation, you need
\r
84 + install-info; these are all part of the texinfo distribution
\r
85 + as of version 5.0.
\r
87 On a modern, package-based operating system you can install all of the
\r
88 dependencies with a simple simple command line. For example:
\r
90 For Debian and similar:
\r
92 - sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev
\r
93 + sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev makeinfo texinfo
\r
95 For Fedora and similar:
\r
97 - sudo yum install xapian-core-devel gmime-devel libtalloc-devel
\r
98 + sudo yum install xapian-core-devel gmime-devel libtalloc-devel texinfo
\r
100 On other systems, a similar command can be used, but the details of
\r
101 the package names may be different.
\r
102 diff --git a/Makefile b/Makefile
\r
103 index 0428160..250fbaa 100644
\r
107 # given explicitly on the command line) so mention it first.
\r
110 -# List all subdirectories here. Each contains its own Makefile.local.
\r
111 -# Use of '=', without '+=', seems to be required for out-of-tree
\r
113 -subdirs = compat completion emacs lib man parse-time-string performance-test util test
\r
114 +# List all subdirectories here. Each contains its own Makefile.local
\r
115 +subdirs := compat completion emacs lib man parse-time-string
\r
116 +subdirs += performance-test util info
\r
117 +# it seems to be important to keep test last.
\r
121 # We make all targets depend on the Makefiles themselves.
\r
122 global_deps = Makefile Makefile.config Makefile.local \
\r
123 diff --git a/configure b/configure
\r
124 index 13b6062..e75c1d4 100755
\r
127 @@ -376,6 +376,10 @@ if [ -z "${EMACSETCDIR}" ]; then
\r
131 +if [ -z "${INFODIR}" ]; then
\r
132 + INFODIR='$(prefix)/share/info'
\r
135 printf "Checking if emacs is available... "
\r
136 if emacs --quick --batch > /dev/null 2>&1; then
\r
138 @@ -385,6 +389,24 @@ else
\r
142 +printf "Checking for makeinfo... "
\r
143 +if makeinfo --version > /dev/null 2>&1; then
\r
147 + printf "No (so will not info docs)\n"
\r
151 +printf "Checking for install-info... "
\r
152 +if install-info --version > /dev/null 2>&1; then
\r
154 + have_installinfo=1
\r
156 + printf "No (so will not install info docs)\n"
\r
157 + have_installinfo=0
\r
160 libdir_in_ldconfig=0
\r
162 printf "Checking which platform we are on... "
\r
163 @@ -740,6 +762,16 @@ emacsetcdir=${EMACSETCDIR}
\r
164 # Whether there's an emacs binary available for byte-compiling
\r
165 HAVE_EMACS = ${have_emacs}
\r
167 +# Whether there's a makeinfo binary available to build info docs
\r
168 +HAVE_MAKEINFO = ${have_makeinfo}
\r
170 +# Whether there's an install-info binary available
\r
171 +HAVE_INSTALLINFO = ${have_installinfo}
\r
173 +# where to install info files
\r
175 +INFODIR = ${INFODIR}
\r
177 # The directory to which desktop files should be installed
\r
178 desktop_dir = \$(prefix)/share/applications
\r
180 diff --git a/info/Makefile b/info/Makefile
\r
181 new file mode 100644
\r
182 index 0000000..de492a7
\r
184 +++ b/info/Makefile
\r
186 +# See Makefile.local for the list of files to be compiled in this
\r
189 + $(MAKE) -C .. all
\r
193 diff --git a/info/Makefile.local b/info/Makefile.local
\r
194 new file mode 100644
\r
195 index 0000000..55e9740
\r
197 +++ b/info/Makefile.local
\r
199 +# -*- makefile -*-
\r
203 +texi_sources := $(dir)/notmuch-emacs.texi
\r
204 +emacs_info := $(texi_sources:.texi=.info)
\r
206 +info := $(emacs_info)
\r
208 +ifeq ($(HAVE_MAKEINFO),1)
\r
212 +ifeq ($(HAVE_INSTALLINFO),1)
\r
213 +install: install-info
\r
217 + makeinfo --no-split -o $@ $<
\r
219 +$(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi
\r
221 +.PHONY: $(dir)/version.texi
\r
222 +$(dir)/version.texi: version
\r
223 + printf "@set VERSION ${VERSION}\n" > $@
\r
225 +.PHONY: install-info
\r
226 +install-info: ${info}
\r
227 + mkdir -p "$(DESTDIR)$(INFODIR)"
\r
228 + install -m0644 $(info) "$(DESTDIR)$(INFODIR)"
\r
229 + install-info --section=Notmuch --info-dir=${DESTDIR}${INFODIR} $(emacs_info)
\r
231 +CLEAN := $(CLEAN) $(info)
\r
232 diff --git a/info/notmuch-emacs.texi b/info/notmuch-emacs.texi
\r
233 new file mode 100644
\r
234 index 0000000..434a360
\r
236 +++ b/info/notmuch-emacs.texi
\r
238 +\input texinfo @c -*-texinfo-*-
\r
240 +@comment %**start of header
\r
241 +@setfilename notmuch-emacs.info
\r
242 +@include version.texi
\r
243 +@settitle Notmuch @value{VERSION}
\r
244 +@comment %**end of header
\r
246 +@macro keyindex {NAME}
\r
251 +@macro funindex {NAME}
\r
256 +@macro varindex {NAME}
\r
263 +This manual is for Notmuch (version @value{VERSION})
\r
265 +Copyright @copyright{} 2013 David Bremner
\r
267 +This manual is distributed under the same terms as notmuch, which are as follows.
\r
269 + This program is free software: you can redistribute it and/or modify
\r
270 + it under the terms of the GNU General Public License as published by
\r
271 + the Free Software Foundation, either version 3 of the License, or
\r
272 + (at your option) any later version.
\r
274 + This program is distributed in the hope that it will be useful,
\r
275 + but WITHOUT ANY WARRANTY; without even the implied warranty of
\r
276 + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
\r
277 + GNU General Public License for more details.
\r
279 + You should have received a copy of the GNU General Public License
\r
280 + along with this program. If not, see http://www.gnu.org/licenses/ .
\r
285 +@dircategory Notmuch
\r
287 +* notmuch-emacs: (notmuch-emacs). Emacs interface to notmuch
\r
292 +@subtitle for version @value{VERSION}
\r
293 +@author David Bremner (@email{david@@tethera.net})
\r
295 +@vskip 0pt plus 1filll
\r
305 +This manual is for Notmuch (version @value{VERSION}).
\r
309 +* About this Manual::
\r
311 +* notmuch-search::
\r
313 +* Function Index::
\r
314 +* Variable Index::
\r
319 +@node About this Manual
\r
320 +@unnumbered About this Manual
\r
322 +This manual covers only the emacs interface to notmuch. For
\r
323 +information on the command line interface, see
\r
324 +@xref{top,the notmuch man page,Description,notmuch,Notmuch Manual Pager}.
\r
326 +typing, we will sometimes use @emph{notmuch} in this manual to refer
\r
327 +to the Emacs interface to notmuch. If the distinction should every be
\r
328 +important, we'll refer to the Emacs inteface as @emph{notmuch-emacs}.
\r
330 +Notmuch-emacs is highly customizable via the the Emacs customization
\r
331 +framework (or just by setting the appropriate variables). We try to
\r
332 +point out relevant variables in this manual, but in order to avoid
\r
333 +duplication of information, but you can usually find the most detailed
\r
334 +description in the varables docstring.
\r
336 +@node notmuch-hello
\r
337 +@chapter notmuch-hello
\r
339 +@funindex notmuch-hello
\r
342 +@command{notmuch-hello} is the main entry point for notmuch. You can
\r
343 +start it with @kbd{M-x notmuch} or @kbd{M-x notmuch-hello}. The
\r
344 +startup screen looks something like the following. There are some
\r
345 +hints at the bottom of the screen. There are three main parts to the
\r
346 +notmuch-hello screen, discussed below. The @strong{bold} text
\r
347 +indicates buttons you can click with a mouse or by positioning the
\r
348 +cursor and pressing @kbd{<return>}
\r
352 +----------------------------------------------------------------------------
\r
354 + Welcome to @strong{notmuch}. You have 52 messages.
\r
356 +Saved searches: @strong{[edit]}
\r
358 + 52 @strong{inbox} 52 @strong{unread}
\r
362 +All tags: @strong{[show]}
\r
364 + Type a search query and hit RET to view matching threads.
\r
365 + Edit saved searches with the `edit' button.
\r
366 + Hit RET or click on a saved search or tag name to view matching threads.
\r
367 + `=' to refresh this screen. `s' to search messages. `q' to quit.
\r
368 + @strong{Customize} this page.
\r
370 +----------------------------------------------------------------------------
\r
374 +You can change the overall appearence of the notmuch-hello screen by
\r
375 +customizing the variable @var{notmuch-hello-sections}.
\r
376 +@varindex{notmuch-hellow-sections}
\r
379 +* notemuch-hello Key Bindings::
\r
380 +* Saved Searches::
\r
385 +@node notemuch-hello Key Bindings
\r
386 +@section notmuch-hello key bindings
\r
391 + Move to the next widget (button or text entry field)
\r
393 + Move to the previous widget.
\r
395 + Activate the current widget.
\r
397 +Refresh the buffer; mainly update the counts of messages for various
\r
400 + Import mail, @xref{Importing Mail}.
\r
402 + Compose a message
\r
404 +Search the notmuch database, @xref{notmuch-search}.
\r
406 + Print notmuch version
\r
412 +@node Saved Searches
\r
413 +@section Saved Searches
\r
414 +@cindex Saved Searches
\r
416 +@varindex notmuch-saved-searches
\r
417 +@varindex notmuch-saved-search-sort-function
\r
418 +@varindex notmuch-column-control
\r
420 +Notmuch replaces the static assignment of messages with the more
\r
421 +dynamic notion of searching.
\r
422 +Notmuch-hello presents the user with a customizable set of saved
\r
423 +searchs. The initial defaults are @code{tag:inbox} and
\r
424 +@code{tag:unread}, but you can customize the following variables
\r
428 +@item notmuch-saved-searches
\r
429 +A list of cons pairs, the first being the name to display, the second
\r
430 +being a query string for notmuch. @xref{top,Notmuch Query
\r
431 +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}.
\r
433 +@item notmuch-saved-searches-sort-function
\r
434 + This variable controls how saved searches should be sorted. A value
\r
435 + of @code{nil} displays the saved searches in the order they are
\r
436 + stored in `notmuch-saved-searches'.
\r
437 +@item notmuch-column-control
\r
438 + Controls the number of columns for displaying saved-searches/tags
\r
442 +@section Search Box
\r
443 +@cindex Search Box
\r
445 +@varindex notmuch-hello-recent-searches-max
\r
446 +The search box lets the user enter an notmuch query. @xref{top,Notmuch
\r
447 +Query Syntax,Description,notmuch-search-terms,Notmuch Query Syntax},
\r
448 +for more info on notmuch query syntax. A history of recent searches is
\r
449 +also displayed by default. The latter is controlled by the variable
\r
450 +@var{notmuch-hello-recent-searches-max}.
\r
453 +@section Know Tags
\r
454 +@cindex Known Tags
\r
455 +@varindex notmuch-hello-tag-list-make-query
\r
456 +@varindex notmuch-hello-hide-tags
\r
457 +@varindex notmuch-column-control
\r
459 +One special kind of saved search provided by default is for each
\r
460 +individual tag defined in the database. This can be controlled via the
\r
461 +following variables.
\r
464 +@item notmuch-hello-tag-list-make-query
\r
465 + Control how to construct a search (``virtual folder'') from a given tag.
\r
466 +@item notmuch-hello-hide-tags
\r
467 + Which tags not to display at all.
\r
468 +@item notmuch-column-control
\r
469 + Controls the number of columns for displaying saved-searches/tags
\r
473 +@node notmuch-search
\r
474 +@chapter notmuch-search
\r
477 +@node Configuration
\r
478 +@chapter Configuration
\r
482 +* Importing Mail::
\r
485 +@node Importing Mail
\r
486 +@section Importing Mail
\r
488 +@funindex notmuch-poll
\r
489 +@vindex notmuch-poll-script
\r
491 +@node Function Index
\r
492 +@unnumbered Function Index
\r
496 +@node Variable Index
\r
497 +@unnumbered Variable Index
\r