Makefile: build and install the mkarchiso(1) man page

rst2man from python-docutils is required to convert the man page from
reStructuredText.

.gitignore

@@ -10,3 +10,4 @@ out/
 *.pem
 user-data
 meta-data
+man/version.rst

.gitlab-ci.yml

@@ -25,7 +25,7 @@ check:
       metrics: output/metrics.txt
   before_script:
     - pacman -Sy --needed --noconfirm archlinux-keyring
-    - pacman -Syu --needed --noconfirm arch-install-scripts bash dosfstools e2fsprogs erofs-utils gnupg grub jq libarchive libisoburn mtools openssl squashfs-tools zsync
+    - pacman -Syu --needed --noconfirm arch-install-scripts bash dosfstools e2fsprogs erofs-utils gnupg grub jq libarchive libisoburn mtools openssl python-docutils squashfs-tools zsync
   script:
     - ./.gitlab/ci/build_archiso.sh ${BUILD_SCRIPT_ARGS}
   stage: build

CHANGELOG.rst

@@ -8,6 +8,8 @@ Changelog
 Added
 -----
 
+- Add a man page for ``mkarchiso``.
+
 Changed
 -------
 

Makefile

@@ -4,11 +4,13 @@
 PREFIX ?= /usr/local
 BIN_DIR=$(DESTDIR)$(PREFIX)/bin
 DOC_DIR=$(DESTDIR)$(PREFIX)/share/doc/archiso
+MAN_DIR?=$(DESTDIR)$(PREFIX)/share/man
 PROFILE_DIR=$(DESTDIR)$(PREFIX)/share/archiso
 
 DOC_FILES=$(wildcard docs/*) $(wildcard *.rst)
 SCRIPT_FILES=$(wildcard archiso/*) $(wildcard scripts/*.sh) $(wildcard .gitlab/ci/*.sh) \
              $(wildcard configs/*/profiledef.sh) $(wildcard configs/*/airootfs/usr/local/bin/*)
+VERSION?=$(shell git describe --long --abbrev=7 | sed 's/^v//;s/\([^-]*-g\)/r\1/;s/-/./g;s/\.r0\.g.*//')
 
 all:
 
@@ -17,7 +19,7 @@ check: shellcheck
 shellcheck:
 	shellcheck -s bash $(SCRIPT_FILES)
 
-install: install-scripts install-profiles install-doc
+install: install-scripts install-profiles install-doc install-man
 
 install-scripts:
 	install -vDm 755 archiso/mkarchiso -t "$(BIN_DIR)/"
@@ -30,4 +32,9 @@ install-profiles:
 install-doc:
 	install -vDm 644 $(DOC_FILES) -t $(DOC_DIR)
 
-.PHONY: check install install-doc install-profiles install-scripts shellcheck
+install-man:
+	@printf '.. |version| replace:: %s\n' '$(VERSION)' > man/version.rst
+	install -d -m 755 $(MAN_DIR)/man1
+	rst2man man/mkarchiso.1.rst $(MAN_DIR)/man1/mkarchiso.1
+
+.PHONY: check install install-doc install-man install-profiles install-scripts shellcheck

README.rst

@@ -36,6 +36,10 @@ For linting the shell scripts the following package is required:
 
 * shellcheck
 
+For generating the man pages:
+
+* python-docutils
+
 Profiles
 ========
 

man/mkarchiso.1.rst

@@ -12,46 +12,42 @@ Arch Linux ISO generator
 Synopsis
 ========
 
-mkarchiso *[options]* *profile_directory*
+**mkarchiso** [options] *profile_directory*
 
 Description
 ===========
 
-mkarchiso create an ISO, netboot artifacts and a bootstrap tarball and optionally signs them.
+**mkarchiso** creates an ISO, netboot artifacts and a bootstrap tarball and optionally signs them.
 
 Options
 =======
 
--A application          Set an application name for the ISO.
+-A application          | Set an application name for the ISO.
-                        Default: |iso_application|.
+                        | Default: |iso_application|.
--C file                 pacman configuration file.
+-C file                 | pacman configuration file.
-                        Default: |pacman_conf|.
+                        | Default: |pacman_conf|.
--D install_dir          Set an install_dir. All files will be located here.
+-D install_dir          | Set an install_dir. All files will be located here.
-                        Default: |install_dir|.
+                        | Default: |install_dir|.
-                        NOTE: Max 8 characters, use only *a-z0-9*.
+                        | NOTE: Max 8 characters, use only *a-z0-9*.
--L label                Set the ISO volume label.
+-L label                | Set the ISO volume label.
-                        Default: |iso_label|.
+                        | Default: |iso_label|.
--P publisher            Set the ISO publisher.
+-P publisher            | Set the ISO publisher.
-                        Default: |iso_publisher|.
+                        | Default: |iso_publisher|.
--c cert_and_key         Provide certificates for codesigning of netboot artifacts as well as the rootfs artifact.
+-c cert_and_key         | Provide certificates for codesigning of netboot artifacts as well as the rootfs artifact.
-                        Multiple files are provided as quoted, space delimited list.
+                        | Multiple files are provided as quoted, space delimited list.
-                        The first file is considered as the signing certificate,
+                        | The first file is considered as the signing certificate, the second as the key and the third as the optional certificate authority.
-                        the second as the key and the third as the optional certificate authority.
+-g gpg_key              | Set the PGP key ID to be used for signing the rootfs image. Passed to gpg as the value for **--default-key**.
--g gpg_key              Set the PGP key ID to be used for signing the rootfs image.
+-G mbox                 | Set the PGP signer (must include an email address). Passed to gpg as the value for **--sender**.
-                        Passed to gpg as the value for **--default-key**.
+-h                      | Help message.
--G mbox                 Set the PGP signer (must include an email address).
+-m mode                 | Build mode(s) to use (valid modes are: *bootstrap*, *iso* and *netboot*). Multiple build modes are provided as quoted, space delimited list.
-                        Passed to gpg as the value for **--sender**.
+-o out_dir              | Set the output directory.
--h                      Help message.
+                        | Default: |out_dir|.
--m mode                 Build mode(s) to use (valid modes are: *bootstrap*, *iso* and *netboot*).
+-p packages             | Package(s) to install.
-                        Multiple build modes are provided as quoted, space delimited list.
+                        | Multiple packages are provided as quoted, space delimited list.
--o out_dir              Set the output directory.
+-r                      | Delete the working directory at the end.
-                        Default: |out_dir|.
+-v                      | Enable verbose output.
--p packages             Package(s) to install.
+-w work_dir             | Set the working directory.
-                        Multiple packages are provided as quoted, space delimited list.
+                        | Default: |work_dir|.
--r                      Delete the working directory at the end.
--v                      Enable verbose output.
--w work_dir             Set the working directory.
-                        Default: |work_dir|.
 
 Examples
 ========

man/variables.rst

@@ -1,9 +1,10 @@
-.. |iso_application| replace:: *mkarchiso iso*
+.. |iso_application| replace:: '*mkarchiso iso*'
 .. |pacman_conf| replace:: */etc/pacman.conf*
 .. |install_dir| replace:: *arch*
 .. |iso_label| replace:: *MKARCHISO*
 .. |iso_publisher| replace:: *mkarchiso*
 .. |out_dir| replace:: *./out*
 .. |work_dir| replace:: *./work*
-.. |version| replace:: insert.version.here
 .. |profile_dir| replace:: /usr/share/archiso
+
+.. include:: version.rst