61/57510aa888dad12ae8c42aa7b4c8700801f051

   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
   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 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
  26         11:39:21 -0000\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
  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: Sun, 05 Jan 2014 11:39:37 -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 | 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
  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..434a360\r
 235 --- /dev/null\r
 236 +++ b/info/notmuch-emacs.texi\r
 237 @@ -0,0 +1,270 @@\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 +* Configuration::\r
 313 +* Function Index::\r
 314 +* Variable Index::\r
 315 +* Index::\r
 316 +@end menu\r
 317 +\r
 318 +\r
 319 +@node About this Manual\r
 320 +@unnumbered About this Manual\r
 321 +\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
 325 +To save\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
 329 +\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
 335 +\r
 336 +@node notmuch-hello\r
 337 +@chapter notmuch-hello\r
 338 +\r
 339 +@funindex notmuch-hello\r
 340 +@funindex notmuch\r
 341 +\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
 349 +\r
 350 +@example\r
 351 +@group\r
 352 +----------------------------------------------------------------------------\r
 353 +\r
 354 +   Welcome to @strong{notmuch}. You have 52 messages.\r
 355 +\r
 356 +Saved searches: @strong{[edit]}\r
 357 +\r
 358 +         52 @strong{inbox}           52 @strong{unread}\r
 359 +\r
 360 +Search:                                                                     .\r
 361 +\r
 362 +All tags: @strong{[show]}\r
 363 +\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
 369 +\r
 370 +----------------------------------------------------------------------------\r
 371 +@end group\r
 372 +@end example\r
 373 +\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
 377 +\r
 378 +@menu\r
 379 +* notemuch-hello Key Bindings::\r
 380 +* Saved Searches::\r
 381 +* Search Box::\r
 382 +* Known Tags::\r
 383 +@end menu\r
 384 +\r
 385 +@node notemuch-hello Key Bindings\r
 386 +@section notmuch-hello key bindings\r
 387 +\r
 388 +@table @kbd\r
 389 +\r
 390 +@item <tab>\r
 391 +      Move to the next widget (button or text entry field)\r
 392 +@item <backtab>\r
 393 +      Move to the previous widget.\r
 394 +@item <return>\r
 395 +      Activate the current widget.\r
 396 +@item =\r
 397 +Refresh the buffer; mainly update the counts of messages for various\r
 398 +saved searches.\r
 399 +@item G\r
 400 +      Import mail, @xref{Importing Mail}.\r
 401 +@item m\r
 402 +      Compose a message\r
 403 +@item s\r
 404 +Search the notmuch database, @xref{notmuch-search}.\r
 405 +@item v\r
 406 +      Print notmuch version\r
 407 +@item q\r
 408 +Quit\r
 409 +@end table\r
 410 +\r
 411 +\r
 412 +@node Saved Searches\r
 413 +@section Saved Searches\r
 414 +@cindex Saved Searches\r
 415 +\r
 416 +@varindex notmuch-saved-searches\r
 417 +@varindex notmuch-saved-search-sort-function\r
 418 +@varindex notmuch-column-control\r
 419 +\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
 425 +\r
 426 +\r
 427 +@table @var\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
 432 +\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
 439 +@end table\r
 440 +\r
 441 +@node Search Box\r
 442 +@section Search Box\r
 443 +@cindex Search Box\r
 444 +\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
 451 +\r
 452 +@node Known Tags\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
 458 +\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
 462 +\r
 463 +@table @var\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
 470 +@end table\r
 471 +\r
 472 +\r
 473 +@node notmuch-search\r
 474 +@chapter notmuch-search\r
 475 +\r
 476 +\r
 477 +@node Configuration\r
 478 +@chapter Configuration\r
 479 +\r
 480 +\r
 481 +@menu\r
 482 +* Importing Mail::\r
 483 +@end menu\r
 484 +\r
 485 +@node Importing Mail\r
 486 +@section Importing Mail\r
 487 +\r
 488 +@funindex notmuch-poll\r
 489 +@vindex notmuch-poll-script\r
 490 +\r
 491 +@node Function Index\r
 492 +@unnumbered Function Index\r
 493 +\r
 494 +@printindex fn\r
 495 +\r
 496 +@node Variable Index\r
 497 +@unnumbered Variable Index\r
 498 +\r
 499 +@printindex vr\r
 500 +\r
 501 +@node Index\r
 502 +@unnumbered Index\r
 503 +\r
 504 +@printindex cp\r
 505 +\r
 506 +\r
 507 +@bye\r
 508 -- \r
 509 1.8.5.2\r
 510 \r