On Wed, 15 Jan 2014, David Bremner <david at tethera.net> wrote: > 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.
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-*- > + 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 > > _______________________________________________ > notmuch mailing list > notmuch at notmuchmail.org > http://notmuchmail.org/mailman/listinfo/notmuch