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 15D41429E4F for ; Wed, 15 Jan 2014 05:09:24 -0800 (PST) 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 x4BzbKnnJGNW for ; Wed, 15 Jan 2014 05:09:16 -0800 (PST) Received: from yantan.tethera.net (yantan.tethera.net [199.188.72.155]) (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits)) (No client certificate requested) by olra.theworths.org (Postfix) with ESMTPS id F030E431FBD for ; Wed, 15 Jan 2014 05:09:13 -0800 (PST) Received: from remotemail by yantan.tethera.net with local (Exim 4.80) (envelope-from ) id 1W3QDZ-0005Ug-Gq; Wed, 15 Jan 2014 09:09:13 -0400 Received: (nullmailer pid 21892 invoked by uid 1000); Wed, 15 Jan 2014 13:08:58 -0000 From: David Bremner To: notmuch@notmuchmail.org Subject: [Patch v3 1/3] info: start info documentation. Date: Wed, 15 Jan 2014 09:08:50 -0400 Message-Id: <1389791332-21719-2-git-send-email-david@tethera.net> X-Mailer: git-send-email 1.8.5.2 In-Reply-To: <1389791332-21719-1-git-send-email-david@tethera.net> References: <1389791332-21719-1-git-send-email-david@tethera.net> 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: Wed, 15 Jan 2014 13:09:24 -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 | 10 +- configure | 32 +++++ info/Makefile | 7 ++ info/Makefile.local | 33 +++++ info/notmuch-emacs.texi | 324 ++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 412 insertions(+), 6 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 0428160..250fbaa 100644 --- a/Makefile +++ b/Makefile @@ -2,10 +2,12 @@ # given explicitly on the command line) so mention it first. all: -# List all subdirectories here. Each contains its own Makefile.local. -# Use of '=', without '+=', seems to be required for out-of-tree -# builds to work. -subdirs = compat completion emacs lib man parse-time-string performance-test util test +# List all subdirectories here. Each contains its own Makefile.local +subdirs := compat completion emacs lib man parse-time-string +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 13b6062..e75c1d4 100755 --- a/configure +++ b/configure @@ -376,6 +376,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" @@ -385,6 +389,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... " @@ -740,6 +762,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..e19d0ea --- /dev/null +++ b/info/notmuch-emacs.texi @@ -0,0 +1,324 @@ +\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:: +* notmuch-show:: +* notmuch-tree:: +* 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 +* notmuch-hello Key Bindings:: +* Saved Searches:: +* Search Box:: +* Known Tags:: +@end menu + +@node notmuch-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 + +@menu +* notmuch-search Key Bindings:: +* notmuch-search Customization:: +@end menu + +@funindex notmuch-search-mode +@funindex notmuch-search + +@command{notmuch-search-mode} is used to display the results from +executing a query via @command{notmuch-search}. The syntax for these +queries is the the same as for @xref{Saved Searches}, namely +@xref{top,Notmuch Query +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}. + +By default the output approximates that of the command line +@xref{top,notmuch search command,Description,notmuch-search,notmuch search command}. + +The main purpose of the @command{notmuch-search-mode} buffer is to act +as a menu of results that the user can explore further by pressing +@kbd{} on the appropriate line. + +@node notmuch-search Key Bindings +@table @kbd +@item n,C-n, + Move to next line +@item p,C-p, + Move to previous line +@item + Open thread on current line in @xref{notmuch-show} +@item ? + Display full set of key bindings +@end table + +@node notmuch-search Customization + +@varindex notmuch-search-result-format +@varindex notmuch-search-oldest-first + +The presentation of results can be controlled by the following variables. +@table @var +@item notmuch-search-result-format + Control how each thread of messages is presented in the + @command{notmuch-show-mode} buffer +@item notmuch-search-oldest-first + Display the oldest threads at the top of the buffer +@end table + +@node notmuch-show +@chapter notmuch-show + +@node notmuch-tree +@chapter notmuch-tree + +@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.5.2