Merge branch 'docs'

5 files changed, 138 insertions, 27 deletions

diff --git a/Makefile b/Makefile
index 53b8642..0557067 100644
--- a/Makefile
+++ b/Makefile
@@ -51,10 +51,12 @@ man:
 	mkdir -pv -- "$(PREFIX)$(DESTDIR)/share/man/man3"
 	mkdir -pv -- "$(PREFIX)$(DESTDIR)/share/man/man5"
 	mkdir -pv -- "$(PREFIX)$(DESTDIR)/share/man/man7"
-	scdoc < share/doc/bashtard.1.scd | gzip -cn9 > "$(PREFIX)$(DESTDIR)/share/man/man1/bashtard.1.gz"
-	scdoc < share/doc/bashtard.3.scd | gzip -cn9 > "$(PREFIX)$(DESTDIR)/share/man/man3/bashtard.3.gz"
-	scdoc < share/doc/bashtard.5.scd | gzip -cn9 > "$(PREFIX)$(DESTDIR)/share/man/man5/bashtard.5.gz"
-	scdoc < share/doc/bashtard.7.scd | gzip -cn9 > "$(PREFIX)$(DESTDIR)/share/man/man7/bashtard.7.gz"
+	bocs -n "bashtard" \
+		bin/bashtard **/*.bash
+	gzip -cn9 < "bashtard.1.man" > "$(PREFIX)$(DESTDIR)/share/man/man1/bashtard.1.gz" && rm "bashtard.1.man"
+	gzip -cn9 < "bashtard.3.man" > "$(PREFIX)$(DESTDIR)/share/man/man1/bashtard.1.gz" && rm "bashtard.1.man"
+	gzip -cn9 < "bashtard.5.man" > "$(PREFIX)$(DESTDIR)/share/man/man1/bashtard.1.gz" && rm "bashtard.1.man"
+	gzip -cn9 < "bashtard.7.man" > "$(PREFIX)$(DESTDIR)/share/man/man1/bashtard.1.gz" && rm "bashtard.1.man"
 	scdoc < share/doc/playbooks.d.7.scd | gzip -cn9 > "$(PREFIX)$(DESTDIR)/share/man/man7/playbooks.d.7.gz"
 
 pkg-debian:
diff --git a/bin/bashtard b/bin/bashtard
index cfe4d00..4521669 100755
--- a/bin/bashtard
+++ b/bin/bashtard
@@ -4,6 +4,12 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+## :bocs:
+## :section: 3
+## :heading: variables
+## :name:    BASHTARD_BIN
+##
+## The absolute path to the *bashtard* binary.
 BASHTARD_BIN="$0"
 BASHTARD_NAME="$(basename "$0")"
 BASHTARD_ETCDIR="/etc/$BASHTARD_NAME"
diff --git a/lib/logging.bash b/lib/logging.bash
index c120abf..37b947d 100644
--- a/lib/logging.bash
+++ b/lib/logging.bash
@@ -17,6 +17,15 @@ log() {
 		>&2
 }
 
+## :bocs:
+## :section:  3
+## :heading:  functions
+## :name:     debug
+## :param:    The system to log for.
+## :param:    The message to log.
+##
+## Log a debug-level message.  This message only shows if BASHTARD_DEBUG
+## evaluates to a truthy value.
 debug()  { [[ -n $BASHTARD_DEBUG ]] && log "$1" "$(printf "\e[0;37m%s" "${@:2}")" ; }
 info()   { log "$1" "$(printf "\e[m%s"     "${@:2}")" ; }
 notice() { log "$1" "$(printf "\e[0;34m%s" "${@:2}")" ; }
diff --git a/lib/main.bash b/lib/main.bash
index 821c2d2..fbf6705 100644
--- a/lib/main.bash
+++ b/lib/main.bash
@@ -32,8 +32,32 @@ main() {
 		exit 2
 	fi
 
-	# Declare some global variables
+	## :bocs:
+	## :heading: variables
+	## :name:    BASHTARD_PLATFORM
+	##
+	## The `$BASHTARD_PLATFORM` variable contains all sorts of information
+	## about the platform it is currently running on. It is an array with
+	## the following keys:
+	##
+	## - arch -- The name of the architecture  
+	## - distro -- The name of the GNU+Linux distribution, if any  
+	## - fqdn -- The fully-qualified domain name of the machine  
+	## - key -- A "key" to uniquely identify the OS  
+	## - os -- The name of the OS  
+	## - term -- The name of the current-running terminal  
+	## - version -- The release version of the OS, if any  
 	declare -A BASHTARD_PLATFORM
+
+	## :bocs:
+	## :heading: variables
+	## :name:    BASHTARD_PLAYBOOK_VARS
+	##
+	## An associative array, in which the keys are the config keys. The
+	## value of each element is a space-seperated list of attributes to
+	## which the config value must adhere. Currently, only _required_ is
+	## available, forcing a variable's value to be non-empty when the
+	## playbook is ran.
 	declare -A BASHTARD_PLAYBOOK_VARS
 
 	# Figure out system details
diff --git a/lib/util.bash b/lib/util.bash
index b032ea3..4a9775b 100644
--- a/lib/util.bash
+++ b/lib/util.bash
@@ -4,6 +4,26 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+## :bocs:
+## :section: 3
+## :heading: description
+##
+## When writing a *playbook*, you will want to know of the variables and
+## functions exposed by *bashtard*, so that you can actually write OS-agnostic
+## installation and maintenance scripts.
+
+## :bocs:
+## :section: 3
+## :heading: authors
+##
+## - Patrick Spek `<p.spek@tyil.nl>`
+
+## :bocs:
+## :section: 3
+## :heading: see also
+##
+## - bashtard(7)
+
 # shellcheck source=lib/util/config.bash
 . "$BASHTARD_LIBDIR/util/config.bash"
 # shellcheck source=lib/util/pkg.bash
@@ -13,21 +33,38 @@
 # shellcheck source=lib/util/secret.bash
 . "$BASHTARD_LIBDIR/util/secret.bash"
 
-# Change the working directory. In usage, this is the same as using cd,
-# however,  it will make additional checks to ensure everything is going fine.
+## :bocs:
+## :section: 3
+## :heading: functions
+## :name:    chgdir
+## :param:   The directory to change to.
+##
+## Change the working directory. In usage, this is the same as using cd,
+## however, it will make additional checks to ensure everything is going fine.
 chgdir() {
 	debug "bashtard/chgdir" "Changing workdir to $1"
 	cd -- "$1" || die "Failed to change directory to $1"
 }
 
-# Removes whitespace surrounding a given text.
+## :bocs:
+## :section: 3
+## :heading: functions
+## :name:    chomp
+## :param:   The text to alter.
+##
+## Removes whitespace surrounding a given text.
 chomp() {
 	awk '{$1=$1};1' <<< "$@"
 }
 
-# Create a datetime stamp. This is a wrapper around the date utility, ensuring
-# that the date being formatted is always in UTC and respect SOURCE_DATE_EPOCH,
-# if it is set.
+## :bocs:
+## :section: 3
+## :heading: functions
+## :name:    datetime
+##
+## Create a datetime stamp. This is a wrapper around the date utility, ensuring
+## that the date being formatted is always in UTC and respect
+## `SOURCE_DATE_EPOCH`, if it is set.
 datetime() {
 	local date_opts
 
@@ -42,9 +79,15 @@ datetime() {
 	date "${date_opts[@]}" +"${1:-%FT%TZ}"
 }
 
-# Log a message as error, and exit the program. This is intended for serious
-# issues that prevent the script from running correctly. The exit code can be
-# specified with -i, or will default to 1.
+## :bocs:
+## :section: 3
+## :heading: functions
+## :name:    die
+## :param:   The message to show.
+##
+## Log a message as error, and exit the program. This is intended for serious
+## issues that prevent the script from running correctly. The exit code can be
+## specified with -i, or will default to 1.
 die() {
 	local OPTIND
 	local code
@@ -63,10 +106,16 @@ die() {
 	exit "${code:-1}"
 }
 
-# Recursively hash files in a directory, and hashing the output of all those
-# hashes again. This results in a single hash representing the state of files
-# in a directory. It can be used to check whether contents changed after
-# templating files in a given directory.
+## :bocs:
+## :section: 3
+## :heading: functions
+## :name:    dir_hash
+## :param:   The path to a directory to hash the contents of.
+##
+## Recursively hash files in a directory, and hashing the output of all those
+## hashes again. This results in a single hash representing the state of files
+## in a directory. It can be used to check whether contents changed after
+## templating files in a given directory.
 dir_hash() {
 	local path
 
@@ -83,7 +132,15 @@ dir_hash() {
 	done | file_hash -
 }
 
-# Fetch a file from an URL. Using this function introduces a dependency on curl.
+## :bocs:
+## :section: 3
+## :heading: functions
+## :name:    fetch_http
+## :param:   The HTTP URL to download.
+## :opt:     -o  The output path to write to.
+##
+## Fetch a file from an URL. Using this function introduces a dependency on
+## curl. If -o is not given, a tempfile will be used to download to.
 fetch_http() {
 	local OPTIND
 	local buffer
@@ -123,10 +180,16 @@ fetch_http_wget() {
 	wget --quiet --output-document "$2" "$1"
 }
 
-# Hash a given file. This is a convenience function to work around different
-# systems calling their file hashing programs differently, and generating
-# different output. This function only expects 1 file as argument, and only
-# outputs the hash of this particular file.
+## :bocs:
+## :section: 3
+## :heading: functions
+## :name:    file_hash
+## :param:   A path to a file to return a hash for.
+##
+## Hash a given file. This is a convenience function to work around different
+## systems calling their file hashing programs differently, and generating
+## different output. This function only expects 1 file as argument, and only
+## outputs the hash of this particular file.
 file_hash() {
 	file_hash_md5 "$@"
 }
@@ -142,10 +205,17 @@ file_hash_md5() {
 	esac
 }
 
-# A very simple means of templating a file, using sed and awk. The template
-# file is assumed to exist within the share directory of the current playbook.
-# Variables are passed as key=value pairs to this function. Inside the
-# template, they are expected to be written as ${key}.
+## :bocs:
+## :section: 3
+## :heading: functions
+## :name:    file_template
+## :param:   The name of the template file.
+## :params:  Zero or more key=value pairs, used for substituting data into the template.
+##
+## A very simple means of templating a file, using sed and awk. The template
+## file is assumed to exist within the share directory of the current playbook.
+## Variables are passed as key=value pairs to this function. Inside the
+## template, they are expected to be written as ${key}.
 file_template()
 {
 	local file