man: Clean up existing documentation

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>
Signed-off-by: Michael Tremer <michael.tremer@ipfire.org>

diff --git a/Makefile.am b/Makefile.am
index 0d0323803a625846821b85d526923cabb5762208..90406ab1135283d3420ef42dedda1226ce3e725d 100644 (file)
--- 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 ec14e166a864b8cefd75e3468abba3eb2061b16a..7d24ed72291ce6108f59c4b70347c69a4678d66f 100644 (file)
--- 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 b5ab8ec3fcb49540fb48c86e9f32b10569498f5c..a5d7b0c6177f1871f911cccd51854de8f8946fd6 100644 (file)
--- 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 b6f780acca4b0375ce5a69ef6f53cd9f55efee4f..9039c3e77a5689c7e19cdba6a104ffa1f79b2b7e 100644 (file)
--- 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 86a021b915785b5d7fec362a52f91053d181077c..e640ea3bc67d6b099e89076c9dcc3ef140c4cb26 100644 (file)
--- 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 c1000be3df3ca60a6dd401c11c414b8295c255f5..67003deb2e0fd1655d928b199b6778832b53652a 100644 (file)
--- 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 (file)
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 00c185456a3ec68f8d3548c1c66e741152bb5bea..27da04c744e05671ca36015f0817778594748e5e 100644 (file)
--- 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 76556bbece171d5d1eeddc4958457ea5330e2513..a5619943c24e8fe205b0a3fde6e6a7893cdb8cab 100644 (file)
--- 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 70352d2be23648e0ce772e7aa4519ee732df031b..b473f6eefc43bad60a829a3e07375a215779556c 100644 (file)
--- 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.