[Patch v3 1/3] info: start info documentation.
David Bremner
david at tethera.net
Wed Jan 15 05:08:50 PST 2014
From: David Bremner <bremner at debian.org>
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-*-
+ at comment $Id at w{$}
+ at comment %**start of header
+ at setfilename notmuch-emacs.info
+ at include version.texi
+ at settitle Notmuch @value{VERSION}
+ at comment %**end of header
+
+ at macro keyindex {NAME}
+ at kindex \NAME\
+ at cindex \NAME\
+ at end macro
+
+ at macro funindex {NAME}
+ at findex \NAME\
+ at cindex \NAME\
+ at end macro
+
+ at macro varindex {NAME}
+ at vindex \NAME\
+ at cindex \NAME\
+ at end macro
+
+
+ at 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.
+ at 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/ .
+
+ at end quotation
+ at end copying
+
+ at dircategory Notmuch
+ at direntry
+* notmuch-emacs: (notmuch-emacs). Emacs interface to notmuch
+ at end direntry
+
+ at titlepage
+ at title Notmuch
+ at subtitle for version @value{VERSION}
+ at author David Bremner (@email{david@@tethera.net})
+ at page
+ at vskip 0pt plus 1filll
+ at insertcopying
+ at end titlepage
+
+ at contents
+
+ at ifnottex
+ at node Top
+ at top Notmuch
+
+This manual is for Notmuch (version @value{VERSION}).
+ at end ifnottex
+
+ at menu
+* About this Manual::
+* notmuch-hello::
+* notmuch-search::
+* notmuch-show::
+* notmuch-tree::
+* Configuration::
+* Function Index::
+* Variable Index::
+* Index::
+ at end menu
+
+
+ at node About this Manual
+ at unnumbered About this Manual
+
+This manual covers only the emacs interface to notmuch. For
+information on the command line interface, see
+ at 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.
+
+ at node notmuch-hello
+ at chapter notmuch-hello
+
+ at funindex notmuch-hello
+ at funindex notmuch
+
+ at 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{<return>}
+
+ at example
+ at 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.
+
+----------------------------------------------------------------------------
+ at end group
+ at end example
+
+You can change the overall appearence of the notmuch-hello screen by
+customizing the variable @var{notmuch-hello-sections}.
+ at varindex{notmuch-hellow-sections}
+
+ at menu
+* notmuch-hello Key Bindings::
+* Saved Searches::
+* Search Box::
+* Known Tags::
+ at end menu
+
+ at node notmuch-hello Key Bindings
+ at section notmuch-hello key bindings
+
+ at table @kbd
+
+ at item <tab>
+ Move to the next widget (button or text entry field)
+ at item <backtab>
+ Move to the previous widget.
+ at item <return>
+ Activate the current widget.
+ at item =
+Refresh the buffer; mainly update the counts of messages for various
+saved searches.
+ at item G
+ Import mail, @xref{Importing Mail}.
+ at item m
+ Compose a message
+ at item s
+Search the notmuch database, @xref{notmuch-search}.
+ at item v
+ Print notmuch version
+ at item q
+Quit
+ at end table
+
+
+ at node Saved Searches
+ at section Saved Searches
+ at cindex Saved Searches
+
+ at varindex notmuch-saved-searches
+ at varindex notmuch-saved-search-sort-function
+ at 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
+ at code{tag:unread}, but you can customize the following variables
+
+
+ at table @var
+ at 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}.
+
+ at 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'.
+ at item notmuch-column-control
+ Controls the number of columns for displaying saved-searches/tags
+ at end table
+
+ at node Search Box
+ at section Search Box
+ at cindex Search Box
+
+ at 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
+ at var{notmuch-hello-recent-searches-max}.
+
+ at node Known Tags
+ at section Know Tags
+ at cindex Known Tags
+ at varindex notmuch-hello-tag-list-make-query
+ at varindex notmuch-hello-hide-tags
+ at 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.
+
+ at table @var
+ at item notmuch-hello-tag-list-make-query
+ Control how to construct a search (``virtual folder'') from a given tag.
+ at item notmuch-hello-hide-tags
+ Which tags not to display at all.
+ at item notmuch-column-control
+ Controls the number of columns for displaying saved-searches/tags
+ at end table
+
+
+ at node notmuch-search
+ at chapter notmuch-search
+
+ at menu
+* notmuch-search Key Bindings::
+* notmuch-search Customization::
+ at end menu
+
+ at funindex notmuch-search-mode
+ at funindex notmuch-search
+
+ at 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
+ at xref{top,Notmuch Query
+Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}.
+
+By default the output approximates that of the command line
+ at 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
+ at kbd{<return>} on the appropriate line.
+
+ at node notmuch-search Key Bindings
+ at table @kbd
+ at item n,C-n,<down>
+ Move to next line
+ at item p,C-p,<up>
+ Move to previous line
+ at item <return>
+ Open thread on current line in @xref{notmuch-show}
+ at item ?
+ Display full set of key bindings
+ at end table
+
+ at node notmuch-search Customization
+
+ at varindex notmuch-search-result-format
+ at varindex notmuch-search-oldest-first
+
+The presentation of results can be controlled by the following variables.
+ at table @var
+ at item notmuch-search-result-format
+ Control how each thread of messages is presented in the
+ @command{notmuch-show-mode} buffer
+ at item notmuch-search-oldest-first
+ Display the oldest threads at the top of the buffer
+ at end table
+
+ at node notmuch-show
+ at chapter notmuch-show
+
+ at node notmuch-tree
+ at chapter notmuch-tree
+
+ at node Configuration
+ at chapter Configuration
+
+
+ at menu
+* Importing Mail::
+ at end menu
+
+ at node Importing Mail
+ at section Importing Mail
+
+ at funindex notmuch-poll
+ at vindex notmuch-poll-script
+
+ at node Function Index
+ at unnumbered Function Index
+
+ at printindex fn
+
+ at node Variable Index
+ at unnumbered Variable Index
+
+ at printindex vr
+
+ at node Index
+ at unnumbered Index
+
+ at printindex cp
+
+
+ at bye
--
1.8.5.2
More information about the notmuch
mailing list