man: Add pages for top level functions

Signed-off-by: Michael Tremer <michael.tremer@ipfire.org>

Makefile.am

@@ -420,11 +420,18 @@ src_test_signature_LDADD = \
 # ------------------------------------------------------------------------------
 
 MANPAGES = \
-	man/location.8
-
-MANPAGES_TXT  = $(patsubst %.8,%.txt,$(MANPAGES))
-MANPAGES_HTML = $(patsubst %.txt,%.html,$(MANPAGES_TXT))
-MANPAGES_XML  = $(patsubst %.txt,%.xml,$(MANPAGES_TXT))
+	man/libloc.3 \
+	man/location.8 \
+	man/loc_get_log_priority.3 \
+	man/loc_new.3 \
+	man/loc_set_log_fn.3 \
+	man/loc_set_log_priority.3
+
+MANPAGES_TXT   = $(MANPAGES_TXT_3) $(MANPAGES_TXT_8)
+MANPAGES_TXT_3 = $(patsubst %.3,%.txt,$(MANPAGES))
+MANPAGES_TXT_8 = $(patsubst %.8,%.txt,$(MANPAGES))
+MANPAGES_HTML  = $(patsubst %.txt,%.html,$(MANPAGES_TXT))
+MANPAGES_XML   = $(patsubst %.txt,%.xml,$(MANPAGES_TXT))
 
 .PHONY: man
 man: $(MANPAGES) $(MANPAGES_HTML)
@@ -467,6 +474,9 @@ man/%.xml: man/%.txt man/asciidoc.conf
 		-f $(abs_srcdir)/man/asciidoc.conf \
 		-d manpage -b docbook -o $@ $<
 
+man/%.3: man/%.xml
+	$(XSLTPROC_COMMAND_MAN)
+
 man/%.8: man/%.xml
 	$(XSLTPROC_COMMAND_MAN)
 

man/libloc.txt

+= libloc(3)
+
+== Name
+
+libloc - A tool to query the IPFire Location database
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+`pkg-config --cflags --libs libloc`
+
+== Description
+
+`libloc` is a lightweight library which can be used to query the IPFire
+Location database.
+
+See
+
+	* link:loc_new[3]
+	* link:loc_get_log_priority[3]
+	* link:loc_set_log_priority[3]
+	* link:loc_get_log_fn[3]
+
+for more information about the functions available.
+
+== Copying
+
+Copyright (C) 2022 {author}. +
+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.
+
+== See Also
+
+link:location[8]
+
+== Bug Reports
+
+Please report all bugs to the bugtracker at https://bugzilla.ipfire.org/;
+refer to https://wiki.ipfire.org/devel/bugzilla for details.
+
+== Authors
+
+Michael Tremer

man/loc_get_log_priority.txt

+= loc_get_log_priority(3)
+
+== Name
+
+loc_get_log_priority - Fetches the log level of a libloc context
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+int loc_get_log_priority(struct loc_ctx{empty}* ctx);
+
+== Description
+
+Returns the log priority of the given context.
+
+The returned integer is a valid syslog log level as defined in syslog(3).
+
+The default value is LOG_ERR.
+
+== See Also
+
+link:libloc[3]
+
+== Authors
+
+Michael Tremer

man/loc_new.txt

+= loc_new(3)
+
+== Name
+
+loc_new - Create a new libloc context
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+struct loc_ctx;
+
+int loc_new(struct loc_ctx{empty}*{empty}* ctx);
+
+struct loc_ctx{empty}* loc_ref(struct loc_ctx{empty}* ctx);
+
+struct loc_ctx{empty}* loc_unref(struct loc_ctx{empty}* ctx);
+
+== Description
+
+Every operation in libloc requires to set up a context first.
+This is done by calling loc_new(3).
+
+Every time another part of your code is holding a reference to the context,
+you will need to call loc_ref() to increase the reference counter.
+If you no longer need the context, you will need to call loc_unref().
+
+== See Also
+
+link:libloc[3]
+
+== Authors
+
+Michael Tremer

man/loc_set_log_fn.txt

+= loc_set_log_fn(3)
+
+== Name
+
+loc_set_log_fn - Sets the log callback function
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+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)
+
+== 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 level.
+
+== See Also
+
+link:libloc[3]
+
+== Authors
+
+Michael Tremer

man/loc_set_log_priority.txt

+= loc_set_log_priority(3)
+
+== Name
+
+loc_set_log_priority - Sets the log level of a libloc context
+
+== Synopsis
+[verse]
+
+#include <libloc/libloc.h>
+
+void loc_set_log_priority(struct loc_ctx{empty}* ctx, int priority)
+
+== Description
+
+Sets the log priority of the given context. See loc_get_log_priority(3) for more details.
+
+== See Also
+
+link:libloc[3]
+link:loc_set_log_fn(3)
+
+== Authors
+
+Michael Tremer