From: David Bremner <david@tethera.net>
To: notmuch@notmuchmail.org
Subject: [PATCH 1/3] info: start info documentation.
Date: Sun,  5 Jan 2014 07:39:08 -0400
Message-Id: <1388921950-5017-2-git-send-email-david@tethera.net>
In-Reply-To: <1388921950-5017-1-git-send-email-david@tethera.net>
References: <1366852752-3584-1-git-send-email-david@tethera.net>
	<1388921950-5017-1-git-send-email-david@tethera.net>
Cc: David Bremner <bremner@debian.org>
Precedence: list

From: David Bremner <bremner@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 | 270 ++++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 358 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..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{<return>}
+
+@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 <tab>
+      Move to the next widget (button or text entry field)
+@item <backtab>
+      Move to the previous widget.
+@item <return>
+      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.5.2