205 lines
6.0 KiB
Plaintext
205 lines
6.0 KiB
Plaintext
= mastorss(1)
|
|
:doctype: manpage
|
|
:Author: tastytea
|
|
:Email: tastytea@tastytea.de
|
|
:Date: 2021-01-18
|
|
:Revision: 0.0.0
|
|
:man source: mastorss
|
|
:man manual: General Commands Manual
|
|
|
|
== NAME
|
|
|
|
mastorss - Another RSS to Mastodon bot.
|
|
|
|
== SYNOPSIS
|
|
|
|
*mastorss* [--help|--version] <profile>
|
|
|
|
== DESCRIPTION
|
|
|
|
*mastorss* reads RSS feeds and posts the items via the Mastodon API. Does not
|
|
support Atom at the moment.
|
|
|
|
== OPTIONS
|
|
|
|
*--dry-run*::
|
|
Do everything like normal, but don't post anything and don't update the config
|
|
file. The initial config file is still created, if the profile doesn't
|
|
exist. The interval between posts is set to 1 second.
|
|
|
|
*--help*::
|
|
Show a short help message.
|
|
|
|
*--version*::
|
|
Show version, copyright and license.
|
|
|
|
== USAGE
|
|
|
|
Put `watchwords.json` into `${XDG_CONFIG_HOME}/mastorss/`. Launch with profile
|
|
name. The first occurence of every watchword in an RSS item will be turned into
|
|
a hashtag (unless *add_hashtags* is set to false). For profile-specific
|
|
watchwords see the example in `watchwords.json`. In the first run only the
|
|
newest entry is posted unless *keep_looking* is set to true.
|
|
|
|
The profile is the identifier for a feed and can't be named "global".
|
|
|
|
.Launch mastorss with the profile “example”.
|
|
================================================================================
|
|
[source,shellsession]
|
|
--------------------------------------------------------------------------------
|
|
% mastorss example
|
|
--------------------------------------------------------------------------------
|
|
================================================================================
|
|
|
|
=== Configuration
|
|
|
|
If the profile does not exist yet, a configuration will be created interactively
|
|
and then saved to `${XDG_CONFIG_HOME}/mastorss/config-<profile>.json`.
|
|
|
|
*access_token*::
|
|
The API token needed to communicate with the Mastodon API on the _instance_
|
|
you're using to post.
|
|
|
|
*append*::
|
|
This string will be appended to every post.
|
|
|
|
*feedurl*::
|
|
The URI of the source feed.
|
|
|
|
*fixes*::
|
|
Array of regular expressions that should be deleted from the text. Applies to
|
|
RSS descriptions (before the HTML is stripped). For information about the syntax
|
|
see *perlre*(1).
|
|
|
|
*instance*::
|
|
Hostname of the instance you're using to post.
|
|
|
|
*keep_looking*::
|
|
If true, keep looking for new items after encountering the first that was
|
|
already posted. If you set this in the beginning, the whole feed will get
|
|
posted, since all items are new.
|
|
|
|
*interval*::
|
|
Time to wait between posts.
|
|
|
|
*max_size*::
|
|
Maximum number of characters a post can have.
|
|
|
|
*skip*::
|
|
Array of strings with titles of posts that should be skipped. Matched against
|
|
the beginning of the title; this means: “Good Day” will match “Good Day in
|
|
Happytown” but not “A Good Day in Happytown”.
|
|
|
|
*titles_as_cw*::
|
|
If true, the title will be used as the subject (also known as spoiler warning or
|
|
content warning) of the post.
|
|
|
|
*titles_only*::
|
|
If true, only post titles, no descriptions.
|
|
|
|
*replacements*::
|
|
Object with a list of regular expressions and replacements. Applies to posts
|
|
(after the HTML is stripped), subjects and links, but not to the string in
|
|
_append_. For information about the syntax see *perlre*(1).
|
|
|
|
*add_hashtags*::
|
|
If true, replace words with hashtags according to `watchwords.json`.
|
|
|
|
== EXAMPLES
|
|
|
|
=== Configuration file
|
|
|
|
[source,json]
|
|
--------------------------------------------------------------------------------
|
|
{
|
|
"example" :
|
|
{
|
|
"access_token" : "123abc",
|
|
"append" : "#bot",
|
|
"feedurl" : "https://example.com/feed.rss",
|
|
"fixes" :
|
|
[
|
|
"delete this",
|
|
"<p>[Rr]ead more(\.{3}|…)</p>"
|
|
],
|
|
"instance" : "newsbots.eu",
|
|
"interval" : 600,
|
|
"keep_looking" : false,
|
|
"max_size" : 500,
|
|
"skip" :
|
|
[
|
|
"If the title starts with this, skip it",
|
|
"Skip me too!"
|
|
],
|
|
"titles_as_cw" : true,
|
|
"titles_only" : false,
|
|
"replacements" :
|
|
{
|
|
"apple" : "strawberry",
|
|
"(chest|wal)nut" : "hazelnut"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------------------------------------
|
|
|
|
== PROTOCOL SUPPORT
|
|
|
|
Currently only HTTP and HTTPS are supported.
|
|
|
|
== PROXY SERVERS
|
|
|
|
Since mastorss is built on libcurl, it respects the same proxy environment
|
|
variables. See *curl*(1), section _ENVIRONMENT_.
|
|
|
|
.Tunnel connections through tor.
|
|
================================================================================
|
|
[source,shellsession]
|
|
--------------------------------------------------------------------------------
|
|
% ALL_PROXY="socks4a://[::1]:9050" mastorss example
|
|
--------------------------------------------------------------------------------
|
|
================================================================================
|
|
|
|
== FILES
|
|
|
|
*Configuration file directory*::
|
|
`${XDG_CONFIG_HOME}/mastorss/`
|
|
|
|
`${XDG_CONFIG_HOME}` is usually `~/.config`.
|
|
|
|
== ERROR CODES
|
|
|
|
[cols=">,<"]
|
|
|===============================================================================
|
|
| Code | Explanation
|
|
|
|
| 1 | No profile specified.
|
|
| 2 | Network error.
|
|
| 3 | File error.
|
|
| 4 | Mastodon API error.
|
|
| 5 | JSON error, most likely the file is wrongly formatted.
|
|
| 6 | Feed parse error. Usually the type of feed could not be detected.
|
|
| 9 | Unknown error.
|
|
|===============================================================================
|
|
|
|
== DEBUGGING
|
|
|
|
Define the variable `MASTORSS_DEBUG` to enable debug output.
|
|
|
|
.Debug mastorss while using the profile “example”.
|
|
================================================================================
|
|
[source,shellsession]
|
|
--------------------------------------------------------------------------------
|
|
% MASTORSS_DEBUG=1 mastorss example
|
|
--------------------------------------------------------------------------------
|
|
================================================================================
|
|
|
|
== REPORTING BUGS
|
|
|
|
Bugtracker: https://schlomp.space/tastytea/mastorss/issues
|
|
|
|
E-mail: tastytea@tastytea.de
|
|
|
|
== SEE ALSO
|
|
|
|
*perlre*(1), *curl*(1), *crontab*(1), *crontab*(5)
|