4 files changed, 248 insertions, 233 deletions

diff --git a/doc/man/README b/doc/man/README
index fb95a11f2..b1c95b754 100644
--- a/doc/man/README
+++ b/doc/man/README
@@ -5,4 +5,4 @@ TODO:
 
 * incomplete pages:
   - gnunet-timeout
-  
\ No newline at end of file
+  - gnunet-gns: Make use of .Ex macro for DIAGNOSTICS section
\ No newline at end of file
diff --git a/doc/man/gnunet-gns.1 b/doc/man/gnunet-gns.1
index 750c72d95..decb8f569 100644
--- a/doc/man/gnunet-gns.1
+++ b/doc/man/gnunet-gns.1
@@ -1,60 +1,75 @@
-.TH GNUNET\-GNS 1 "March 23, 2018" "GNUnet"
-.SH NAME
-gnunet\-gns \- Access to GNU Name System
-.SH SYNOPSIS
-.B gnunet\-gns
-.RI [ options ]
-.SH DESCRIPTION
-\fBgnunet\-gns\fP can be used to lookup and process GNU Name Service
-names.
-.SH OPTIONS
-.IP "\-c FILENAME,  \-\-config=FILENAME"
+.Dd March 23, 2018
+.Dt GNUNET-GNS 1
+.Os
+.Sh NAME
+.Nm gnunet-gns
+.Nd
+access to GNU Name System
+.Sh SYNOPSIS
+.Nm
+.Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
+.Op Fl h | \-help
+.Op Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
+.Op Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME
+.Op Fl r | \-raw
+.Op Fl t Ar TYPE | Fl \-type= Ns Ar TYPE
+.Op Fl u Ar NAME | Fl \-lookup= Ns Ar NAME
+.Op Fl v | \-version
+.Sh DESCRIPTION
+.Nm
+can be used to lookup and process GNU Name Service names.
+.Bl -tag -width Ds
+.It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
 Use the configuration file FILENAME.
-.IP "\-r, \-\-raw"
-No unneeded output.
-This is a quiet mode where only important information is displayed.
-For example a lookup for an IP address will only yield the IP address,
-no descriptive text.
-.IP "\-h, \-\-help"
+.It Fl h | \-help
 Print short help on options.
-.IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL"
+.It Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
 Use LOGLEVEL for logging.
 Valid values are DEBUG, INFO, WARNING and ERROR.
-.IP "\-u NAME, \-\-lookup=NAME"
-Name to lookup.
-Resolve the specified name using the GNU Name System.
-.IP "\-t TYPE, \-\-type=TYPE"
+.It Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME
+Write logs to FILENAME.
+.It Fl r | \-raw
+No unneeded output.
+This is a quiet mode where only important information is displayed.
+For example a lookup for an IP address will only yield the IP address, no descriptive text.
+.It Fl t Ar TYPE | Fl \-type= Ns Ar TYPE
 Resource Record Type (TYPE) to look for.
-Supported TYPE's are: A, AAAA, CNAME, NS, PKEY, PSEU, TLSA, SRV, SOA,
-MX, LEHO, VPN, REV, PTR, TXT.
+Supported TYPE's are: A, AAAA, CNAME, NS, PKEY, PSEU, TLSA, SRV, SOA, MX, LEHO, VPN, REV, PTR, TXT.
 Defaults to "A".
-.IP "\-v, \-\-version"
+.It Fl u Ar NAME | Fl \-lookup= Ns Ar NAME
+Name to lookup.
+Resolve the specified name using the GNU Name System.
+.It Fl v | \-version
 Print GNUnet version number.
-.SH RETURN VALUE
-gnunet\-gns will return 0 on success, 1 on internal failures, 2 on
+.El
+.Sh DIAGNOSTICS
+.Nm
+will return 0 on success, 1 on internal failures, 2 on
 launch failures, 4 if the given name is not configured to use GNS.
