feed2toot/docs/source/configure.rst

Configure Feed2toot
===================

As a prerequisite to use Feed2toot, you need to authorize a Mastodon app for your account.

Just use the script register_feed2toot_app to register the feed2toot app for your account.::

    $ ./register_feed2toot_app

    This app generates Mastodon app credentials needed by Feed2toot.
    feed2toot_clientcred.txt and feed2toot_usercred.txt will be written in the current dir /home/chaica/progra/python/feed2toot.
    One connection is initiated to create the app.
    Your password is *not* stored.

    Mastodon instance url (defaults to https://mastodon.social):
    Mastodon login:chaica@ohmytux.com
    Mastodon password:
    The feed2toot app was added to your preferences=>authorized apps page

As described above, two files were created. You'll need them in the feed2toot configuration.

In order to configure Feed2toot, you need to create a feed2toot.ini file (or any name you prefer, finishing with the extension .ini) with the following parameters::

    [mastodon]
    instance_url=https://mastodon.social
    ; Here you need the two files created by register_feed2toot_app
    user_credentials=/etc/feed2toot/credentials/feed2toot_usercred.txt
    client_credentials=/etc/feed2toot/credentials/feed2toot_clientcred.txt
    ; Default visibility is public, but you can override it:
    ; toot_visibility=unlisted

    [cache]
    cachefile=/var/lib/feed2toot/feed2toot.db
    cache_limit=10000

    [rss]
    uri=https://www.journalduhacker.net/rss
    uri_list=/etc/feed2toot//rsslist.txt
    toot={title} {link}
    title_pattern=Open Source
    title_pattern_case_sensitive=true
    no_uri_pattern_no_global_pattern=true

    [hashtaglist]
    several_words_hashtags_list=/etc/feed2toot/hashtags.txt

    [feedparser]
    accept_bozo_exceptions=true

    [media]
    custom=/var/lib/feed2toot/media/logo.png

For the [mastodon] section:

- instance_url: the url of your Mastodon instance
- user_credentials: a file with the user credentials, generated by the command register_feed2toot_app
- client_credentials: a file with the client credentials, generated by the command register_feed2toot_app
- toot_visibility: any of the valid options for the *visibility* field
  `here`__.
  Default is *public*, but *unlisted* prevents flooding
  the instance's public timeline (which is more polite).

__ https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#posting-a-new-status

For the [cache] section:

- cachefile: the path to the cache file storing ids of already tooted links. Absolute path is mandatory. This file should always use the .db extension.
- cache_limit: length of the cache queue. defaults to 100.

For the [rss] section:

- uri: the url of the rss feed to parse
- uri_list: a path to a file with several adresses of rss feeds, one by line. Absolute path is mandatory.
- toot: format of the toot you want to post. It should use existing entries of the RSS fields like {title} or {link}. Launch it with this field empty to display all available entries. If you want to shorten the size of a field, you can use the syntax {summary:.100} to cut the field "summary" of the rss feed after the first 100 characters (starting from Feed2toot 0.10).
- {one field of the rss feed}_pattern: takes a string representing a pattern to match for a specified field of each rss entry of the rss feed, like title_pattern or summary_pattern.
- {one field of the rss feed}_pattern_case_sensitive: either the pattern matching for the specified field should be case sensitive or not. Default to true if not specified.
- no_uri_pattern_no_global_pattern: don't apply global pattern (see above) when no pattern-by-uri is defined in the uri_list. Allows to get all entries of a rss in the uri_list because no pattern is defined so we match them all. Defaults to false, meaning the global patterns will be tried on every rss in the uri_list NOT HAVING specific patterns and so ONLY entries from the specific uri in the uri_list matching the global patterns will be considered.
 addtags: add the tags from the rss feed at the end of the toot. Defaults to true.

For the [hashtaglist] section:

- several_words_hashtags_list: a path to the file containing hashtags in two or more words. Absolute path is mandatory. By default Feed2toot adds a # before every words of a hashtag. See documentation below for an example of this file.

for the [feedparser] section:

- accept_bozo_exceptions: If set to true, feed2toot will accept malformed feeds, which are rejected by default.

For the [media] section:

- custom: the path to a media (should be supported by Mastodon) to be posted with every Mastodon post.

Example of the list of hash tags
================================
The list of hash tags is a simple text file with one hash tag composed by several words on a single line::

    free software community
    open-source

Instead of having #free #software #community or #open-source in the resulting toot, you will have #freesoftwarecommunity and #opensource. You only have to identify the hash tags you frequently use in your RSS feeds and put them in this file to have well formatted hash tags in your toots.

List of rss feeds
=================
Simple list of rss feeds
------------------------
With the parameter **uri_list**, you can define a list of uri to use. Feed2toot is able to match specific patterns for each of the rss feeds from this list. Consider the following rss section of the configuration file::

    [rss]
    uri_list=/home/john/feed2toot/rsslist.txt
    toot={title} {link}

Now let's have a look at the =/home/john/feed2toot/rsslist.txt file::

    https://www.journalduhacker.net/rss
    https://carlchenet.com/feed

Each line of this file is a url to a rss feed. Pretty simple.

Display the name of the feed in the toots
-----------------------------------------

If you want to display the name of the feed in the resulting toot, you can do so by giving it a name with the following syntax::

    Le journal du hacker <https://www.journalduhacker.net/rss/>

Then in the `toot` configuration, you can use the `{feedname}` syntax, which will be replaced by the actual name of the feed.

Match specific patterns of rss feeds in the uri_list files
----------------------------------------------------------
You can use specific pattern matching for uri in the uri_list file to filter some of the rss entries of a rss feed. Lets modify the previous file::

https://www.journalduhacker.net/rss|title|hacker,psql
https://carlchenet.com/feed|title|gitlab

Each line of this file starts with an uri, followed by a pipe (|), followed by the name of the available section to parse (see below), again followed by a pipe (|), followed by patterns, each pattern being separated from the other one by a semi-colon (,).

In the example file above wee get every rss entries from the feed available at https://www.journalduhacker.net/rss where a substring in the title section of this entry matches either "hacker" or "psql". Specific patterns are not case sensitive. For the second line, we match every rss entries from the feed available at https://carlchenet.com/feed where a substring in the title section of this entry matches "gitlab".

Consider every entries of a rss feed from a uri in the uri_list file
--------------------------------------------------------------------
It is possible to get all entries from a rss feed available in the uri_list file. You need an option to deactivate the global pattern matching for uri in the uri_list NOT having specific patterns::

    [rss]
    ...
    no_uri_pattern_no_global_pattern=true

In you rsslist.txt, just don't give anything else than the needed feed url to get all the entries::

    https://www.journalduhacker.net/rss|title|hacker,psql
    https://carlchenet.com/feed|title|gitlab
    https://blog.linuxjobs.fr/feed.php?rss

The last line of the file above only has the url of a rss feed. All entries from this feed will be tooted.

How to display available sections of the rss feed
=================================================
Feed2toot offers the **--rss-sections** command line option to display the available section of the rss feed and exits::

    $ feed2toot --rss-sections -c feed2toot.ini
    The following sections are available in this RSS feed: ['title', 'comments', 'authors', 'link', 'author', 'summary', 'links', 'tags', id', 'author_detail', 'published'].