= mastorss(1)
:doctype:       manpage
:Author:        tastytea
:Email:         tastytea@tastytea.de
:Date:          2020-01-01
: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

*--help*::
Show 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. For profile-specific watchwords see the example in
`watchwords.json`. In the first run only the newest entry is posted.

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. 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.

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

== 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,shell]
// --------------------------------------------------------------------------------
// ALL_PROXY="socks4a://[::1]:9050" mastorss example
// --------------------------------------------------------------------------------
// ================================================================================

== PROXY SERVERS

mastorss supports HTTP proxies set via the environment variable
_http_proxy_. Accepted format: _+++http://[user[:password]@]host[:port]/+++_. No
SOCKS proxy support yet, sorry.

.Use mastorss with a proxy server
================================================================================
[source,shellsession]
--------------------------------------------------------------------------------
% http_proxy="http://localhost:3128/" 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), *crontab*(1), *crontab*(5)
