mirror of
https://code.mensbeam.com/MensBeam/Arsse.git
synced 2024-12-22 13:12:41 +00:00
More work on mdoc manual
This commit is contained in:
J. King
parent
174ed544b2
commit
2ff3286aa9
2 changed files with 222 additions and 11 deletions
|
|
@ -11,7 +11,7 @@
|
|||
.Sh SYNOPSIS
|
||||
.Nm "arsse user"
|
||||
.Op Nm list
|
||||
.Nm "arsee user add"
|
||||
.Nm "arsse user add"
|
||||
.Ar username
|
||||
.Op Ar password
|
||||
.Op Fl Fl admin
|
||||
|
|
@ -77,12 +77,223 @@ Managing passwords and authentication tokens
|
|||
Importing and exporting OPML newsfeed-lists
|
||||
.El
|
||||
.Pp
|
||||
.Sm off
|
||||
These are documented in the next section
|
||||
.Sx COMMANDS
|
||||
\&. Further, seldom-used commands are documented in the following section
|
||||
.Sx "ADDITIONAL COMMANDS"
|
||||
\&.
|
||||
.Sm on
|
||||
.Sx COMMANDS Ns No .
|
||||
Further, seldom-used commands are documented in the following section
|
||||
.Sx ADDITIONAL COMMANDS Ns No .
|
||||
.
|
||||
.
|
||||
.Sh COMMANDS
|
||||
.
|
||||
.Ss Managing users and metadata
|
||||
.Bl -tag
|
||||
.It Nm "user" Op Nm list
|
||||
Displays a simple list of user names with one entry per line
|
||||
.It Nm "user add" Ar username Oo Ar password Oc Oo Fl Fl admin Oc
|
||||
Adds a new user to the database with the specified username and password.
|
||||
If
|
||||
.Ar password
|
||||
is omitted a random password will be generated and printed.
|
||||
.Pp
|
||||
The
|
||||
.Fl Fl 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.
|
||||
.It Nm "user remove" Ar username
|
||||
Immediately removes a user from the database.
|
||||
All associated data (folders, subscriptions, etc.) are also removed.
|
||||
.It Nm "user show" Ar username
|
||||
Displays a table of metadata properties and their assigned values for
|
||||
.Ar username Ns No .
|
||||
These properties are primarily used by the Miniflux protocol.
|
||||
Consult the section
|
||||
.Sx USER METADATA
|
||||
for details.
|
||||
.It Nm "user set" Ar username Ar property Ar value
|
||||
Sets a metadata property for a user.
|
||||
These properties are primarily used by the Miniflux protocol.
|
||||
Consult the section
|
||||
.Sx USER METADATA
|
||||
for details.
|
||||
.It Nm "user unset" Ar username Ar property
|
||||
Clears a metadata property for a user.
|
||||
The property is thereafter set to its default value, which is protocol-dependent.
|
||||
.El
|
||||
.
|
||||
.Ss Managing passwords and authentication tokens
|
||||
.Bl -tag
|
||||
.It Nm "user set\-pass" Ar username Oo Ar password Oc Oo Fl Fl fever Oc
|
||||
Changes a user's password to the specified value.
|
||||
If no password is specified, a random password will be generated and printed.
|
||||
.Pp
|
||||
The
|
||||
.Fl Fl 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.
|
||||
.It Nm "user unset\-pass" Ar username Oo Fl Fl fever Oc
|
||||
Unsets a user's password, effectively disabling their account.
|
||||
As with password setting, the
|
||||
.Fl Fl fever
|
||||
option may be used to operate on a user's Fever password instead of their general password.
|
||||
.It Nm "user auth" Ar username Ar password Oo Fl Fl fever Oc
|
||||
Tests logging a user in.
|
||||
This only checks that the user's password is correctly recognized;
|
||||
it has no side effects.
|
||||
.Pp
|
||||
The
|
||||
.Fl Fl fever
|
||||
option may be used to test the user's Fever protocol password, if any.
|
||||
.It Nm "token list" Ar 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.
|
||||
.It Nm "token create" Ar username Oo Ar label Oc
|
||||
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
|
||||
.Ar label
|
||||
may be specified to give the token a meaningful name.
|
||||
.It Nm "token revoke" Ar username Oo Ar token Oc
|
||||
Deletes the specified
|
||||
.Ar token
|
||||
from the database.
|
||||
The token itself must be supplied, not its label.
|
||||
If it is omitted all tokens for
|
||||
.Ar username
|
||||
are revoked.
|
||||
.El
|
||||
.
|
||||
.Ss Importing and exporting data
|
||||
.Bl -tag
|
||||
.It Nm "import" Ar username Oo Ar file Oc Oo Fl r | Fl Fl replace Oc Oo Fl f | Fl Fl flat Oc
|
||||
Imports the newsfeeds, folders, and tags found in the OPML formatted
|
||||
.Ar 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.
|
||||
.Pp
|
||||
The
|
||||
.Fl Fl replace
|
||||
(or
|
||||
.Fl r Ns
|
||||
) option interprets the OPML file as the list of
|
||||
.Em 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
|
||||
.Em additions only Ns No .
|
||||
.Pp
|
||||
The
|
||||
.Fl Fl flat
|
||||
(or
|
||||
.Fl f Ns
|
||||
) option can be used to ignore any folder structures in the file, importing any newsfeeds directly into the root folder.
|
||||
Combining this with the
|
||||
.Fl Fl replace
|
||||
option is possible.
|
||||
.It Nm "export" Ar username Oo Ar file Oc Oo Fl f | Fl Fl flat Oc
|
||||
Exports a user's newsfeeds, folders, and tags to the OPML file specified by
|
||||
.Ar file Ns
|
||||
, 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.
|
||||
.Pp
|
||||
The
|
||||
.Fl Fl flat
|
||||
(or
|
||||
.Fl f Ns
|
||||
) 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.
|
||||
.El
|
||||
.
|
||||
.
|
||||
.Sh ADDITIONAL COMMANDS
|
||||
.Bl -tag
|
||||
.It Nm "daemon" Oo Fl Fl fork Ns = Ns Ar pidfile Oc
|
||||
Starts the newsfeed fetching service.
|
||||
Normally this command is only invoked by systemd.
|
||||
.Pp
|
||||
The
|
||||
.Fl Fl 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
|
||||
.Ar pidfile
|
||||
after forking.
|
||||
.It Nm "feed refresh\-all"
|
||||
Performs a one-time fetch of all stale feeds.
|
||||
This command can be used as the basis of a
|
||||
.Nm cron
|
||||
job to keep newsfeeds up-to-date.
|
||||
.It Nm "feed refresh" Ar n
|
||||
Performs a one-time fetch of the feed (not subscription) identified by integer
|
||||
.Ar n Ns No .
|
||||
This is used internally by the fetching service and should not normally be needed.
|
||||
.It Nm "conf save\-defaults" Oo Ar file Oc
|
||||
Prints default configuration parameters to standard output, or to
|
||||
.Ar file
|
||||
if specified.
|
||||
Each parameter is annotated with a short description of its purpose and usage.
|
||||
.El
|
||||
.
|
||||
.
|
||||
.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.
|
||||
.Pp
|
||||
Booleans accept any of the values
|
||||
.Ar true Ns No / Ns Ar false Ns No ,
|
||||
.Ar 1 Ns No / Ns Ar 0 Ns No ,
|
||||
.Ar yes Ns No / Ns Ar no Ns No ,
|
||||
or
|
||||
.Ar on Ns No / Ns Ar off Ns No .
|
||||
.Pp
|
||||
The following metadata properties exist for each user:
|
||||
.Pp
|
||||
.Bl -tag
|
||||
.It Cm num No (integer)
|
||||
The numeric identifier of the user.
|
||||
This is assigned at user creation and is read-only.
|
||||
.It Cm admin No (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.
|
||||
.It Cm lang No (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.
|
||||
.It Cm tz No (string)
|
||||
The time zone of the user as a Time Zone Database identifier, for example "America/Los_Angeles".
|
||||
.It Cm root_folder_name No (string)
|
||||
The name of the root folder, in protocols which allow it to be renamed.
|
||||
.It Cm sort_asc No (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.
|
||||
.It Cm theme No (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.
|
||||
.It Cm page_size No (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.
|
||||
.It Cm shortcuts No (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.
|
||||
.It Cm gestures No (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.
|
||||
.It Cm reading_time No (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.
|
||||
.It Cm stylesheet No (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.
|
||||
.El
|
||||
.
|
||||
.
|
||||
.Sh EXAMPLES
|
||||
|
|
|
|||
|
|
@ -89,7 +89,7 @@ Further, seldom-used commands are documented in the following section
|
|||
.
|
||||
.
|
||||
.SH COMMANDS
|
||||
.SS "Managing uses and metadata"
|
||||
.SS "Managing users and metadata"
|
||||
.TP
|
||||
.BR "user " [ list ]
|
||||
Displays a simple list of user names with one entry per line
|
||||
|
|
@ -132,7 +132,7 @@ Consult the section
|
|||
.B "USER METADATA"
|
||||
for details.
|
||||
.TP
|
||||
.BR "user set " \c
|
||||
.BR "user unset " \c
|
||||
.RI < username "> \c"
|
||||
.RI < property >
|
||||
Clears a metadata property for a user.
|
||||
|
|
@ -153,7 +153,7 @@ 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 set\-pass " \c
|
||||
.BR "user unset\-pass " \c
|
||||
.RI < username "> \c"
|
||||
.RB [ \-\-fever ]
|
||||
Unsets a user's password, effectively disabling their account.
|
||||
|
|
@ -163,7 +163,7 @@ option may be used to operate on a user's Fever password instead of their genera
|
|||
.TP
|
||||
.BR "user auth " \c
|
||||
.RI < username "> \c"
|
||||
.RI [< password ">] \c"
|
||||
.RI < password "> \c"
|
||||
.RB [ \-\-fever ]
|
||||
Tests logging a user in.
|
||||
This only checks that the user's password is correctly recognized;
|
||||
|
|
|
|||
Loading…
Reference in a new issue