[PATCH] doc: arrange search prefix documentation in a definition list

[Jani Nikula]

Having first a list of prefixes followed by detailed descriptions was
viable when we didn't have all that many prefixes. Now, arranging the
prefix descriptions in a definition list makes more sense.

While at it, include all the supported prefix forms, especially some
missing regex ones.
---
 doc/man7/notmuch-search-terms.rst | 237 ++++++++++++++++++--------------------
 1 file changed, 112 insertions(+), 125 deletions(-)

diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
index 637f7777dd93..6d2bf62ad7a1 100644
--- a/doc/man7/notmuch-search-terms.rst
+++ b/doc/man7/notmuch-search-terms.rst
@@ -30,137 +30,124 @@ recipient headers.
 As a special case, a search string consisting of exactly a single
 asterisk ("\*") will match all messages.
 
+Search prefixes
+---------------
+
 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>
-
--  from:/<regex>/
-
--  to:<name-or-address>
-
--  subject:<word-or-quoted-phrase>
-
--  subject:/<regex>/
-
--  attachment:<word>
-
--  mimetype:<word>
-
--  tag:<tag> (or is:<tag>)
-
--  id:<message-id>
-
--  thread:<thread-id>
-
--  folder:<maildir-folder>
-
--  path:<directory-path> or path:<directory-path>/**
-
--  date:<since>..<until>
-
--  lastmod:<initial-revision>..<final-revision>
-
--  query:<name>
+indicate user-supplied values).
 
--  property:<key>=<value>
-
-The **from:** prefix is used to match the name or address of the sender
-of an email message.
-
-The **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 **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
-**subject:**.
-
-If notmuch is built with **Xapian Field Processors** (see below) the
-**from:** and **subject** prefix can be also used to restrict the
-results to those whose from/subject value matches a regular expression
-(see **regex(7)**) delimited with //.
-
-::
+If notmuch is built with **Xapian Field Processors** (see below) some
+of the prefixes with <regex> forms can be also used to restrict the
+results to those whose value matches a regular expression (see
+**regex(7)**) delimited with //, for example::
 
    notmuch search 'from:/bob at .*[.]example[.]com/'
 
-The **attachment:** prefix can be used to search for specific filenames
-(or extensions) of attachments to email messages.
-
-The **mimetype:** prefix will be used to match text from the
-content-types of MIME parts within email messages (as specified by the
-sender).
-
-For **tag:** and **is:** valid tag values include **inbox** and
-**unread** by default for new messages added by **notmuch new** as well
-as any other tag values added manually with **notmuch tag**.
-
-For **id:**, message ID values are the literal contents of the
-Message-ID: header of email messages, but without the '<', '>'
-delimiters.
-
-The **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
-**notmuch search**
-
-The **path:** prefix searches for email messages that are in
-particular directories within the mail store. The directory must be
-specified relative to the top-level maildir (and without the leading
-slash). By default, **path:** matches messages in the specified
-directory only. The "/\*\*" suffix can be used to match messages in
-the specified directory and all its subdirectories recursively.
-**path:""** matches messages in the root of the mail store and,
-likewise, **path:\*\*** matches all messages.
-
-The **folder:** prefix searches for email messages by maildir or MH
-folder. For MH-style folders, this is equivalent to **path:**. For
-maildir, this includes messages in the "new" and "cur"
-subdirectories. The exact syntax for maildir folders depends on your
-mail configuration. For maildir++, **folder:""** matches the inbox
-folder (which is the root in maildir++), other folder names always
-start with ".", and nested folders are separated by "."s, such as
-**folder:.classes.topology**. For "file system" maildir, the inbox is
-typically **folder:INBOX** and nested folders are separated by
-slashes, such as **folder:classes/topology**.
-
-Both **path:** and **folder:** will find a message if *any* copy of
-that message is in the specific directory/folder.
-
-The **date:** prefix can be used to restrict the results to only
-messages within a particular time range (based on the Date: header) with
-a range syntax of:
-
-date:<since>..<until>
-
-See **DATE AND TIME SEARCH** below for details on the range expression,
-and supported syntax for <since> and <until> date and time expressions.
-
-The time range can also be specified using timestamps 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.
-
-The **lastmod:** prefix can be used to restrict the result by the
-database revision number of when messages were last modified (tags
-were added/removed or filenames changed).  This is usually used in
-conjunction with the **--uuid** argument to **notmuch search**
-to find messages that have changed since an earlier query.
-
-The **query:** prefix allows queries to refer to previously saved
-queries added with **notmuch-config(1)**. Named queries are only
-available if notmuch is built with **Xapian Field Processors** (see
-below).
-
-The **property:** prefix searches for messages with a particular
-<key>=<value> property pair. Properties are used internally by notmuch
-(and extensions) to add metadata to messages. A given key can be
-present on a given message with several different values.  See
-**notmuch-properties(7)** for more details.
+from:<name-or-address> or from:/<regex>/
+    The **from:** prefix is used to match the name or address of
+    the sender of an email message.
+
+to:<name-or-address>
+    The **to:** prefix is used to match the names or addresses of any
+    recipient of an email message, (whether To, Cc, or Bcc).
+
+subject:<word-or-quoted-phrase> or subject:/<regex>/
+    Any term prefixed with **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 **subject:**.
+
+attachment:<word>
+    The **attachment:** prefix can be used to search for specific
+    filenames (or extensions) of attachments to email messages.
+
+mimetype:<word>
+    The **mimetype:** prefix will be used to match text from the
+    content-types of MIME parts within email messages (as specified by
+    the sender).
+
+tag:<tag> or tag:/<regex>/ or is:<tag> or is:/<regex>/
+    For **tag:** and **is:** valid tag values include **inbox** and
+    **unread** by default for new messages added by **notmuch new** as
+    well as any other tag values added manually with **notmuch tag**.
+
+id:<message-id> or mid:<message-id> or mid:/<regex>/
+    For **id:** and **mid:**, message ID values are the literal
+    contents of the Message-ID: header of email messages, but without
+    the '<', '>' delimiters.
+
+thread:<thread-id>
+    The **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 **notmuch search**
+
+path:<directory-path> or path:<directory-path>/** or path:/<regex>/
+    The **path:** prefix searches for email messages that are in
+    particular directories within the mail store. The directory must
+    be specified relative to the top-level maildir (and without the
+    leading slash). By default, **path:** matches messages in the
+    specified directory only. The "/\*\*" suffix can be used to match
+    messages in the specified directory and all its subdirectories
+    recursively. **path:""** matches messages in the root of the mail
+    store and, likewise, **path:\*\*** matches all messages.
+
+    **path:** will find a message if *any* copy of that message is in
+    the specific directory.
+
+folder:<maildir-folder> or folder:/<regex>/
+    The **folder:** prefix searches for email messages by maildir or
+    MH folder. For MH-style folders, this is equivalent to
+    **path:**. For maildir, this includes messages in the "new" and
+    "cur" subdirectories. The exact syntax for maildir folders depends
+    on your mail configuration. For maildir++, **folder:""** matches
+    the inbox folder (which is the root in maildir++), other folder
+    names always start with ".", and nested folders are separated by
+    "."s, such as **folder:.classes.topology**. For "file system"
+    maildir, the inbox is typically **folder:INBOX** and nested
+    folders are separated by slashes, such as
+    **folder:classes/topology**.
+
+    **folder:** will find a message if *any* copy of that message is
+    in the specific folder.
+
+date:<since>..<until> or date:<date>
+    The **date:** prefix can be used to restrict the results to only
+    messages within a particular time range (based on the Date:
+    header).
+
+    See **DATE AND TIME SEARCH** below for details on the range
+    expression, and supported syntax for <since> and <until> date and
+    time expressions.
+
+    The time range can also be specified using timestamps 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.
+
+lastmod:<initial-revision>..<final-revision>
+    The **lastmod:** prefix can be used to restrict the result by the
+    database revision number of when messages were last modified (tags
+    were added/removed or filenames changed). This is usually used in
+    conjunction with the **--uuid** argument to **notmuch search** to
+    find messages that have changed since an earlier query.
+
+query:<name>
+    The **query:** prefix allows queries to refer to previously saved
+    queries added with **notmuch-config(1)**. Named queries are only
+    available if notmuch is built with **Xapian Field Processors**
+    (see below).
+
+property:<key>=<value>
+    The **property:** prefix searches for messages with a particular
+    <key>=<value> property pair. Properties are used internally by
+    notmuch (and extensions) to add metadata to messages. A given key
+    can be present on a given message with several different values.
+    See **notmuch-properties(7)** for more details.
 
 Operators
 ---------
-- 
2.11.0