From: david Date: Sun, 10 Mar 2013 02:22:31 +0000 (+2000) Subject: [RFC patch] emacs: skeleton of texinfo manual for emacs interface. X-Git-Url: http://git.tremily.us/gitweb.cgi?a=commitdiff_plain;h=dcdfdfb59b1b9a7c918d53ae210e5c2c25ecf283;p=notmuch-archives.git [RFC patch] emacs: skeleton of texinfo manual for emacs interface. --- diff --git a/7f/e5a7ced713ec1263b083a4ed09ea47d3347fcd b/7f/e5a7ced713ec1263b083a4ed09ea47d3347fcd new file mode 100644 index 000000000..856ec0f7d --- /dev/null +++ b/7f/e5a7ced713ec1263b083a4ed09ea47d3347fcd @@ -0,0 +1,373 @@ +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 D941A431FAE + for ; Sat, 9 Mar 2013 18:22:51 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: 0 +X-Spam-Level: +X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none] + 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 zHaDnvLIHj29 for ; + Sat, 9 Mar 2013 18:22:48 -0800 (PST) +Received: from tesseract.cs.unb.ca (tesseract.cs.unb.ca [131.202.240.238]) + (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id 12797431FAF + for ; Sat, 9 Mar 2013 18:22:48 -0800 (PST) +Received: from fctnnbsc30w-156034082078.dhcp-dynamic.fibreop.nb.bellaliant.net + ([156.34.82.78] helo=zancas.localnet) + by tesseract.cs.unb.ca with esmtpsa + (TLS1.2:DHE_RSA_AES_128_CBC_SHA1:128) (Exim 4.80) + (envelope-from ) + id 1UEVuN-0007lr-LL; Sat, 09 Mar 2013 22:22:47 -0400 +Received: from bremner by zancas.localnet with local (Exim 4.80) + (envelope-from ) + id 1UEVuI-0003yZ-2J; Sat, 09 Mar 2013 22:22:38 -0400 +From: david@tethera.net +To: notmuch@notmuchmail.org +Subject: [RFC patch] emacs: skeleton of texinfo manual for emacs interface. +Date: Sat, 9 Mar 2013 22:22:31 -0400 +Message-Id: <1362882151-14030-1-git-send-email-david@tethera.net> +X-Mailer: git-send-email 1.8.2.rc1 +X-Spam_bar: - +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: Sun, 10 Mar 2013 02:22:52 -0000 + +From: David Bremner + +Currently this only attempts to document the notmuch-hello interface. +--- + +I have thought for a long time that we should have some unified +documentation for the emacs interface. This is some sketch of a +beginning. Building such a document turns out to be a fair amount of +work, but I guess it should be possible to have something better than +what we have now (i.e. nothing). I did try to avoid duplication with +both the docstrings and the man pages. Eventually perhaps we should +have some common format to generate the man pages and info pages from, +but I didn't want to hold up the whole effort waiting for that. + +One thing that would make this effort more bearable is being able to +re-use material from the wiki. Currently there is no license +information at all on that material; I'm not sure exactly how to +proceed. + +To build this, use "makeinfo notmuch.texi" +You can then (perversely) view it without emacs with "info -f notmuch.info" +or in emacs with C-u C-h i notmuch.info. + + + emacs/notmuch.texi | 274 +++++++++++++++++++++++++++++++++++++++++++++++++++++ + emacs/version.texi | 2 + + 2 files changed, 276 insertions(+) + create mode 100644 emacs/notmuch.texi + create mode 100644 emacs/version.texi + +diff --git a/emacs/notmuch.texi b/emacs/notmuch.texi +new file mode 100644 +index 0000000..d4f7296 +--- /dev/null ++++ b/emacs/notmuch.texi +@@ -0,0 +1,274 @@ ++\input texinfo @c -*-texinfo-*- ++@comment $Id@w{$} ++@comment %**start of header ++@setfilename notmuch.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}, @value{UPDATED}) ++ ++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 Texinfo documentation system ++@direntry ++* notmuch: (notmuch)Emacs interface to notmuch ++@end direntry ++ ++@titlepage ++@title Notmuch ++@subtitle for version @value{VERSION}, @value{UPDATED} ++@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}, @value{UPDATED}). ++@end ifnottex ++ ++@menu ++* About this Manual:: ++* notmuch-hello:: ++* notmuch-search:: ++* Search Syntax:: ++* 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 ++@url{http://notmuchmail.org/manpages/notmuch-1,the notmuch man page}. ++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{} ++ ++@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 ++ 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{Search Syntax}, for more info. ++@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{Search ++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 Search Syntax ++@chapter Search Syntax ++ ++The canonical reference for notmuch search syntax is ++@url{http://notmuchmail.org/manpages/notmuch-search-terms-7,notmuch-search-terms(7)} ++ ++@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 +diff --git a/emacs/version.texi b/emacs/version.texi +new file mode 100644 +index 0000000..4de9b21 +--- /dev/null ++++ b/emacs/version.texi +@@ -0,0 +1,2 @@ ++@set VERSION 0.15.2 ++@set UPDATED April 01, 1970 +-- +1.8.2.rc1 +