From d2c9cde735ff46efb73bb10de16b651e2c090d17 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Fri, 17 Jan 2014 17:59:36 +0200 Subject: [PATCH] Re: [Patch v3 1/3] info: start info documentation. --- 2b/5f2261c0006ac15826c323ef883ec00ec29e17 | 604 ++++++++++++++++++++++ 1 file changed, 604 insertions(+) create mode 100644 2b/5f2261c0006ac15826c323ef883ec00ec29e17 diff --git a/2b/5f2261c0006ac15826c323ef883ec00ec29e17 b/2b/5f2261c0006ac15826c323ef883ec00ec29e17 new file mode 100644 index 000000000..285a1cf9a --- /dev/null +++ b/2b/5f2261c0006ac15826c323ef883ec00ec29e17 @@ -0,0 +1,604 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 194ED431FBC + for ; Fri, 17 Jan 2014 07:59:55 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: -0.7 +X-Spam-Level: +X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5 + tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled +Received: from olra.theworths.org ([127.0.0.1]) + by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id nZJlZFMq0zTQ for ; + Fri, 17 Jan 2014 07:59:44 -0800 (PST) +Received: from mail-ee0-f54.google.com (mail-ee0-f54.google.com + [74.125.83.54]) (using TLSv1 with cipher RC4-SHA (128/128 bits)) (No client + certificate requested) by olra.theworths.org (Postfix) with ESMTPS id + 32705431FB6 for ; Fri, 17 Jan 2014 07:59:44 -0800 + (PST) +Received: by mail-ee0-f54.google.com with SMTP id e53so1473295eek.13 + for ; Fri, 17 Jan 2014 07:59:41 -0800 (PST) +X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; + d=1e100.net; s=20130820; + h=x-gm-message-state:from:to:cc:subject:in-reply-to:references + :user-agent:date:message-id:mime-version:content-type; + bh=qqZuSOAo1PWKcRzhbTytvAhCsCVkHJDYePkHsf//gzY=; + b=GolbP+d6Vq47GRZThAjhsZ4sYeDSv6pYq2H1RfieRJJRelaxXijDl0ZuVBhSyO7zME + jNNuPJdwtu5pE1ug0y/xXnDhZbCATLZO6ABMbUi+f4/lg9SebbnWwJ+74KqWhXc0kDnC + Q58WAuJD3H5utu/akyXYpMPxMS4TgB+NFIueZ21j3UIoEZ8qaEKcXFgtKbTrZGxgdBRP + HKZehLJ4Nt/QYXltss5E30PXGmNk38OoyRbhkdafvIQkaxbZdj7WKRPiOl1VxesfvbeK + QGmuzjI6jiPciSBVU6fOCcg19vGV6ohw6rkaeuUo+qc783RYsnNf+Y/NUOjqTN5I+4sr + yd3w== +X-Gm-Message-State: + ALoCoQmZz/38usdiLeYsun/zJ8Ih0yb1jI+6gewo1McYuvqCrk92OrCl3EwBUf4MvYRO+0JyQ25C +X-Received: by 10.14.221.193 with SMTP id r41mr3385833eep.92.1389974380297; + Fri, 17 Jan 2014 07:59:40 -0800 (PST) +Received: from localhost (dsl-hkibrasgw2-58c36f-91.dhcp.inet.fi. + [88.195.111.91]) + by mx.google.com with ESMTPSA id n7sm27933201eef.5.2014.01.17.07.59.38 + for + (version=TLSv1.2 cipher=RC4-SHA bits=128/128); + Fri, 17 Jan 2014 07:59:39 -0800 (PST) +From: Jani Nikula +To: David Bremner , 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: + <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 17:59:36 +0200 +Message-ID: <87ob3ar447.fsf@nikula.org> +MIME-Version: 1.0 +Content-Type: text/plain +Cc: David Bremner +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Fri, 17 Jan 2014 15:59:55 -0000 + +On Wed, 15 Jan 2014, David Bremner wrote: +> From: David Bremner +> +> 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 + +Please read the comment you're removing again! ;) + +> +# 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" + +Parse error? + +> + 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 +> + + +Extra empty line. + +> +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. + +Extra "but"? + +> + +> +@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{} +> + +> +@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 +> + Move to the next widget (button or text entry field) +> +@item +> + Move to the previous widget. +> +@item +> + 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{} on the appropriate line. +> + +> +@node notmuch-search Key Bindings +> +@table @kbd +> +@item n,C-n, +> + Move to next line +> +@item p,C-p, +> + Move to previous line +> +@item +> + 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 + +Reading the content, seems like a reasonable start. I ignored the +syntax; I don't know anything about it. + +BR, +Jani. + + -- 2.26.2