From: david Date: Thu, 25 Apr 2013 01:19:10 +0000 (+2100) Subject: [RFC Patch v2 1/3] info: start info documentation. X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=cfff7575a125b6c55013958ed51ca25a99ce8227;p=notmuch-archives.git [RFC Patch v2 1/3] info: start info documentation. --- diff --git a/79/1f8276ffdf22ed2758d499767f7827f34417af b/79/1f8276ffdf22ed2758d499767f7827f34417af new file mode 100644 index 000000000..d633fe91e --- /dev/null +++ b/79/1f8276ffdf22ed2758d499767f7827f34417af @@ -0,0 +1,510 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +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 +