man: update man pages

Explicitly mention PCRE where appropriate.

Include section headers (through MAN_CLASS_OPTIONS)

Fix mu-easy manpage

Make date dynamic

21 files changed, 371 insertions, 349 deletions

diff --git a/man/copyright.inc.in b/man/copyright.inc.in
index ba4d8bb..d7a78d7 100644
--- a/man/copyright.inc.in
+++ b/man/copyright.inc.in
@@ -2,7 +2,7 @@
 
 This manpage is part of ~mu~ @VERSION@.
 
-Copyright © 2022 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later
+Copyright © @YEAR@ Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later
 <https://gnu.org/licenses/gpl.html>. This is free software: you are free to
 change and redistribute it. There is NO WARRANTY, to the extent permitted by
 law.
diff --git a/man/meson.build b/man/meson.build
index 14aced6..e498c92 100644
--- a/man/meson.build
+++ b/man/meson.build
@@ -17,8 +17,10 @@
 #
 # generate org include files
 #
+year = run_command('date', '+%Y', check:true, capture:true)
 man_data=configuration_data()
 man_data.set('VERSION', meson.project_version())
+man_data.set('YEAR', year.stdout().strip())
 incs=[
   'author.inc',
   'bugs.inc',
@@ -46,7 +48,7 @@ man_orgs=[
   'mu-add.1.org',
   'mu-bookmarks.5.org',
   'mu-cfind.1.org',
-  'mu-easy.5.org',
+  'mu-easy.7.org',
   'mu-extract.1.org',
   'mu-fields.1.org',
   'mu-find.1.org',
@@ -62,14 +64,27 @@ man_orgs=[
   'mu-view.1.org'
 ]
 
+env = environment()
+env.set('LANG', 'C')
+yearmonth = run_command('date', '+%B %Y', check:true, capture:true, env: env)
+ym=yearmonth.stdout().strip()
+
 foreach src : man_orgs
-  # copy to builddir so org-includes work.
-  configure_file(input: src, output:'@BASENAME@.org', copy:true)
 
   # meson makes in tricky to use the results of e.g. configure_file
   # in custom_commands..., so this is admittedly a little hacky.
   org = join_paths(meson.current_build_dir(), src)
   man = '@BASENAME@'
+  section = src.substring(-5, -4)
+
+  # we fill in some man-page details:
+  #  @SECTION_ID@: the man-page section
+  #  @MAN_DATE@: date of the generation (not yet supported by ox-man)
+  conf_data = configuration_data()
+  conf_data.set('SECTION_ID', section)
+  conf_data.set('MAN_DATE', ym)
+  configure_file(input: src, output:'@BASENAME@.org',
+                 configuration: conf_data)
 
   expr_tmpl = ''.join([
     '(progn',
@@ -77,7 +92,7 @@ foreach src : man_orgs
     '  (org-export-to-file \'man "@0@"))',
   ])
   expr = expr_tmpl.format(org.substring(0,-4))
-  sectiondir = join_paths(mandir, 'man' + src.substring(-5, -4))
+  sectiondir = join_paths(mandir, 'man' + section)
 
   custom_target(src + '-to-man',
                 build_by_default: true,
diff --git a/man/mu-add.1.org b/man/mu-add.1.org
index bef1bec..a7f3ba7 100644
--- a/man/mu-add.1.org
+++ b/man/mu-add.1.org
@@ -1,4 +1,5 @@
-#+title: MU ADD
+#+TITLE: MU ADD
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
diff --git a/man/mu-bookmarks.5.org b/man/mu-bookmarks.5.org
index 80e2608..6fbbe35 100644
--- a/man/mu-bookmarks.5.org
+++ b/man/mu-bookmarks.5.org
@@ -1,4 +1,5 @@
-#+title: MU-BOOKMARKS
+#+TITLE: MU BOOKMARKS
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
diff --git a/man/mu-cfind.1.org b/man/mu-cfind.1.org
index 91aae03..840e1b6 100644
--- a/man/mu-cfind.1.org
+++ b/man/mu-cfind.1.org
@@ -1,4 +1,5 @@
-#+title:  MU CFIND
+#+TITLE: MU CFIND
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
@@ -41,8 +42,7 @@ If you do not specify a search expression, *mu cfind* returns the full list of
 contacts. Note, *mu cfind* uses a cache with the e-mail information, which is
 populated during the indexing process.
 
-The regular expressions are Perl-compatible (as per the PCRE-library used by
-GRegex).
+The regular expressions are basic case-insensitive PCRE, see *pcre(3)*.
 
 * CFIND OPTIONS
 
@@ -113,4 +113,4 @@ otherwise: 1 for a generals error and 2 for 'no matches'.
 #+include: "copyright.inc" :minlevel 1
 
 * SEE ALSO
-*mu(1)*, *mu-index(1)*, *mu-find(1)*
+*mu(1)*, *mu-index(1)*, *mu-find(1)*, *pcre(3)*
diff --git a/man/mu-easy.5.org b/man/mu-easy.5.org
deleted file mode 100644
index 27e9258..0000000
--- a/man/mu-easy.5.org
+++ /dev/null
@@ -1,313 +0,0 @@
-.TH MU-EASY 1 "February 2020" "User Manuals"
-
-.SH NAME
-
-mu easy \- a quick introduction to mu
-
-.SH DESCRIPTION
-
-\fBmu\fR is a set of tools for dealing with e-mail messages in Maildirs. There
-are many options, which are all described in the man pages for the various
-sub-commands. This man pages jumps over all of the details and gives examples of
-some common use cases. If the use cases described here do not precisely do what
-you want, please check the more extensive information in the man page about the
-sub-command you are using -- for example, the \fBmu-index\fR(1) or
-\fBmu-find\fR(1) man pages.
-
-\fBNOTE\fR: the \fBindex\fR command (and therefore, the ones that depend on
-that, such as \fBfind\fR), require that you store your mail in the
-Maildir-format. If you don't do so, you can still use the other commands, but
-you won't be able to index/search your mail.
-
-By default, \fBmu\fR uses colorized output when it thinks your terminal is
-capable of doing so. If you don't like color, you can use the \fB--nocolor\fR
-command-line option, or set either the \fBMU_NOCOLOR\fR or the \fBNO_COLOR\fR
-environment variable to non-empty.
-
-.SH SETTING THINGS UP
-
-The first time you run the mu commands, you need to initialize it. This is done
-with the \fBinit\fR command.
-
-.nf
-  \fB$ mu init\fR
-.fi
-
-This uses the defaults (see \fBmu-init(1)\fR for details on how to change that).
-
-
-.SH INDEXING YOUR E-MAIL
-
-Before you can search e-mails, you'll first need to index them:
-
-.nf
-  \fB$ mu index\fR
-.fi
-
-The process can take a few minutes, depending on the amount of mail
-you have, the speed of your computer, hard drive etc. Usually,
-indexing should be able to reach a speed of a few hundred messages per
-second.
-
-\fBmu index\fR guesses the top-level Maildir to do its job; if it guesses wrong,
-you can use the \fI--maildir\fR option to specify the top-level directory that
-should be processed. See the \fBmu-index\fR(1) man page for more details.
-
-Normally, \fBmu index\fR visits all the directories under the top-level Maildir;
-however, you can exclude certain directories (say, the 'trash' or 'spam'
-folders) by creating a file called \fI.noindex\fR in the directory. When
-\fBmu\fR sees such a file, it will exclude this directory and its
-sub-directories from indexing. Also see \fB.noupdate\fR in the \fBmu-index\fR(1)
-manpage.
-
-.SH SEARCHING YOUR E-MAIL
-
-After you have indexed your mail, you can start searching it. By default, the
-search results are printed on standard output. Alternatively, the output can
-take the form of Maildir with symbolic links to the found messages. This enables
-integration with e-mail clients; see the \fBmu-find\fR(1) man page for details,
-the syntax of the search parameters and so on. Here, we just give some examples
-for common cases.
-
-You can use the \fBmu fields\fR command to get information about all possible
-fields and flags.
-
-First, let's search for all messages sent to Julius (Caesar) regarding
-fruit:
-
-.nf
-\fB$ mu find t:julius fruit\fR
-.fi
-
-This should return something like:
-
-.nf
-  2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
-.fi
-
-This means there is a message to 'julius' with 'fruit' somewhere in the message.
-In this case, it's a message from John Milton. Note that the date format depends
-on your the language/locale you are using.
-
-How do we know that the message was sent to Julius Caesar? Well, it's not
-visible from the results above, because the default fields that are shown are
-date/sender/subject. However, we can change this using the \fI--fields\fR
-parameter (try \fBmu fields\fR to see all the details):
-
-.nf
-  \fB$ mu find --fields="t s" t:julius fruit\fR
-.fi
-
-In other words, display the 'To:'-field (t) and the subject (s). This should
-return something like:
-.nf
-  Julius Caesar <jc@example.com> Fere libenter homines id quod volunt credunt
-.fi
-
-This is the same message found before, only with some different fields
-displayed.
-
-By default, \fBmu\fR uses the logical AND for the search parameters -- that
-is, it displays messages that match all the parameters. However, we can use
-logical OR as well:
-
-.nf
-  \fB$ mu find t:julius OR f:socrates\fR
-.fi
-
-In other words, display messages that are either sent to Julius Caesar
-\fBor\fR are from Socrates. This could return something like:
-
-.nf
-  2008-07-31T21:57:25 EEST Socrates <soc@example.com> cool stuff
-  2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
-.fi
-
-What if we want to see some of the body of the message?  You can get
-a 'summary' of the first lines of the message using the \fI--summary-len\fR
-option, which will 'summarize' the first \fIn\fR lines of the message:
-
-.nf
-  \fB$ mu find --summary-len=3 napoleon m:/archive\fR
-.fi
-
-.nf
-  1970-01-01T02:00:00 EET Napoleon Bonaparte <nb@example.com> rock on dude
-  Summary: Le 24 février 1815, la vigie de Notre-Dame de la Garde signala le
-  trois-mâts le Pharaon, venant de Smyrne, Trieste et Naples. Comme
-  d'habitude, un pilote côtier partit aussitôt du port, rasa le château
-.fi
-
-The summary consists of the first n lines of the message with all superfluous
-whitespace removed.
-
-Also note the \fBm:/archive\fR parameter in the query. This means that we only
-match messages in a maildir called '/archive'.
-
-.SH MORE QUERIES
-
-Let's list a few more queries that may be interesting; please note that
-searches for message flags, priority and date ranges are only available in mu
-version 0.9 or later.
-
-Get all important messages which are signed:
-.nf
-  \fB$ mu find flag:signed prio:high \fR
-.fi
-
-Get all messages from Jim without an attachment:
-.nf
-  \fB$ mu find from:jim AND NOT flag:attach\fR
-.fi
-
-Get all messages where Jack is in one of the contact fields:
-.nf
-  \fB$ mu find contact:jack\fR
-.fi
-This uses the special contact: pseudo-field which matches (\fBfrom\fR,
-\fBto\fR, \fBcc\fR and \fBbcc\fR).
-
-Get all messages in the Sent Items folder about yoghurt:
-.nf
- \fB$mu find maildir:'/Sent Items' yoghurt\fR
-.fi
-Note how we need to quote search terms that include spaces.
-
-
-Get all unread messages where the subject mentions Ångström:
-.nf
-  \fB$ mu find subject:Ångström flag:unread\fR
-.fi
-which is equivalent to:
-.nf
-  \fB$ mu find subject:angstrom flag:unread\fR
-.fi
-because does mu is case-insensitive and accent-insensitive.
-
-Get all unread messages between March 2002 and August 2003 about some bird (or
-a Swedish rock band):
-.nf
-  \fB$ mu find date:20020301..20030831 nightingale flag:unread\fR
-.fi
-
-Get all messages received today:
-.nf
-  \fB$ mu find date:today..now\fR
-.fi
-
-Get all messages we got in the last two weeks about emacs:
-.nf
-  \fB$ mu find date:2w..now emacs\fR
-.fi
-
-Another powerful feature (since 0.9.6) are wildcard searches, where you can
-search for the last \fIn\fR characters in a word. For example, you can search
-for:
-.nf
-  \fB$ mu find 'subject:soc*'\fR
-.fi
-and get mails about soccer, Socrates, society, and so on. Note, it's important
-to quote the search query, otherwise the shell will interpret
-the '*'.
-
-You can also search for messages with a certain attachment using their
-filename, for example:
-
-.nf
-  \fB$ mu find 'file:pic*'\fR
-.fi
-will get you all messages with an attachment starting with 'pic'.
-
-If you want to find attachments with a certain MIME-type, you can use the
-following:
-
-Get all messages with PDF attachments:
-.nf
-  \fB$ mu find mime:application/pdf\fR
-.fi
-
-or even:
-
-Get all messages with image attachments:
-.nf
-  \fB$ mu find 'mime:image/*'\fR
-.fi
-
-
-Note that (1) the '*' wildcard can only be used as the rightmost thing in a
-search query, and (2) that you need to quote the search term, because
-otherwise your shell will interpret the '*' (expanding it to all files in the
-current directory -- probably not what you want).
-
-.SH DISPLAYING MESSAGES
-
-We might also want to display the complete messages instead of the header
-information. This can be done using \fBmu view\fR command. Note that this
-command does not use the database; you simply provide it the path to a
-message.
-
-Therefore, if you want to display some message from a search query, you'll
-need its path. To get the path (think \fBl\fRocation) for our first example we
-can use:
-
-.nf
-  \fB$ mu find --fields="l" t:julius fruit\fR
-.fi
-
-And we'll get something like:
-.nf
-  /home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,
-.fi
-We can now display this message:
-
-.nf
-  \fB$ mu view /home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,\fR
-
-     From: John Milton <jm@example.com>
-     To: Julius Caesar <jc@example.com>
-     Subject: Fere libenter homines id quod volunt credunt
-     Date: 2008-07-31T21:57:25 EEST
-
-     OF Mans First Disobedience, and the Fruit
-     Of that Forbidden Tree, whose mortal taste
-     Brought Death into the World, and all our woe,
-     [...]
-.fi
-
-.SH FINDING CONTACTS
-
-While \fBmu find\fR searches for messages, there is also \fBmu cfind\fR to
-find \fIcontacts\fR, that is, names + addresses. Without any search
-expression, \fBmu cfind\fR lists all of your contacts.
-
-.nf
-  \fB$ mu cfind julius\fR
-.fi
-
-will find all contacts with 'julius' in either name or e-mail address. Note
-that \fBmu cfind\fR accepts a \fIregular expression\fR.
-
-\fBmu cfind\fR also supports a \fI--format=\fR-parameter, which sets the
-output to some specific format, so the results can be imported into another
-program. For example, to export your contact information to a \fBmutt\fR
-address book file, you can use something like:
-
-.nf
-  \fB$ mu cfind --format=mutt-alias > ~/mutt-aliases \fR
-.fi
-
-Then, you can use them in \fBmutt\fR if you add something like \fBsource
-~/mutt-aliases\fR to your \fImuttrc\fR.
-
-.SH AUTHOR
-Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
-
-.SH "SEE ALSO"
-.BR mu (1),
-.BR mu-init (1),
-.BR mu-index (1),
-.BR mu-find (1),
-.BR mu-mfind (1),
-.BR mu-mkdir (1),
-.BR mu-view (1),
-.BR mu-extract (1)
diff --git a/man/mu-easy.7.org b/man/mu-easy.7.org
new file mode 100644
index 0000000..b862172
--- /dev/null
+++ b/man/mu-easy.7.org
@@ -0,0 +1,303 @@
+#+TITLE: MU EASY
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
+
+* NAME
+
+mu easy - a quick introduction to mu
+
+* DESCRIPTION
+
+*mu* is a set of tools for dealing with e-mail messages in Maildirs. There are
+many options, which are all described in the man pages for the various
+sub-commands. This man pages jumps over all of the details and gives examples of
+some common use cases. If the use cases described here do not precisely do what
+you want, please check the more extensive information in the man page about the
+sub-command you are using -- for example, the *mu-index(1)* or *mu-find(1)* man
+pages.
+
+*NOTE*: the *index* command (and therefore, the ones that depend on that, such as
+*find*), require that you store your mail in the Maildir-format. If you don't do
+so, you can still use the other commands, but you won't be able to index/search
+your mail.
+
+By default, *mu* uses colorized output when it thinks your terminal is capable of
+doing so. If you don't like color, you can use the *--nocolor* command-line
+option, or set either the *MU_NOCOLOR* or the *NO_COLOR* environment variable to
+non-empty.
+
+* SETTING THINGS UP
+
+The first time you run the mu commands, you need to initialize it. This is done
+with the *init* command.
+
+#+begin_example
+$ mu init
+#+end_example
+
+This uses the defaults (see *mu-init(1)* for details on how to change that).
+
+
+* INDEXING YOUR E-MAIL
+
+Before you can search e-mails, you'll first need to index them:
+
+#+begin_example
+$ mu index
+#+end_example
+
+The process can take a few minutes, depending on the amount of mail you have,
+the speed of your computer, hard drive etc. Usually, indexing should be able to
+reach a speed of a few hundred messages per second.
+
+*mu index* guesses the top-level Maildir to do its job; if it guesses wrong, you
+can use the =--maildir= option to specify the top-level directory that should be
+processed. See the *mu-index*(1) man page for more details.
+
+Normally, *mu index* visits all the directories under the top-level Maildir;
+however, you can exclude certain directories (say, the 'trash' or 'spam'
+folders) by creating a file called =.noindex= in the directory. When *mu* sees such
+a file, it will exclude this directory and its sub-directories from indexing.
+Also see *.noupdate* in the *mu-index*(1) manpage.
+
+* SEARCHING YOUR E-MAIL
+
+After you have indexed your mail, you can start searching it. By default, the
+search results are printed on standard output. Alternatively, the output can
+take the form of Maildir with symbolic links to the found messages. This enables
+integration with e-mail clients; see the *mu-find*(1) man page for details, the
+syntax of the search parameters and so on. Here, we just give some examples for
+common cases.
+
+You can use the *mu fields* command to get information about all possible fields
+and flags.
+
+First, let's search for all messages sent to Julius (Caesar) regarding fruit:
+
+#+begin_example
+$ mu find t:julius fruit
+#+end_example
+
+This should return something like:
+
+#+begin_example
+2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
+#+end_example
+
+This means there is a message to 'julius' with 'fruit' somewhere in the message.
+In this case, it's a message from John Milton. Note that the date format depends
+on your the language/locale you are using.
+
+How do we know that the message was sent to Julius Caesar? Well, it's not
+visible from the results above, because the default fields that are shown are
+date/sender/subject. However, we can change this using the =--fields= parameter
+(try *mu fields* to see all the details):
+
+#+begin_example
+$ mu find --fields="t s" t:julius fruit
+#+end_example
+
+In other words, display the 'To:'-field (t) and the subject (s). This should
+return something like:
+#+begin_example
+Julius Caesar <jc@example.com> Fere libenter homines id quod volunt credunt
+#+end_example
+
+This is the same message found before, only with some different fields
+displayed.
+
+By default, *mu* uses the logical ~AND~ for the search parameters -- that is, it
+displays messages that match all the parameters. However, we can use logical ~OR~
+as well:
+
+#+begin_example
+$ mu find t:julius OR f:socrates
+#+end_example
+
+In other words, display messages that are either sent to Julius Caesar *or* are
+from Socrates. This could return something like:
+
+#+begin_example
+2008-07-31T21:57:25 EEST Socrates <soc@example.com> cool stuff
+2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
+#+end_example
+
+What if we want to see some of the body of the message? You can get a 'summary'
+of the first lines of the message using the =--summary-len= option, which will
+'summarize' the first =n= lines of the message:
+
+#+begin_example
+$ mu find --summary-len=3 napoleon m:/archive
+#+end_example
+
+#+begin_example
+1970-01-01T02:00:00 EET Napoleon Bonaparte <nb@example.com> rock on dude
+Summary: Le 24 février 1815, la vigie de Notre-Dame de la Garde signala le
+trois-mâts le Pharaon, venant de Smyrne, Trieste et Naples. Comme
+d'habitude, un pilote côtier partit aussitôt du port, rasa le château
+#+end_example
+
+The summary consists of the first /n/ lines of the message with all superfluous
+whitespace removed.
+
+Also note the *m:/archive* parameter in the query. This means that we only match
+messages in a maildir called ~'/archive'~.
+
+* MORE QUERIES
+
+Let's list a few more queries that may be interesting; please note that
+searches for message flags, priority and date ranges are only available in mu
+version 0.9 or later.
+
+Get all important messages which are signed:
+#+begin_example
+  *$ mu find flag:signed prio:high *
+#+end_example
+
+Get all messages from Jim without an attachment:
+#+begin_example
+  *$ mu find from:jim AND NOT flag:attach*
+#+end_example
+
+Get all messages where Jack is in one of the contact fields:
+#+begin_example
+  *$ mu find contact:jack*
+#+end_example
+This uses the special contact: pseudo-field which matches (*from*,
+*to*, *cc* and *bcc*).
+
+Get all messages in the Sent Items folder about yoghurt:
+#+begin_example
+ *$mu find maildir:'/Sent Items' yoghurt*
+#+end_example
+Note how we need to quote search terms that include spaces.
+
+
+Get all unread messages where the subject mentions Ångström:
+#+begin_example
+  *$ mu find subject:Ångström flag:unread*
+#+end_example
+which is equivalent to:
+#+begin_example
+  *$ mu find subject:angstrom flag:unread*
+#+end_example
+because does mu is case-insensitive and accent-insensitive.
+
+Get all unread messages between March 2002 and August 2003 about some bird (or
+a Swedish rock band):
+#+begin_example
+  *$ mu find date:20020301..20030831 nightingale flag:unread*
+#+end_example
+
+Get all messages received today:
+#+begin_example
+  *$ mu find date:today..now*
+#+end_example
+
+Get all messages we got in the last two weeks about emacs:
+#+begin_example
+  *$ mu find date:2w..now emacs*
+#+end_example
+
+Another powerful feature (since 0.9.6) are wildcard searches, where you can
+search for the last =n= characters in a word. For example, you can search
+for:
+#+begin_example
+  *$ mu find 'subject:soc*'*
+#+end_example
+and get mails about soccer, Socrates, society, and so on. Note, it's important
+to quote the search query, otherwise the shell will interpret
+the '*'.
+
+You can also search for messages with a certain attachment using their
+filename, for example:
+
+#+begin_example
+  *$ mu find 'file:pic*'*
+#+end_example
+will get you all messages with an attachment starting with 'pic'.
+
+If you want to find attachments with a certain MIME-type, you can use the
+following:
+
+Get all messages with PDF attachments:
+#+begin_example
+  *$ mu find mime:application/pdf*
+#+end_example
+
+or even:
+
+Get all messages with image attachments:
+#+begin_example
+  *$ mu find 'mime:image/*'*
+#+end_example
+
+
+Note that (1) the '*' wildcard can only be used as the rightmost thing in a
+search query, and (2) that you need to quote the search term, because
+otherwise your shell will interpret the '*' (expanding it to all files in the
+current directory -- probably not what you want).
+
+* DISPLAYING MESSAGES
+
+We might also want to display the complete messages instead of the header
+information. This can be done using *mu view* command. Note that this
+command does not use the database; you simply provide it the path to a
+message.
+
+Therefore, if you want to display some message from a search query, you'll
+need its path. To get the path (think *l*ocation) for our first example we
+can use:
+
+#+begin_example
+$ mu find --fields="l" t:julius fruit
+#+end_example
+
+And we'll get something like:
+#+begin_example
+/home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,
+#+end_example
+
+We can now display this message:
+
+#+begin_example
+$ mu view /home/someuser/Maildir/archive/cur/1266188485_0.6850.cthulhu:2,
+From: John Milton <jm@example.com>
+To: Julius Caesar <jc@example.com>
+Subject: Fere libenter homines id quod volunt credunt
+Date: 2008-07-31T21:57:25 EEST
+
+OF Mans First Disobedience, and the Fruit
+Of that Forbidden Tree, whose mortal taste
+Brought Death into the World, and all our woe,
+[...]
+#+end_example
+
+* FINDING CONTACTS
+
+While *mu find* searches for messages, there is also *mu cfind* to find =contacts=,
+that is, names + addresses. Without any search expression, *mu cfind* lists all of
+your contacts.
+
+#+begin_example
+$ mu cfind julius
+#+end_example
+
+will find all contacts with 'julius' in either name or e-mail address. Note that
+*mu cfind* accepts a =regular expression= (as per *pcre(3)*)
+
+*mu cfind* also supports a =--format==-parameter, which sets the output to some
+specific format, so the results can be imported into another program. For
+example, to export your contact information to a *mutt* address book file, you can
+use something like:
+
+#+begin_example
+$ mu cfind --format=mutt-alias > ~/mutt-aliases
+#+end_example
+
+Then, you can use them in *mutt* if you add something like *source ~/mutt-aliases*
+to your =muttrc=.
+
+#+include: "prefooter.inc" :minlevel 1
+
+* SEE ALSO
+*mu(1)*, *mu-init(1)*, *mu-index(1)*, *mu-find(1)*, *mu-mfind(1)*, *mu-mkdir(1)*, *mu-view(1)*, *mu-extract(1)*
diff --git a/man/mu-extract.1.org b/man/mu-extract.1.org
index ceade67..d7fb759 100644
--- a/man/mu-extract.1.org
+++ b/man/mu-extract.1.org
@@ -1,4 +1,5 @@
-#+title: MU EXTRACT
+#+TITLE: MU EXTRACT
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
@@ -21,10 +22,9 @@ For attachments, the file name used when saving it is the name of the attachment
 in the message. If there is no such name, or when saving non-attachment
 MIME-parts, a name is derived from the message-id of the message.
 
-If you specify a pattern (a case-insensitive regular expression) as the second
-argument, all attachments with filenames matching that pattern will be
-extracted. The regular expressions are Perl-compatible (as per the
-PCRE-library).
+If you specify a regular express pattern as the second argument, all attachments
+with filenames matching that pattern will be extracted. The regular expressions
+are basic PCRE, and are case-sensitive by default; see *pcre(3)* for more details.
 
 Without any options, *mu extract* simply outputs the list of leaf MIME-parts in
 the message. Only 'leaf' MIME-parts (including RFC822 attachments) are
diff --git a/man/mu-fields.1.org b/man/mu-fields.1.org
index 79e78e9..9b4179f 100644
--- a/man/mu-fields.1.org
+++ b/man/mu-fields.1.org
@@ -1,4 +1,6 @@
-#+title:  MU FIELDS
+#+TITLE: MU FIELDS
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
+
 
 * NAME
 
diff --git a/man/mu-find.1.org b/man/mu-find.1.org
index 79d4720..98be357 100644
--- a/man/mu-find.1.org
+++ b/man/mu-find.1.org
@@ -1,4 +1,5 @@
-#+title:  MU FIND
+#+TITLE: MU FIND
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
diff --git a/man/mu-help.1.org b/man/mu-help.1.org
index 7144722..e283195 100644
--- a/man/mu-help.1.org
+++ b/man/mu-help.1.org
@@ -1,4 +1,5 @@
-#+title:  MU HELP
+#+TITLE: MU HELP
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
diff --git a/man/mu-index.1.org b/man/mu-index.1.org
index 1db1e5f..75e9560 100644
--- a/man/mu-index.1.org
+++ b/man/mu-index.1.org
@@ -1,4 +1,5 @@
-#+title:  MU-INDEX
+#+TITLE: MU INDEX
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
diff --git a/man/mu-info.1.org b/man/mu-info.1.org
index 36f92f9..5e0b3f9 100644
--- a/man/mu-info.1.org
+++ b/man/mu-info.1.org
@@ -1,4 +1,5 @@
-#+title: MU-INFO
+#+TITLE: MU INFO
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
diff --git a/man/mu-init.1.org b/man/mu-init.1.org
index 5fc9ace..77cbe8d 100644
--- a/man/mu-init.1.org
+++ b/man/mu-init.1.org
@@ -1,4 +1,5 @@
-#+title:  MU-INIT
+#+TITLE: MU INIT
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
@@ -29,9 +30,9 @@ used for filtering in *mu-find(1)*, *mu-cfind(1)* and *mu4e*, e.g. to filter-out
 mailing list messages.
 
 =<my-email-address>= can be either a plain e-mail address (such as
-*foo@example.com*), or a regular-expression (of the 'Basic POSIX' flavor), wrapped
-in */* (such as =/foo-.*@example\\.com/=). Depending on your shell, the argument may
-need to b quoted.
+*foo@example.com*), or a basic PCRE regular-expression (see *pcre(3)* for details),
+wrapped in */* (such as =/foo-.*@example\\.com/=). Depending on your shell, the
+argument may need to b quoted.
 
 #+include: "muhome.inc" :minlevel 2
 
@@ -39,4 +40,4 @@ need to b quoted.
 
 * SEE ALSO
 
-*mu-index(1)*, *mu-find(1)*, *mu-cfind(1)*
+*mu-index(1)*, *mu-find(1)*, *mu-cfind(1)*, *pcre(3)*
diff --git a/man/mu-mkdir.1.org b/man/mu-mkdir.1.org
index c2e9edf..aafd013 100644
--- a/man/mu-mkdir.1.org
+++ b/man/mu-mkdir.1.org
@@ -1,4 +1,6 @@
-#+title:  MU MKDIR
+#+TITLE: MU MKDIR
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
+
 
 * NAME
 
diff --git a/man/mu-query.7.org b/man/mu-query.7.org
index ff3d896..67ce6d9 100644
--- a/man/mu-query.7.org
+++ b/man/mu-query.7.org
@@ -1,4 +1,5 @@
-#+title:  MU QUERY
+#+TITLE: MU QUERY
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
@@ -82,8 +83,7 @@ Note that a =pure not= - e.g. searching for *not apples* is quite a 'heavy' quer
 
 * REGULAR EXPRESSIONS AND WILDCARDS
 
-The language supports matching regular expressions that follow ECMAScript; for
-details, see http://www.cplusplus.com/reference/regex/ECMAScript/
+The language supports matching basic PCRE regular expressions, see *pcre(3*).
 
 Regular expressions are enclosed in *//*. Some examples:
 #+begin_example
@@ -331,4 +331,4 @@ above.
 
 * SEE ALSO
 
-*mu-find(1)*, *mu-fields(1)*
+*mu-find(1)*, *mu-fields(1), *pcre(3)*
diff --git a/man/mu-remove.1.org b/man/mu-remove.1.org
index 1b6b099..52adf94 100644
--- a/man/mu-remove.1.org
+++ b/man/mu-remove.1.org
@@ -1,4 +1,6 @@
-#+title:  MU REMOVE
+#+TITLE: MU REMOVE
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
+
 
 * NAME
 
diff --git a/man/mu-server.1.org b/man/mu-server.1.org
index 65d0d69..7d029ad 100644
--- a/man/mu-server.1.org
+++ b/man/mu-server.1.org
@@ -1,4 +1,5 @@
-#+title:  MU-SERVER
+#+TITLE:  MU-SERVER
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
diff --git a/man/mu-verify.1.org b/man/mu-verify.1.org
index 1a321e8..6d229e0 100644
--- a/man/mu-verify.1.org
+++ b/man/mu-verify.1.org
@@ -1,4 +1,5 @@
-#+title:  MU VERIFY
+#+TITLE: MU VERIFY
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
diff --git a/man/mu-view.1.org b/man/mu-view.1.org
index 391b3bb..838bd1c 100644
--- a/man/mu-view.1.org
+++ b/man/mu-view.1.org
@@ -1,4 +1,5 @@
-#+title:  MU VIEW
+#+TITLE: MU VIEW
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME
 
diff --git a/man/mu.1.org b/man/mu.1.org
index c4c3f69..952ee0c 100644
--- a/man/mu.1.org
+++ b/man/mu.1.org
@@ -1,4 +1,5 @@
-#+title: MU
+#+TITLE: MU
+#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
 
 * NAME