From 1cd5af399dc0db7481c142bff1c492e1df3d15f5 Mon Sep 17 00:00:00 2001
From: djcb <djcb@djcbsoftware.nl>
Date: Mon, 22 Oct 2012 23:13:45 +0300
Subject: [PATCH] * mu: document mu script command

---
 man/Makefile.am        |  2 +-
 man/mu-script.1        | 83 ++++++++++++++++++++++++++++++++++++++++++
 man/mu-stats.1         | 51 --------------------------
 mu/mu-help-strings.txt | 13 ++++---
 4 files changed, 92 insertions(+), 57 deletions(-)
 create mode 100644 man/mu-script.1
 delete mode 100644 man/mu-stats.1

diff --git a/man/Makefile.am b/man/Makefile.am
index bba78c4b..03a67d83 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -28,7 +28,7 @@ dist_man_MANS =		\
 	mu-mkdir.1	\
 	mu-remove.1	\
 	mu-server.1	\
-	mu-stats.1	\
+	mu-script.1	\
 	mu-verify.1     \
 	mu-view.1	\
 	mu.1		\
diff --git a/man/mu-script.1 b/man/mu-script.1
new file mode 100644
index 00000000..52322172
--- /dev/null
+++ b/man/mu-script.1
@@ -0,0 +1,83 @@
+.TH MU SCRIPT 1 "October 2012" "User Manuals"
+
+.SH NAME
+
+mu script\- run a mu script
+
+.SH SYNOPSIS
+
+.B mu script [options] [--script=<script>] [<pattern>] [-- [script-options]]
+
+.SH DESCRIPTION
+
+\fBmu script\fR is the \fBmu\fR command to list available \fBmu\fR scripts,
+and run them. The scripts are implemented in the Guile programming language,
+and thus only work if your \fBmu\fR is built with support for Guile. In
+addition, many scripts require you to have \fBgnuplot\fR installed.
+
+Without any parameters, \fBmu script\fR lists the available scripts. If you
+provide a pattern (regular expression), only the scripts whose name or
+one-line description match this pattern, are listed. See the examples below.
+
+\fBmu\fR ships with a number of scripts.
+
+.SH OPTIONS
+
+.TP
+\fB\-\-script=\fR\fI<script>\fR
+run the given script.
+
+\fB\-\-verbose\fR,\fB\-v\fR
+when listing the available scripts, show the long descriptions.
+
+\fB\-\-\fR
+all options on the right side of the \fB\-\-\fR are passed to the script.
+
+.SH EXAMPLES
+
+List all available scripts (one-line descriptions):
+.nf
+  $ mu script
+.fi
+
+List all available scripts matching \fImonth\fR (long descriptions):
+.nf
+  $ mu script -v month
+.fi
+
+Run the \fImsgs-per-month\fR script, and pass it the \fI--textonly\fR
+parameter:
+.nf
+  $ mu script --script=msgs-per-month -- --textonly
+.fi
+
+.SH RETURN VALUE
+
+\fBmu script\fR returns 0 when all went well, and returns some non-zero error
+code when this is not the case.
+
+.SH FILES
+
+You can make your own Scheme scripts accessible throught \fBmu script\fR by
+putting them in \fI<muhome>/scripts\fR (which is typically
+\fI~/.mu/scripts\fR). It is a good idea to document it using some special
+comments in the source code:
+.nf
+;; INFO: this is my script -- one-line description
+;; INFO: (longer description)
+;; INFO: --option1=<foo> (describe option1)
+;; INFO: etc.
+.fi
+
+.SH BUGS
+
+Please report bugs if you find them:
+.BR http://code.google.com/p/mu0/issues/list
+
+.SH AUTHOR
+
+Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
+
+.SH "SEE ALSO"
+
+.BR mu(1)
diff --git a/man/mu-stats.1 b/man/mu-stats.1
deleted file mode 100644
index eb3f4755..00000000
--- a/man/mu-stats.1
+++ /dev/null
@@ -1,51 +0,0 @@
-.TH MU VERIFY 1 "October 2012" "User Manuals"
-
-.SH NAME
-
-mu stats\- run statistic on the mu database
-
-.SH SYNOPSIS
-
-.B mu stats [options] [--stat=<statistic>] [<query>]
-
-.SH DESCRIPTION
-
-\fBmu stats\fR is the \fBmu\fR command to get statistics from the \fBmu\fR
-database. The statistics are implement in the Guile programming language, and
-thus only work if your \fBmu\fR is built with support for Guile. In addition,
-you need to have \fBgnuplot\fR installed.
-
-\fBmu stats\fR supports a number of different statistics; running \fBmu
-stats\fR without any options, lists the available statistics.
-
-.SH OPTIONS
-
-.TP
-\fB\-\-stat=\fR\fI<statistic>\fR
-show the results for the given statistic
-
-\fB\-\-textonly\fR
-show the statistics in text-only format, even if the environment is
-capable of graphics.
-
-\fB\-\-muhome\fR
-causes \fBmu\fR to use an alternative directory to
-store and read its database and logs. By default, \fI~/.mu\fR is used.
-
-.SH RETURN VALUE
-
-\fBmu stats\fR returns 0 when all went well, and returns some non-zero error
-code when this is not the case.
-
-.SH BUGS
-
-Please report bugs if you find them:
-.BR http://code.google.com/p/mu0/issues/list
-
-.SH AUTHOR
-
-Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
-
-.SH "SEE ALSO"
-
-.BR mu(1)
diff --git a/mu/mu-help-strings.txt b/mu/mu-help-strings.txt
index 4d97a494..aaf210b8 100644
--- a/mu/mu-help-strings.txt
+++ b/mu/mu-help-strings.txt
@@ -96,13 +96,16 @@ mu4e e-mail client.
 #END
 
 
-#BEGIN MU_CONFIG_CMD_STATS
+#BEGIN MU_CONFIG_CMD_SCRIPT
 #STRING
-mu stats [options] [--stat=<statistic>] [<query>]
+mu script [--script=<script>] [<pattern>] [-v] -- [script-options]
 #STRING
-Run some statistics on the mu database. Option '--stat=' selects the statistic to
-show, optionally limited to the messages matching <query>. Without '--stat',
-lists the available statistics.
+Without any parameter, list the available scripts. With <pattern>,
+list only those scripts whose name or one-line description matches it.
+With -v, give longer descriptions of each script.
+
+With --script=<script>, run the script whose name is <script>; pass
+any arguments to the script after the "--" double-dash.
 #END