mu-man: improve typesetting of references

Try to stick to the man-pages(7) standard.
This commit is contained in:
Tristan Riehs
2024-07-22 15:18:46 +09:00
parent d2ec1751eb
commit dcc3807155
18 changed files with 137 additions and 73 deletions

View File

@ -1,5 +1,6 @@
#+TITLE: MU ADD
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -26,4 +27,6 @@ must be specified with an absolute path.
* SEE ALSO
*mu(1)*, *mu-index(1)*, *mu-remove(1)*
{{{man-link(mu,1)}}},
{{{man-link(mu-index,1)}}},
{{{man-link(mu-remove,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU BOOKMARKS
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -13,7 +14,7 @@ name for often-used queries. The bookmarks are also visible as shortcuts in the
The bookmarks file is read from =<muhome>/bookmarks=. On Unix this would typically
be w be =~/.config/mu/bookmarks=, but this can be influenced using the *--muhome*
parameter for *mu-find(1)*.
parameter for {{{man-link(mu-find,1)}}}.
The bookmarks file is a typical key=value *.ini*-file, which is best shown by
means of an example:
@ -25,7 +26,7 @@ oldhat=maildir:/archive subject:hat # archived with subject containing 'hat'
#+end_example
The *[mu]* group header is required. For practical uses of bookmarks, see
*mu-find(1)*.
{{{man-link(mu-find,1)}}}.
#+include: "author.inc" :minlevel 1
@ -33,4 +34,5 @@ The *[mu]* group header is required. For practical uses of bookmarks, see
* SEE ALSO
*mu(1)*, *mu-find(1)*
{{{man-link(mu,1)}}},
{{{man-link(mu-find,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU CFIND
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -42,7 +43,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 basic case-insensitive PCRE, see *pcre(3)*.
The regular expressions are basic case-insensitive PCRE, see {{{man-link(pcre,3)}}}.
* CFIND OPTIONS
@ -124,7 +125,7 @@ Each contact has the following fields:
| ~personal~ | whether the email was seen in a message together with a personal address |
| ~frequency~ | approximation of the number of times this contact was seen in messages |
The JSON format is useful for further processing, e.g. using the *jq(1)* tool:
The JSON format is useful for further processing, e.g. using the {{{man-link(jq,1)}}} tool:
List display names, sorted by their last-seen date:
#+begin_example
@ -146,7 +147,7 @@ which is (by default) accessible by pressing *Q*.
* ENCODING
*mu cfind* output is encoded according to the current locale except for
=--format=bbdb=. This is hard-coded to UTF-8, and as such specified in the
*--format=bbdb*. This is hard-coded to UTF-8, and as such specified in the
output-file, so emacs/bbdb can handle things correctly, without guessing.
#+include: "exit-code.inc" :minlevel 1
@ -158,4 +159,9 @@ output-file, so emacs/bbdb can handle things correctly, without guessing.
#+include: "copyright.inc" :minlevel 1
* SEE ALSO
*mu(1)*, *mu-index(1)*, *mu-find(1)*, *pcre(3)*, *jq(1)*
{{{man-link(mu,1)}}},
{{{man-link(mu-index,1)}}},
{{{man-link(mu-find,1)}}},
{{{man-link(pcre,3)}}},
{{{man-link(jq,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU EASY
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -12,8 +13,8 @@ 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.
sub-command you are using -- for example, the {{{man-link(mu-index,1)}}} or
{{{man-link(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
@ -34,7 +35,7 @@ with the *init* command.
$ mu init
#+end_example
This uses the defaults (see *mu-init(1)* for details on how to change that).
This uses the defaults (see {{{man-link(mu-init,1)}}} for details on how to change that).
* INDEXING YOUR E-MAIL
@ -50,23 +51,23 @@ 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.
can use the *--maildir* option to specify the top-level directory that should be
processed. See the {{{man-link(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.
Also see *.noupdate* in the {{{man-link(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.
integration with e-mail clients; see the {{{man-link(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.
@ -89,7 +90,7 @@ 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
date/sender/subject. However, we can change this using the *--fields* parameter
(try *mu fields* to see all the details):
#+begin_example
@ -122,7 +123,7 @@ from Socrates. This could return something like:
#+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
of the first lines of the message using the *--summary-len* option, which will
`summarize' the first =n= lines of the message:
#+begin_example
@ -283,9 +284,9 @@ $ 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* accepts a =regular expression= (as per {{{man-link(pcre,3)}}}
*mu cfind* also supports a =--format==-parameter, which sets the output to some
*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:
@ -300,4 +301,12 @@ 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)*
{{{man-link(mu,1)}}},
{{{man-link(mu-init,1)}}},
{{{man-link(mu-index,1)}}},
{{{man-link(mu-find,1)}}},
{{{man-link(mu-mfind,1)}}},
{{{man-link(mu-mkdir,1)}}},
{{{man-link(mu-view,1)}}},
{{{man-link(mu-extract,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU EXTRACT
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -24,7 +25,7 @@ MIME-parts, a name is derived from the message-id of the message.
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.
are basic PCRE, and are case-sensitive by default; see {{{man-link(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
@ -62,8 +63,8 @@ a legal filename in the target directory.
** --matches=<pattern>
Attachments with filenames matching the pattern will be extracted. The regular
expressions are basic PCRE, and are case-sensitive by default; see *pcre(3)* for
more details.
expressions are basic PCRE, and are case-sensitive by default; see
{{{man-link(pcre,3)}}} for more details.
** --play
Try to `play' (open) the attachment with the default application for the
@ -105,4 +106,4 @@ $ cat msgfile | mu extract --play --matches 'whoopsididitagain.mp3'
* SEE ALSO
*mu(1)*
{{{man-link(mu,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU FIND
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -12,12 +13,12 @@ mu-find - find e-mail messages in the *mu* database.
* DESCRIPTION
*mu find* is the *mu* command for searching e-mail message that were stored earlier
using *mu index(1)*.
using {{{man-link(mu index,1)}}}.
* SEARCHING MAIL
*mu find* starts a search for messages in the database that match some search
pattern. The search patterns are described in detail in *mu-query(7)*.
pattern. The search patterns are described in detail in {{{man-link(mu-query,7)}}}.
For example:
@ -40,12 +41,12 @@ The search pattern is taken as a command-line parameter. If the search
parameter consists of multiple parts (as in the example) they are
treated as if there were a logical *and* between them.
For details on the possible queries, see *mu-query(7)*.
For details on the possible queries, see {{{man-link(mu-query,7)}}}.
* FIND OPTIONS
Note, some of the important options are described in the *mu*(1) man-page
and not here, as they apply to multiple *mu* commands.
Note, some of the important options are described in the {{{man-link(mu*,1)}}}
manual page and not here, as they apply to multiple *mu* commands.
The *find*-command has various options that influence the way *mu* displays the
results. If you don't specify anything, the defaults are *--fields="d f s"*,
@ -81,9 +82,9 @@ parameters, such as:
For the complete list, try the command: *mu info fields*.
The message flags are described in *mu-query(7)*. As an example, a message which
is `seen', has an attachment and is signed would have `asz' as its corresponding
output string, while an encrypted new message would have `nx'.
The message flags are described in {{{man-link(mu-query,7)}}}. As an example, a
message which is `seen', has an attachment and is signed would have `asz' as its
corresponding output string, while an encrypted new message would have `nx'.
** -s, --sortfield=<field> and -z,--reverse
specify the field to sort the search results by and the direction (i.e.,
@ -176,8 +177,8 @@ $ mu find milkshake --fields="l" | xargs less
** -b, --bookmark=<bookmark>
use a bookmarked search query. Using this option, a query from your bookmark
file will be prepended to other search queries. See *mu-bookmarks(5)* for the
details of the bookmarks file.
file will be prepended to other search queries. See
{{{man-link(mu-bookmarks,5)}}} for the details of the bookmarks file.
** -u, --skip-dups
@ -276,7 +277,7 @@ After restarting Wanderlust, the virtual folders should appear.
* ENCODING
*mu find* output is encoded according to the locale for =--format=plain= (the
*mu find* output is encoded according to the locale for *--format=plain* (the
default format), and UTF-8 for all other formats (=sexp=, =xml=).
@ -311,4 +312,7 @@ taking the total number for 10 test runs.
* SEE ALSO
*mu(1)*, *mu-index(1)*, *mu-query(7)*, *mu-info(1)*
{{{man-link(mu,1)}}},
{{{man-link(mu-index,1)}}},
{{{man-link(mu-query,7)}}},
{{{man-link(mu-info,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU INDEX
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -13,15 +14,15 @@ mu-index - index e-mail messages stored in Maildirs
*mu index* is the *mu* command for scanning the contents of Maildir directories and
storing the results in a Xapian database. The data can then be queried using
*mu-find(1)*.
{{{man-link(mu-find,1)}}}.
Before the first time you run *mu index*, you must run *mu init* to initialize the
database.
*index* understands Maildirs as defined by Daniel Bernstein for *qmail(7)*. In
addition, it understands recursive Maildirs (Maildirs within Maildirs),
Maildir++. It also supports VFAT-based Maildirs which use =!= or =;= as the
separators instead of =:=.
*index* understands Maildirs as defined by Daniel Bernstein for
{{{man-link(qmail,7)}}}. In addition, it understands recursive Maildirs
(Maildirs within Maildirs), Maildir++. It also supports VFAT-based Maildirs
which use =!= or =;= as the separators instead of =:=.
E-mail messages which are not stored in something resembling a maildir
leaf-directory (=cur= and =new=) are ignored, as are the cache directories for
@ -215,4 +216,8 @@ least for now, the latest code is both the fastest and the most featureful!
* SEE ALSO
*maildir(5)*, *mu(1)*, *mu-init(1)*, *mu-find(1)*, *mu-cfind(1)*
{{{man-link(maildir,5)}}},
{{{man-link(mu,1)}}},
{{{man-link(mu-init,1)}}},
{{{man-link(mu-find,1)}}},
{{{man-link(mu-cfind,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU INFO
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -29,4 +30,4 @@ delayed due to database caching.
* SEE ALSO
*mu(1)*
{{{man-link(mu,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU INIT
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -30,19 +31,20 @@ performed).
specifies that some e-mail address is `my-address' (the option can be used
multiple times). Any message in which at least one of the contact fields
contains such an address is considered a `personal' messages; this can then be
used for filtering in *mu-find(1)*, *mu-cfind(1)* and *mu4e*, e.g. to filter-out
mailing list messages.
used for filtering in {{{man-link(mu-find,1)}}}, {{{man-link(mu-cfind,1)}}} and
*mu4e*, e.g. to filter-out mailing list messages.
=<email-address-or-regex>= can be either a plain e-mail address (such as
*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 be quoted.
*foo@example.com*), or a basic PCRE regular-expression (see
{{{man-link(pcre,3)}}} for details), wrapped in */* (such as
=/foo-.*@example\\.com/=). Depending on your shell, the argument may need to be
quoted.
** --ignored-address=<email-address-or-regex>
specifies that some e-mail address is to be ignored from the contacts-cache (the
option can be used multiple times). Such addresses then cannot be found with
*mu-cfind(1)* or in the Mu4e contacts cache.
{{{man-link(mu-cfind,1)}}} or in the Mu4e contacts cache.
=<my-email-address>= can be either a plain e-mail address or a regexp, just like
for the =--my-address= option.
@ -97,4 +99,7 @@ $ mu init --maildir=~/Maildir --my-address=alice@example.com --my-address=bob@ex
* SEE ALSO
*mu-index(1)*, *mu-find(1)*, *mu-cfind(1)*, *pcre(3)*
{{{man-link(mu-index,1)}}},
{{{man-link(mu-find,1)}}},
{{{man-link(mu-cfind,1)}}},
{{{man-link(pcre,3)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU MKDIR
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -11,8 +12,9 @@ mu-mkdir - create a new Maildir
* DESCRIPTION
*mu mkdir* is the command for creating Maildirs as per *maildir(5)*. A maildir is a
a directory with subdirectories ~new~, ~cur~ and ~tmp~.
*mu mkdir* is the command for creating Maildirs as per
{{{man-link(maildir,5)}}}. A maildir is a a directory with subdirectories ~new~,
~cur~ and ~tmp~.
The command does not use the *mu* database.
@ -22,8 +24,8 @@ were created. This is for safety reasons.
* MKDIR OPTIONS
** --mode=<mode>
set the file access mode for the new maildir(s) as in *chmod(1)*. The default
is 0755.
set the file access mode for the new maildir(s) as in
{{{man-link(chmod,1)}}}. The default is 0755.
#+include: "common-options.inc" :minlevel 1
@ -39,4 +41,5 @@ creates three maildirs, =tom=, =dick= and =harry=.
* SEE ALSO
*maildir(5)*, *chmod(1)*
{{{man-link(maildir,5)}}},
{{{man-link(chmod,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU MOVE
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -28,7 +29,8 @@ specify the new message flags. See *FLAGS* for details.
** --change-name
change the basename of the message file when moving; this can be useful when
using some external tools such as *mbsync(1)* which otherwise get confused
using some external tools such as {{{man-link(mbsync,1)}}} which otherwise get
confused
** --update-dups
@ -48,8 +50,8 @@ use a dry-run to predict the exact name when doing a `real' run.
* FLAGS
(Note: if you are not familiar with Maildirs, please refer to the *maildir(5)*
man-page, or see http://cr.yp.to/proto/maildir.html)
(Note: if you are not familiar with Maildirs, please refer to the
{{{man-link(maildir,5)}}} man-page, or see http://cr.yp.to/proto/maildir.html)
The message flags specify the Maildir-metadata for a message and are represented
by uppercase letters at the end of the message file name for all `non-new'
@ -114,4 +116,4 @@ $ mu move /home/user/Maildir/project1/cur/1695559560.a73985881f4611ac2.hostname!
* SEE ALSO
*maildir(5)*
{{{man-link(maildir,5)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU QUERY
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -84,7 +85,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 basic PCRE regular expressions, see *pcre(3)*.
The language supports matching basic PCRE regular expressions, see {{{man-link(pcre,3)}}}.
Regular expressions are enclosed in *//*. Some examples:
@ -381,4 +382,6 @@ interprets your query.
* SEE ALSO
*mu-find(1)*, *mu-info(1), *pcre(3)*
{{{man-link(mu-find,1)}}},
{{{man-link(mu-info,1)}}},
{{{man-link(pcre,3)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU REMOVE
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -24,4 +25,6 @@ their filename. The files do not have to exist in the file system.
* SEE ALSO
*mu(1)*, *mu-index(1)*, *mu-add(1)*
{{{man-link(mu,1)}}},
{{{man-link(mu-index,1)}}},
{{{man-link(mu-add,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU-SERVER
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -88,4 +89,5 @@ time build/mu/mu server --allow-temp-file --eval '(find :query "\"\"" :include-r
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
*mu(1)*
{{{man-link(mu,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU VERIFY
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -21,8 +22,8 @@ standard-input.
* VERIFY OPTIONS
** -r, --auto-retrieve
attempt to find keys online (see the *auto-key-retrieve* option in the *gnupg(1)*
documentation).
attempt to find keys online (see the *auto-key-retrieve* option in the
{{{man-link(gnupg,1)}}} documentation).
** decrypt
attempt to decrypt the message
@ -52,4 +53,4 @@ which does not give any output unless there is an error.
* SEE ALSO
*mu(1)*
{{{man-link(mu,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU VIEW
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -51,4 +52,4 @@ attempt to retrieve crypto-keys automatically from the network, when needed.
* SEE ALSO
*mu(1)*
{{{man-link(mu,1)}}}

View File

@ -1,5 +1,6 @@
#+TITLE: MU
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* NAME
@ -85,6 +86,18 @@ not require the *mu* database.
#+include: "prefooter.inc" :minlevel 1
* SEE ALSO
~mu-add(1)~, ~mu-cfind(1)~, ~mu-extract(1)~, ~mu-find(1)~, ~mu-help(1)~, ~mu-index(1)~,
~mu-info(1)~, ~mu-init(1)~, ~mu-mkdir(1)~, ~mu-remove(1)~, ~mu-server(1)~, ~mu-view(1)~,
~mu-query(7)~, ~mu-easy(1)~
{{{man-link(mu-add,1)}}},
{{{man-link(mu-cfind,1)}}},
{{{man-link(mu-extract,1)}}},
{{{man-link(mu-find,1)}}},
{{{man-link(mu-help,1)}}},
{{{man-link(mu-index,1)}}},
{{{man-link(mu-info,1)}}},
{{{man-link(mu-init,1)}}},
{{{man-link(mu-mkdir,1)}}},
{{{man-link(mu-remove,1)}}},
{{{man-link(mu-server,1)}}},
{{{man-link(mu-view,1)}}},
{{{man-link(mu-query,7)}}},
{{{man-link(mu-easy,1)}}}

View File

@ -2,7 +2,7 @@
use a non-default directory to store and read the database, write the logs, etc.
By default, *mu* uses the XDG Base Directory Specification (e.g. on GNU/Linux this
defaults to =~/.cache/mu= and =~/.config/mu=). Earlier versions of *mu* defaulted to
=~/.mu=, which now requires =--muhome=~/.mu=.
=~/.mu=, which now requires *--muhome=~/.mu*.
The environment variable ~MUHOME~ can be used as an alternative to *--muhome*. The
latter has precedence.