Browse Source

Prototype manual page

rpm
J. King 3 years ago
parent
commit
6cc9f96728
  1. 5
      README.md
  2. 13
      RoboFile.php
  3. 3
      dist/arch/PKGBUILD
  4. 4
      dist/arch/PKGBUILD-git
  5. 37
      docs/en/025_Using_The_Arsse/999_The_Command-Line_Manual_Page.md

5
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.

13
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 = "";

3
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

4
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

37
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.
Loading…
Cancel
Save