-.SH BUGS
-Report bugs by using Mantis <https://bugs.gnunet.org/> or by sending
-electronic mail to <gnunet\-developers@gnu.org>
-.SH SEE ALSO
-\fBgnunet\-namestore\fP(1), \fBgnunet\-identity\fP(1)
-.PP
-The full documentation for
-.B gnunet
-is maintained as a Texinfo manual.  If the
-.B info
-and
-.B gnunet
-programs are properly installed at your site, the command
-.IP
-.B info gnunet
-.PP
+.Sh SEE ALSO
+.Xr gnunet-namestore 1 ,
+.Xr gnunet-identity 1
+.sp
+The full documentation for gnunet is maintained as a Texinfo manual.
+If the
+.Xr info 1
+and gnunet programs are properly installed at your site, the command
+.Pp
+.Dl info gnunet
+.Pp
 should give you access to the complete handbook,
-.IP
-.B info gnunet-c-tutorial
-.PP
+.Pp
+.Dl info gnunet-c-tutorial
+.Pp
 will give you access to a tutorial for developers.
-.PP
-Depending on your installation, this information is also
-available in
-\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7).
+.sp
+Depending on your installation, this information is also available in
+.Xr gnunet 7 and
+.Xr gnunet-c-tutorial 7 .
+.\".Sh HISTORY
+.\".Sh AUTHORS
+.Sh BUGS
+Report bugs by using
+.Lk https://bugs.gnunet.org
+or by sending electronic mail to
+.Aq Mt gnunet-developers@gnu.org .
diff --git a/doc/man/gnunet-scrypt.1 b/doc/man/gnunet-scrypt.1
index 545af37e9..915acbb7a 100644
--- a/doc/man/gnunet-scrypt.1
+++ b/doc/man/gnunet-scrypt.1
@@ -1,51 +1,65 @@
-.TH GNUNET-SCRYPT 1 "September 13, 2014" "GNUnet"
-.SH NAME
-gnunet\-scrypt \- Manipulate GNUnet proof of work files.
-.SH SYNOPSIS
-.B gnunet\-scrypt
-.RI [ options ]
-.SH DESCRIPTION
-\fBgnunet\-scrypt\fP is a command line tool to manipulate GNUnet proof of work files.
-.SH OPTIONS
-.IP "\-b BITS,  \-\-bits=BITS"
+.Dd September 13, 2014
+.Dt GNUNET-SCRYPT 1
+.Os
+.Sh NAME
+.Nm gnunet-scrypt
+.Nd
+manipulate GNUnet proof of work files
+.Sh SYNOPSIS
+.Nm
+.Op Fl b Ar BITS | Fl \-bits= Ns Ar BITS
+.Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
+.Op Fl h | \-help
+.Op Fl k Ar FILENAME | Fl \-keyfile= Ns Ar FILENAME
+.Op Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
+.Op Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME
+.Op Fl o Ar FILENAME | Fl \-outfile= Ns Ar FILENAME
+.Op Fl t Ar DELAY | Fl \-timeout= Ns Ar DELAY
+.Op Fl v | \-version
+.Sh DESCRIPTION
+.Nm
+is a command line tool to manipulate GNUnet proof of work files.
+.Bl -tag -width Ds
+.It Fl b Ar BITS | Fl \-bits= Ns Ar BITS
 Number of bits to require for the proof of work.
-.IP "\-c FILENAME,  \-\-config=FILENAME"
+.It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
 Use the configuration file FILENAME.
-.IP "\-h, \-\-help"
+.It Fl h | \-help
 Print short help on options.
-.IP "\-k FILE, \-\-keyfile=FILE"
+.It Fl k Ar FILENAME | Fl \-keyfile= Ns Ar FILENAME
 File with private key, otherwise default is used.
-.IP "\-L LOGLEVEL, \-\-loglevel=LOGLEVEL"
-Use LOGLEVEL for logging.  Valid values are DEBUG, INFO, WARNING and ERROR.
-.IP "\-l LOGFILE, \-\-logfile=LOGFILE"
-Configure logging to write logs to LOGFILE.
-.IP "\-o FILE, \-\-outfile=FILE"
+.It Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
+Use LOGLEVEL for logging.
+Valid values are DEBUG, INFO, WARNING and ERROR.
+.It Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME
+Configure logging to write logs to FILENAME.
+.It Fl o Ar FILENAME | Fl \-outfile= Ns Ar FILENAME
 File with proof of work, otherwise default is used.
-.IP "\-t TIME, \-\-timeout=TIME"
+.It Fl t Ar DELAY | Fl \-timeout= Ns Ar DELAY
 Time to wait between calculations.
-.IP "\-v, \-\-version"
+.It Fl v | \-version
 Print GNUnet version number.
-.SH BUGS
-Report bugs by using Mantis <https://bugs.gnunet.org/> or by sending
-electronic mail to <gnunet\-developers@gnu.org>
-.SH SEE ALSO
-The full documentation for
-.B gnunet
-is maintained as a Texinfo manual.
+.Sh SEE ALSO
+The full documentation for gnunet is maintained as a Texinfo manual.
 If the
-.B info
-and
-.B gnunet
-programs are properly installed at your site, the command
-.IP
-.B info gnunet
-.PP
+.Xr info 1
+and gnunet programs are properly installed at your site, the command
+.Pp
+.Dl info gnunet
+.Pp
 should give you access to the complete handbook,
-.IP
-.B info gnunet-c-tutorial
-.PP
+.Pp
+.Dl info gnunet-c-tutorial
+.Pp
 will give you access to a tutorial for developers.
