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/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..3a577cc8 100644 --- a/RoboFile.php +++ b/RoboFile.php @@ -185,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")); @@ -202,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", @@ -324,6 +327,26 @@ 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 { + $t = $this->collectionBuilder(); + $man = [ + 'en' => "man1/arsse.1", + ]; + foreach($man as $src => $out) { + $src = BASE."manpages/$src.md"; + $out = BASE."dist/man/$out"; + $t->addTask($this->taskFilesystemStack()->mkdir(dirname($out), 0755)); + $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(". ")); + } + return $t->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..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" "etc/php/php-fpm.d/" "etc/webapps/arsse" "etc/webapps/arsse/nginx" - #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,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 -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 4249f0a1..1de2bfd8 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,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" "etc/php/php-fpm.d/" "etc/webapps/arsse" "etc/webapps/arsse/nginx" - #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" @@ -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 -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/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 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 = << - arsse.php conf save-defaults [] arsse.php user [list] arsse.php user add [] [--admin] arsse.php user remove arsse.php user show arsse.php user set arsse.php user unset - arsse.php user set-pass [] - [--oldpass=] [--fever] - arsse.php user unset-pass - [--oldpass=] [--fever] + arsse.php user set-pass [] [--fever] + arsse.php user unset-pass [--fever] arsse.php user auth [--fever] arsse.php token list arsse.php token create [