From: Jani Nikula <jani@nikula.org>
To: David Bremner <david@tethera.net>, notmuch@notmuchmail.org
Subject: Re: [Patch v3 1/3] info: start info documentation.
In-Reply-To: <1389791332-21719-2-git-send-email-david@tethera.net>
References: <m2bnzeoiij.fsf@guru.guru-group.fi>
	<1389791332-21719-1-git-send-email-david@tethera.net>
	<1389791332-21719-2-git-send-email-david@tethera.net>
User-Agent: Notmuch/0.17~rc2+18~g39a67a6 (http://notmuchmail.org) Emacs/24.3.1
	(x86_64-pc-linux-gnu)
Date: Fri, 17 Jan 2014 18:12:30 +0200
Message-ID: <87iotir3ip.fsf@nikula.org>
MIME-Version: 1.0
Content-Type: text/plain
Cc: David Bremner <bremner@debian.org>
Precedence: list

On Wed, 15 Jan 2014, David Bremner <david@tethera.net> wrote:
> 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.

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-*-
> +@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::
> +* notmuch-show::
> +* notmuch-tree::
> +* 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
> +* notmuch-hello Key Bindings::
> +* Saved Searches::
> +* Search Box::
> +* Known Tags::
> +@end menu
> +
> +@node notmuch-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
> +
> +@menu
> +* notmuch-search Key Bindings::
> +* notmuch-search Customization::
> +@end menu
> +
> +@funindex notmuch-search-mode
> +@funindex notmuch-search
> +
> +@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
> +@xref{top,Notmuch Query
> +Syntax,Description,notmuch-search-terms,Notmuch Query Syntax}.
> +
> +By default the output approximates that of the command line
> +@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
> +@kbd{<return>} on the appropriate line.
> +
> +@node notmuch-search Key Bindings
> +@table @kbd
> +@item n,C-n,<down>
> +      Move to next line
> +@item p,C-p,<up>
> +      Move to previous line
> +@item <return>
> +      Open thread on current line in @xref{notmuch-show}
> +@item ?
> +      Display full set of key bindings
> +@end table
> +
> +@node notmuch-search Customization
> +
> +@varindex notmuch-search-result-format
> +@varindex notmuch-search-oldest-first
> +
> +The presentation of results can be controlled by the following variables.
> +@table @var
> +@item notmuch-search-result-format
> +      Control how each thread of messages is presented in the
> +      @command{notmuch-show-mode} buffer
> +@item notmuch-search-oldest-first
> +      Display the oldest threads at the top of the buffer
> +@end table
> +
> +@node notmuch-show
> +@chapter notmuch-show
> +
> +@node notmuch-tree
> +@chapter notmuch-tree
> +
> +@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
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch