[PATCH] man: Clean up existing documentation

[Valters Jansons <valter.jansons@gmail.com>]

While generating the `location-importer` manual page, tooling flagged
supplemental fixes for location(1) and other man3 pages. Some are minor
style and grammar fixes, as well as AsciiDoc markup fixes, but most of
the changes proposed are gradual drift resulting from codebase changes.
This commit incorporates those suggestions.

In addition to existing manpages being cleaned up, loc_set_log_callback
man3 page is being added, as loc_set_log_fn has been deprecated, and
previously had a manpage created. Without the new page, the existing
manpage would just be a dead-end.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Valters Jansons <valter.jansons@gmail.com>
---
 Makefile.am                      |  1 +
 man/libloc.txt                   |  7 ++---
 man/loc_database_get_country.txt |  1 +
 man/loc_database_lookup.txt      |  3 ++-
 man/loc_database_new.txt         |  8 +++---
 man/loc_new.txt                  |  2 +-
 man/loc_set_log_callback.txt     | 37 ++++++++++++++++++++++++++
 man/loc_set_log_fn.txt           |  8 +++---
 man/loc_set_log_priority.txt     |  4 +--
 man/location.txt                 | 45 +++++++++++++++++++++++++++-----
 10 files changed, 96 insertions(+), 20 deletions(-)
 create mode 100644 man/loc_set_log_callback.txt

diff --git a/Makefile.am b/Makefile.am
index 0d03238..90406ab 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -562,6 +562,7 @@ MANPAGES_3 = \
 	man/loc_database_new.3 \
 	man/loc_get_log_priority.3 \
 	man/loc_new.3 \
+	man/loc_set_log_callback.3 \
 	man/loc_set_log_fn.3 \
 	man/loc_set_log_priority.3
 
diff --git a/man/libloc.txt b/man/libloc.txt
index ec14e16..7d24ed7 100644
--- a/man/libloc.txt
+++ b/man/libloc.txt
@@ -2,7 +2,7 @@
 
 == Name
 
-libloc - A tool to query the IPFire Location database
+libloc - A library to query the IPFire Location database
 
 == Synopsis
 [verse]
@@ -21,7 +21,8 @@ See
 	* link:loc_new[3]
 	* link:loc_get_log_priority[3]
 	* link:loc_set_log_priority[3]
-	* link:loc_get_log_fn[3]
+	* link:loc_set_log_fn[3]
+	* link:loc_set_log_callback[3]
 	* link:loc_database_count_as[3]
 	* link:loc_database_get_as[3]
 	* link:loc_database_get_country[3]
@@ -32,7 +33,7 @@ for more information about the functions available.
 
 == Copying
 
-Copyright (C) 2022 {author}. +
+Copyright (C) 2022 IPFire Development Team. +
 This library is free software; you can redistribute it and/or modify it under the terms
 of the GNU Lesser General Public License as published by the Free Software Foundation;
 either version 2.1 of the License, or (at your option) any later version.
diff --git a/man/loc_database_get_country.txt b/man/loc_database_get_country.txt
index b5ab8ec..a5d7b0c 100644
--- a/man/loc_database_get_country.txt
+++ b/man/loc_database_get_country.txt
@@ -5,6 +5,7 @@
 loc_database_get_country - Fetch country information from the database
 
 == Synopsis
+[verse]
 
 #include <libloc/database.h>
 
diff --git a/man/loc_database_lookup.txt b/man/loc_database_lookup.txt
index b6f780a..9039c3e 100644
--- a/man/loc_database_lookup.txt
+++ b/man/loc_database_lookup.txt
@@ -5,6 +5,7 @@
 loc_database_lookup - Lookup a network from the database
 
 == Synopsis
+[verse]
 
 #include <libloc/database.h>
 
@@ -21,7 +22,7 @@ The lookup functions try finding a network in the database.
 _loc_database_lookup_ takes the IP address as _struct in6_addr_ format which can either
 be a regular IPv6 address or a mapped IPv4 address.
 
-_loc_database_lookup_string_ takes the IP address as string and will parse it automatically.
+_loc_database_lookup_from_string_ takes the IP address as string and will parse it automatically.
 
 == Return Value
 
diff --git a/man/loc_database_new.txt b/man/loc_database_new.txt
index 86a021b..e640ea3 100644
--- a/man/loc_database_new.txt
+++ b/man/loc_database_new.txt
@@ -2,7 +2,7 @@
 
 == Name
 
