From 6cc9f967288e3e37d5c4cefa9016276ebe055c83 Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 11:13:19 -0400
Subject: [PATCH 01/13] Prototype manual page

---
 README.md                                     |  5 ++-
 RoboFile.php                                  | 13 +++++++
 dist/arch/PKGBUILD                            |  3 +-
 dist/arch/PKGBUILD-git                        |  4 +-
 .../999_The_Command-Line_Manual_Page.md       | 37 +++++++++++++++++++
 5 files changed, 58 insertions(+), 4 deletions(-)
 create mode 100644 docs/en/025_Using_The_Arsse/999_The_Command-Line_Manual_Page.md

diff --git a/README.md b/README.md
index 74831aa4..ad8cdc25 100644
--- a/README.md
+++ b/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.
diff --git a/RoboFile.php b/RoboFile.php
index 8c107fe3..cd2c7a90 100644
--- a/RoboFile.php
+++ b/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 = "";
diff --git a/dist/arch/PKGBUILD b/dist/arch/PKGBUILD
index 48a6dc33..a264a3eb 100644
--- a/dist/arch/PKGBUILD
+++ b/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
diff --git a/dist/arch/PKGBUILD-git b/dist/arch/PKGBUILD-git
index 4249f0a1..fb25a490 100644
--- a/dist/arch/PKGBUILD-git
+++ b/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
diff --git a/docs/en/025_Using_The_Arsse/999_The_Command-Line_Manual_Page.md b/docs/en/025_Using_The_Arsse/999_The_Command-Line_Manual_Page.md
new file mode 100644
index 00000000..454c28d6
--- /dev/null
+++ b/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. 
\ No newline at end of file

From e439dd82778c468491a665a364f4a18714119bef Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 12:26:51 -0400
Subject: [PATCH 02/13] Fix manpage in Arch PKGBUILD

---
 RoboFile.php           | 6 +++---
 dist/arch/PKGBUILD     | 2 +-
 dist/arch/PKGBUILD-git | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/RoboFile.php b/RoboFile.php
index cd2c7a90..4e1cdb58 100644
--- a/RoboFile.php
+++ b/RoboFile.php
@@ -171,8 +171,6 @@ 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
@@ -187,7 +185,9 @@ class RoboFile extends \Robo\Tasks {
             $t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^source=\("arsse-[^"]+"\)$/m')->to('source=("'.basename($tarball).'")'));
             // perform Composer installation in the temp location with dev dependencies
             $t->addTask($this->taskComposerInstall()->arg("-q")->dir($dir));
-            // generate the manual
+            // generate manpages
+            $t->addTask($this->taskExec("./robo manpage")->dir($dir));
+            // generate the HTML manual
             $t->addTask($this->taskExec("./robo manual -q")->dir($dir));
             // perform Composer installation in the temp location for final output
             $t->addTask($this->taskComposerInstall()->dir($dir)->noDev()->optimizeAutoloader()->arg("--no-scripts")->arg("-q"));
diff --git a/dist/arch/PKGBUILD b/dist/arch/PKGBUILD
index a264a3eb..ad4b6711 100644
--- a/dist/arch/PKGBUILD
+++ b/dist/arch/PKGBUILD
@@ -42,7 +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 -T 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
diff --git a/dist/arch/PKGBUILD-git b/dist/arch/PKGBUILD-git
index fb25a490..104a2992 100644
--- a/dist/arch/PKGBUILD-git
+++ b/dist/arch/PKGBUILD-git
@@ -59,7 +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 -T 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

From 176aac0ad79604cd2fae9fe509e768f48165f0f5 Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 12:37:32 -0400
Subject: [PATCH 03/13] Fix stupid typo properly

---
 dist/arch/PKGBUILD     | 4 ++--
 dist/arch/PKGBUILD-git | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/dist/arch/PKGBUILD b/dist/arch/PKGBUILD
index ad4b6711..7d4d7d49 100644
--- a/dist/arch/PKGBUILD
+++ b/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" "usr/share/man/man1", "etc/php/php-fpm.d" "etc/webapps/arsse"
+    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,7 +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 -T dist/manpage "$pkgdir/usr/share/man/man1/arsse.1"
+    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
diff --git a/dist/arch/PKGBUILD-git b/dist/arch/PKGBUILD-git
index 104a2992..41bae532 100644
--- a/dist/arch/PKGBUILD-git
+++ b/dist/arch/PKGBUILD-git
@@ -49,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" "usr/share/man/man1", "etc/php/php-fpm.d" "etc/webapps/arsse"
+    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"
@@ -59,7 +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 -T dist/manpage "$pkgdir/usr/share/man/man1/arsse.1"
+    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

From d3a983e7f0e9f3b8f7af08fd24393c95c4bba0ad Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 14:05:30 -0400
Subject: [PATCH 04/13] Move the markdown manpage

Daux uses Cmmonmark, which does not support indention, required for
proper formatting of manual pages. Consequently, the manul page will
instead be standalone.
---
 RoboFile.php                                                    | 2 +-
 .../999_The_Command-Line_Manual_Page.md => manpage.md}          | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename docs/{en/025_Using_The_Arsse/999_The_Command-Line_Manual_Page.md => manpage.md} (100%)