-.PP
-Depending on your installation, this information is also
-available in
-\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7).
+.sp
+Depending on your installation, this information is also available in
+.Xr gnunet 7 and
+.Xr gnunet-c-tutorial 7 .
+.\".Sh HISTORY
+.\".Sh AUTHORS
+.Sh BUGS
+Report bugs by using
+.Lk https://bugs.gnunet.org
+or by sending electronic mail to
+.Aq Mt gnunet-developers@gnu.org .
diff --git a/doc/man/gnunet-search.1 b/doc/man/gnunet-search.1
index af72d369d..c1bb7c1e4 100644
--- a/doc/man/gnunet-search.1
+++ b/doc/man/gnunet-search.1
@@ -1,121 +1,108 @@
-.TH GNUNET-SEARCH "1" "February 25, 2012" "0.9.6" "GNUnet"
-.SH NAME
-gnunet\-search \- a command line interface to search for content on GNUnet
-.SH SYNOPSIS
-.B gnunet\-search
-[\fIOPTIONS\fR] [+]\fIKEYWORD\fR [[+]\fIKEYWORD\fR]*
-
-.B gnunet\-search
-[\fIOPTIONS\fR] [+]\fIURI\fR
-.SH DESCRIPTION
-.PP
-Search for content on GNUnet. The keywords are case\-sensitive.
-gnunet\-search can be used both for a search in the global namespace
-as well as for searching a private subspace.
-.TP
-\fB\-a \fILEVEL\fR, \fB\-\-anonymity=\fILEVEL\fR
-
-The \fB\-a\fR option can be used to specify additional anonymity
-constraints. If set to 0, GNUnet will try to download the file as fast
-as possible, including using non-anonymous methods.  If you set it to
-1 (default), you use the standard anonymous routing algorithm (which
-does not explicitly leak your identity).  However, a powerful
-adversary may still be able to perform traffic analysis (statistics)
-to over time infer data about your identity.  You can gain better
-privacy by specifying a higher level of anonymity, which increases the
-amount of cover traffic your own traffic will get, at the expense of
-performance.  Note that your download performance is not only
-determined by your own anonymity level, but also by the anonymity
-level of the peers publishing the file.  So even if you download with
-anonymity level 0, the peers publishing the data might be sharing with
-a higher anonymity level, which in this case will determine
-performance.  Also, peers that cache content in the network always use
-anonymity level 1.
-
-This option can be used to limit requests further than that. In
-particular, you can require GNUnet to receive certain amounts of
-traffic from other peers before sending your queries. This way, you
-can gain very high levels of anonymity \- at the expense of much more
-traffic and much higher latency. So set it only if you really believe
-you need it.
-
-The definition of ANONYMITY\-RECEIVE is the following.  0 means no
-anonymity is required.  Otherwise a value of 'v' means that 1 out of v
-bytes of "anonymous" traffic can be from the local user, leaving 'v-1'
-bytes of cover traffic per byte on the wire.  Thus, if GNUnet routes n
-bytes of messages from foreign peers (using anonymous routing), it may
-originate n/(v-1) bytes of queries in the same time\-period. The
-time\-period is twice the average delay that GNUnet defers forwarded
-queries.
-
-The default is 1 and this should be fine for most users.  Also notice
-that if you choose very large values, you may end up having no
-throughput at all, especially if many of your fellow GNUnet\-peers all
-do the same.
-
-.TP
-\fB\-c \fIFILENAME\fR, \fB\-\-config=\fIFILENAME\fR
+.Dd February 25, 2012
+.Dt GNUNET-SEARCH 1
+.Os
+.Sh NAME
+.Nm gnunet-search
+.Nd
+a command line interface to search for content on GNUnet
+.Sh SYNOPSIS
+.Nm
+.Op Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL
+.Op Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
+.Op Fl h | \-help
+.Op Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
+.Op Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME
+.Op Fl o Ar FILENAME | Fl \-output= Ns Ar FILENAME
+.Op Fl n | \-no-network
+.Op Fl N Ar VALUE | Fl \-results= Ns Ar VALUE
+.Op Fl t Ar DELAY | Fl \-timeout= Ns Ar DELAY
+.Op Fl v | \-version
+.Op Fl V | \-verbose
+.Ao KEYWORD Ac Ao +KEYWORD Ac | Ao Ar URI Ac Ao Ar +URI Ac
+.Sh DESCRIPTION
+Search for content on GNUnet.
+The keywords are case-sensitive.
+.Nm
+can be used both for a search in the global namespace as well as for searching a private subspace.
+.Bl -tag -width Ds
+.It Fl a Ar LEVEL | Fl \-anonymity= Ns Ar LEVEL
+The \fB\-a\fR option can be used to specify additional anonymity constraints.
+If set to 0, GNUnet will try to download the file as fast as possible, including using non-anonymous methods.
+If you set it to 1 (default), you use the standard anonymous routing algorithm (which does not explicitly leak your identity).
+However, a powerful adversary may still be able to perform traffic analysis (statistics) to over time infer data about your identity.
+You can gain better privacy by specifying a higher level of anonymity, which increases the amount of cover traffic your own traffic will get, at the expense of performance.
+Note that your download performance is not only determined by your own anonymity level, but also by the anonymity level of the peers publishing the file.
+So even if you download with anonymity level 0, the peers publishing the data might be sharing with a higher anonymity level, which in this case will determine performance.
+Also, peers that cache content in the network always use anonymity level 1.
+.sp
+This option can be used to limit requests further than that.
+In particular, you can require GNUnet to receive certain amounts of traffic from other peers before sending your queries.
+This way, you can gain very high levels of anonymity \- at the expense of much more traffic and much higher latency.
+So set it only if you really believe you need it.
+.sp
+The definition of ANONYMITY\-RECEIVE is the following.
+0 means no anonymity is required.
+Otherwise a value of 'v' means that 1 out of v bytes of "anonymous" traffic can be from the local user, leaving 'v-1' bytes of cover traffic per byte on the wire.
+Thus, if GNUnet routes n bytes of messages from foreign peers (using anonymous routing), it may originate n/(v-1) bytes of queries in the same time\-period.
+The time\-period is twice the average delay that GNUnet defers forwarded queries.
+.sp
+The default is 1 and this should be fine for most users.
+Also notice that if you choose very large values, you may end up having no throughput at all, especially if many of your fellow GNUnet\-peers all do the same.
+.It Fl c Ar FILENAME | Fl \-config= Ns Ar FILENAME
 use config file (defaults: ~/.config/gnunet.conf)
