mastorss/man/mastorss.1.adoc

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

*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,
        "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)