From 2ff3286aa940683ecfdf4fceba3fa4cf7ed986c8 Mon Sep 17 00:00:00 2001 From: "J. King" Date: Fri, 27 Oct 2023 20:44:01 -0400 Subject: [PATCH] More work on mdoc manual --- manpages/arsse.1.en.mdoc | 225 +++++++++++++++++++++++++++++++++++++-- manpages/en.groff | 8 +- 2 files changed, 222 insertions(+), 11 deletions(-) diff --git a/manpages/arsse.1.en.mdoc b/manpages/arsse.1.en.mdoc index 977cab5..58dd034 100644 --- a/manpages/arsse.1.en.mdoc +++ b/manpages/arsse.1.en.mdoc @@ -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 diff --git a/manpages/en.groff b/manpages/en.groff index adb9403..4dc9ba8 100644 --- a/manpages/en.groff +++ b/manpages/en.groff @@ -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;