[Patch v3 1/3] info: start info documentation.
Jani Nikula
jani at nikula.org
Fri Jan 17 08:12:30 PST 2014
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
More information about the notmuch
mailing list