diff --git a/RoboFile.php b/RoboFile.php
index 4e1cdb58..acd93976 100644
--- a/RoboFile.php
+++ b/RoboFile.php
@@ -332,7 +332,7 @@ class RoboFile extends \Robo\Tasks {
      * available in $PATH.
      */
     public function manpage(): Result {
-        $src = BASE."docs/en/025_Using_The_Arsse/999_The_Command-Line_Manual_Page.md";
+        $src = BASE."docs/manpage.md";
         $out = BASE."dist/manpage";
         return $this->taskExec("pandoc -s -f markdown -t man -o ".escapeshellarg($out)." ".escapeshellarg($src))->run();
     }
diff --git a/docs/en/025_Using_The_Arsse/999_The_Command-Line_Manual_Page.md b/docs/manpage.md
similarity index 100%
rename from docs/en/025_Using_The_Arsse/999_The_Command-Line_Manual_Page.md
rename to docs/manpage.md

From 2ec7acc50b33d61a0b8a30682099bc30bb8cbb1d Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 14:13:45 -0400
Subject: [PATCH 05/13] Turn off "smart" character substitution in Pandoc

---
 RoboFile.php    | 2 +-
 docs/manpage.md | 6 +++++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/RoboFile.php b/RoboFile.php
index acd93976..1049f232 100644
--- a/RoboFile.php
+++ b/RoboFile.php
@@ -334,7 +334,7 @@ class RoboFile extends \Robo\Tasks {
     public function manpage(): Result {
         $src = BASE."docs/manpage.md";
         $out = BASE."dist/manpage";
-        return $this->taskExec("pandoc -s -f markdown -t man -o ".escapeshellarg($out)." ".escapeshellarg($src))->run();
+        return $this->taskExec("pandoc -s -f markdown-smart -t man -o ".escapeshellarg($out)." ".escapeshellarg($src))->run();
     }
 
     protected function changelogParse(string $text, string $targetVersion): array {
diff --git a/docs/manpage.md b/docs/manpage.md
index 454c28d6..d2e116de 100644
--- a/docs/manpage.md
+++ b/docs/manpage.md
@@ -34,4 +34,8 @@ These are documented in the next section **PRIMARY COMMANDS**. Further, seldom-u
 
 : 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. 
\ No newline at end of file
+   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 control access to certain features in the Miniflux and Nextcloud News protocols. 
+
+**arsse user remove** <*username*>
+
+: Immediately removes a user from the database. All associated data (folders, subscriptions, etc.) are also removed.

From 3e55ab3849d6a5c4d3067238944763c673d09205 Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 15:44:51 -0400
Subject: [PATCH 06/13] Move man pages to their own directory

---
 .gitignore                        |  1 +
 RoboFile.php                      | 12 +++++++++---
 docs/manpage.md => manpages/en.md |  0
 3 files changed, 10 insertions(+), 3 deletions(-)
 rename docs/manpage.md => manpages/en.md (100%)

diff --git a/.gitignore b/.gitignore
index b4883827..f81d4dcd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@
 /dist/arch/arsse/
 /dist/arch/src/
 /dist/arch/pkg/
+/dist/man/
 /arsse.db*
 /config.php
 /.php_cs.cache
diff --git a/RoboFile.php b/RoboFile.php
index 1049f232..964164ad 100644
--- a/RoboFile.php
+++ b/RoboFile.php
@@ -204,6 +204,7 @@ class RoboFile extends \Robo\Tasks {
                 $dir."RoboFile.php",
                 $dir."CONTRIBUTING.md",
                 $dir."docs",
+                $dir."manpages",
                 $dir."tests",
                 $dir."vendor-bin",
                 $dir."vendor/bin",
@@ -332,9 +333,14 @@ class RoboFile extends \Robo\Tasks {
      * available in $PATH.
      */
     public function manpage(): Result {
-        $src = BASE."docs/manpage.md";
-        $out = BASE."dist/manpage";
-        return $this->taskExec("pandoc -s -f markdown-smart -t man -o ".escapeshellarg($out)." ".escapeshellarg($src))->run();
+        $p = $this->taskParallelExec();
+        $man = [
+            'en' => "man1/arsse.1",
+        ];
+        foreach($man as $src => $out) {
+            $p->process("pandoc -s -f markdown-smart -t man -o ".escapeshellarg(BASE."dist/$out")." ".escapeshellarg(BASE."manpages/$src.md"));
+        }
+        return $p->run();
     }
 
     protected function changelogParse(string $text, string $targetVersion): array {
diff --git a/docs/manpage.md b/manpages/en.md
similarity index 100%
rename from docs/manpage.md
rename to manpages/en.md

From 92823d5bc27a681367dcb77545cb33f237770953 Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 16:19:52 -0400
Subject: [PATCH 07/13] Create directories before executing Pandoc

---
 RoboFile.php | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/RoboFile.php b/RoboFile.php
index 964164ad..51406244 100644
--- a/RoboFile.php
+++ b/RoboFile.php
@@ -333,14 +333,19 @@ class RoboFile extends \Robo\Tasks {
      * available in $PATH.
      */
     public function manpage(): Result {
+        $t = $this->collectionBuilder();
         $p = $this->taskParallelExec();
         $man = [
             'en' => "man1/arsse.1",
         ];
         foreach($man as $src => $out) {
-            $p->process("pandoc -s -f markdown-smart -t man -o ".escapeshellarg(BASE."dist/$out")." ".escapeshellarg(BASE."manpages/$src.md"));
+            $src = BASE."manpages/$src.md";
+            $out = BASE."dist/man/$out";
+            $t->addTask($this->taskFilesystemStack()->mkdir(dirname($out), 0755));
+            $p->process("pandoc -s -f markdown-smart -t man -o ".escapeshellarg($out)." ".escapeshellarg($src));
         }
-        return $p->run();
+        $t->addTask($p);
+        return $t->run();
     }
 
     protected function changelogParse(string $text, string $targetVersion): array {

From 46c88f584f4ea1443c68b612a58a197a63a7af6b Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 16:29:53 -0400
Subject: [PATCH 08/13] Fix copying of man page in PKGBUILDs

---
 dist/arch/PKGBUILD     | 6 +++---
 dist/arch/PKGBUILD-git | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/dist/arch/PKGBUILD b/dist/arch/PKGBUILD
index 7d4d7d49..872f06b7 100644
--- a/dist/arch/PKGBUILD
+++ b/dist/arch/PKGBUILD
@@ -32,8 +32,8 @@ 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" "usr/share/man/man1" "etc/php/php-fpm.d" "etc/webapps/arsse"
-    #copy requisite files
+    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"
+    # copy requisite files
     cd "$srcdir/arsse"
     cp -r lib locale sql vendor www CHANGELOG UPGRADING README.md arsse.php "$pkgdir/usr/share/webapps/arsse"
     cp -r manual/* "$pkgdir/usr/share/doc/arsse"
@@ -42,7 +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/man "$pkgdir/usr/share"
     cp -r dist/nginx dist/apache config.defaults.php "$pkgdir/etc/webapps/arsse"
     cd "$pkgdir"
     # copy files requiring special permissions
diff --git a/dist/arch/PKGBUILD-git b/dist/arch/PKGBUILD-git
index 41bae532..1de2bfd8 100644
--- a/dist/arch/PKGBUILD-git
+++ b/dist/arch/PKGBUILD-git
@@ -49,8 +49,8 @@ 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" "usr/share/man/man1" "etc/php/php-fpm.d" "etc/webapps/arsse"
-    #copy requisite files
+    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"
+    # copy requisite files
     cd "$srcdir/arsse"
     cp -r lib locale sql vendor www CHANGELOG UPGRADING README.md arsse.php "$pkgdir/usr/share/webapps/arsse"
     cp -r manual/* "$pkgdir/usr/share/doc/arsse"
@@ -59,7 +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/man "$pkgdir/usr/share"
     cp -r dist/nginx dist/apache config.defaults.php "$pkgdir/etc/webapps/arsse"
     cd "$pkgdir"
     # copy files requiring special permissions

From 88487d27a20ab47da3bad697ad7c22dc4ad47e77 Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 17:40:20 -0400
Subject: [PATCH 09/13] Expand manual page

---
 manpages/en.md | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/manpages/en.md b/manpages/en.md
index d2e116de..15ab3049 100644
--- a/manpages/en.md
+++ b/manpages/en.md
@@ -16,7 +16,7 @@ arsse - manage an instance of The Advanced RSS Environment (The Arsse)
 
 **arsse** allows a sufficiently privileged user to perform various administrative operations related to The Arsse, including:
 
-- Adding and removing users
+- Adding and removing users and managing their metadata
 - Managing passwords and authentication tokens
 - Importing and exporting OPML newsfeed-lists
 
@@ -24,7 +24,7 @@ These are documented in the next section **PRIMARY COMMANDS**. Further, seldom-u
 
 # PRIMARY COMMANDS
 
-## Managing users
+## Managing users and metadata
 
 **arsse user [list]**
 
@@ -34,8 +34,28 @@ These are documented in the next section **PRIMARY COMMANDS**. Further, seldom-u
 
 : 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 control access to certain features in the Miniflux and Nextcloud News protocols. 
+: 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 control access to certain features in the Miniflux and Nextcloud News protocols. 
 
 **arsse user remove** <*username*>
 
 : Immediately removes a user from the database. All associated data (folders, subscriptions, etc.) are also removed.
+
+**arsse user show** <*username*>
+
+: Displays a table of metadata properties and their assigned values for <*username*>. These properties are primarily used by the Miniflux protocol. Consult the section **USER METADATA** for details.
+
+**arsse user set** <*username*> <*property*> <*value*>
+
+: Sets a metadata property for a user. These properties are primarily used by the Miniflux protocol. Consult the section **USER METADATA** for details.
+
+**arsse user unset** <*username*> <*property*>
+
+: Clears a metadata property for a user. The property is thereafter set to its default value, which is protocol-dependent.
+
+## Managing passwords and authentication tokens
+
+**arsse user set-pass** <*username*> [<*password*>] [--fever]
+
+: Changes a user's password to the specified value. If no password is specified, a random password will be generated and printed.
+\
+: The **--fever** option sets a user's Fever protocol password instead of their general password. As Fever requires that passwords be stored insecurely, users do not have Fever passwords by default, and logging in to the Fever protocol is disabled until a password is set. It is highly recommended that a user's Fever password be different from their general password.

From 62d49e0d3cfe89c5aaa9af699593e85c48b3fb73 Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 21:48:02 -0400
Subject: [PATCH 10/13] Fill out most of the manual page

Removed most of the online help as a consequence since maintaining
both is frought
---
 lib/CLI.php    | 211 +++----------------------------------------------
 manpages/en.md | 165 +++++++++++++++++++++++++++++++++-----
 2 files changed, 158 insertions(+), 218 deletions(-)

diff --git a/lib/CLI.php b/lib/CLI.php
index f892bddd..c867b3cd 100644
--- a/lib/CLI.php
+++ b/lib/CLI.php
@@ -13,223 +13,34 @@ use JKingWeb\Arsse\REST\Miniflux\Token as Miniflux;
 class CLI {
     public const USAGE = <<<USAGE_TEXT
 Usage:
-    arsse.php daemon
-    arsse.php feed refresh-all
-    arsse.php feed refresh <n>
-    arsse.php conf save-defaults [<file>]
     arsse.php user [list]
     arsse.php user add <username> [<password>] [--admin]
     arsse.php user remove <username>
     arsse.php user show <username>
     arsse.php user set <username> <property> <value>
     arsse.php user unset <username> <property>
-    arsse.php user set-pass <username> [<password>]
-        [--oldpass=<pass>] [--fever]
-    arsse.php user unset-pass <username>
-        [--oldpass=<pass>] [--fever]
+    arsse.php user set-pass <username> [<password>] [--fever]
+    arsse.php user unset-pass <username> [--fever]
     arsse.php user auth <username> <password> [--fever]
     arsse.php token list <username>
     arsse.php token create <username> [<label>]
     arsse.php token revoke <username> [<token>]
-    arsse.php import <username> [<file>]
-        [-f | --flat] [-r | --replace]
-    arsse.php export <username> [<file>] 
-        [-f | --flat]
+    arsse.php import <username> [<file>] [-f|--flat] [-r|--replace]
+    arsse.php export <username> [<file>] [-f|--flat]
+    arsse.php daemon
+    arsse.php feed refresh-all
+    arsse.php feed refresh <n>
+    arsse.php conf save-defaults [<file>]
     arsse.php --version
-    arsse.php -h | --help
+    arsse.php -h|--help
 
 The Arsse command-line interface can be used to perform various administrative
 tasks such as starting the newsfeed refresh service, managing users, and 
 importing or exporting data.
 
-Commands:
+See the manual page for more details:
 
-    daemon
-
-    Starts the newsfeed refreshing service, which will refresh stale feeds at
-    the configured interval automatically.
-
-    feed refresh-all
-
-    Refreshes any stale feeds once, then exits. This performs the same 
-    function as the daemon command without looping; this is useful if use of
-    a scheduler such a cron is preferred over a persitent service.
-
-    feed refresh <n>
-
-    Refreshes a single feed by numeric ID. This is principally for internal
-    use as the feed ID numbers are not usually exposed to the user.
-
-    conf save-defaults [<file>]
-
-    Prints default configuration parameters to standard output, or to <file>
-    if specified. Each parameter is annotated with a short description of its
-    purpose and usage.
-
-    user [list]
-
-    Prints a list of all existing users, one per line.
-
-    user add <username> [<password>] [--admin]
-
-    Adds the user specified by <username>, with the provided password
-    <password>. If no password is specified, a random password will be
-    generated and printed to standard output. The --admin option will make 
-    the user an administrator, which allows them to manage users via the 
-    Miniflux protocol, among other things.
-
-    user remove <username>
-
-    Removes the user specified by <username>. Data related to the user, 
-    including folders and subscriptions, are immediately deleted. Feeds to
-    which the user was subscribed will be retained and refreshed until the
-    configured retention time elapses.
-
-    user show <username>
-
-    Displays the metadata of a user in a basic tabular format. See below for
-    details on the various properties displayed.
-
-    user set <username> <property> <value>
-
-    Sets a user's metadata property to the supplied value. See below for
-    details on the various properties available.
-
-    user unset <username> <property>
-
-    Sets a user's metadata property to its default value. See below for
-    details on the various properties available. What the default value
-    for a property evaluates to depends on which protocol is used. 
-
-    user set-pass <username> [<password>]
-
-    Changes <username>'s password to <password>. If no password is specified,
-    a random password will be generated and printed to standard output.
-
-    The --oldpass=<pass> option can be used to supply a user's exiting 
-    password if this is required by the authentication driver to change a
-    password. Currently this is not used by any existing driver.
-    
-    The --fever option sets a user's Fever protocol password instead of their
-    general password. As Fever requires that passwords be stored insecurely,
-    users do not have Fever passwords by default, and logging in to the Fever
-    protocol is disabled until a password is set. It is highly recommended
-    that a user's Fever password be different from their general password.
-
-    user unset-pass <username>
-
-    Unsets a user's password, effectively disabling their account. As with
-    password setting, the --oldpass and --fever options may be used.
-
-    user auth <username> <password>
-
-    Tests logging in as <username> with password <password>. This only checks
-    that the user's password is correctly recognized; it has no side effects.
-
-    The --fever option may be used to test the user's Fever protocol password,
-    if any.
-
-    token list <username>
-
-    Lists available tokens for <username> in a simple tabular format. These 
-    tokens act as an alternative means of authentication for the Miniflux
-    protocol and may be required by some clients. They do not expire.
-
-    token create <username> [<label>]
-
-    Creates a new login token for <username> and prints it. These tokens act
-    as an alternative means of authentication for the Miniflux protocol and
-    may be required by some clients. An optional label may be specified to 
-    give the token a meaningful name.
-
-    token revoke <username> [<token>]
-
-    Deletes the specified token from the database. The token itself must be
-    supplied, not its label. If it is omitted all tokens are revoked.
-
-    import <username> [<file>]
-
-    Imports the feeds, folders, and tags found in the OPML formatted <file>
-    into the account of <username>. If no file is specified, data is instead
-    read from standard input.
-
-    The --replace option interprets the OPML file as the list of all desired 
-    feeds, folders and tags, performing any deletion or moving of existing 
-    entries which do not appear in the flle. If this option is not specified,
-    the file is assumed to list desired additions only.
-
-    The --flat option can be used to ignore any folder structures in the file,
-    importing any feeds only into the root folder.
-
-    export <username> [<file>]
-
-    Exports <username>'s feeds, folders, and tags to the OPML file specified
-    by <file>, or standard output if none is provided. Note that due to a 
-    limitation of the OPML format, any commas present in tag names will not be
-    retained in the export.
-
-    The --flat option can be used to omit folders from the export. Some OPML
-    implementations may not support folders, or arbitrary nesting; this option
-    may be used when planning to import into such software.
-
-User metadata:
-
-    User metadata are primarily used by the Miniflux protocol, and most 
-    properties have identical or similar names to those used by Miniflux.
-    Properties may also affect other protocols, or conversely may have no
-    effect even when using the Miniflux protocol; this is noted below when
-    appropriate.
-    
-    Booleans accept any of the values true/false, 1/0, yes/no, on/off.
-    
-    The following metadata properties exist for each user:
-
-    num
-        Integer. The numeric identifier of the user. This is assigned at user
-        creation and is read-only.
-    admin
-        Boolean. Whether the user is an administrator. Administrators may
-        manage other users via the Miniflux protocol, and also may trigger
-        feed updates manually via the Nextcloud News protocol.
-    lang
-        String. The preferred language of the user, as a BCP 47 language tag
-        e.g. "en-ca". Note that since The Arsse currently only includes 
-        English text it is not used by The Arsse itself, but clients may
-        use this metadatum in protocols which expose it.
-    tz
-        String. The time zone of the user, as a tzdata identifier e.g.
-        "America/Los_Angeles". 
-    root_folder_name
-        String. The name of the root folder, in protocols which allow it to
-        be renamed. 
-    sort_asc
-        Boolean. Whether the user prefers ascending sort order for articles.
-        Descending order is usually the default, but explicitly setting this
-        property false will also make a preference for descending order 
-        explicit.
-    theme
-        String. The user's preferred theme. This is not used by The Arsse
-        itself, but clients may use this metadatum in protocols which expose
-        it.
-    page_size
-        Integer. The user's preferred page size when listing articles. This is
-        not used by The Arsse itself, but clients may use this metadatum in 
-        protocols which expose it.
-    shortcuts
-        Boolean. Whether to enable keyboard shortcuts. This is not used by 
-        The Arsse itself, but clients may use this metadatum in protocols which
-        expose it.
-    gestures
-        Boolean. Whether to enable touch gestures. This is not used by 
-        The Arsse itself, but clients may use this metadatum in protocols which
-        expose it.
-    reading_time
-        Boolean. Whether to calculate and display the estimated reading time
-        for articles. Currently The Arsse does not calculate reading time, so
-        changing this will likely have no effect.
-    stylesheet
-        String. A user CSS stylesheet. This is not used by  The Arsse itself,
-        but clients may use this metadatum in protocols which expose it.
+    man 1 arsse
 USAGE_TEXT;
 
     protected function usage($prog): string {
diff --git a/manpages/en.md b/manpages/en.md
index 15ab3049..4b0bfa13 100644
--- a/manpages/en.md
+++ b/manpages/en.md
@@ -1,5 +1,5 @@
 % ARSSE(1) arsse 0.9.2
-% J. King
+%
 % 2021-05-28
 
 # NAME
@@ -8,7 +8,24 @@ arsse - manage an instance of The Advanced RSS Environment (The Arsse)
 
 # SYNOPSIS
 
-**arsse** <*command*> [<*args*>]\
+**arsse** user [list]\
+**arsse** user add <_username_> [<_password_>] [--admin]\
+**arsse** user remove <_username_>\
+**arsse** user show <_username_>\
+**arsse** user set <_username_> <_property_> <_value_>\
+**arsse** user unset <_username_> <_property_>\
+**arsse** user set-pass <_username_> [<_password_>] [--fever]\
+**arsse** user unset-pass <_username_> [--fever]\
+**arsse** user auth <_username_> <_password_> [--fever]\
+**arsse** token list <_username_>\
+**arsse** token create <_username_> [<_label_>]\
+**arsse** token revoke <_username_> [<_token_>]\
+**arsse** import <_username_> [<_file_>] [-f|--flat] [-r|--replace]\
+**arsse** export <_username_> [<_file_>] [-f|--flat]\
+**arsse** daemon\
+**arsse** feed refresh-all\
+**arsse** feed refresh <_n_>\
+**arsse** conf save-defaults [<_file_>]\
 **arsse** --version\
 **arsse** -h|--help
 
@@ -28,34 +45,146 @@ These are documented in the next section **PRIMARY COMMANDS**. Further, seldom-u
 
 **arsse user [list]**
 
-: Displays a simple list of user names with one entry per line
+:   Displays a simple list of user names with one entry per line
 
-**arsse user add** <*username*> [<*password*>] [--admin]
+**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.
+:   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 control access to certain features in the Miniflux and Nextcloud News protocols. 
+    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 control access to certain features in the Miniflux and Nextcloud News protocols. 
 
-**arsse user remove** <*username*>
+**arsse user remove** <_username_>
 
-: Immediately removes a user from the database. All associated data (folders, subscriptions, etc.) are also removed.
+:   Immediately removes a user from the database. All associated data (folders, subscriptions, etc.) are also removed.
 
-**arsse user show** <*username*>
+**arsse user show** <_username_>
 
-: Displays a table of metadata properties and their assigned values for <*username*>. These properties are primarily used by the Miniflux protocol. Consult the section **USER METADATA** for details.
+:   Displays a table of metadata properties and their assigned values for <_username_>. These properties are primarily used by the Miniflux protocol. Consult the section **USER METADATA** for details.
 
-**arsse user set** <*username*> <*property*> <*value*>
+**arsse user set** <_username_> <_property_> <_value_>
 
-: Sets a metadata property for a user. These properties are primarily used by the Miniflux protocol. Consult the section **USER METADATA** for details.
+:   Sets a metadata property for a user. These properties are primarily used by the Miniflux protocol. Consult the section **USER METADATA** for details.
 
-**arsse user unset** <*username*> <*property*>
+**arsse user unset** <_username_> <_property_>
 
-: Clears a metadata property for a user. The property is thereafter set to its default value, which is protocol-dependent.
+:   Clears a metadata property for a user. The property is thereafter set to its default value, which is protocol-dependent.
 
 ## Managing passwords and authentication tokens
 
-**arsse user set-pass** <*username*> [<*password*>] [--fever]
+**arsse user set-pass** <_username_> [<_password_>] [--fever]
 
-: Changes a user's password to the specified value. If no password is specified, a random password will be generated and printed.
-\
-: The **--fever** option sets a user's Fever protocol password instead of their general password. As Fever requires that passwords be stored insecurely, users do not have Fever passwords by default, and logging in to the Fever protocol is disabled until a password is set. It is highly recommended that a user's Fever password be different from their general password.
+:   Changes a user's password to the specified value. If no password is specified, a random password will be generated and printed.
+  
+    The **--fever** option sets a user's Fever protocol password instead of their general password. As the Fever protocol requires that passwords be stored insecurely, users do not have Fever passwords by default, and logging in to the Fever protocol is disabled until a suitable password is set. It is highly recommended that a user's Fever password be different from their general password.
+
+**arsse user unset-pass** <_username_> [--fever]
+
+:   Unsets a user's password, effectively disabling their account. As with password setting, the **--fever** option may be used to operate on a user's Fever password instead of their general password.
+
+**arsse user auth** <_username_> <_password_> [--fever]
+
+:   Tests logging a user in. This only checks that the user's password is correctly recognized; it has no side effects.
+
+    The **--fever** option may be used to test the user's Fever protocol password, if any.
+
+**arsse token list** <_username_>
+
+:   Displays a user's authentication tokens in a simple tabular format. These tokens act as an alternative means of authentication for the Miniflux protocol and may be required by some clients. They do not expire.
+
+**arsse token create** <_username_> [<_label_>]
+
+:   Creates a new random login token and prints it. These tokens act as an alternative means of authentication for the Miniflux protocol and may be required by some clients. An optional <_label_> may be specified to give the token a meaningful name.
+
+**arsse token revoke** <_username_> [<_token_>]
+
+:   Deletes the specified token from the database. The token itself must be supplied, not its label. If it is omitted all tokens are revoked.
+
+## Importing and exporting data
+
+**arsse import** <_username_> [<_file_>] [-r|--replace] [-f|--flat]
+
+:   Imports the newsfeeds, folders, and tags found in the OPML formatted <_file_> into the account of the specified user. If no file is specified, data is instead read from standard input. Import operations are atomic: if any of the newsfeeds listed in the input cannot be retrieved, the entire import operation will fail.
+
+    The **--replace** (or **-r**) option interprets the OPML file as the list of **all** desired newsfeeds, folders and tags, performing any deletion or moving of existing entries which do not appear in the flle. If this option is not specified, the file is assumed to list desired **additions** only.
+
+    The **--flat** (or **-f**) option can be used to ignore any folder structures in the file, importing any newsfeeds directly into the root folder. Combining this with the **--replace** option is possible.
+
+**arsse export** <_username_> [<_file_>] [-f|--flat]
+
+:   Exports a user's newsfeeds, folders, and tags to the OPML file specified by <_file_>, or standard output if no file is specified. Note that due to a limitation of the OPML format, any commas present in tag names will not be retained in the export.
+
+    The **--flat** (or **-f**) option can be used to omit folders from the export. Some OPML implementations may not support folders, or arbitrary nesting; this option may be used when planning to import into such software.
+
+# ADDITIONAL COMMANDS
+
+**arsse daemon**
+
+:   Starts the newsfeed fetching service. Normally this command is only invoked by systemd.
+
+**arsse feed refresh-all**
+
+:   Performs a one-time fetch of all stale feeds. This command can be used as the basis of a **cron** job to keep newsfeeds up-to-date.
+
+**arsse feed refresh** <_n_>
+
+:   Performs a one-time fetch of the feed (not subscription) identified by integer <_n_>. This is used internally by the fetching service and should not normally be needed.
+
+# USER METADATA
+
+User metadata are primarily used by the Miniflux protocol, and most properties have identical or similar names to those used by Miniflux. Properties may also affect other protocols, or conversely may have no effect even when using the Miniflux protocol; this is noted below when appropriate.
+
+Booleans accept any of the values **true**/**false**, **1**/**0**, **yes**/**no**, or **on**/**off**.
+
+The following metadata properties exist for each user:
+
+**num**
+:   Integer. The numeric identifier of the user. This is assigned at user creation and is read-only.
+
+**admin**
+:   Boolean. Whether the user is an administrator. Administrators may manage other users via the Miniflux protocol, and also may trigger feed updates manually via the Nextcloud News protocol.
+
+**lang**
+:   String. The preferred language of the user, as a BCP 47 language tag e.g. "en-ca". Note that since The Arsse currently only includes English text it is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
+
+**tz**
+:   String. The time zone of the user, as a tzdata identifier e.g. "America/Los_Angeles".
+
+**root_folder_name**
+:   String. The name of the root folder, in protocols which allow it to be renamed.
+
+**sort_asc**
+:   Boolean. Whether the user prefers ascending sort order for articles. Descending order is usually the default, but explicitly setting this property false will also make a preference for descending order explicit.
+
+**theme**
+:   String. The user's preferred theme. This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
+
+**page_size**
+:   Integer. The user's preferred page size when listing articles. This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
+
+**shortcuts**
+:   Boolean. Whether to enable keyboard shortcuts. This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
+
+**gestures**
+:   Boolean. Whether to enable touch gestures. This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
+
+**reading_time**
+:   Boolean. Whether to calculate and display the estimated reading time for articles. Currently The Arsse does not calculate reading time, so changing this will likely have no effect.
+
+**stylesheet**
+:   String. A user CSS stylesheet. This is not used by  The Arsse itself, but clients may use this metadatum in protocols which expose it.
+
+# EXAMPLES
+
+TODO
+
+# REPORTING BUGS
+
+Any bugs found in The Arsse may be reported on the Web at [https://code.mensbeam.com/MensBeam/arsse](). Reports may also be directed to the authors (below) by e-mail.
+
+# AUTHORS
+
+J. King\
+[https://jkingweb.ca/]()
+
+Dustin Wilson\
+[https://dustinwilson.com/]()
\ No newline at end of file

From 4317a96db18f218e4fcfd29046da1121dc161b4f Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 22:45:13 -0400
Subject: [PATCH 11/13] Work around double spacing

---
 RoboFile.php   | 5 ++---
 manpages/en.md | 2 +-
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/RoboFile.php b/RoboFile.php
index 51406244..3a577cc8 100644
--- a/RoboFile.php
+++ b/RoboFile.php
@@ -334,7 +334,6 @@ class RoboFile extends \Robo\Tasks {
      */
     public function manpage(): Result {
         $t = $this->collectionBuilder();
-        $p = $this->taskParallelExec();
         $man = [
             'en' => "man1/arsse.1",
         ];
@@ -342,9 +341,9 @@ class RoboFile extends \Robo\Tasks {
             $src = BASE."manpages/$src.md";
             $out = BASE."dist/man/$out";
             $t->addTask($this->taskFilesystemStack()->mkdir(dirname($out), 0755));
-            $p->process("pandoc -s -f markdown-smart -t man -o ".escapeshellarg($out)." ".escapeshellarg($src));
+            $t->addTask($this->taskExec("pandoc -s -f markdown-smart -t man -o ".escapeshellarg($out)." ".escapeshellarg($src)));
+            $t->addTask($this->taskReplaceInFile($out)->regex('/\.\n(?!\.)/s')->to(". "));
         }
-        $t->addTask($p);
         return $t->run();
     }
 
diff --git a/manpages/en.md b/manpages/en.md
index 4b0bfa13..b577264a 100644
--- a/manpages/en.md
+++ b/manpages/en.md
@@ -187,4 +187,4 @@ J. King\
 [https://jkingweb.ca/]()
 
 Dustin Wilson\
-[https://dustinwilson.com/]()
\ No newline at end of file
+[https://dustinwilson.com/]()

From fd76b1b6117a5958689c64c0354e6e42c26b3874 Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sat, 29 May 2021 23:37:02 -0400
Subject: [PATCH 12/13] Add examples to manual page

---
 manpages/en.md | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/manpages/en.md b/manpages/en.md
index b577264a..7a7aa64f 100644
--- a/manpages/en.md
+++ b/manpages/en.md
@@ -129,6 +129,10 @@ These are documented in the next section **PRIMARY COMMANDS**. Further, seldom-u
 
 :   Performs a one-time fetch of the feed (not subscription) identified by integer <_n_>. This is used internally by the fetching service and should not normally be needed.
 
+**arsse conf save-defaults** [<_file_>]
+
+:   Prints default configuration parameters to standard output, or to <_file_> if specified. Each parameter is annotated with a short description of its purpose and usage.
+
 # USER METADATA
 
 User metadata are primarily used by the Miniflux protocol, and most properties have identical or similar names to those used by Miniflux. Properties may also affect other protocols, or conversely may have no effect even when using the Miniflux protocol; this is noted below when appropriate.
@@ -171,11 +175,37 @@ The following metadata properties exist for each user:
 :   Boolean. Whether to calculate and display the estimated reading time for articles. Currently The Arsse does not calculate reading time, so changing this will likely have no effect.
 
 **stylesheet**
-:   String. A user CSS stylesheet. This is not used by  The Arsse itself, but clients may use this metadatum in protocols which expose it.
+:   String. A user CSS stylesheet. This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
 
 # EXAMPLES
 
-TODO
+- Add an administrator to the database with an explicit password
+
+      $ arsse user add --admin alice "Curiouser and curiouser!"
+
+- Add a regular user to the database with a random password
+
+      $ arsse user add "Bob the Builder"
+      bLS!$_UUZ!iN2i_!^IC6
+        
+- Make Bob the Builder an administrator
+
+      $ arsse user set admin true
+
+- Disable Alice's account by clearing her password
+
+      $ arsse user unset-pass alice
+
+- Move all of Foobar's newsfeeds to the root folder
+
+      $ arsse export foobar -f | arsse import -r foobar
+
+- Fail to log in as Alice
+
+      $ arsse user authbLS!$_UUZ!iN2i_!^IC6 alice "Oh, dear!"
+      Authentication failed
+      $ echo $?
+      1
 
 # REPORTING BUGS
 

From 8c0f0477477c94e2842aabd2cf7ccb07e16ac106 Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sun, 30 May 2021 09:19:08 -0400
Subject: [PATCH 13/13] Update HTML manual to mention man page

---
 .../020_Download_and_Installation/020_On_Debian_and_Ubuntu.md   | 1 +
 docs/en/025_Using_The_Arsse/index.md                            | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/en/020_Getting_Started/020_Download_and_Installation/020_On_Debian_and_Ubuntu.md b/docs/en/020_Getting_Started/020_Download_and_Installation/020_On_Debian_and_Ubuntu.md
index ea8c0d92..38906142 100644
--- a/docs/en/020_Getting_Started/020_Download_and_Installation/020_On_Debian_and_Ubuntu.md
+++ b/docs/en/020_Getting_Started/020_Download_and_Installation/020_On_Debian_and_Ubuntu.md
@@ -35,6 +35,7 @@ sudo mv sysusers.conf /etc/sysusers.d/arsse.conf
 sudo mv tmpfiles.conf /etc/tmpfiles.d/arsse.conf
 sudo mv config.php nginx apache /etc/arsse/
 sudo mv php-fpm.conf /etc/php/$php_ver/fpm/pool.d/arsse.conf
+sudo mv man/man1/* /usr/shame/man/man1/
 # Move the administration executable
 sudo mv arsse /usr/bin/
 ```
diff --git a/docs/en/025_Using_The_Arsse/index.md b/docs/en/025_Using_The_Arsse/index.md
index a6c215ef..475fdce8 100644
--- a/docs/en/025_Using_The_Arsse/index.md
+++ b/docs/en/025_Using_The_Arsse/index.md
@@ -2,7 +2,7 @@
 
 This section details a few administrative tasks which may need to be performed after installing The Arsse. As no Web-based administrative interface is included, these tasks are generally performed via command line interface.
 
-Though this section describes some commands briefly, complete documentation of The Arsse's command line interface is not included in this manual. Documentation for CLI commands can instead be viewed with the CLI itself by executing `arsse --help`.
+Though this section describes some commands briefly, complete documentation of The Arsse's command line interface is not included in this manual. Documentation for CLI commands can instead be viewed using the system manual service by executing `man arsse`.
 
 # A Note on Command Invocation