-
-.TP
-\fB\-h\fR, \fB\-\-help\fR
+.It Fl h | \-help
 print help page
-
-.TP
-\fB\-L \fILOGLEVEL\fR, \fB\-\-loglevel=\fILOGLEVEL\fR
-Change the loglevel.  Possible values for LOGLEVEL are
-ERROR, WARNING, INFO and DEBUG.
-
-.TP
-\fB\-o \fIFILENAME\fR, \fB\-\-output=\fIFILENAME\fR
+.It Fl L Ar LOGLEVEL | Fl \-loglevel= Ns Ar LOGLEVEL
+Change the loglevel.
+Possible values for LOGLEVEL are ERROR, WARNING, INFO and DEBUG.
+.It Fl l Ar FILENAME | Fl \-logfile= Ns Ar FILENAME
+Write logs to FILENAME.
+.It Fl o Ar FILENAME | Fl \-output= Ns Ar FILENAME
 Writes a GNUnet directory containing all of the search results to FILENAME.
-
-.TP
-\fB\-n\fR, \fB\-\-no-network\fR
+.It Fl n | \-no-network
 Only search locally, do not forward requests to other peers.
-
-.TP
-\fB\-N \fIVALUE\fR, \fB\-\-results=\fIVALUE\fR
-automatically terminate the search after receiving VALUE results.
-
-.TP
-\fB\-t \fIDELAY\fR, \fB\-\-timeout=\fIDELAY\fR
-Automatically timeout search after DELAY.  The value given must be a
-number followed by a space and a time unit, for example "500 ms".
-Note that the quotes are required on the shell.  Otherwise the search
-runs until gnunet\-search is aborted with CTRL\-C.
-
-.TP
-\fB\-v\fR, \fB\-\-version\fR
+.It Fl N Ar VALUE | Fl \-results= Ns Ar VALUE
+Automatically terminate the search after receiving VALUE results.
+.It Fl t Ar DELAY | Fl \-timeout= Ns Ar DELAY
+Automatically timeout search after DELAY.
+The value given must be a number followed by a space and a time unit, for example "500 ms".
+Note that the quotes are required on the shell.
+Otherwise the search runs until gnunet\-search is aborted with CTRL\-C.
+.It Fl v | \-version
 print the version number
-
-.TP
-\fB\-V\fR, \fB\-\-verbose\fR
+.It Fl V | \-verbose
 print meta data from search results as well
-.SH NOTES
-
-You can run gnunet\-search with an URI instead of a keyword.  The URI
-can have the format for a namespace search or for a keyword search.
+.El
+You can run gnunet\-search with an URI instead of a keyword.
+The URI can have the format for a namespace search or for a keyword search.
 For a namespace search, the format is
-gnunet://fs/sks/NAMESPACE/IDENTIFIER.  For a keyword search, use
-gnunet://fs/ksk/KEYWORD[+KEYWORD]*.  If the format does not correspond
-to a GNUnet URI, GNUnet will automatically assume that keywords are
-supplied directly.
-
+.Pp
+.Dl gnunet://fs/sks/NAMESPACE/IDENTIFIER
+.Pp
+For a keyword search, use
+.Pp
+.Dl gnunet://fs/ksk/KEYWORD[+KEYWORD]*
+.Pp
+If the format does not correspond to a GNUnet URI, GNUnet will automatically assume that keywords are supplied directly.
+.sp
 If multiple keywords are passed, gnunet-search will look for content
