[PATCH] configure: add --without-api-docs option
[notmuch-archives.git] / d2 / 4e053130a253e5f99998e781c4e67dd5bb570a
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 15D41429E4F\r
6         for <notmuch@notmuchmail.org>; Wed, 15 Jan 2014 05:09:24 -0800 (PST)\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
8 X-Spam-Flag: NO\r
9 X-Spam-Score: 0\r
10 X-Spam-Level: \r
11 X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]\r
12         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 x4BzbKnnJGNW for <notmuch@notmuchmail.org>;\r
16         Wed, 15 Jan 2014 05:09:16 -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 F030E431FBD\r
21         for <notmuch@notmuchmail.org>; Wed, 15 Jan 2014 05:09:13 -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 1W3QDZ-0005Ug-Gq; Wed, 15 Jan 2014 09:09:13 -0400\r
25 Received: (nullmailer pid 21892 invoked by uid 1000); Wed, 15 Jan 2014\r
26         13:08:58 -0000\r
27 From: David Bremner <david@tethera.net>\r
28 To: notmuch@notmuchmail.org\r
29 Subject: [Patch v3 1/3] info: start info documentation.\r
30 Date: Wed, 15 Jan 2014 09:08:50 -0400\r
31 Message-Id: <1389791332-21719-2-git-send-email-david@tethera.net>\r
32 X-Mailer: git-send-email 1.8.5.2\r
33 In-Reply-To: <1389791332-21719-1-git-send-email-david@tethera.net>\r
34 References: <m2bnzeoiij.fsf@guru.guru-group.fi>\r
35         <1389791332-21719-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
39 Precedence: list\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: Wed, 15 Jan 2014 13:09:24 -0000\r
50 \r
51 From: David Bremner <bremner@debian.org>\r
52 \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
56 \r
57 As far as actual documentation, so far this contains only a brief\r
58 intro to notmuch-hello.\r
59 ---\r
60  INSTALL                 |  12 +-\r
61  Makefile                |  10 +-\r
62  configure               |  32 +++++\r
63  info/Makefile           |   7 ++\r
64  info/Makefile.local     |  33 +++++\r
65  info/notmuch-emacs.texi | 324 ++++++++++++++++++++++++++++++++++++++++++++++++\r
66  6 files changed, 412 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
70 \r
71 diff --git a/INSTALL b/INSTALL\r
72 index fce9352..451bf05 100644\r
73 --- a/INSTALL\r
74 +++ b/INSTALL\r
75 @@ -60,16 +60,24 @@ Talloc which are each described below:\r
76  \r
77         Talloc is available from http://talloc.samba.org/\r
78  \r
79 +       texinfo\r
80 +       -------\r
81 +\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
86 +\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
89  \r
90    For Debian and similar:\r
91  \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
94  \r
95    For Fedora and similar:\r
96  \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
99  \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
104 --- a/Makefile\r
105 +++ b/Makefile\r
106 @@ -2,10 +2,12 @@\r
107  # given explicitly on the command line) so mention it first.\r
108  all:\r
109  \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
112 -# builds to work.\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
118 +subdirs += test\r
119 +\r
120  \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
125 --- a/configure\r
126 +++ b/configure\r
127 @@ -376,6 +376,10 @@ if [ -z "${EMACSETCDIR}" ]; then\r
128      fi\r
129  fi\r
130  \r
131 +if [ -z "${INFODIR}" ]; then\r
132 +    INFODIR='$(prefix)/share/info'\r
133 +fi\r
134 +\r
135  printf "Checking if emacs is available... "\r
136  if emacs --quick --batch > /dev/null 2>&1; then\r
137      printf "Yes.\n"\r
138 @@ -385,6 +389,24 @@ else\r
139      have_emacs=0\r
140  fi\r
141  \r
142 +printf "Checking for makeinfo... "\r
143 +if makeinfo --version > /dev/null 2>&1; then\r
144 +    printf "Yes.\n"\r
145 +    have_makeinfo=1\r
146 +else\r
147 +    printf "No (so will not info docs)\n"\r
148 +    have_makeinfo=0\r
149 +fi\r
150 +\r
151 +printf "Checking for install-info... "\r
152 +if install-info --version > /dev/null 2>&1; then\r
153 +    printf "Yes.\n"\r
154 +    have_installinfo=1\r
155 +else\r
156 +    printf "No (so will not install info docs)\n"\r
157 +    have_installinfo=0\r
158 +fi\r
159 +\r
160  libdir_in_ldconfig=0\r
161  \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
166  \r
167 +# Whether there's a makeinfo binary available to build info docs\r
168 +HAVE_MAKEINFO = ${have_makeinfo}\r
169 +\r
170 +# Whether there's an install-info binary available\r
171 +HAVE_INSTALLINFO = ${have_installinfo}\r
172 +\r
173 +# where to install info files\r
174 +\r
175 +INFODIR = ${INFODIR}\r
176 +\r
177  # The directory to which desktop files should be installed\r
178  desktop_dir = \$(prefix)/share/applications\r
179  \r
180 diff --git a/info/Makefile b/info/Makefile\r
181 new file mode 100644\r
182 index 0000000..de492a7\r
183 --- /dev/null\r
184 +++ b/info/Makefile\r
185 @@ -0,0 +1,7 @@\r
186 +# See Makefile.local for the list of files to be compiled in this\r
187 +# directory.\r
188 +all:\r
189 +       $(MAKE) -C .. all\r
190 +\r
191 +.DEFAULT:\r
192 +       $(MAKE) -C .. $@\r
193 diff --git a/info/Makefile.local b/info/Makefile.local\r
194 new file mode 100644\r
195 index 0000000..55e9740\r
196 --- /dev/null\r
197 +++ b/info/Makefile.local\r
198 @@ -0,0 +1,33 @@\r
199 +# -*- makefile -*-\r
200 +\r
201 +dir := info\r
202 +\r
203 +texi_sources :=  $(dir)/notmuch-emacs.texi\r
204 +emacs_info := $(texi_sources:.texi=.info)\r
205 +\r
206 +info := $(emacs_info)\r
207 +\r
208 +ifeq ($(HAVE_MAKEINFO),1)\r
209 +all: $(info)\r
210 +endif\r
211 +\r
212 +ifeq ($(HAVE_INSTALLINFO),1)\r
213 +install: install-info\r
214 +endif\r
215 +\r
216 +%.info: %.texi\r
217 +       makeinfo --no-split -o $@ $<\r
218 +\r
219 +$(dir)/notmuch-emacs.info: $(dir)/notmuch-emacs.texi $(dir)/version.texi\r
220 +\r
221 +.PHONY: $(dir)/version.texi\r
222 +$(dir)/version.texi: version\r
223 +       printf "@set VERSION ${VERSION}\n" > $@\r
224 +\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
230 +\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..e19d0ea\r
235 --- /dev/null\r
236 +++ b/info/notmuch-emacs.texi\r
237 @@ -0,0 +1,324 @@\r
238 +\input texinfo   @c -*-texinfo-*-\r
239 +@comment $Id@w{$}\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
245 +\r
246 +@macro keyindex {NAME}\r
247 +@kindex \NAME\\r
248 +@cindex \NAME\\r
249 +@end macro\r
250 +\r
251 +@macro funindex {NAME}\r
252 +@findex \NAME\\r
253 +@cindex \NAME\\r
254 +@end macro\r
255 +\r
256 +@macro varindex {NAME}\r
257 +@vindex \NAME\\r
258 +@cindex \NAME\\r
259 +@end macro\r
260 +\r
261 +\r
262 +@copying\r
263 +This manual is for Notmuch (version @value{VERSION})\r
264 +\r
265 +Copyright @copyright{} 2013 David Bremner\r
266 +\r
267 +This manual is distributed under the same terms as notmuch, which are as follows.\r
268 +@quotation\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
273 +\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
278 +\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
281 +\r
282 +@end quotation\r
283 +@end copying\r
284 +\r
285 +@dircategory Notmuch\r
286 +@direntry\r
287 +* notmuch-emacs: (notmuch-emacs).  Emacs interface to notmuch\r
288 +@end direntry\r
289 +\r
290 +@titlepage\r
291 +@title Notmuch\r
292 +@subtitle for version @value{VERSION}\r
293 +@author David Bremner (@email{david@@tethera.net})\r
294 +@page\r
295 +@vskip 0pt plus 1filll\r
296 +@insertcopying\r
297 +@end titlepage\r
298 +\r
299 +@contents\r
300 +\r
301 +@ifnottex\r
302 +@node Top\r
303 +@top Notmuch\r
304 +\r
305 +This manual is for Notmuch (version @value{VERSION}).\r
306 +@end ifnottex\r
307 +\r
308 +@menu\r
309 +* About this Manual::\r
310 +* notmuch-hello::\r
311 +* notmuch-search::\r
312 +* notmuch-show::\r
313 +* notmuch-tree::\r
314 +* Configuration::\r
315 +* Function Index::\r
316 +* Variable Index::\r
317 +* Index::\r
318 +@end menu\r
319 +\r
320 +\r
321 +@node About this Manual\r
322 +@unnumbered About this Manual\r
323 +\r
324 +This manual covers only the emacs interface to notmuch. For\r
325 +information on the command line interface, see\r
326 +@xref{top,the notmuch man page,Description,notmuch,Notmuch Manual Pager}.\r
327 +To save\r
328 +typing, we will sometimes use @emph{notmuch} in this manual to refer\r
329 +to the Emacs interface to notmuch. If the distinction should every be\r
330 +important, we'll refer to the Emacs inteface as @emph{notmuch-emacs}.\r
331 +\r
332 +Notmuch-emacs is highly customizable via the the Emacs customization\r
333 +framework (or just by setting the appropriate variables).  We try to\r
334 +point out relevant variables in this manual, but in order to avoid\r
335 +duplication of information, but you can usually find the most detailed\r
336 +description in the varables docstring.\r
337 +\r
338 +@node notmuch-hello\r
339 +@chapter notmuch-hello\r
340 +\r
341 +@funindex notmuch-hello\r
342 +@funindex notmuch\r
343 +\r
344 +@command{notmuch-hello} is the main entry point for notmuch. You can\r
345 +start it with @kbd{M-x notmuch} or @kbd{M-x notmuch-hello}. The\r
346 +startup screen looks something like the following. There are some\r
347 +hints at the bottom of the screen.  There are three main parts to the\r
348 +notmuch-hello screen, discussed below. The @strong{bold} text\r
349 +indicates buttons you can click with a mouse or by positioning the\r
350 +cursor and pressing @kbd{<return>}\r
351 +\r
352 +@example\r
353 +@group\r
354 +----------------------------------------------------------------------------\r
355 +\r
356 +   Welcome to @strong{notmuch}. You have 52 messages.\r
357 +\r
358 +Saved searches: @strong{[edit]}\r
359 +\r
360 +         52 @strong{inbox}           52 @strong{unread}\r
361 +\r
362 +Search:                                                                     .\r
363 +\r
364 +All tags: @strong{[show]}\r
365 +\r
366 +        Type a search query and hit RET to view matching threads.\r
367 +               Edit saved searches with the `edit' button.\r
368 +  Hit RET or click on a saved search or tag name to view matching threads.\r
369 +      `=' to refresh this screen. `s' to search messages. `q' to quit.\r
370 +                   @strong{Customize} this page.\r
371 +\r
372 +----------------------------------------------------------------------------\r
373 +@end group\r
374 +@end example\r
375 +\r
376 +You can change the overall appearence of the notmuch-hello screen by\r
377 +customizing the variable @var{notmuch-hello-sections}.\r
378 +@varindex{notmuch-hellow-sections}\r
379 +\r
380 +@menu\r
381 +* notmuch-hello Key Bindings::\r
382 +* Saved Searches::\r
383 +* Search Box::\r
384 +* Known Tags::\r
385 +@end menu\r
386 +\r
387 +@node notmuch-hello Key Bindings\r
388 +@section notmuch-hello key bindings\r
389 +\r
390 +@table @kbd\r
391 +\r
392 +@item <tab>\r
393 +      Move to the next widget (button or text entry field)\r
394 +@item <backtab>\r
395 +      Move to the previous widget.\r
396 +@item <return>\r
397 +      Activate the current widget.\r
398 +@item =\r
399 +Refresh the buffer; mainly update the counts of messages for various\r
400 +saved searches.\r
401 +@item G\r
402 +      Import mail, @xref{Importing Mail}.\r
403 +@item m\r
404 +      Compose a message\r
405 +@item s\r
406 +Search the notmuch database, @xref{notmuch-search}.\r
407 +@item v\r
408 +      Print notmuch version\r
409 +@item q\r
410 +Quit\r
411 +@end table\r
412 +\r
413 +\r
414 +@node Saved Searches\r
415 +@section Saved Searches\r
416 +@cindex Saved Searches\r
417 +\r
418 +@varindex notmuch-saved-searches\r
419 +@varindex notmuch-saved-search-sort-function\r
420 +@varindex notmuch-column-control\r
421 +\r
422 +Notmuch replaces the static assignment of messages with the more\r
423 +dynamic notion of searching.\r
424 +Notmuch-hello presents the user with a customizable set of saved\r
425 +searchs. The initial defaults are @code{tag:inbox} and\r
426 +@code{tag:unread}, but you can customize the following variables\r
427 +\r
428 +\r
429 +@table @var\r
430 +@item notmuch-saved-searches\r
431 +A list of cons pairs, the first being the name to display, the second\r
432 +being a query string for notmuch. @xref{top,Notmuch Query\r
433 +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}.\r
434 +\r
435 +@item notmuch-saved-searches-sort-function\r
436 +   This variable controls how saved searches should be sorted. A value\r
437 +   of @code{nil} displays the saved searches in the order they are\r
438 +   stored in `notmuch-saved-searches'.\r
439 +@item notmuch-column-control\r
440 +      Controls the number of columns for displaying saved-searches/tags\r
441 +@end table\r
442 +\r
443 +@node Search Box\r
444 +@section Search Box\r
445 +@cindex Search Box\r
446 +\r
447 +@varindex notmuch-hello-recent-searches-max\r
448 +The search box lets the user enter an notmuch query. @xref{top,Notmuch\r
449 +Query Syntax,Description,notmuch-search-terms,Notmuch Query Syntax},\r
450 +for more info on notmuch query syntax. A history of recent searches is\r
451 +also displayed by default.  The latter is controlled by the variable\r
452 +@var{notmuch-hello-recent-searches-max}.\r
453 +\r
454 +@node Known Tags\r
455 +@section Know Tags\r
456 +@cindex Known Tags\r
457 +@varindex notmuch-hello-tag-list-make-query\r
458 +@varindex notmuch-hello-hide-tags\r
459 +@varindex notmuch-column-control\r
460 +\r
461 +One special kind of saved search provided by default is for each\r
462 +individual tag defined in the database. This can be controlled via the\r
463 +following variables.\r
464 +\r
465 +@table @var\r
466 +@item notmuch-hello-tag-list-make-query\r
467 +      Control how to construct a search (``virtual folder'') from a given tag.\r
468 +@item notmuch-hello-hide-tags\r
469 +      Which tags not to display at all.\r
470 +@item notmuch-column-control\r
471 +      Controls the number of columns for displaying saved-searches/tags\r
472 +@end table\r
473 +\r
474 +\r
475 +@node notmuch-search\r
476 +@chapter notmuch-search\r
477 +\r
478 +@menu\r
479 +* notmuch-search Key Bindings::\r
480 +* notmuch-search Customization::\r
481 +@end menu\r
482 +\r
483 +@funindex notmuch-search-mode\r
484 +@funindex notmuch-search\r
485 +\r
486 +@command{notmuch-search-mode} is used to display the results from\r
487 +executing a query via @command{notmuch-search}. The syntax for these\r
488 +queries is the the same as for @xref{Saved Searches}, namely\r
489 +@xref{top,Notmuch Query\r
490 +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}.\r
491 +\r
492 +By default the output approximates that of the command line\r
493 +@xref{top,notmuch search command,Description,notmuch-search,notmuch search command}.\r
494 +\r
495 +The main purpose of the @command{notmuch-search-mode} buffer is to act\r
496 +as a menu of results that the user can explore further by pressing\r
497 +@kbd{<return>} on the appropriate line.\r
498 +\r
499 +@node notmuch-search Key Bindings\r
500 +@table @kbd\r
501 +@item n,C-n,<down>\r
502 +      Move to next line\r
503 +@item p,C-p,<up>\r
504 +      Move to previous line\r
505 +@item <return>\r
506 +      Open thread on current line in @xref{notmuch-show}\r
507 +@item ?\r
508 +      Display full set of key bindings\r
509 +@end table\r
510 +\r
511 +@node notmuch-search Customization\r
512 +\r
513 +@varindex notmuch-search-result-format\r
514 +@varindex notmuch-search-oldest-first\r
515 +\r
516 +The presentation of results can be controlled by the following variables.\r
517 +@table @var\r
518 +@item notmuch-search-result-format\r
519 +      Control how each thread of messages is presented in the\r
520 +      @command{notmuch-show-mode} buffer\r
521 +@item notmuch-search-oldest-first\r
522 +      Display the oldest threads at the top of the buffer\r
523 +@end table\r
524 +\r
525 +@node notmuch-show\r
526 +@chapter notmuch-show\r
527 +\r
528 +@node notmuch-tree\r
529 +@chapter notmuch-tree\r
530 +\r
531 +@node Configuration\r
532 +@chapter Configuration\r
533 +\r
534 +\r
535 +@menu\r
536 +* Importing Mail::\r
537 +@end menu\r
538 +\r
539 +@node Importing Mail\r
540 +@section Importing Mail\r
541 +\r
542 +@funindex notmuch-poll\r
543 +@vindex notmuch-poll-script\r
544 +\r
545 +@node Function Index\r
546 +@unnumbered Function Index\r
547 +\r
548 +@printindex fn\r
549 +\r
550 +@node Variable Index\r
551 +@unnumbered Variable Index\r
552 +\r
553 +@printindex vr\r
554 +\r
555 +@node Index\r
556 +@unnumbered Index\r
557 +\r
558 +@printindex cp\r
559 +\r
560 +\r
561 +@bye\r
562 -- \r
563 1.8.5.2\r
564 \r