= 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)