From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by olra.theworths.org (Postfix) with ESMTP id 43774431FC2 for ; Wed, 24 Apr 2013 18:19:50 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: 0 X-Spam-Level: X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none] autolearn=disabled Received: from olra.theworths.org ([127.0.0.1]) by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id z1GeSw7R98zf for ; Wed, 24 Apr 2013 18:19:48 -0700 (PDT) Received: from tesseract.cs.unb.ca (tesseract.cs.unb.ca [131.202.240.238]) (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits)) (No client certificate requested) by olra.theworths.org (Postfix) with ESMTPS id EF725431FAF for ; Wed, 24 Apr 2013 18:19:47 -0700 (PDT) Received: from fctnnbsc30w-156034082078.dhcp-dynamic.fibreop.nb.bellaliant.net ([156.34.82.78] helo=zancas.localnet) by tesseract.cs.unb.ca with esmtpsa (TLS1.2:DHE_RSA_AES_128_CBC_SHA1:128) (Exim 4.80) (envelope-from ) id 1UVAqd-0002Tw-35; Wed, 24 Apr 2013 22:19:47 -0300 Received: from bremner by zancas.localnet with local (Exim 4.80) (envelope-from ) id 1UVAqX-00013z-Fi; Wed, 24 Apr 2013 22:19:37 -0300 From: david@tethera.net To: notmuch@notmuchmail.org Subject: [RFC Patch v2 1/3] info: start info documentation. Date: Wed, 24 Apr 2013 22:19:10 -0300 Message-Id: <1366852752-3584-2-git-send-email-david@tethera.net> X-Mailer: git-send-email 1.8.2.rc2 In-Reply-To: <1366852752-3584-1-git-send-email-david@tethera.net> References: <1362882151-14030-1-git-send-email-david@tethera.net> <1366852752-3584-1-git-send-email-david@tethera.net> X-Spam_bar: - Cc: David Bremner X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 25 Apr 2013 01:19:50 -0000 From: David Bremner 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{} + +@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 + Move to the next widget (button or text entry field) +@item + Move to the previous widget. +@item + 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