-loc_database_new - Create a new libloc context
+loc_database_new - Open a location database
 
 == Synopsis
 [verse]
@@ -33,9 +33,9 @@ const char{empty}* loc_database_get_license(struct loc_database{empty}* db);
 
 == Description
 
-loc_database_new() opens a new database from the given file descriptor.
-The file descriptor can be closed after this operation because the function is creating
-its own copy.
+loc_database_new() opens a new database from the given file handle.
+The file handle can be closed after this operation because the function duplicates
+the underlying file descriptor.
 
 If the database could be opened successfully, zero is returned. Otherwise a non-zero
 return code will indicate an error and errno will be set appropriately.
diff --git a/man/loc_new.txt b/man/loc_new.txt
index c1000be..67003de 100644
--- a/man/loc_new.txt
+++ b/man/loc_new.txt
@@ -19,7 +19,7 @@ struct loc_ctx{empty}* loc_unref(struct loc_ctx{empty}* ctx);
 
 == Description
 
-Every operation in libloc requires to set up a context first.
+Every operation in libloc requires a context to be set up first.
 This is done by calling loc_new(3).
 
 Every time another part of your code is holding a reference to the context,
diff --git a/man/loc_set_log_callback.txt b/man/loc_set_log_callback.txt
new file mode 100644
index 0000000..864b885
--- /dev/null
+++ b/man/loc_set_log_callback.txt
@@ -0,0 +1,37 @@
+= loc_set_log_callback(3)
+
+== Name
+
+loc_set_log_callback - Set a callback for log messages
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+typedef void ({empty}*loc_log_callback)(struct loc_ctx{empty}* ctx, void{empty}* data,
+	int priority, const char{empty}* file, int line, const char{empty}* fn,
+	const char{empty}* format, va_list args);
+
+void loc_set_log_callback(struct loc_ctx{empty}* ctx, loc_log_callback callback,
+	void{empty}* data);
+
+== Description
+
+libloc can use the calling application's logging system by setting this callback.
+
+It will be called once for each log message according to the configured log
+priority (see link:loc_set_log_priority[3]).
+
+_data_ is an opaque pointer which is passed through to the callback on every
+invocation.
+
+This function replaces the deprecated link:loc_set_log_fn[3].
+
+== See Also
+
+link:libloc[3]
+
+== Authors
+
+Michael Tremer
diff --git a/man/loc_set_log_fn.txt b/man/loc_set_log_fn.txt
index 00c1854..27da04c 100644
--- a/man/loc_set_log_fn.txt
+++ b/man/loc_set_log_fn.txt
@@ -12,17 +12,19 @@ loc_set_log_fn - Sets the log callback function
 void loc_set_log_fn(struct loc_ctx{empty}* ctx,
 	void ({empty}*log_fn)(struct loc_ctx{empty}* ctx, int priority,
 	const char{empty}* file, int line, const char{empty}* fn, const char{empty}* format,
-	va_list args)
+	va_list args));
 
 == Description
 
-libloc can use the calling application's logging system by setting this callback.
+This function is deprecated and has no effect.
 
-It will be called once for each log message according to the configured log level.
+Use link:loc_set_log_callback[3] to send log messages to the calling
+application's logging system instead.
 
 == See Also
 
 link:libloc[3]
+link:loc_set_log_callback[3]
 
 == Authors
 
diff --git a/man/loc_set_log_priority.txt b/man/loc_set_log_priority.txt
index 76556bb..a561994 100644
--- a/man/loc_set_log_priority.txt
+++ b/man/loc_set_log_priority.txt
@@ -9,7 +9,7 @@ loc_set_log_priority - Sets the log level of a libloc context
 
 #include <libloc/libloc.h>
 
-void loc_set_log_priority(struct loc_ctx{empty}* ctx, int priority)
+void loc_set_log_priority(struct loc_ctx{empty}* ctx, int priority);
 
 == Description
 
@@ -18,7 +18,7 @@ Sets the log priority of the given context. See loc_get_log_priority(3) for more
 == See Also
 
 link:libloc[3]
-link:loc_set_log_fn(3)
+link:loc_set_log_fn[3]
 
 == Authors
 
