* generate help from pod.
2010-10-29 23:01 ` Carl Worth
@ 2010-11-03 17:18 ` david
2010-11-03 17:18 ` [PATCH 1/4] notmuch.pod: pod version of documentation, converted by rman, massaged by hand david
` (3 subsequent siblings)
4 siblings, 0 replies; 13+ messages in thread
From: david @ 2010-11-03 17:18 UTC (permalink / raw)
To: notmuch
Hi Carl;
Here is the generation. I hope you don't hate perl too much. I also
hope the syntax in notmuch.pod is self-explanatory. For me, with perl
5.10.1, this only uses modules included with Perl.
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH 1/4] notmuch.pod: pod version of documentation, converted by rman, massaged by hand.
2010-10-29 23:01 ` Carl Worth
2010-11-03 17:18 ` generate help from pod david
@ 2010-11-03 17:18 ` david
2010-11-03 17:18 ` [PATCH 2/4] Perl script to generate online help david
` (2 subsequent siblings)
4 siblings, 0 replies; 13+ messages in thread
From: david @ 2010-11-03 17:18 UTC (permalink / raw)
To: notmuch; +Cc: David Bremner
From: David Bremner <bremner@unb.ca>
Some places I deleted a bit of the continuity text introducing a
command because I didn't see how to make it work with the slightly
more structured layout.
I also moved show in front of search, because it explains the output
formats. Probably it would make sense to add a separate section
explaining common output formats.
The =for help lines are ignored for the man page, but used to generate
the online help.
I also added dummy sections for currently undocumented commands; or
more precisely, commands that were not documented that last time I
refreshed notmuch.pod.
---
notmuch.pod | 409 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 409 insertions(+), 0 deletions(-)
create mode 100644 notmuch.pod
diff --git a/notmuch.pod b/notmuch.pod
new file mode 100644
index 0000000..f4127e0
--- /dev/null
+++ b/notmuch.pod
@@ -0,0 +1,409 @@
+=head1 Name
+
+notmuch - thread-based email index, search, and tagging
+
+=head1 Synopsis
+
+=over
+
+=item B<notmuch> I<command> [I<args> ...]
+
+=back
+
+=head1 Description
+
+Notmuch is a command-line based program for indexing, searching,
+reading, and tagging large collections of email messages. The
+quickest way to get started with Notmuch is to simply invoke the
+B<notmuch> command with no arguments, which will interactively guide
+you through the process of indexing your mail.
+
+=head2 Using notmuch
+
+The B<search> and B<show> commands are used to query the email
+database. The B<tag> command is the only command available for
+manipulating database contents. Several of the notmuch commands
+accept search terms with a common syntax. See the B<SEARCH SYNTAX>
+section below for more details on the supported syntax.
+
+=head2 Note
+
+While the command-line program B<notmuch> provides powerful
+functionality, it does not provide the most convenient interface for
+that functionality. More sophisticated interfaces are expected to be
+built on top of either the command-line interface, or more likely, on
+top of the notmuch library interface. See L<http://notmuchmail.org> for
+more about alternate interfaces to notmuch.
+
+=head1 Commands
+
+=head2 setup
+
+=for help args NULL
+
+=for help desc Interactively sets up notmuch for first use.
+
+The setup command will prompt for your full name, your primary email
+address, any alternate email addresses you use, and the directory
+containing your email archives. Your answers will be written to a
+configuration file in ${NOTMUCH_CONFIG} (if set) or
+${HOME}/.notmuch-config . This configuration file will be created with
+descriptive comments, making it easy to edit by hand later to change
+the configuration. Or you can run B<notmuch setup> again to change the
+configuration.
+
+The mail directory you specify can contain any number of
+sub-directories and should primarily contain only files with
+individual email messages (eg. maildir or mh archives are perfect). If
+there are other, non-email files (such as indexes maintained by other
+email programs) then notmuch will do its best to detect those and
+ignore them.
+
+Mail storage that uses mbox format, (where one mbox file contains many
+messages), will not work with notmuch. If that's how your mail is
+currently stored, it is recommended you first convert it to maildir
+format with a utility such as mb2md before running B<notmuch setup>
+
+Invoking B<notmuch> with no command argument will run B<setup> if the
+setup command has not previously been completed.
+
+=head2 new
+
+=for help args NULL
+
+=for help desc Find and import any new messages to the database.
+
+The B<new> command scans all sub-directories of the database,
+performing full-text indexing on new messages that are found. Each new
+message will automatically be tagged with both the B<inbox> and
+B<unread> tags. You should run B<notmuch new> once after first
+running B<notmuch setup> to create the initial database. The first run
+may take a long time if you have a significant amount of mail (several
+hundred thousand messages or more). Subsequently, you should run
+B<notmuch new> whenever new mail is delivered and you wish to
+incorporate it into the database. These subsequent runs will be much
+quicker than the initial run.
+
+Invoking B<notmuch> with no command argument will run B<new> if
+B<notmuch setup> has previously been completed, but B<notmuch new> has
+not previously been run.
+
+=head2 show [options...] <search-term>...
+
+=for help args [options...] <search-term>...
+=for help desc Shows all messages matching the search terms.
+
+The messages will be grouped and sorted based on the threading (all
+replies to a particular message will appear immediately after that
+message in date order). The output is not indented by default, but
+depth tags are printed so that proper indentation can be performed by
+a post-processor (such as the emacs interface to notmuch). Supported
+options for B<show> include
+
+=over
+
+=item B<--entire-thread>
+
+By default only those messages that
+match the search terms will be displayed. With this option, all messages
+in the same thread as any matched message will be displayed.
+
+=item B<--format=(json|text)>
+
+=over
+
+=item B<text>
+
+The default plain-text format has text-content MIME parts decoded.
+Various components in the output, (B<message>, B<header>, B<body>,
+B<attachment>, and MIME B<part>), will be delimited by easily-parsed
+markers. Each marker consists of a Control-L character (ASCII decimal
+12), the name of the marker, and then either an opening or closing
+brace, ('{' or '}'), to either open or close the component.
+
+=item B<json>
+
+Format output as Javascript Object Notation (JSON).
+JSON output always includes all messages in a matching thread; in effect
+B<--format=json> implies B<--entire-thread>.
+
+=back
+
+=back
+
+A common use of B<notmuch show> is to display a single thread of
+email messages. For this, use a search term of "thread:<thread-id>" as
+can be seen in the first column of output from the B<notmuch search>
+command.
+
+See the B<SEARCH SYNTAX> section below for details of the supported
+syntax for <search-terms>.
+
+=head2 search [options...] <search-term>...
+
+=for help args [options...] <search-term>...
+=for help desc Search threads containing messages matching the given search terms.
+
+The output consists of one line per thread, giving a thread ID, the
+date of the newest (or oldest, depending on the sort option) matched
+message in the thread, the number of matched messages and total
+messages in the thread, the names of all participants in the thread,
+and the subject of the newest (or oldest) message. Supported options
+for B<search> include
+
+=over
+
+=item B<--format=>(B<json>|B<text>)
+
+Presents the results in either JSON or plain-text (default).
+
+=item B<--sort=>(B<newest-first>|B<oldest-first>)
+
+This option can be used to present results in either chronological
+order (B<oldest-first>) or reverse chronological order
+(B<newest-first>). Note: The thread order will be distinct between
+these two options (beyond being simply reversed). When sorting by
+B<oldest-first> the threads will be sorted by the oldest message in
+each thread, but when sorting by B<newest-first> the threads will be
+sorted by the newest message in each thread. By default, results will
+be displayed in reverse chronological order, (that is, the newest
+results will be displayed first).
+
+=back
+
+See the B<SEARCH SYNTAX> section below for details of the supported
+syntax for B<search-terms>.
+
+=head2 count <search-term>...
+
+=for help args <search-term>...
+
+=for help desc Count messages matching the search terms.
+
+The number of matching messages is output to stdout. With no search
+terms, a count of all messages in the database will be displayed.
+
+=head2 reply [options...] <search-term>...
+
+=for help args [options...] <search-term>...
+=for help desc Construct a reply template for a set of messages.
+
+To make replying to email easier, B<notmuch reply> takes an existing
+set of messages and constructs a suitable mail template. The Reply-to
+header (if any, otherwise From:) is used for the To: address. Values
+from the To: and Cc: headers are copied, but not including any of the
+current user's email addresses (as configured in primary_mail or
+other_email in the .notmuch-config file) in the recipient list It also
+builds a suitable new subject, including Re: at the front (if not
+already present), and adding the message IDs of the messages being
+replied to to the References list and setting the In-Reply-To: field
+correctly. Finally, the original contents of the emails are quoted by
+prefixing each line with '> ' and included in the body. The resulting
+message template is output to stdout. Supported options for B<reply>
+include
+
+=over
+
+=item B<--format=>(B<default>|B<headers-only>)
+
+=over
+
+=item B<default>
+
+Includes subject and quoted message body.
+
+=item B<headers-only>
+
+Only produces In-Reply-To, References, To, Cc, and Bcc headers.
+
+=back
+
+=back
+
+Note: It is most common to use B<notmuch reply> with a search string
+matching a single message, (such as id:<message-id>), but it can be
+useful to reply to several messages at once. For example, when a
+series of patches are sent in a single thread, replying to the entire
+thread allows for the reply to comment on issue found in multiple
+patches.
+
+=head2 tag +<tag>|-<tag> [...] [--] <search-term>...
+
+=for help args +<tag>|-<tag> [...] [--] <search-term>...
+
+=for help desc Add/remove tags for all messages matching the search terms.
+
+Tags prefixed by '+' are added while those prefixed by '-' are
+removed. For each message, tag removal is performed before tag
+addition. The beginning of I<search-terms> is recognized by the first
+argument that begins with neither '+' nor '-'. Support for an initial
+search term beginning with '+' or '-' is provided by allowing the user
+to specify a "--" argument to separate the tags from the search terms.
+See the B<SEARCH SYNTAX> section below for details of the supported
+syntax for I<search-terms>. The B<dump> and B<restore> commands can
+be used to create a textual dump of email tags for backup purposes,
+and to restore from that dump
+
+=head2 dump [<filename>]
+
+=for help args [<filename>]
+=for help desc Create a plain-text dump of the tags of each message.
+
+The output is to the given filename, if any, or to stdout. These tags
+are the only data in the notmuch database that can't be recreated from
+the messages themselves. The output of notmuch dump is therefore the
+only critical thing to backup (and much more friendly to incremental
+backup than the native database files.)
+
+=head2 restore <filename>
+
+=for help args [<filename>]
+=for help desc Restore the tags from the given file (see <notmuch dump>).
+
+Note: The dump file format is specifically chosen to be compatible
+with the format of files produced by sup-dump. So if you've previously
+been using sup for mail, then the B<notmuch restore> command provides
+you a way to import all of your tags (or labels as sup calls them).
+
+=head2 part --part=<part-number> <search-term>...
+
+=for help args --part=<part-number> <search-term>...
+=for help desc Output a single MIME part of a message.
+
+A single decoded MIME part, with no encoding or framing, is output to
+stdout. The search terms must match only a single message, otherwise
+this command will fail. The part number should match the part "id"
+field output by the "--format=json" option of "notmuch show". If the
+message specified by the search terms does not include a part with the
+specified "id" there will be no output. See the B<SEARCH SYNTAX>
+section below for details of the supported syntax for <search-terms>.
+
+=head2 search-tags
+
+=for help args dummy args
+=for help desc dummy description
+
+dummy text
+
+=head2 config
+
+=for help args dummy args
+=for help desc dummy description
+
+dummy text
+
+=head2 help
+
+=for help args dummy args
+=for help desc dummy description
+
+dummy text
+
+
+=head1 Search Syntax
+
+=for help name search_syntax
+
+Several notmuch commands accept a common syntax
+for search terms.
+The search terms can consist of free-form text (and quoted
+phrases) which will match all messages that contain all of the given terms/phrases
+in the body, the subject, or any of the sender or recipient headers.
+ As
+a special case, a search string consisting of exactly a single asterisk
+("*") will match all messages.
+ In addition to free text, the following
+prefixes can be used to force terms to match against specific portions
+of an email, (where <brackets> indicate user-supplied values):
+
+
+ from:<name-or-address>
+ to:<name-or-address>
+ subject:<word-or-quoted-phrase>
+ attachment:<word>
+ tag:<tag> (or is:<tag>)
+ id:<message-id>
+ thread:<thread-id>
+
+
+The B<from:> prefix is used to match the name or address of the sender
+of an email message. The B<to:> prefix is used to match the names or
+addresses of any recipient of an email message, (whether To, Cc, or
+Bcc). Any term prefixed with B<subject:> will match only text from
+the subject of an email.
+
+Searching for a phrase in the subject is supported by including quotation
+marks around the phrase, immediately following B<subject:>.
+
+The B<attachment:>
+prefix can be used to search for specific filenames (or extensions) of
+attachments to email messages.
+ For B<tag:> and B<is:> valid tag values include
+B<inbox> and B<unread> by default for new messages added by B<notmuch new> as well
+as any other tag values added manually with B<notmuch tag>.
+For B<id:>, message
+ID values are the literal contents of the Message-ID: header of email messages,
+but without the '<', '>' delimiters.
+
+The B<thread:> prefix can be used with the
+thread ID values that are generated internally by notmuch (and do not appear
+in email messages). These thread ID values can be seen in the first column
+of output from B<notmuch search>
+
+In addition to individual terms, multiple
+terms can be combined with Boolean operators ( B<and>, B<or>, B<not> , etc.). Each
+term in the query will be implicitly connected by a logical AND if no explicit
+operator is provided, (except that terms with a common prefix will be implicitly
+combined with OR until we get Xapian defect #402 fixed).
+Parentheses can
+also be used to control the combination of the Boolean operators, but will
+have to be protected from interpretation by the shell, (such as by putting
+quotation marks around any parenthesized expression).
+
+Finally, results
+can be restricted to only messages within a particular time range, (based
+on the Date: header) with a syntax of:
+
+ <initial-timestamp>..<final-timestamp>
+
+Each timestamp is a number representing the number of seconds since
+1970-01-01 00:00:00 UTC. This is not the most convenient means of
+expressing date ranges, but until notmuch is fixed to accept a more
+convenient form, one can use the date program to construct
+timestamps. For example, with the bash shell the folowing syntax would
+specify a date range to return messages from 2009-10-01 until the
+current time:
+
+
+ $(date +%s -d 2009-10-01)..$(date +%s)
+
+=head1 Environment
+
+The following environment variables can be used to control
+the behavior of notmuch.
+
+=over
+
+=item B<NOTMUCH_CONFIG>
+
+Specifies the location of the notmuch
+configuration file. Notmuch will use ${HOME}/.notmuch-config if this variable
+is not set.
+
+=back
+
+=head1 See Also
+
+The emacs-based interface to notmuch (available
+as B<notmuch.el> in the Notmuch distribution).
+
+The notmuch website: L<http://notmuchmail.org>
+
+=head1 Contact
+
+Feel free to send questions, comments, or kudos to the notmuch mailing
+list <notmuch@notmuchmail.org> . Subscription is not required before
+posting, but is available from the notmuchmail.org website.
+
+Real-time interaction with the Notmuch community is available via IRC
+(server: irc.freenode.net, channel: #notmuch).
\ No newline at end of file
--
1.7.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH 2/4] Perl script to generate online help.
2010-10-29 23:01 ` Carl Worth
2010-11-03 17:18 ` generate help from pod david
2010-11-03 17:18 ` [PATCH 1/4] notmuch.pod: pod version of documentation, converted by rman, massaged by hand david
@ 2010-11-03 17:18 ` david
2010-11-03 17:18 ` [PATCH 3/4] Add rules to build notmuch.1 and notmuch-help.h from the pod file david
2010-11-03 17:18 ` [PATCH 4/4] notmuch.c: use help strings generated from notmuch.pod david
4 siblings, 0 replies; 13+ messages in thread
From: david @ 2010-11-03 17:18 UTC (permalink / raw)
To: notmuch; +Cc: David Bremner
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 3410 bytes --]
From: David Bremner <bremner@unb.ca>
This is a bit more complicated than expected, mainly because it needs
to split a chunk of the docs into 3 pieces corresponding to the
strings currently filled into a struct command_t.
To disable the ANSI escape codes, replace Pod::Text:Color with
Pod::Text. It would not be that much more work to generate colorized
and uncolorized help strings, and choose at runtime.
---
pod2help_h.pl | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 108 insertions(+), 0 deletions(-)
create mode 100644 pod2help_h.pl
diff --git a/pod2help_h.pl b/pod2help_h.pl
new file mode 100644
index 0000000..99cfb96
--- /dev/null
+++ b/pod2help_h.pl
@@ -0,0 +1,108 @@
+#!/usr/bin/perl
+
+# Copyright © David Bremner, 2010
+# This file is distributed under the same terms as perl, Artistic or GPL 1+.
+#
+# Authors: David Bremner <david@tethera.net>
+
+use Pod::Select;
+use Pod::Text::Color;
+use strict;
+
+# Create customized version of Pod::Select, that uses Pod::Text to
+# format pieces of the file.
+
+package OurParser;
+our @ISA = qw(Pod::Select);
+
+sub new{
+ my $class = shift;
+ my $self = { body => "" , name => undef};
+ bless $self, $class;
+ $self->initialize();
+ return $self;
+}
+
+# process verbatim blocks, err, verbatimly. Note that $self->{body} is
+# processed a second time by Pod::Text
+
+sub verbatim {
+ my ($self,$text,$line_num,$pod_para)=@_;
+
+ $self->{body} .= $text;
+}
+
+# process a normal text or command block. Either do some command
+# starting with =for, append to text to be process, or process the
+# current section. Note that this has the weakness/bug that nested
+# sections are not supported as chunks of text for help.
+sub textblock{
+ my ($self,$text,$line_num,$pod_para) = @_;
+
+ my $cmd = $pod_para -> cmd_name;
+
+ if ($cmd =~ /^head/){
+
+ $self->output() if defined($self->{name});
+
+ # grab name heuristically as the first word.
+ $text =~ m/\s*\w+\s+([\w-]+)/;
+ $self->{name} = $1;
+ $self->{name} =~s/-/_/;
+
+ } elsif ($cmd =~ /^for/){
+
+ $text =~ s/^\s+//;
+ $text =~ s/\s+$//;
+
+ # work around a pod bug/misfeature that requires a blank line between
+ # =for paragraphs.
+
+ my @lines=split("\n",$text);
+ foreach my $line (@lines){
+
+ $line =~ s/^=for\s+help\s+//;
+
+ # override name if specified.
+ $self->{name} = $1 if ($line =~ m/^name\s+(.*)$/);
+
+ # other "subcommands" could be supported here.
+ if ($line =~ s/^(args|desc)\s+//) {
+ my $quote="\"";
+ my $subcmd=$1;
+
+ # special case NULL; we don't want "NULL"
+ $quote = "" if ($line =~ /^NULL/);
+
+ print ("#define HELP_$self->{name}_$subcmd $quote$line$quote\n");
+ }
+ }
+ } else {
+ $self->{body} .= $text;
+ }
+}
+
+sub output {
+ my $self = shift;
+ my $formatter = new Pod::Text::Color(margin=>4);
+ my $output;
+ $formatter -> output_string (\$output);
+ $formatter -> parse_string_document ("=pod\n\n".$self->{body});
+
+ # post-process to turn into a C string.
+ $output =~ s/"/\\"/g;
+ $output =~ s/\n/\\n"\\\n"/g;
+ $output =~ s/\e/\\e/g;
+
+ print "#define HELP_$self->{name}_text \\\n\"$output\"\n";
+ $self->{body} = "";
+
+}
+
+package main;
+
+my $parser = new OurParser();
+
+$parser->select("Commands/..*","Search Syntax");
+$parser->parse_from_filehandle(\*STDIN);
+$parser->output();
--
1.7.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH 3/4] Add rules to build notmuch.1 and notmuch-help.h from the pod file.
2010-10-29 23:01 ` Carl Worth
` (2 preceding siblings ...)
2010-11-03 17:18 ` [PATCH 2/4] Perl script to generate online help david
@ 2010-11-03 17:18 ` david
2010-11-03 17:29 ` David Bremner
2010-11-03 17:18 ` [PATCH 4/4] notmuch.c: use help strings generated from notmuch.pod david
4 siblings, 1 reply; 13+ messages in thread
From: david @ 2010-11-03 17:18 UTC (permalink / raw)
To: notmuch; +Cc: David Bremner
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 20348 bytes --]
From: David Bremner <bremner@unb.ca>
Add generated files to CLEAN. Remove notmuch.1 from git because we
auto generate it now.
---
Makefile.local | 22 ++-
notmuch.1 | 609 --------------------------------------------------------
2 files changed, 21 insertions(+), 610 deletions(-)
delete mode 100644 notmuch.1
diff --git a/Makefile.local b/Makefile.local
index 490265b..3e20d0c 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -251,6 +251,18 @@ notmuch_client_srcs = \
show-message.c \
json.c
+notmuch_help_files= \
+ notmuch-setup-help.h \
+ notmuch-new-help.h \
+ notmuch-show-help.h \
+ notmuch-search-help.h \
+ notmuch-count-help.h \
+ notmuch-reply-help.h \
+ notmuch-tag-help.h \
+ notmuch-dump-help.h \
+ notmuch-restore-help.h \
+ notmuch-part-help.h
+
notmuch_client_modules = $(notmuch_client_srcs:.c=.o)
notmuch: $(notmuch_client_modules) lib/libnotmuch.a
@@ -259,6 +271,14 @@ notmuch: $(notmuch_client_modules) lib/libnotmuch.a
notmuch-shared: $(notmuch_client_modules) lib/$(LINKER_NAME)
$(call quiet,$(FINAL_NOTMUCH_LINKER) $(CFLAGS)) $(notmuch_client_modules) $(FINAL_NOTMUCH_LDFLAGS) -o $@
+notmuch.1: notmuch.pod
+ pod2man --stderr --center "User Commands" --release $(VERSION) $^ > $@
+
+notmuch.o: notmuch-help.h
+
+notmuch-help.h: notmuch.pod pod2help_h.pl
+ perl pod2help_h.pl < notmuch.pod > notmuch-help.h
+
notmuch.1.gz: notmuch.1
gzip --stdout $^ > $@
@@ -294,4 +314,4 @@ install-desktop:
desktop-file-install --mode 0644 --dir $(DESTDIR)$(desktop_dir) notmuch.desktop
SRCS := $(SRCS) $(notmuch_client_srcs)
-CLEAN := $(CLEAN) notmuch notmuch-shared $(notmuch_client_modules) notmuch.elc notmuch.1.gz
+CLEAN := $(CLEAN) notmuch notmuch-shared $(notmuch_client_modules) notmuch.elc notmuch.1.gz notmuch.1 notmuch-help.h
diff --git a/notmuch.1 b/notmuch.1
deleted file mode 100644
index 2c33749..0000000
--- a/notmuch.1
+++ /dev/null
@@ -1,609 +0,0 @@
-.\" notmuch - Not much of an email program, (just index, search and tagging)
-.\"
-.\" Copyright © 2009 Carl Worth
-.\"
-.\" Notmuch 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.
-.\"
-.\" Notmuch 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/ .
-.\"
-.\" Author: Carl Worth <cworth@cworth.org>
-.TH NOTMUCH 1 2009-10-31 "Notmuch 0.1"
-.SH NAME
-notmuch \- thread-based email index, search, and tagging
-.SH SYNOPSIS
-.B notmuch
-.IR command " [" args " ...]"
-.SH DESCRIPTION
-Notmuch is a command-line based program for indexing, searching,
-reading, and tagging large collections of email messages.
-
-The quickest way to get started with Notmuch is to simply invoke the
-.B notmuch
-command with no arguments, which will interactively guide you through
-the process of indexing your mail.
-.SH NOTE
-While the command-line program
-.B notmuch
-provides powerful functionality, it does not provide the most
-convenient interface for that functionality. More sophisticated
-interfaces are expected to be built on top of either the command-line
-interface, or more likely, on top of the notmuch library
-interface. See http://notmuchmail.org for more about alternate
-interfaces to notmuch.
-.SH COMMANDS
-The
-.BR setup
-command is used to configure Notmuch for first use, (or to reconfigure
-it later).
-.RS 4
-.TP 4
-.B setup
-
-Interactively sets up notmuch for first use.
-
-The setup command will prompt for your full name, your primary email
-address, any alternate email addresses you use, and the directory
-containing your email archives. Your answers will be written to a
-configuration file in ${NOTMUCH_CONFIG} (if set) or
-${HOME}/.notmuch-config . This configuration file will be created with
-descriptive comments, making it easy to edit by hand later to change the
-configuration. Or you can run
-.B "notmuch setup"
-again to change the configuration.
-
-The mail directory you specify can contain any number of
-sub-directories and should primarily contain only files with individual
-email messages (eg. maildir or mh archives are perfect). If there are
-other, non-email files (such as indexes maintained by other email
-programs) then notmuch will do its best to detect those and ignore
-them.
-
-Mail storage that uses mbox format, (where one mbox file contains many
-messages), will not work with notmuch. If that's how your mail is
-currently stored, it is recommended you first convert it to maildir
-format with a utility such as mb2md before running
-.B "notmuch setup" .
-
-Invoking
-.B notmuch
-with no command argument will run
-.B setup
-if the setup command has not previously been completed.
-.RE
-
-The
-.B new
-command is used to incorporate new mail into the notmuch database.
-.RS 4
-.TP 4
-.B new
-
-Find and import any new messages to the database.
-
-The
-.B new
-command scans all sub-directories of the database, performing
-full-text indexing on new messages that are found. Each new message
-will automatically be tagged with both the
-.BR inbox " and " unread
-tags.
-
-You should run
-.B "notmuch new"
-once after first running
-.B "notmuch setup"
-to create the initial database. The first run may take a long time if
-you have a significant amount of mail (several hundred thousand
-messages or more). Subsequently, you should run
-.B "notmuch new"
-whenever new mail is delivered and you wish to incorporate it into the
-database. These subsequent runs will be much quicker than the initial
-run.
-
-Invoking
-.B notmuch
-with no command argument will run
-.B new
-if
-.B "notmuch setup"
-has previously been completed, but
-.B "notmuch new"
-has not previously been run.
-.RE
-
-Several of the notmuch commands accept search terms with a common
-syntax. See the
-.B "SEARCH SYNTAX"
-section below for more details on the supported syntax.
-
-The
-.BR search ", " show " and " count
-commands are used to query the email database.
-.RS 4
-.TP 4
-.BR search " [options...] <search-term>..."
-
-Search for messages matching the given search terms, and display as
-results the threads containing the matched messages.
-
-The output consists of one line per thread, giving a thread ID, the
-date of the newest (or oldest, depending on the sort option) matched
-message in the thread, the number of matched messages and total
-messages in the thread, the names of all participants in the thread,
-and the subject of the newest (or oldest) message.
-
-Supported options for
-.B search
-include
-.RS 4
-.TP 4
-.BR \-\-format= ( json | text )
-
-Presents the results in either JSON or plain-text (default).
-.RE
-
-.RS 4
-.TP 4
-.B \-\-output=(summary|threads|messages|files|tags)
-
-.RS 4
-.TP 4
-.B summary
-
-Output a summary of each thread with any message matching the search
-terms. The summary includes the thread ID, date, the number of
-messages in the thread (both the number matched and the total number),
-the authors of the thread and the subject.
-.RE
-.RS 4
-.TP 4
-.B threads
-
-Output the thread IDs of all threads with any message matching the
-search terms, either one per line (--format=text) or as a JSON array
-(--format=json).
-.RE
-.RS 4
-.TP 4
-.B messages
-
-Output the message IDs of all messages matching the search terms,
-either one per line (--format=text) or as a JSON array
-(--format=json).
-.RE
-.RS 4
-.TP 4
-.B files
-
-Output the filenames of all messages matching the search terms, either
-one per line (--format=text) or as a JSON array (--format=json).
-.RE
-.RS 4
-.TP 4
-.B tags
-
-Output all tags that appear on any message matching the search terms,
-either one per line (--format=text) or as a JSON array
-(--format=json).
-.RE
-.RE
-
-.RS 4
-.TP 4
-.BR \-\-sort= ( newest\-first | oldest\-first )
-
-This option can be used to present results in either chronological order
-.RB ( oldest\-first )
-or reverse chronological order
-.RB ( newest\-first ).
-
-Note: The thread order will be distinct between these two options
-(beyond being simply reversed). When sorting by
-.B oldest\-first
-the threads will be sorted by the oldest message in each thread, but
-when sorting by
-.B newest\-first
-the threads will be sorted by the newest message in each thread.
-
-.RE
-.RS 4
-By default, results will be displayed in reverse chronological order,
-(that is, the newest results will be displayed first).
-
-See the
-.B "SEARCH SYNTAX"
-section below for details of the supported syntax for <search-terms>.
-.RE
-.TP
-.BR show " [options...] <search-term>..."
-
-Shows all messages matching the search terms.
-
-The messages will be grouped and sorted based on the threading (all
-replies to a particular message will appear immediately after that
-message in date order). The output is not indented by default, but
-depth tags are printed so that proper indentation can be performed by
-a post-processor (such as the emacs interface to notmuch).
-
-Supported options for
-.B show
-include
-.RS 4
-.TP 4
-.B \-\-entire\-thread
-
-By default only those messages that match the search terms will be
-displayed. With this option, all messages in the same thread as any
-matched message will be displayed.
-.RE
-
-.RS 4
-.TP 4
-.B \-\-format=(text|json|mbox)
-
-.RS 4
-.TP 4
-.B text
-
-The default plain-text format has all text-content MIME parts
-decoded. Various components in the output,
-.RB ( message ", " header ", " body ", " attachment ", and MIME " part ),
-will be delimited by easily-parsed markers. Each marker consists of a
-Control-L character (ASCII decimal 12), the name of the marker, and
-then either an opening or closing brace, ('{' or '}'), to either open
-or close the component.
-.RE
-.RS 4
-.TP 4
-.B json
-
-The output is formatted with Javascript Object Notation (JSON). This
-format is more robust than the text format for automated
-processing. JSON output always includes all messages in a matching
-thread; in effect
-.B \-\-format=json
-implies
-.B \-\-entire\-thread
-
-.RE
-.RS 4
-.TP 4
-.B mbox
-
-All matching messages are output in the traditional, Unix mbox format
-with each message being prefixed by a line beginning with "From " and
-a blank line separating each message. Lines in the message content
-beginning with "From " (preceded by zero or more '>' characters) have
-an additional '>' character added. This reversible escaping
-is termed "mboxrd" format and described in detail here:
-http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
-.RE
-A common use of
-.B notmuch show
-is to display a single thread of email messages. For this, use a
-search term of "thread:<thread-id>" as can be seen in the first
-column of output from the
-.B notmuch search
-command.
-
-See the
-.B "SEARCH SYNTAX"
-section below for details of the supported syntax for <search-terms>.
-.RE
-.TP
-.BR count " <search-term>..."
-
-Count messages matching the search terms.
-
-The number of matching messages is output to stdout.
-
-With no search terms, a count of all messages in the database will be
-displayed.
-.RE
-.RE
-
-The
-.B reply
-command is useful for preparing a template for an email reply.
-.RS 4
-.TP 4
-.BR reply " [options...] <search-term>..."
-
-Constructs a reply template for a set of messages.
-
-To make replying to email easier,
-.B notmuch reply
-takes an existing set of messages and constructs a suitable mail
-template. The Reply-to header (if any, otherwise From:) is used for
-the To: address. Vales from the To: and Cc: headers are copied, but
-not including any of the current user's email addresses (as configured
-in primary_mail or other_email in the .notmuch\-config file) in the
-recipient list
-
-It also builds a suitable new subject, including Re: at the front (if
-not already present), and adding the message IDs of the messages being
-replied to to the References list and setting the In\-Reply\-To: field
-correctly.
-
-Finally, the original contents of the emails are quoted by prefixing
-each line with '> ' and included in the body.
-
-The resulting message template is output to stdout.
-
-Supported options for
-.B reply
-include
-.RS
-.TP 4
-.BR \-\-format= ( default | headers\-only )
-.RS
-.TP 4
-.BR default
-Includes subject and quoted message body.
-.TP
-.BR headers\-only
-Only produces In\-Reply\-To, References, To, Cc, and Bcc headers.
-.RE
-
-See the
-.B "SEARCH SYNTAX"
-section below for details of the supported syntax for <search-terms>.
-
-Note: It is most common to use
-.B "notmuch reply"
-with a search string matching a single message, (such as
-id:<message-id>), but it can be useful to reply to several messages at
-once. For example, when a series of patches are sent in a single
-thread, replying to the entire thread allows for the reply to comment
-on issue found in multiple patches.
-.RE
-.RE
-
-The
-.B tag
-command is the only command available for manipulating database
-contents.
-
-.RS 4
-.TP 4
-.BR tag " +<tag>|\-<tag> [...] [\-\-] <search-term>..."
-
-Add/remove tags for all messages matching the search terms.
-
-Tags prefixed by '+' are added while those prefixed by '\-' are
-removed. For each message, tag removal is performed before tag
-addition.
-
-The beginning of <search-terms> is recognized by the first
-argument that begins with neither '+' nor '\-'. Support for
-an initial search term beginning with '+' or '\-' is provided
-by allowing the user to specify a "\-\-" argument to separate
-the tags from the search terms.
-
-See the
-.B "SEARCH SYNTAX"
-section below for details of the supported syntax for <search-terms>.
-.RE
-
-The
-.BR dump " and " restore
-commands can be used to create a textual dump of email tags for backup
-purposes, and to restore from that dump
-
-.RS 4
-.TP 4
-.BR dump " [<filename>]"
-
-Creates a plain-text dump of the tags of each message.
-
-The output is to the given filename, if any, or to stdout.
-
-These tags are the only data in the notmuch database that can't be
-recreated from the messages themselves. The output of notmuch dump is
-therefore the only critical thing to backup (and much more friendly to
-incremental backup than the native database files.)
-.TP
-.BR restore " <filename>"
-
-Restores the tags from the given file (see
-.BR "notmuch dump" "."
-
-Note: The dump file format is specifically chosen to be
-compatible with the format of files produced by sup-dump.
-So if you've previously been using sup for mail, then the
-.B "notmuch restore"
-command provides you a way to import all of your tags (or labels as
-sup calls them).
-.RE
-
-The
-.B part
-command can used to output a single part of a multi-part MIME message.
-
-.RS 4
-.TP 4
-.BR part " \-\-part=<part-number> <search-term>..."
-
-Output a single MIME part of a message.
-
-A single decoded MIME part, with no encoding or framing, is output to
-stdout. The search terms must match only a single message, otherwise
-this command will fail.
-
-The part number should match the part "id" field output by the
-"\-\-format=json" option of "notmuch show". If the message specified by
-the search terms does not include a part with the specified "id" there
-will be no output.
-
-See the
-.B "SEARCH SYNTAX"
-section below for details of the supported syntax for <search-terms>.
-.RE
-
-The
-.B config
-command can be used to get or set settings int the notmuch
-configuration file.
-
-.RS 4
-.TP 4
-.BR "config get " <section> . <item>
-
-The value of the specified configuration item is printed to stdout. If
-the item has multiple values, each value is separated by a newline
-character.
-
-Available configuration items include at least
-
- database.path
-
- user.name
-
- user.primary_email
-
- user.other_email
-
- new.tags
-.RE
-
-.RS 4
-.TP 4
-.BR "config set " <section> . "<item> [values ...]"
-
-The specified configuration item is set to the given value. To
-specify a multiple-value item, provide each value as a separate
-command-line argument.
-
-If no values are provided, the specified configuration item will be
-removed from the configuration file.
-.RE
-
-.SH SEARCH SYNTAX
-Several notmuch commands accept a common syntax for search terms.
-
-The search terms can consist of free-form text (and quoted phrases)
-which will match all messages that contain all of the given
-terms/phrases in the body, the subject, or any of the sender or
-recipient headers.
-
-As a special case, a search string consisting of exactly a single
-asterisk ("*") will match all messages.
-
-In addition to free text, the following prefixes can be used to force
-terms to match against specific portions of an email, (where
-<brackets> indicate user-supplied values):
-
- from:<name-or-address>
-
- to:<name-or-address>
-
- subject:<word-or-quoted-phrase>
-
- attachment:<word>
-
- tag:<tag> (or is:<tag>)
-
- id:<message-id>
-
- thread:<thread-id>
-
-The
-.B from:
-prefix is used to match the name or address of the sender of an email
-message.
-
-The
-.B to:
-prefix is used to match the names or addresses of any recipient of an
-email message, (whether To, Cc, or Bcc).
-
-Any term prefixed with
-.B subject:
-will match only text from the subject of an email. Searching for a
-phrase in the subject is supported by including quotation marks around
-the phrase, immediately following
-.BR subject: .
-
-The
-.B attachment:
-prefix can be used to search for specific filenames (or extensions) of
-attachments to email messages.
-
-For
-.BR tag: " and " is:
-valid tag values include
-.BR inbox " and " unread
-by default for new messages added by
-.B notmuch new
-as well as any other tag values added manually with
-.BR "notmuch tag" .
-
-For
-.BR id: ,
-message ID values are the literal contents of the Message\-ID: header
-of email messages, but without the '<', '>' delimiters.
-
-The
-.B thread:
-prefix can be used with the thread ID values that are generated
-internally by notmuch (and do not appear in email messages). These
-thread ID values can be seen in the first column of output from
-.B "notmuch search"
-
-In addition to individual terms, multiple terms can be
-combined with Boolean operators (
-.BR and ", " or ", " not
-, etc.). Each term in the query will be implicitly connected by a
-logical AND if no explicit operator is provided, (except that terms
-with a common prefix will be implicitly combined with OR until we get
-Xapian defect #402 fixed).
-
-Parentheses can also be used to control the combination of the Boolean
-operators, but will have to be protected from interpretation by the
-shell, (such as by putting quotation marks around any parenthesized
-expression).
-
-Finally, results can be restricted to only messages within a
-particular time range, (based on the Date: header) with a syntax of:
-
- <intial-timestamp>..<final-timestamp>
-
-Each timestamp is a number representing the number of seconds since
-1970\-01\-01 00:00:00 UTC. This is not the most convenient means of
-expressing date ranges, but until notmuch is fixed to accept a more
-convenient form, one can use the date program to construct
-timestamps. For example, with the bash shell the folowing syntax would
-specify a date range to return messages from 2009\-10\-01 until the
-current time:
-
- $(date +%s \-d 2009\-10\-01)..$(date +%s)
-.SH ENVIRONMENT
-The following environment variables can be used to control the
-behavior of notmuch.
-.TP
-.B NOTMUCH_CONFIG
-Specifies the location of the notmuch configuration file. Notmuch will
-use ${HOME}/.notmuch\-config if this variable is not set.
-.SH SEE ALSO
-The emacs-based interface to notmuch (available as
-.B notmuch.el
-in the Notmuch distribution).
-
-The notmuch website:
-.B http://notmuchmail.org
-.SH CONTACT
-Feel free to send questions, comments, or kudos to the notmuch mailing
-list <notmuch@notmuchmail.org> . Subscription is not required before
-posting, but is available from the notmuchmail.org website.
-
-Real-time interaction with the Notmuch community is available via IRC
-(server: irc.freenode.net, channel: #notmuch).
--
1.7.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* Re: [PATCH 3/4] Add rules to build notmuch.1 and notmuch-help.h from the pod file.
2010-11-03 17:18 ` [PATCH 3/4] Add rules to build notmuch.1 and notmuch-help.h from the pod file david
@ 2010-11-03 17:29 ` David Bremner
0 siblings, 0 replies; 13+ messages in thread
From: David Bremner @ 2010-11-03 17:29 UTC (permalink / raw)
To: notmuch
On Wed, 3 Nov 2010 14:18:55 -0300, david@tethera.net wrote:
> +notmuch_help_files= \
> + notmuch-setup-help.h \
> + notmuch-new-help.h \
> + notmuch-show-help.h \
> + notmuch-search-help.h \
> + notmuch-count-help.h \
> + notmuch-reply-help.h \
> + notmuch-tag-help.h \
> + notmuch-dump-help.h \
> + notmuch-restore-help.h \
> + notmuch-part-help.h
> +
Oops. This bit is leftover from when I tried to do everything in the
Makefile. It is not needed now.
Also I'm sad that deleting a file made a 600 line diff, sorry about
that. Maybe there is some option to tell it that the patch will be
applied by git. I didn't see it right away.
d
^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH 4/4] notmuch.c: use help strings generated from notmuch.pod.
2010-10-29 23:01 ` Carl Worth
` (3 preceding siblings ...)
2010-11-03 17:18 ` [PATCH 3/4] Add rules to build notmuch.1 and notmuch-help.h from the pod file david
@ 2010-11-03 17:18 ` david
4 siblings, 0 replies; 13+ messages in thread
From: david @ 2010-11-03 17:18 UTC (permalink / raw)
To: notmuch; +Cc: David Bremner
From: David Bremner <bremner@unb.ca>
It is quite possible this could be more automagically generated; there
is a certain amount of boilerplate in typing HELP_command_args,
HELP_command_desc, HELP_command_text. But, this way is less error
prone.
---
notmuch.c | 388 +++++++++----------------------------------------------------
1 files changed, 54 insertions(+), 334 deletions(-)
diff --git a/notmuch.c b/notmuch.c
index 030e494..d1ae366 100644
--- a/notmuch.c
+++ b/notmuch.c
@@ -21,6 +21,7 @@
*/
#include "notmuch-client.h"
+#include "notmuch-help.h"
typedef int (*command_function_t) (void *ctx, int argc, char *argv[]);
@@ -36,354 +37,73 @@ static int
notmuch_help_command (void *ctx, int argc, char *argv[]);
static const char search_terms_help[] =
- "\tSeveral notmuch commands accept a comman syntax for search\n"
- "\tterms.\n"
- "\n"
- "\tThe search terms can consist of free-form text (and quoted\n"
- "\tphrases) which will match all messages that contain all of\n"
- "\tthe given terms/phrases in the body, the subject, or any of\n"
- "\tthe sender or recipient headers.\n"
- "\n"
- "\tAs a special case, a search string consisting of exactly a\n"
- "\tsingle asterisk (\"*\") will match all messages.\n"
- "\n"
- "\tIn addition to free text, the following prefixes can be used\n"
- "\tto force terms to match against specific portions of an email,\n"
- "\t(where <brackets> indicate user-supplied values):\n"
- "\n"
- "\t\tfrom:<name-or-address>\n"
- "\t\tto:<name-or-address>\n"
- "\t\tsubject:<word-or-quoted-phrase>\n"
- "\t\tattachment:<word>\n"
- "\t\ttag:<tag> (or is:<tag>)\n"
- "\t\tid:<message-id>\n"
- "\t\tthread:<thread-id>\n"
- "\n"
- "\tThe from: prefix is used to match the name or address of\n"
- "\tthe sender of an email message.\n"
- "\n"
- "\tThe to: prefix is used to match the names or addresses of\n"
- "\tany recipient of an email message, (whether To, Cc, or Bcc).\n"
- "\n"
- "\tAny term prefixed with subject: will match only text from\n"
- "\tthe subject of an email. Quoted phrases are supported when\n"
- "\tsearching with: subject:\"this is a phrase\".\n"
- "\n"
- "\tFor tag: and is:, valid tag values include \"inbox\" and \"unread\"\n"
- "\tby default for new messages added by \"notmuch new\" as well\n"
- "\tas any other tag values added manually with \"notmuch tag\".\n"
- "\n"
- "\tFor id:, message ID values are the literal contents of the\n"
- "\tMessage-ID: header of email messages, but without the '<','>'\n"
- "\tdelimiters.\n"
- "\n"
- "\tThe thread: prefix can be used with the thread ID values that\n"
- "\tare generated internally by notmuch (and do not appear in email\n"
- "\tmessages). These thread ID values can be seen in the first\n"
- "\tcolumn of output from \"notmuch search\".\n"
- "\n"
- "\tIn addition to individual terms, multiple terms can be\n"
- "\tcombined with Boolean operators (\"and\", \"or\", \"not\", etc.).\n"
- "\tEach term in the query will be implicitly connected by a\n"
- "\tlogical AND if no explicit operator is provided, (except\n"
- "\tthat terms with a common prefix will be implicitly combined\n"
- "\twith OR until we get Xapian defect #402 fixed).\n"
- "\n"
- "\tParentheses can also be used to control the combination of\n"
- "\tthe Boolean operators, but will have to be protected from\n"
- "\tinterpretation by the shell, (such as by putting quotation\n"
- "\tmarks around any parenthesized expression).\n"
- "\n"
- "\tFinally, results can be restricted to only messages within a\n"
- "\tparticular time range, (based on the Date: header) with:\n"
- "\n"
- "\t\t<intial-timestamp>..<final-timestamp>\n"
- "\n"
- "\tEach timestamp is a number representing the number of seconds\n"
- "\tsince 1970-01-01 00:00:00 UTC. This is not the most convenient\n"
- "\tmeans of expressing date ranges, but until notmuch is fixed to\n"
- "\taccept a more convenient form, one can use the date program to\n"
- "\tconstruct timestamps. For example, with the bash shell the\n"
- "\tfollowing syntax would specify a date range to return messages\n"
- "\tfrom 2009-10-01 until the current time:\n"
- "\n"
- "\t\t$(date +%%s -d 2009-10-01)..$(date +%%s)\n\n";
+ HELP_search_syntax_text;
command_t commands[] = {
{ "setup", notmuch_setup_command,
- NULL,
- "Interactively setup notmuch for first use.",
- "\tThe setup command will prompt for your full name, your primary\n"
- "\temail address, any alternate email addresses you use, and the\n"
- "\tdirectory containing your email archives. Your answers will be\n"
- "\twritten to a configuration file in ${NOTMUCH_CONFIG} (if set)\n"
- "\tor ${HOME}/.notmuch-config.\n"
- "\n"
- "\tThis configuration file will be created with descriptive\n"
- "\tcomments, making it easy to edit by hand later to change the\n"
- "\tconfiguration. Or you can run \"notmuch setup\" again.\n"
- "\n"
- "\tInvoking notmuch with no command argument will run setup if\n"
- "\tthe setup command has not previously been completed." },
+ HELP_setup_args,
+ HELP_setup_desc,
+ HELP_setup_text },
{ "new", notmuch_new_command,
- "[--verbose]",
- "Find and import new messages to the notmuch database.",
- "\tScans all sub-directories of the mail directory, performing\n"
- "\tfull-text indexing on new messages that are found. Each new\n"
- "\tmessage will be tagged as both \"inbox\" and \"unread\".\n"
- "\n"
- "\tYou should run \"notmuch new\" once after first running\n"
- "\t\"notmuch setup\" to create the initial database. The first\n"
- "\trun may take a long time if you have a significant amount of\n"
- "\tmail (several hundred thousand messages or more).\n"
- "\n"
- "\tSubsequently, you should run \"notmuch new\" whenever new mail\n"
- "\tis delivered and you wish to incorporate it into the database.\n"
- "\tThese subsequent runs will be much quicker than the initial run.\n"
- "\n"
- "\tSupported options for new include:\n"
- "\n"
- "\t--verbose\n"
- "\n"
- "\t\tVerbose operation. Shows paths of message files as\n"
- "\t\tthey are being indexed.\n"
- "\n"
- "\tInvoking notmuch with no command argument will run new if\n"
- "\tthe setup command has previously been completed, but new has\n"
- "\tnot previously been run." },
+ HELP_new_args,
+ HELP_new_desc,
+ HELP_new_text },
{ "search", notmuch_search_command,
- "[options...] <search-terms> [...]",
- "Search for messages matching the given search terms.",
- "\tNote that the individual mail messages will be matched\n"
- "\tagainst the search terms, but the results will be the\n"
- "\tthreads (one per line) containing the matched messages.\n"
- "\n"
- "\tSupported options for search include:\n"
- "\n"
- "\t--format=(json|text)\n"
- "\n"
- "\t\tPresents the results in either JSON or\n"
- "\t\tplain-text (default)\n"
- "\n"
- "\t--output=(summary|threads|messages|files|tags)\n"
- "\n"
- "\t\tsummary (default)\n"
- "\n"
- "\t\tOutput a summary of each thread with any message matching the\n"
- "\t\tsearch terms. The summary includes the thread ID, date, the\n"
- "\t\tnumber of messages in the thread (both the number matched and\n"
- "\t\tthe total number), the authors of the thread and the subject.\n"
- "\n"
- "\t\tthreads\n"
- "\n"
- "\t\tOutput the thread IDs of all threads with any message matching\n"
- "\t\tthe search terms, either one per line (--format=text) or as a\n"
- "\t\tJSON array (--format=json).\n"
- "\n"
- "\t\tmessages\n"
- "\n"
- "\t\tOutput the message IDs of all messages matching the search\n"
- "\t\tterms, either one per line (--format=text) or as a JSON array\n"
- "\t\t(--format=json).\n"
- "\n"
- "\t\tfiles\n"
- "\n"
- "\t\tOutput the filenames of all messages matching the search\n"
- "\t\tterms, either one per line (--format=text) or as a JSON array\n"
- "\t\t(--format=json).\n"
- "\n"
- "\t\ttags\n"
- "\n"
- "\t\tOutput all tags that appear on any message matching the search\n"
- "\t\tterms, either one per line (--format=text) or as a JSON array\n"
- "\t\t(--format=json).\n"
- "\n"
- "\t--sort=(newest-first|oldest-first)\n"
- "\n"
- "\t\tPresent results in either chronological order\n"
- "\t\t(oldest-first) or reverse chronological order\n"
- "\t\t(newest-first), which is the default.\n"
- "\n"
- "\tSee \"notmuch help search-terms\" for details of the search\n"
- "\tterms syntax." },
+ HELP_search_args,
+ HELP_search_desc,
+ HELP_search_text
+ },
{ "show", notmuch_show_command,
- "<search-terms> [...]",
- "Show all messages matching the search terms.",
- "\tThe messages are grouped and sorted based on the threading\n"
- "\t(all replies to a particular message appear immediately\n"
- "\tafter that message in date order).\n"
- "\n"
- "\tSupported options for show include:\n"
- "\n"
- "\t--entire-thread\n"
- "\n"
- "\t\tBy default only those messages that match the\n"
- "\t\tsearch terms will be displayed. With this option,\n"
- "\t\tall messages in the same thread as any matched\n"
- "\t\tmessage will be displayed.\n"
- "\n"
- "\t--format=(text|json|mbox)\n"
- "\n"
- "\t\ttext (default)\n"
- "\n"
- "\t\tThe default plain-text format has all text-content MIME parts\n"
- "\t\tdecoded. Various components in the output, ('message', 'header',\n"
- "\t\t'body', 'attachment', and MIME 'part') are delimited by\n"
- "\t\teasily-parsed markers. Each marker consists of a Control-L\n"
- "\t\tcharacter (ASCII decimal 12), the name of the marker, and\n"
- "\t\tthen either an opening or closing brace, '{' or '}' to\n"
- "\t\teither open or close the component.\n"
- "\n"
- "\t\tjson\n"
- "\n"
- "\t\tThe output is formatted with Javascript Object Notation\n"
- "\t\t(JSON). This format is more robust than the text format\n"
- "\t\tfor automated processing. JSON output always includes all\n"
- "\t\tmessages in a matching thread; in effect '--format=json'\n"
- "\t\timplies '--entire-thread'\n"
- "\n"
- "\t\tmbox\n"
- "\n"
- "\t\tAll matching messages are output in the traditional, Unix\n"
- "\t\tmbox format with each message being prefixed by a line\n"
- "\t\tbeginning with 'From ' and a blank line separating each\n"
- "\t\tmessage. Lines in the message content beginning with 'From '\n"
- "\t\t(preceded by zero or more '>' characters) have an additional\n"
- "\t\t'>' character added. This reversible escaping is termed\n"
- "\t\t\"mboxrd\" format and described in detail here:\n"
- "\n"
- "\t\thttp://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html\n"
- "\n"
- "\tA common use of \"notmuch show\" is to display a single\n"
- "\tthread of email messages. For this, use a search term of\n"
- "\t\"thread:<thread-id>\" as can be seen in the first column\n"
- "\tof output from the \"notmuch search\" command.\n"
- "\n"
- "\tSee \"notmuch help search-terms\" for details of the search\n"
- "\tterms syntax." },
+ HELP_show_args,
+ HELP_show_desc,
+ HELP_show_text
+ },
{ "count", notmuch_count_command,
- "<search-terms> [...]",
- "Count messages matching the search terms.",
- "\tThe number of matching messages is output to stdout.\n"
- "\n"
- "\tWith no search terms, a count of all messages in the database\n"
- "\twill be displayed.\n"
- "\n"
- "\tSee \"notmuch help search-terms\" for details of the search\n"
- "\tterms syntax." },
+ HELP_count_args,
+ HELP_count_desc,
+ HELP_count_text
+ },
{ "reply", notmuch_reply_command,
- "[options...] <search-terms> [...]",
- "Construct a reply template for a set of messages.",
- "\tConstructs a new message as a reply to a set of existing\n"
- "\tmessages. The Reply-To: header (if any, otherwise From:) is\n"
- "\tused for the To: address. The To: and Cc: headers are copied,\n"
- "\tbut not including any of the user's configured addresses.\n"
- "\n"
- "\tA suitable subject is constructed. The In-Reply-to: and\n"
- "\tReferences: headers are set appropriately, and the content\n"
- "\tof the original messages is quoted and included in the body\n"
- "\t(unless --format=headers-only is given).\n"
- "\n"
- "\tThe resulting message template is output to stdout.\n"
- "\n"
- "\tSupported options for reply include:\n"
- "\n"
- "\t--format=(default|headers-only)\n"
- "\n"
- "\t\tdefault:\n"
- "\t\t\tIncludes subject and quoted message body.\n"
- "\n"
- "\t\theaders-only:\n"
- "\t\t\tOnly produces In-Reply-To, References, To\n"
- "\t\t\tCc, and Bcc headers.\n"
- "\n"
- "\tSee \"notmuch help search-terms\" for details of the search\n"
- "\tterms syntax." },
+ HELP_reply_args,
+ HELP_reply_desc,
+ HELP_reply_text
+ },
{ "tag", notmuch_tag_command,
- "+<tag>|-<tag> [...] [--] <search-terms> [...]",
- "Add/remove tags for all messages matching the search terms.",
- "\tThe search terms are handled exactly as in 'search' so one\n"
- "\tcan use that command first to see what will be modified.\n"
- "\n"
- "\tTags prefixed by '+' are added while those prefixed by\n"
- "\t'-' are removed. For each message, tag removal is performed\n"
- "\tbefore tag addition.\n"
- "\n"
- "\tThe beginning of <search-terms> is recognized by the first\n"
- "\targument that begins with neither '+' nor '-'. Support for\n"
- "\tan initial search term beginning with '+' or '-' is provided\n"
- "\tby allowing the user to specify a \"--\" argument to separate\n"
- "\tthe tags from the search terms.\n"
- "\n"
- "\tSee \"notmuch help search-terms\" for details of the search\n"
- "\tterms syntax." },
+ HELP_tag_args,
+ HELP_tag_desc,
+ HELP_tag_text
+ },
{ "dump", notmuch_dump_command,
- "[<filename>]",
- "Create a plain-text dump of the tags for each message.",
- "\tOutput is to the given filename, if any, or to stdout.\n"
- "\tThese tags are the only data in the notmuch database\n"
- "\tthat can't be recreated from the messages themselves.\n"
- "\tThe output of notmuch dump is therefore the only\n"
- "\tcritical thing to backup (and much more friendly to\n"
- "\tincremental backup than the native database files.)" },
+ HELP_dump_args,
+ HELP_dump_desc,
+ HELP_dump_text
+ },
+
{ "restore", notmuch_restore_command,
- "<filename>",
- "Restore the tags from the given dump file (see 'dump').",
- "\tNote: The dump file format is specifically chosen to be\n"
- "\tcompatible with the format of files produced by sup-dump.\n"
- "\tSo if you've previously been using sup for mail, then the\n"
- "\t\"notmuch restore\" command provides you a way to import\n"
- "\tall of your tags (or labels as sup calls them)." },
+ HELP_restore_args,
+ HELP_restore_desc,
+ HELP_restore_text
+ },
{ "search-tags", notmuch_search_tags_command,
- "[<search-terms> [...] ]",
- "List all tags found in the database or matching messages.",
- "\tRun this command without any search-term(s) to obtain a list\n"
- "\tof all tags found in the database. If you provide one or more\n"
- "\tsearch-terms as argument(s) then the resulting list will\n"
- "\tcontain tags only from messages that match the search-term(s).\n"
- "\n"
- "\tIn both cases the list will be alphabetically sorted." },
+ HELP_search_tags_args,
+ HELP_search_tags_desc,
+ HELP_search_tags_text
+ },
{ "part", notmuch_part_command,
- "--part=<num> <search-terms>",
- "Output a single MIME part of a message.",
- "\tA single decoded MIME part, with no encoding or framing,\n"
- "\tis output to stdout. The search terms must match only a single\n"
- "\tmessage, otherwise this command will fail.\n"
- "\n"
- "\tThe part number should match the part \"id\" field output\n"
- "\tby the \"--format=json\" option of \"notmuch show\". If the\n"
- "\tmessage specified by the search terms does not include a\n"
- "\tpart with the specified \"id\" there will be no output." },
+ HELP_part_args,
+ HELP_part_desc,
+ HELP_part_text
+ },
{ "config", notmuch_config_command,
- "[get|set] <section>.<item> [value ...]",
- "Get or set settings in the notmuch configuration file.",
- " config get <section>.<item>\n"
- "\n"
- "\tThe value of the specified configuration item is printed\n"
- "\tto stdout. If the item has multiple values, each value\n"
- "\tis separated by a newline character.\n"
- "\n"
- "\tAvailable configuration items include at least\n"
- "\n"
- "\t\tdatabase.path\n"
- "\t\tuser.name\n"
- "\t\tuser.primary_email\n"
- "\t\tuser.other_email\n"
- "\t\tnew.tags\n"
- "\n"
- " config set <section>.<item> [value ...]\n"
- "\n"
- "\tThe specified configuration item is set to the given value.\n"
- "\tTo specify a multiple-value item, provide each value as\n"
- "\ta separate command-line argument.\n"
- "\n"
- "\tIf no values are provided, the specified configuration item\n"
- "\twill be removed from the configuration file." },
+ HELP_config_args,
+ HELP_config_desc,
+ HELP_config_text
+ },
{ "help", notmuch_help_command,
- "[<command>]",
- "This message, or more detailed help for the named command.",
- "\tExcept in this case, where there's not much more detailed\n"
- "\thelp available." }
+ HELP_help_args,
+ HELP_help_desc,
+ HELP_help_text
+ }
};
static void
@@ -454,7 +174,7 @@ notmuch_help_command (unused (void *ctx), int argc, char *argv[])
}
}
printf ("\n");
- printf (search_terms_help);
+ fputs (search_terms_help, stdout);
return 0;
}
--
1.7.1
^ permalink raw reply related [flat|nested] 13+ messages in thread