Try to improve overall manual page typesetting

man/common-options.inc

@@ -1,30 +1,30 @@
 * COMMON OPTIONS
 
 ** -d, --debug
-makes mu generate extra debug information, useful for debugging the program
-itself. By default, debug information goes to the log file, ~/.cache/mu/mu.log.
-It can safely be deleted when mu is not running. When running with --debug
+Makes *mu* generate extra debug information, useful for debugging the program
+itself. By default, debug information goes to the log file, _~/.cache/mu/mu.log_.
+It can safely be deleted when *mu* is not running. When running with *--debug*
 option, the log file can grow rather quickly. See the note on logging below.
 
 ** -q, --quiet
-causes mu not to output informational messages and progress information to
+Causes *mu* not to output informational messages and progress information to
 standard output, but only to the log file. Error messages will still be sent to
-standard error. Note that mu index is much faster with --quiet, so it is
-recommended you use this option when using mu from scripts etc.
+standard error. Note that *mu index* is much faster with *--quiet*, so it is
+recommended you use this option when using *mu* from scripts etc.
 
 ** --log-stderr
-causes mu to not output log messages to standard error, in addition to sending
+Causes *mu* to not output log messages to standard error, in addition to sending
 them to the log file.
 
 ** --nocolor
-do not use ANSI colors. The environment variable ~NO_COLOR~ can be used as an
-alternative to ~--nocolor~.
+Do not use ANSI colors. The environment variable *NO_COLOR* can be used as an
+alternative to *--nocolor*.
 
 ** -V, --version
-prints mu version and copyright information.
+Prints *mu* version and copyright information.
 
 ** -h, --help
-lists the various command line options.
+Lists the various command line options.
 
 # Local Variables:
 # mode: org

man/copyright.inc.in

@@ -1,6 +1,6 @@
 * COPYRIGHT
 
-This manpage is part of ~mu~ @VERSION@.
+This manpage is part of *mu* @VERSION@.
 
 Copyright © 2008-@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

man/exit-code.inc

@@ -1,12 +1,14 @@
+#+include: macros.inc
+
 * EXIT CODE
 
 This command returns 0 upon successful completion, or a non-zero exit code
 otherwise.
 
     0. success
     2. no matches found. Try a different query
-   11. database schema mismatch. You need to re-initialize ~mu~, see *mu-init(1)*
-   19. failed to acquire lock. Some other program has exclusive access to the mu database
+   11. database schema mismatch. You need to re-initialize *mu*, see {{{man-link(mu-init,1)}}}
+   19. failed to acquire lock. Some other program has exclusive access to the *mu* database
    99. caught an exception
 
 # Local Variables:

man/macros.inc

@@ -0,0 +1,5 @@
+#+MACRO: man-link *$1*​($2)
+
+# Local Variables:
+# mode: org
+# End:

man/meson.build

@@ -26,6 +26,7 @@ incs=[
   'common-options.inc',
   'copyright.inc.in',
   'exit-code.inc',
+  'macros.inc',
   'muhome.inc',
   'prefooter.inc',
 ]

man/mu-add.1.org

@@ -1,17 +1,18 @@
 #+TITLE: MU ADD
 #+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
+#+include: macros.inc
 
 * NAME
 
 mu-add - add one or more messages to the database
 
 * SYNOPSIS
 
-*mu [common-options] add [options] <file> [<files>]*
+*mu* [​_COMMON-OPTIONS_​] *add* [​_OPTIONS_​] _FILE_...
 
 * DESCRIPTION
 
-~mu add~ is the command to add specific message files to the database. Each file
+*mu add* is the command to add specific message files to the database. Each file
 must be specified with an absolute path.
 
 * ADD OPTIONS
@@ -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)}}}

man/mu-bookmarks.5.org

@@ -1,19 +1,20 @@
 #+TITLE: MU BOOKMARKS
 #+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
+#+include: macros.inc
 
 * NAME
 
-mu-bookmarks - file with bookmarks (shortcuts) for mu search expressions
+mu-bookmarks - file with bookmarks (shortcuts) for *mu* search expressions
 
 * DESCRIPTION
 
 Bookmarks are named shortcuts for search queries. They allow using a convenient
 name for often-used queries. The bookmarks are also visible as shortcuts in the
-mu experimental user interfaces, =mug= and =mug2=.
+*mu* experimental user interfaces, =mug= and =mug2=.
 
-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)*.
+The bookmarks file is read from _<muhome>/bookmarks_. On Unix this would typically
+be _~/.config/mu/bookmarks_, but this can be influenced using the *--muhome*
+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,12 +26,13 @@ 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
 
 #+include: "copyright.inc" :minlevel 1
 
 * SEE ALSO
 
-*mu(1)*, *mu-find(1)*
+{{{man-link(mu,1)}}},
+{{{man-link(mu-find,1)}}}

man/mu-cfind.1.org

@@ -1,5 +1,6 @@
 #+TITLE: MU CFIND
 #+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
+#+include: macros.inc
 
 * NAME
 
@@ -8,7 +9,7 @@ for use in other programs.
 
 * SYNOPSIS
 
-*mu [common-options] cfind [options] [<pattern>]*
+*mu* [​_COMMON-OPTIONS_​] *cfind* [​_OPTIONS_​] [​_PATTERN_​]
 
 * DESCRIPTION
 
@@ -42,12 +43,12 @@ 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
 
-** --format=plain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv
-sets the output format to the given value. The following are available:
+** --format plain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv
+Sets the output format to the given value. The following are available:
 
 #+ATTR_MAN: :disable-caption t
 | --format=   | description                       |
@@ -67,13 +68,14 @@ any double-quote is replaced by a double-double quote (thus, "hello" become
 ""hello"", and fields with commas are put in double-quotes. Normally, this
 should only apply to name fields.
 
-** --personal,-p only show addresses seen in messages where one of `my' e-mail
+** -p, --personal
+Only show addresses seen in messages where one of `my' e-mail
 addresses was seen in one of the address fields; this is to exclude addresses
-only seen in mailing-list messages. See the ~--my-address~ parameter to *mu init*.
+only seen in mailing-list messages. See the *--my-address* parameter to *mu init*.
 
-** --after=<timestamp> only show addresses last seen after
-=<timestamp>=. =<timestamp>= is a UNIX *time_t* value, the number of
-seconds since 1970-01-01 (in UTC).
+** --after _timestamp_
+Only show addresses last seen after _timestamp_. _timestamp_ is a UNIX
+*time_t* value, the number of seconds since 1970-01-01 (in UTC).
 
 From the command line, you can use the *date* command to get this value. For
 example, only consider addresses last seen after 2020-06-01, you could specify
@@ -87,7 +89,7 @@ example, only consider addresses last seen after 2020-06-01, you could specify
 
 * JSON FORMAT
 
-With ~--format=json~, the matching contacts come out as a JSON array, e.g.,
+With *--format=json*, the matching contacts come out as a JSON array, e.g.,
 #+begin_example
 [
   {
@@ -124,7 +126,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
@@ -134,7 +136,7 @@ $ mu cfind --format=json --personal | jq -r '.[] | ."last-seen-iso" + " " + .dis
 * INTEGRATION WITH MUTT
 
 You can use *mu cfind* as an external address book server for *mutt*.
-For this to work, add the following to your =muttrc=:
+For this to work, add the following to your _muttrc_:
 
 #+begin_example
 set query_command = "mu cfind --format=mutt-ab '%s'"
@@ -146,7 +148,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 +160,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)}}}