mirror/Arsse
1
1
Fork 0
mirror of https://code.mensbeam.com/MensBeam/Arsse.git synced 2024-12-22 13:12:41 +00:00
Code Issues Activity

Use mdoc manual directly without any preprocessing

Browse source
This commit is contained in:
J. King 2023-10-29 22:20:14 -04:00
parent 73446887f5
commit 692af39768
6 changed files with 24 additions and 684 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -7,7 +7,6 @@
/dist/arch/arsse/ /dist/arch/arsse/
/dist/arch/src/ /dist/arch/src/
/dist/arch/pkg/ /dist/arch/pkg/
/dist/man/
/arsse.db* /arsse.db*
/config.php /config.php
/.php_cs.cache /.php_cs.cache

17
README.md
View file

@ -34,7 +34,7 @@ Also necessary to the functioning of the application is the `/vendor/` directory
The `/locale/` and `/sql/` directories contain human-language files and database schemata, both of which are occasionally used by the application in the course of execution. The `/www/` directory serves as a document root for a few static files to be made available to users by a Web server. The `/locale/` and `/sql/` directories contain human-language files and database schemata, both of which are occasionally used by the application in the course of execution. The `/www/` directory serves as a document root for a few static files to be made available to users by a Web server.
The `/dist/` directory, on the other hand, contains general and system-specific build files, and samples of configuration for Web servers and other system integration. These are not used by The Arsse itself, but are used during the process of preparing new releases for supported operating systems. The `/dist/` directory, on the other hand, contains general and system-specific build files, manual pages, and samples of configuration for Web servers and other system integration. These are not used by The Arsse itself, but are used during the process of preparing new releases for supported operating systems.
## Documentation ## Documentation
@ -65,11 +65,11 @@ PHPUnit's configuration can be customized by copying its configuration file to `
The `/vendor-bin/` directory houses the files needed for the tools used in The Arsse's programming environment. These are managed by the Composer ["bin" plugin](https://github.com/bamarni/composer-bin-plugin) and are not used by The Arsse itself. The following files are also related to various programming tools: The `/vendor-bin/` directory houses the files needed for the tools used in The Arsse's programming environment. These are managed by the Composer ["bin" plugin](https://github.com/bamarni/composer-bin-plugin) and are not used by The Arsse itself. The following files are also related to various programming tools:
| Path | Description | | Path | Description |
|-------------------|----------------------------------------------------------| |---------------------------|----------------------------------------------------------|
| `/.gitattributes` | Git settings for handling files | | `/.gitattributes` | Git settings for handling files |
| `/.gitignore` | Git file exclusion patterns | | `/.gitignore` | Git file exclusion patterns |
| `/.php_cs.dist` | Configuration for [php-cs-fixer](https://cs.symfony.com) | | `/.php-cs-fixer.dist.php` | Configuration for [php-cs-fixer](https://cs.symfony.com) |
| `/.php_cs.cache` | Cache for php-cs-fixer | | `/.php-cs-fixer.cache` | Cache for php-cs-fixer |
| `/composer.json` | Configuration for Composer | | `/composer.json` | Configuration for Composer |
| `/composer.lock` | Version synchronization data for Composer | | `/composer.lock` | Version synchronization data for Composer |
| `/RoboFile.php` | Task definitions for [Robo](https://robo.li/) | | `/RoboFile.php` | Task definitions for [Robo](https://robo.li/) |
@ -90,11 +90,11 @@ There is also a `test:quick` Robo task which excludes slower tests, and a `test:
### Test coverage ### Test coverage
Computing the coverage of tests can be done by running `./robo coverage`, after which an HTML-format coverage report will be written to `/tests/coverage/`. Either [PCOV](https://github.com/krakjoe/pcov), [Xdebug](https://xdebug.org), or [phpdbg](https://php.net/manual/en/book.phpdbg.php) is required for this. PCOV is generally recommended as it is faster than Xdebug; phpdbg is faster still, but less accurate. If using either PCOV or Xdebug, the extension need not be enabled globally; PHPUnit will enable it when needed. Computing the coverage of tests can be done by running `./robo coverage`, after which an HTML-format coverage report will be written to `/tests/coverage/`. Either [PCOV](https://github.com/krakjoe/pcov) or [Xdebug](https://xdebug.org) is required for this. PCOV is generally recommended as it is faster than Xdebug. Neither extension need be enabled globally; Robo will enable it when needed.
## Enforcing coding style ## Enforcing coding style
The [php-cs-fixer](https://cs.symfony.com) tool, executed via `./robo clean`, can be used to rewrite code to adhere to The Arsse's coding style. The style largely follows [PSR-2](https://www.php-fig.org/psr/psr-2/) with some exceptions: The [php-cs-fixer](https://cs.symfony.com) tool, executed via `./robo clean`, can be used to rewrite code to adhere to The Arsse's coding style. The style largely follows [PSR-12](https://www.php-fig.org/psr/psr-12/) with some exceptions:
- Classes, methods, and functions should have their opening brace on the same line as the signature - Classes, methods, and functions should have their opening brace on the same line as the signature
- Anonymous functions should have no space before the parameter list - Anonymous functions should have no space before the parameter list
@ -107,16 +107,11 @@ The Arsse's user manual, made using [Daux](https://daux.io/), can be compiled by
The manual employs a custom theme derived from the standard Daux theme. If the standard Daux theme receives improvements, the custom theme can be rebuilt by running `./robo manual:theme`. This requires that [NodeJS](https://nodejs.org) and [Yarn](https://yarnpkg.com/) be installed, but JavaScript tools are not required to modify The Arsse itself, nor the content of the manual. The manual employs a custom theme derived from the standard Daux theme. If the standard Daux theme receives improvements, the custom theme can be rebuilt by running `./robo manual:theme`. This requires that [NodeJS](https://nodejs.org) and [Yarn](https://yarnpkg.com/) be installed, but JavaScript tools are not required to modify The Arsse itself, nor the content of the manual.
## Building the man page
The Arsse's UNIX manual page is authored in Markdown, and must be converted to the native roff format using [Pandoc](https://pandoc.org/). This can be done by running `./robo manpage`, which will output appropriate files to `/dist/man/`. The conversion should not be done manually as there is post-processing required for optimal output.
## Packaging a release ## Packaging a release
Producing release packages is done by running `./robo package`. This performs the following operations: Producing release packages is done by running `./robo package`. This performs the following operations:
- Duplicates a [Git](https://git-scm.com/) working tree with the commit (usually a release tag) to package - Duplicates a [Git](https://git-scm.com/) working tree with the commit (usually a release tag) to package
- Generates UNIX manual pages with [Pandoc](https://pandoc.org/)
- Generates the HTML manual - Generates the HTML manual
- Installs runtime Composer dependencies with an optimized autoloader - Installs runtime Composer dependencies with an optimized autoloader
- Deletes numerous unneeded files - Deletes numerous unneeded files

37
RoboFile.php
View file

@ -237,18 +237,18 @@ class RoboFile extends \Robo\Tasks {
} }
// save commit description to VERSION file for reference // save commit description to VERSION file for reference
$t->addTask($this->taskWriteToFile($dir."VERSION")->text($version)); $t->addTask($this->taskWriteToFile($dir."VERSION")->text($version));
if (file_exists($dir."docs") || file_exists($dir."manpages")) { if (file_exists($dir."docs") || file_exists($dir."manpages/en.md")) {
// perform Composer installation in the temp location with dev dependencies to include Robo and Daux // perform Composer installation in the temp location with dev dependencies to include Robo and Daux
$t->addTask($this->taskExec("composer install")->arg("-q")->dir($dir)); $t->addTask($this->taskExec("composer install")->arg("-q")->dir($dir));
}
if (file_exists($dir."manpages")) {
// generate manpages
$t->addTask($this->taskExec("./robo manpage")->dir($dir));
}
if (file_exists($dir."docs")) { if (file_exists($dir."docs")) {
// generate the HTML manual // generate the HTML manual
$t->addTask($this->taskExec("./robo manual -q")->dir($dir)); $t->addTask($this->taskExec("./robo manual -q")->dir($dir));
} }
if (file_exists($dir."manpages/en.md")) {
// generate manpages (NOTE: obsolete process)
$t->addTask($this->taskExec("./robo manpage")->dir($dir));
}
}
// perform Composer installation in the temp location for final output // perform Composer installation in the temp location for final output
$t->addTask($this->taskExec("composer install")->dir($dir)->arg("--no-dev")->arg("-o")->arg("--no-scripts")->arg("-q")); $t->addTask($this->taskExec("composer install")->dir($dir)->arg("--no-dev")->arg("-o")->arg("--no-scripts")->arg("-q"));
// delete unwanted files // delete unwanted files
@ -454,29 +454,6 @@ class RoboFile extends \Robo\Tasks {
return $t->run(); 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 {
if (!$this->toolExists("pandoc")) {
throw new \Exception("Pandoc is required in PATH to generate manual pages");
}
$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();
}
/** Parses the contents of the CHANGELOG file into an array structure /** Parses the contents of the CHANGELOG file into an array structure
* *
* This is done line-by-line and tends to be quite strict. * This is done line-by-line and tends to be quite strict.
@ -495,7 +472,7 @@ class RoboFile extends \Robo\Tasks {
$expected = ["version"]; $expected = ["version"];
for ($a = 0; $a < sizeof($lines);) { for ($a = 0; $a < sizeof($lines);) {
$l = rtrim($lines[$a++]); $l = rtrim($lines[$a++]);
if (in_array("version", $expected) && preg_match('/^Version (\d+(?:\.\d+)*) \(([\d\?]{4}-[\d\?]{2}-[\d\?]{2})\)\s*$/D', $l, $m)) { if (in_array("version", $expected) && preg_match('/^Version ([\d\?]+(?:\.[\d\?]+)*) \(([\d\?]{4}-[\d\?]{2}-[\d\?]{2})\)\s*$/D', $l, $m)) {
$version = $m[1]; $version = $m[1];
if (!preg_match('/^\d{4}-\d{2}-\d{2}$/D', $m[2])) { if (!preg_match('/^\d{4}-\d{2}-\d{2}$/D', $m[2])) {
// uncertain dates are allowed only for the top version, and only if it does not match the target version (otherwise we have forgotten to set the correct date before tagging) // uncertain dates are allowed only for the top version, and only if it does not match the target version (otherwise we have forgotten to set the correct date before tagging)

0
manpages/arsse.1.en.mdoc → dist/man/man1/arsse.1 vendored
View file

405
manpages/en.groff
View file

@ -1,405 +0,0 @@
.\" This manual was written using stylistic recommendations from the very
.\" helpful groff_man_style(7) manual page with some suggestions from the
.\" man-pages(7) manual followed as well. When in doubt those manuals should
.\" be consulted while making edits to this document.
.
.TH ARSSE 1 "2023\-10\-26" "The Arsse 0.10.4"
.
.SH NAME
arsse \- manage an instance of The Advanced RSS Environment (The Arsse)
.
.
.SH SYNOPSIS
.SY "arsse user"
.RB [ list ]
.SY "arsse user add"
.RI < username >
.RI [< password >]
.RB [ \-\-admin ]
.SY "arsse user remove"
.RI < username >
.SY "arsse user show"
.RI < username >
.SY "arsse user set"
.RI < username >
.RI < property >
.RI < value >
.SY "arsse user unset"
.RI < username >
.RI < property >
.SY "arsse user set\-pass"
.RI < username >
.RI [< password >]
.RB [ \-\-fever ]
.SY "arsse user unset\-pass"
.RI < username >
.RB [ \-\-fever ]
.SY "arsse user auth"
.RI < username >
.RI [< password >]
.RB [ \-\-fever ]
.SY "arsse token list"
.RI < username >
.SY "arsse token create"
.RI < username >
.RI [< label >]
.SY "arsse token revoke"
.RI < username >
.RI [< token >]
.SY "arsse import"
.RI < username >
.RI [< file >]
.RB [ \-f | \-\-flat ]
.RB [ \-r | \-\-replace ]
.SY "arsse export"
.RI < username >
.RI [< file >]
.RB [ \-f | \-\-flat ]
.SY "arsse daemon"
.RB [ \-\-fork =\c
.IR pidfile ]
.SY "arsse feed refresh\-all"
.SY "arsse feed refresh"
.RI < n >
.SY "arsse conf save\-defaults"
.RI [< file >]
.SY "arsse \-\-version"
.SY "arsse"
.BR \-h | \-\-help
.YS
.
.
.SH DESCRIPTION
.P
.B arsse
allows a sufficiently privileged user to perform various administrative operations related to The Arsse, including:
.IP \[bu] 2
.PD 0
Adding and removing users and managing their metadata
.IP \[bu] 2
Managing passwords and authentication tokens
.IP \[bu] 2
Importing and exporting OPML newsfeed-lists
.PD
.P
These are documented in the next section
.BR COMMANDS .
Further, seldom-used commands are documented in the subsequent section
.BR "ADDITIONAL COMMANDS" .
.
.
.SH COMMANDS
.SS "Managing users and metadata"
.TP
.BR "user " [ list ]
Displays a simple list of user names with one entry per line
.TP
.BR "user add " \c
.RI < username "> [<" password ">] \c"
.RB [ \-\-admin ]
Adds a new user to the database with the specified username and password.
If
.I password
is omitted a random password will be generated and printed.
.IP
The
.B \-\-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.
.TP
.BR "user remove " \c
.RI < username >
Immediately removes a user from the database.
All associated data (folders, subscriptions, etc.) are also removed.
.TP
.BR "user show " \c
.RI < username >
Displays a table of metadata properties and their assigned values for
.IR username .
These properties are primarily used by the Miniflux protocol.
Consult the section
.B USER METADATA
for details.
.TP
.BR "user set " \c
.RI < username "> \c"
.RI < property "> \c"
.RI < value >
Sets a metadata property for a user.
These properties are primarily used by the Miniflux protocol.
Consult the section
.B "USER METADATA"
for details.
.TP
.BR "user unset " \c
.RI < username "> \c"
.RI < property >
Clears a metadata property for a user.
The property is thereafter set to its default value, which is protocol-dependent.
.SS "Managing passwords and authentication tokens"
.TP
.BR "user set\-pass " \c
.RI < username "> \c"
.RI [< password ">] \c"
.RB [ \-\-fever ]
Changes a user's password to the specified value.
If no password is specified, a random password will be generated and printed.
.IP
The
.B \-\-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.
.TP
.BR "user unset\-pass " \c
.RI < username "> \c"
.RB [ \-\-fever ]
Unsets a user's password, effectively disabling their account.
As with password setting, the
.B \-\-fever
option may be used to operate on a user's Fever password instead of their general password.
.TP
.BR "user auth " \c
.RI < username "> \c"
.RI < password "> \c"
.RB [ \-\-fever ]
Tests logging a user in.
This only checks that the user's password is correctly recognized;
it has no side effects.
.IP
The
.B \-\-fever
option may be used to test the user's Fever protocol password, if any.
.TP
.BR "token list " \c
.RI < 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.
.TP
.BR "token create " \c
.RI < username "> \c"
.RI [< 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
.I label
may be specified to give the token a meaningful name.
.TP
.BR "token revoke " \c
.RI < username "> \c"
.RI [< token >]
Deletes the specified
.I token
from the database. The token itself must be supplied, not its label.
If it is omitted all tokens for
.I username
are revoked.
.SS "Importing and exporting data"
.TP
.BR "import " \c
.RI < username "> \c"
.RI [< file ">] \c"
.RB [ \-r | \-\-replace "] \c"
.RB [ \-f | \-\-flat ]
Imports the newsfeeds, folders, and tags found in the OPML formatted
.I 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.
.IP
The
.BR \-\-replace " (or " \-r )
option interprets the OPML file as the list of
.B 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
.B additions only.
.IP
The
.BR \-\-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
.B \-\-replace
option is possible.
.TP
.BR "export " \c
.RI < username "> \c"
.RI [< file ">] \c"
.RB [ \-f | \-\-flat ]
Exports a user's newsfeeds, folders, and tags to the OPML file specified by
.I file\c
, 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.
.IP
The
.BR \-\-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.
.
.
.SH "ADDITIONAL COMMANDS"
.TP
.BR "daemon" \c
.RB [ \-\-fork =\c
.IR pidfile ]
Starts the newsfeed fetching service.
Normally this command is only invoked by systemd.
.IP
The
.B \-\-fork
option executes an "old-style" fork-then-terminate daemon rather than a "new-style" non-terminating daemon.
This option should only be employed if using a System V-style init daemon on POSIX systems;
normally systemd is used. When using this option the daemon will write its process identifier to
.I pidfile
after forking.
.TP
.BR "feed refresh\-all"
Performs a one-time fetch of all stale feeds.
This command can be used as the basis of a
.B cron
job to keep newsfeeds up-to-date.
.TP
.BR "feed refresh " \c
.RI < n >
Performs a one-time fetch of the feed (not subscription) identified by integer
.IR n .
This is used internally by the fetching service and should not normally be needed.
.TP
.BR "conf save\-defaults " \c
.RI [< file >]
Prints default configuration parameters to standard output, or to
.I file
if specified.
Each parameter is annotated with a short description of its purpose and usage.
.
.
.SH "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.
.P
Booleans accept any of the values
.BR true / false ,
.BR 1 / 0 ,
.BR yes / no ,
or
.BR on / off .
.P
The following metadata properties exist for each user:
.TP
.BR num " (integer)"
The numeric identifier of the user.
This is assigned at user creation and is read-only.
.TP
.BR admin " (boolean)"
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.
.TP
.BR lang " (string)"
The preferred language of the user as a BCP 47 language tag, for example "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.
.TP
.BR tz " (string)"
The time zone of the user as a Time Zone Database identifier, for example "America/Los_Angeles".
.TP
.BR root_folder_name " (string)"
The name of the root folder, in protocols which allow it to be renamed.
.TP
.BR 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.
.TP
.BR theme " (string)"
The user's preferred user-interface theme.
This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR stylesheet " (string)"
A user stylesheet in CSS format.
This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
.
.
.SH EXAMPLES
.IP \[bu] 2
Add an administrator to the database with an explicit password:
.EX
$ arsse user add \-\-admin alice "Curiouser and curiouser!"
.EE
.P
.IP \[bu] 2
Add a regular user to the database with a random password:
.EX
$ arsse user add "Bob the Builder"
bLS!$_UUZ!iN2i_!\^IC6
.EE
.P
.IP \[bu] 2
Make Bob the Builder an administrator:
.EX
$ arsse user set "Bob the Builder" admin true
.EE
.P
.IP \[bu] 2
Disable Alice's account by clearing her password:
.EX
$ arsse user unset\-pass alice
.EE
.P
.IP \[bu] 2
Move all of Foobar's newsfeeds to the root folder:
.EX
$ arsse export foobar \-f | arsse import \-r foobar
.EE
.P
.IP \[bu] 2
Fail to log in as Alice:
.EX
$ arsse user auth alice "Oh, dear!"
Authentication failed
$ echo $?
1
.EE
.P
.
.
.SH "REPORTING BUGS"
.P
Any bugs found in The Arsse may be reported on the Web via the
.UR https://\:code.mensbeam.com/\:MensBeam/\:arsse
MensBeam code repository
.UE \c
\&. Reports may also be directed to the principal authors by e-mail:
.IP \[bu] 2
.UR https://\:jkingweb.ca/
J. King
.UE
.PD 0
.IP \[bu] 2
.UR https://\:dustinwilson.com/
Dustin Wilson
.UE
.PD

226
manpages/en.md
View file

@ -1,226 +0,0 @@
---
title: "ARSSE"
section: 1
date: 2021-07-03
footer: "arsse 0.10.0"
header: "User Commands"
---
# NAME
arsse - manage an instance of The Advanced RSS Environment (The Arsse)
# SYNOPSIS
**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** [**--fork=**<_pidfile_>]\
**arsse feed refresh-all**\
**arsse feed refresh** <_n_>\
**arsse conf save-defaults** [<_file_>]\
**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 and managing their metadata
- 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 subsequent section **ADDITIONAL COMMANDS**.
# PRIMARY COMMANDS
## Managing users and metadata
**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 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 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** [**--fork=**<_pidfile_>]
: Starts the newsfeed fetching service. Normally this command is only invoked by Systemd.
The **--fork** option executes an "old-style" fork-then-terminate daemon rather than a "new-style" non-terminating daemon. This option should only be employed if using a System V-style init daemon on POSIX systems; normally Systemd is used. When using this option the daemon will write its process identifier to <_pidfile_> after forking.
**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.
**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.
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
- 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 "Bob the Builder" 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 auth alice "Oh, dear!"
Authentication failed
$ echo $?
1
# 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/]()