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 16049431FBC for ; Fri, 17 Jan 2014 08:12:42 -0800 (PST) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: -0.7 X-Spam-Level: X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5 tests=[RCVD_IN_DNSWL_LOW=-0.7] 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 KKyR3rYIGld9 for ; Fri, 17 Jan 2014 08:12:34 -0800 (PST) Received: from mail-ee0-f45.google.com (mail-ee0-f45.google.com [74.125.83.45]) (using TLSv1 with cipher RC4-SHA (128/128 bits)) (No client certificate requested) by olra.theworths.org (Postfix) with ESMTPS id 50875431FB6 for ; Fri, 17 Jan 2014 08:12:34 -0800 (PST) Received: by mail-ee0-f45.google.com with SMTP id b15so2153433eek.4 for ; Fri, 17 Jan 2014 08:12:33 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:in-reply-to:references :user-agent:date:message-id:mime-version:content-type; bh=HbFbb0ElwUCwgCyPkuf8PV/VcyetMI/rULzvuL6e+QU=; b=e9eZM6sGxuvKJ7FYI14NpXRCQbtiR3mXbv0xJCUdEBy4jG24ItDlunN8CiIjgtwx9k muvWvSGNlx7LhV+KVh6bgYVWDz40KuZWRxyfG4oJrTUGzaoDIs+SmX7vcwVt4YWuWHxE 61V7sHfmSOoNmTv+efOqSRuulwT7ftJg2d8FoLSA9q+1EhMwiMq4YiAiPAk+6Qrq9xh4 G0P2txWG39Hl+qV89k2Xe7sMpgm+gd4bD+wDYdMZmflhb5HEMvd0UvGG4fma2abKEYB0 lcK7uciubIQSsDDTxy+LIaPRTgui73bTLtBOfS4dPjGgeIiMJKjACllAGAdFMYhbT8Yp 8+XA== X-Gm-Message-State: ALoCoQnYc25zjKrh6uDvRmSa0kRD7jOgdINMaNC9hittJXIFBBxenBNy9UPXV0L1LbRiVunNrP/T X-Received: by 10.15.56.132 with SMTP id y4mr3393213eew.61.1389975153157; Fri, 17 Jan 2014 08:12:33 -0800 (PST) Received: from localhost (dsl-hkibrasgw2-58c36f-91.dhcp.inet.fi. [88.195.111.91]) by mx.google.com with ESMTPSA id 7sm28033283eee.12.2014.01.17.08.12.31 for (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Fri, 17 Jan 2014 08:12:32 -0800 (PST) From: Jani Nikula To: David Bremner , notmuch@notmuchmail.org Subject: Re: [Patch v3 1/3] info: start info documentation. In-Reply-To: <1389791332-21719-2-git-send-email-david@tethera.net> References: <1389791332-21719-1-git-send-email-david@tethera.net> <1389791332-21719-2-git-send-email-david@tethera.net> User-Agent: Notmuch/0.17~rc2+18~g39a67a6 (http://notmuchmail.org) Emacs/24.3.1 (x86_64-pc-linux-gnu) Date: Fri, 17 Jan 2014 18:12:30 +0200 Message-ID: <87iotir3ip.fsf@nikula.org> MIME-Version: 1.0 Content-Type: text/plain 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: Fri, 17 Jan 2014 16:12:42 -0000 On Wed, 15 Jan 2014, David Bremner wrote: > 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. Is it possible to add a link to the info page from notmuch-hello? Jani. > > 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 > > _______________________________________________ > notmuch mailing list > notmuch@notmuchmail.org > http://notmuchmail.org/mailman/listinfo/notmuch