Prototype manual page

README.md

@@ -110,10 +110,11 @@ The manual employs a custom theme derived from the standard Daux theme. If the s
 Producing a release package is done by running `./robo package`. This performs the following operations:
 
 - Duplicates a working tree with the commit (usually a release tag) to package
-- Generates the manual
+- Generates UNIX manual pages with [Pandoc](https://pandoc.org/)
+- Generates the HTML manual
 - Installs runtime Composer dependencies with an optimized autoloader
 - Deletes numerous unneeded files
 - Exports the default configuration of The Arsse to a file
 - Compresses the remaining files into a tarball
 
-Due to the first step, [Git](https://git-scm.com/) is required to package a release.
+Due to the first two steps, [Git](https://git-scm.com/) and [Pandoc](https://pandoc.org/) are required in PATH to package a release.

RoboFile.php

@@ -171,6 +171,8 @@ class RoboFile extends \Robo\Tasks {
             // get useable version strings from Git
             $version = trim(`git -C "$dir" describe --tags`);
             $archVersion = preg_replace('/^([^-]+)-(\d+)-(\w+)$/', "$1.r$2.$3", $version);
+            // generate manpages
+            $t->addTask($this->taskExec("./robo manpage")->dir($dir));
             // name the generic release tarball
             $tarball = "arsse-$version.tar.gz";
             // generate the Debian changelog; this also validates our original changelog
@@ -324,6 +326,17 @@ class RoboFile extends \Robo\Tasks {
         return $t->run();
     }
 
+    /** Generates the "arsse" command's manual page (UNIX man page)
+     * 
+     * This requires that the Pandoc document converter be installed and 
+     * available in $PATH.
+     */
+    public function manpage(): Result {
+        $src = BASE."docs/en/025_Using_The_Arsse/999_The_Command-Line_Manual_Page.md";
+        $out = BASE."dist/manpage";
+        return $this->taskExec("pandoc -s -f markdown -t man -o ".escapeshellarg($out)." ".escapeshellarg($src))->run();
+    }
+
     protected function changelogParse(string $text, string $targetVersion): array {
         $lines = preg_split('/\r?\n/', $text);
         $version = "";

dist/arch/PKGBUILD

@@ -32,7 +32,7 @@ package() {
     depends=("php>=7.1" "php-intl>=7.1" "php-sqlite>=7.1" "php-fpm>=7.1")
     # create most directories necessary for the final package
     cd "$pkgdir"
-    mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "etc/php/php-fpm.d/" "etc/webapps/arsse" "etc/webapps/arsse/nginx"
+    mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "usr/share/man/man1", "etc/php/php-fpm.d" "etc/webapps/arsse"
     #copy requisite files
     cd "$srcdir/arsse"
     cp -r lib locale sql vendor www CHANGELOG UPGRADING README.md arsse.php "$pkgdir/usr/share/webapps/arsse"
@@ -42,6 +42,7 @@ package() {
     cp dist/sysuser.conf "$pkgdir/usr/lib/sysusers.d/arsse.conf"
     cp dist/tmpfiles.conf "$pkgdir/usr/lib/tmpfiles.d/arsse.conf"
     cp dist/php-fpm.conf "$pkgdir/etc/php/php-fpm.d/arsse.conf"
+    cp dist/manpage "$pkgdir/usr/share/man/man1/arsse.1"
     cp -r dist/nginx dist/apache config.defaults.php "$pkgdir/etc/webapps/arsse"
     cd "$pkgdir"
     # copy files requiring special permissions

dist/arch/PKGBUILD-git

@@ -37,6 +37,7 @@ pkgver() {
 build() {
     cd "$srcdir/arsse"
     composer install
+    ./robo manpage
     ./robo manual
     composer install --no-dev -o --no-scripts
     php arsse.php conf save-defaults config.defaults.php
@@ -48,7 +49,7 @@ package() {
     depends=("php>=7.1" "php-intl>=7.1" "php-sqlite>=7.1" "php-fpm>=7.1")
     # create most directories necessary for the final package
     cd "$pkgdir"
-    mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "etc/php/php-fpm.d/" "etc/webapps/arsse" "etc/webapps/arsse/nginx"
+    mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "usr/share/man/man1", "etc/php/php-fpm.d" "etc/webapps/arsse"
     #copy requisite files
     cd "$srcdir/arsse"
     cp -r lib locale sql vendor www CHANGELOG UPGRADING README.md arsse.php "$pkgdir/usr/share/webapps/arsse"
@@ -58,6 +59,7 @@ package() {
     cp dist/sysuser.conf "$pkgdir/usr/lib/sysusers.d/arsse.conf"
     cp dist/tmpfiles.conf "$pkgdir/usr/lib/tmpfiles.d/arsse.conf"
     cp dist/php-fpm.conf "$pkgdir/etc/php/php-fpm.d/arsse.conf"
+    cp dist/manpage "$pkgdir/usr/share/man/man1/arsse.1"
     cp -r dist/nginx dist/apache config.defaults.php "$pkgdir/etc/webapps/arsse"
     cd "$pkgdir"
     # copy files requiring special permissions

docs/en/025_Using_The_Arsse/999_The_Command-Line_Manual_Page.md

@@ -0,0 +1,37 @@
+% ARSSE(1) arsse 0.9.2
+% J. King
+% 2021-05-28
+
+# NAME
+
+arsse - manage an instance of The Advanced RSS Environment (The Arsse)
+
+# SYNOPSIS
+
+**arsse** <*command*> [<*args*>]\
+**arsse** --version\
+**arsse** -h|--help
+
+# DESCRIPTION
+
+**arsse** allows a sufficiently privileged user to perform various administrative operations related to The Arsse, including:
+
+- Adding and removing users
+- Managing passwords and authentication tokens
+- Importing and exporting OPML newsfeed-lists
+
+These are documented in the next section **PRIMARY COMMANDS**. Further, seldom-used commands are documented in the following section **ADDITIONAL COMMANDS**.
+
+# PRIMARY COMMANDS
+
+## Managing users
+
+**arsse user [list]**
+
+: Displays a simple list of user names with one entry per line
+
+**arsse user add** <*username*> [<*password*>] [--admin]
+
+: Adds a new user to the database with the specified username and password. If <*password*> is omitted a random password will be generated and printed.
+
+: The **--admin** flag may be used to mark the user as an administrator. This has no meaning within the context of The Arsse as a whole, but it is used for access control in the Miniflux and Nextcloud News protocols.