diff --git a/man/location.txt b/man/location.txt
index 70352d2..b473f6e 100644
--- a/man/location.txt
+++ b/man/location.txt
@@ -5,12 +5,15 @@ location - Query the location database
 
 == SYNOPSIS
 [verse]
-`location export --directory=DIR [--format=FORMAT] [--family=ipv6|ipv4] [ASN|CC ...]`
+`location dump [OUTPUT]`
+`location export [--directory=DIR] [--format=FORMAT] [--family=ipv6|ipv4] [ASN|CC ...]`
+`location export-zone --output=FILE --origin=ORIGIN [--ttl=TTL] [--master=MASTER] [--zonemaster=EMAIL] [--nameserver=NS ...] TYPE`
 `location get-as ASN [ASN...]`
+`location list-bogons [--family=ipv6|ipv4] [--format=FORMAT]`
 `location list-countries [--show-name] [--show-continent]`
-`location list-networks-by-as ASN`
-`location list-networks-by-cc COUNTRY_CODE`
-`location list-networks-by-flags [--anonymous-proxy|--satellite-provider|--anycast|--drop]`
+`location list-networks-by-as [--family=ipv6|ipv4] [--format=FORMAT] ASN`
+`location list-networks-by-cc [--family=ipv6|ipv4] [--format=FORMAT] COUNTRY_CODE`
+`location list-networks-by-flags [--family=ipv6|ipv4] [--format=FORMAT] [--anonymous-proxy|--satellite-provider|--anycast|--drop]`
 `location lookup ADDRESS [ADDRESS...]`
 `location search-as STRING`
 `location update [--cron=daily|weekly|monthly]`
@@ -31,6 +34,14 @@ or countries.
 	+
 	If this option is omitted, the system's database will be opened.
 
+--public-key FILE::
+-k FILE::
+	The path of the public key which is used to verify the database
+	(see 'verify' command).
+	+
+	If this option is omitted, the vendor's public key that is shipped
+	with libloc will be used.
+
 --quiet::
 	Enable quiet mode
 
@@ -39,6 +50,13 @@ or countries.
 
 == COMMANDS
 
+'dump [OUTPUT]'::
+	This command dumps the entire database as text, preceded by a header
+	with its metadata (creation time, vendor, license, and description).
+	+
+	The output is written to the given file, or to stdout if OUTPUT is
+	omitted.
+
 'export [--directory=DIR] [--format=FORMAT] [--family=ipv6|ipv4] [ASN|CC ...]'::
 	This command exports the whole database into the given directory.
 	+
@@ -51,6 +69,21 @@ or countries.
 	If the '--directory' option is omitted, the output will be written to stdout which
 	is useful when you want to load any custom exports straight into nftables or ipset.
 
+'export-zone --output=FILE --origin=ORIGIN [--ttl=TTL] [--master=MASTER] [--zonemaster=EMAIL] [--nameserver=NS ...] TYPE'::
+	This command exports the database as a DNS zone file.
+	+
+	TYPE selects which data is being exported: 'asn' (AS names), 'cc'
+	(country codes of all networks), 'bogons', 'origin' (the AS of each
+	network), 'prefix', or 'everything'.
+	+
+	The zone is written to the file given with '--output' and rooted at
+	the origin given with '--origin'. Both options are required.
+	+
+	The '--ttl', '--master', and '--zonemaster' parameters set the TTL,
+	the zone master, and the email address of the zone's administrator,
+	respectively. Nameservers can be added to the zone by passing
+	'--nameserver' one or more times.
+
 'get-as ASN [ASN...]'::
 	This command returns the name of the owning organisation of the Autonomous
 	System.
@@ -73,7 +106,7 @@ or countries.
 'list-networks-by-cc [--family=[ipv6|ipv4]] [--format=FORMAT] COUNTRY_CODE'::
 	Lists all networks that belong to a country.
 	+
-	The country has to be encoded in ISO3166 Alpha-2 notation.
+	The country has to be encoded in ISO 3166 Alpha-2 notation.
 	+
 	See above for usage of the '--family' and '--format' parameters.
 
@@ -117,7 +150,7 @@ or countries.
 	Shows a short help text on using this program.
 
 '--version'::
-	Shows the program's version and exists.
+	Shows the program's version and exits.
 
 == EXIT CODES
 The 'location' command will normally exit with code zero.
-- 
2.54.0