[[[ SYNOPSIS ]]]

gancioff [options] <configuration file path>

[[[ DESCRIPTION ]]]

This is GancioFF v0.3, a CLI PHP script that can be used to periodically
fetch the RSS feed from an instance of Gancio (https://gancio.org) and post
its new entries – the events – on the fediverse through a Mastodon account,
keeping track of already posted events’ GUIDs (Global Unique IDentifiers) in
order to post only the new ones on each run.
 It can be useful, for example, when the admins of a Gancio instance chose not
to use its federation feature because it would be too heavy on its server: in
this case GancioFF is a quite light alternative, moving from the server
running Gancio to the one running Mastodon the burden of posting each event to
all the instances that host at least one follower, and of sending them the
image a Gancio user can and almost always do attach to each event, because
GancioFF will fetch it only once and attach it to the post for the event.
 GancioFF is meant to be periodically run, every half an hour or so, by a cron
job, or systemd timer, or the likes (you can find a sample «gancioff.timer»
and a commented sample «gancioff.service» in the «systemd» directory).
 In order to work, GancioFF needs a configuration file path to be passed to it
as an argument on the command line.

[[[ CONFIGURATION FILE ]]]

The configuration file needs to be like this:

--- Example configuration file ---
# Lines beginnig with a «#» and empty lines will be ignored

# «feed_url» is required to specify the URL to fetch the RSS feed from;
# for example:
feed_url = https://gancio.some.domain/feed/rss?show_recurrent=true

# «fedi_hostname» is required to specify the hostname of the Mastodon instance
# you want to post to; for example:
fedi_hostname = mastodon.another.domain

# «fedi_token» is required to specify an «app token» to access the account
# that you want to use on the instance defined by «fedi_hostname». On Mastodon
# default web frontend you can get such a token under «Preferences» ->
# «Development», by clicking on the «New application» button; the new
# application should have at least the «write:media» and «write:statuses»
# privileges; when you’ll be done setting it up, it will be listed under
# «Your applications», and by clicking on its name you’ll be able to copy
# «Your access token» and paste it here. For example:
fedi_token = w6oQ_Ot2LSAm_Q31hrvp0asfl22ip3O4ipYq1kV1ceY

# «state_file_absolute_path» is required to specify the absolute path of the
# state file where GancioFF will store the GUIDs of already posted events and
# the timestamps of the moments when it posted them (on each run, GancioFF
# will check for entries older than one year and discard them, in order to
# avoid the state file to grow too much). For example:
state_file_absolute_path = /var/local/cache/gancio.some.domain.feed.state

# «posts_language» is required to specify the ISO 639-1 code for the language
# of posts (see https://www.loc.gov/standards/iso639-2/php/code_list.php for
# a complete list); for example:
posts_language = it

# «posts_visibility» is optional and lets you override the default “public”
# visibility of posts; it can be set to «public» (posts will be visible in the
# «Local» and «Federated» timelines, and any user will be able to boost them),
# «unlisted» (posts will be visible only in the «Home» timeline of followers
# and on the profile of the Mastodon account in use, not in the «Local» or
# «Federated» timelines, but any user will still be able to boost them),
# «private» (AKA «followers only»: posts will be visible only by followers and
# won’t be boostable by anyone), and «direct» (since GancioFF posts won’t ever
# explicitly mention any account, posts with this visibility will be visible
# only from the Mastodon account in use). For example:
post_visibility = unlisted

# «max_post_length» is optional and lets you override the automatically
# detected maximum length that a post can have on the instance specified with
# «fedi_hostname»; it can be used for testing purposes or just to keep the
# posts shorter than they would be otherwise; for example:
max_post_length = 840

# «always_link_gancio_post» is optional and if unspecified it defaults to
# «false», which means that GancioFF adds to the Mastodon post a link to the
# original Gancio post only if the latter is too long to fit into the first
# (i.e. into the Mastodon instance “max post length”, or into the
# «max_post_length» specified in this configuration file - see above); this
# way, GancioFF reduces the burden on the Gancio instance that is due to the
# requests that it gets from every Mastodon instance where a Mastodon post
# with a link to the original Gancio post will end up, in order for each of
# them to generate a “link preview”; such burden gets reduced in different
# measures depending on the average length of a post on the Gancio instance
# and on the “max post length” on the Mastodon instance that GancioFF is using
# to post (or on the «max_post_length» explicitly specified in this file).
# If set to «true», GancioFF will instead always add a link to the original
# Gancio post.
always_link_gancio_post = true
--- End of example configuration file ---

[[[ OPTIONS ]]]

-h / --help
  Show this help text and exit.
-t / --test
  Do a test: GancioFF will try as always to read the configuration file, fetch
 the defined Mastodon instance’s info, load the state file and fetch the feed,
 but it will post only the first event it may find there, with a visibility of
 «direct», even if according to the state file it has already been posted, and
 won’t update the state file.
-p / --do-post <y|n>
  When a state file already exists, this option defaults to «y» («yes»), which
 means that GancioFF will try to post all the new events it may find in the
 feed; if set to «n» («no»), GancioFF will not try to post them, but it will
 save their GUIDs into the state file nonetheless, so they won’t be posted
 again on subsequent runs.
  This is mainly useful on GancioFF’s first run on a given feed, i.e. when
 the state file specified in the configuration file doesn’t exist yet and thus
 all the events in the feed will be considered “new”: in this case, GancioFF
 refuses to run unless you explicitly set this option to «y» or «n»: this is a
 way to prevent you from unintentionally flooding your Mastodon instance with
 all the events in the feed.
  When “test mode” is active (see the previous option description), setting
 this option has no effect.
-v / --verbose
 Show some more messages about what the script is doing.
--
 Treat every possible subsequent argument as non-options. Useful only in the
 very improbable case your config file is named «--help» or as another option.

[[[ EXIT VALUES ]]]

0: regular run
1: some error occurred
99: killed with signal (ctrl+c, etc.)

[[[ DISCLAIMER AND LICENSE ]]]

This program comes with ABSOLUTELY NO WARRANTY; for details see the source.
This is free software, and you are welcome to redistribute it under certain
conditions; see <http://www.gnu.org/licenses/> for details.