diff --git a/README.md b/README.md index 74831aa..ad8cdc2 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 8c107fe..cd2c7a9 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 48a6dc3..a264a3e 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 4249f0a..fb25a49 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 0000000..454c28d --- /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