-matching any of the keywords.  The prefix "+" makes a keyword
-mandatory.
-
-# gnunet\-search "Das Kapital"
-
-searches for content matching the keyword "Das Kapital".  Whereas
-
-# gnunet\-search +Das +Kapital
-
+matching any of the keywords.
+The prefix "+" makes a keyword mandatory.
+.Sh FILES
+.Pa ~/.config/gnunet.conf
+GNUnet configuration file; specifies the default value for the timeout
+.Sh EXAMPLES
+.Pp
+.Dl $ gnunet\-search "Das Kapital"
+.Pp
+Searches for content matching the keyword "Das Kapital".
+.Pp
+.Dl $ gnunet\-search +Das +Kapital
+.Pp
 Searches for content matching both mandatory keywords "Das" and "Kapital".
-
+.sp
 Search results are printed by gnunet\-search like this:
-.P
+.Pp
 .ad l
         gnunet\-download \-o "COPYING" gnunet://fs/chk/HASH1.HASH2.SIZE
 
@@ -124,38 +111,37 @@ Search results are printed by gnunet\-search like this:
                 Mime-type: text/plain
 .ad b
 
-The first line contains the command to run to download the file.  The
-suggested filename in the example is COPYING.  The GNUnet URI consists
-of the key and query hash of the file and finally the size of the
-file.  After the command to download the file GNUnet will print
-meta\-data about the file as advertised in the search result, here
-"The GNU General Public License" and the mime\-type (see the options
-for gnunet\-publish on how to supply meta-data by hand).
-
-.SH FILES
-.TP
-~/.config/gnunet.conf
-GNUnet configuration file; specifies the default value for the timeout
-.SH "REPORTING BUGS"
-Report bugs to <https://bugs.gnunet.org/> or by sending electronic mail to <gnunet\-developers@gnu.org>
-.SH "SEE ALSO"
-\fBgnunet\-fs\-gtk\fP(1), \fBgnunet\-publish\fP(1), \fBgnunet\-download\fP(1), \fBgnunet.conf\fP(5),
-The full documentation for
-.B gnunet
-is maintained as a Texinfo manual.  If the
-.B info
-and
-.B gnunet
-programs are properly installed at your site, the command
-.IP
-.B info gnunet
-.PP
+The first line contains the command to run to download the file.
+The suggested filename in the example is COPYING.
+The GNUnet URI consists of the key and query hash of the file and finally the size of the file.
+After the command to download the file GNUnet will print meta\-data about the file as advertised in the search result, here "The GNU General Public License" and the mime\-type (see the options for gnunet\-publish on how to supply meta-data by hand).
+.Sh SEE ALSO
+.Xr gnunet-fs-gtk 1 ,
+.Xr gnunet\-publish 1 ,
+.Xr gnunet\-download 1 ,
+.Xr gnunet.conf 5
+.sp
+The full documentation for gnunet is maintained as a Texinfo manual.
+If the
+.Xr info 1
+and gnunet programs are properly installed at your site, the command
+.Pp
+.Dl info gnunet
+.Pp
 should give you access to the complete handbook,
-.IP
-.B info gnunet-c-tutorial
-.PP
+.Pp
+.Dl info gnunet-c-tutorial
+.Pp
 will give you access to a tutorial for developers.
-.PP
-Depending on your installation, this information is also
-available in
-\fBgnunet\fP(7) and \fBgnunet-c-tutorial\fP(7).
+.sp
+Depending on your installation, this information is also available in
+.Xr gnunet 7 and
+.Xr gnunet-c-tutorial 7 .
+.\".Sh HISTORY
+.\"gnunet-search first appeared in GNUnet 0.9.6.
+.\".Sh AUTHORS
+.Sh BUGS
+Report bugs by using
+.Lk https://bugs.gnunet.org
+or by sending electronic mail to
+.Aq Mt gnunet-developers@gnu.org .