Jones/GancioF2F
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Updated to help text as in 2458d03 commit

Browse source
This commit is contained in:
pezcurrel 2024-10-29 13:54:43 +01:00
parent 2458d03010
commit da718747be
1 changed files with 31 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

61
README.md
View file

@ -1,30 +1,31 @@
```text
[[[ SYNOPSIS ]]]
gancioff [options] <configuration file path>
ganciof2f [options] <configuration file path>
[[[ DESCRIPTION ]]]
This is GancioFF v0.4.4, 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 announcements – on the fediverse through a
Mastodon account, recording into a state file a reference to each already
posted announcement in order to post only new or changed ones on each run.
This is GancioF2F v0.5 («GancioFeed2Fedi»), a CLI PHP script that can
be used to periodically fetch the JSON feed from an instance of Gancio
(https://gancio.org) and post its new or changed events announcements on the
Fediverse through a Mastodon account, recording into a state file a reference
to each already posted announcement in order to post only new or changed 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 fact, GancioFF is a light alternative to federating the Gancio instance,
in fact, GancioF2F is a light alternative to federating the Gancio instance,
moving from its server to the one running Mastodon the burden of posting each
announcement to each fediverse instance hosting at least one follower, and of
announcement to each Fediverse instance hosting at least one follower, and of
sending them the image a Gancio user can attach to each announcement, because
GancioFF will fetch it only once and attach it to the Mastodon post; moreover,
GancioF2F will fetch it only once and attach it to the Mastodon post; moreover,
by default, if an announcement on the Gancio instance fits into a Mastodon
post GancioFF doesn’t place a link to the original announcement into the post,
post GancioF2F doesn’t place a link to the original announcement into the post,
thus further reducing the burden due to the requests the Gancio instance gets
from every Mastodon instance trying to generate a “link preview”.
GancioFF is meant to be run periodically, 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
GancioF2F is meant to be run periodically, every half an hour or so, by a cron
job, or systemd timer, or the likes (you can find a sample «ganciof2f.timer»
and a commented sample «ganciof2f.service» in the «systemd» directory).
In order to work, GancioF2F needs a configuration file path to be passed to it
as an argument on the command line.
[[[ CONFIGURATION FILE ]]]
@ -34,9 +35,9 @@ as an argument on the command line.
--- 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.
# «feed_hostname» is required to specify the hostname of the Gancio instance.
# For example:
feed_url = https://gancio.some.domain/feed/rss?show_recurrent=true
feed_hostname = gancio.some.domain
# «fedi_hostname» is required to specify the hostname of the Mastodon instance
# you want to post to. For example:
@ -53,16 +54,16 @@ fedi_hostname = mastodon.another.domain
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 references to already posted
# announcements (on every run, GancioFF will check this file for entries older
# state file where GancioF2F will store the references to already posted
# announcements (on every run, GancioF2F will check this file for entries older
# than one year and discard them, to avoid the state file to grow too much).
# For example:
state_file_absolute_path = /var/local/cache/gancio.some.domain.feed.state
state_file_absolute_path = /var/local/cache/gancioff/gancio.some.domain.state
# «timezone» is required to specify the timezone of the Gancio instance, in
# order for GancioFF to calculate the correct datetimes. You can list the
# order for GancioF2F to calculate the correct datetimes. You can list the
# supported timezones using option «-T» or «--timezones» (see the related
# entry in the «OPTIONS» section. For example:
# entry in the «OPTIONS» section). For example:
timezone = Europe/Rome
# «posts_language» is required to specify the ISO 639-1 code for the language
@ -77,7 +78,7 @@ posts_language = it
# 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
# won’t be boostable by anyone), and «direct» (since GancioF2F posts won’t ever
# explicitly mention any account, posts with this visibility will be visible
# only from the Mastodon account in use, which may be good for testing).
# For example:
@ -90,13 +91,13 @@ post_visibility = unlisted
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
# «false», which means that GancioF2F 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 maximum post length allowed by the Mastodon instance, or into
# the «max_post_length» specified in this configuration file - see above);
# this further reduces the burden on the Gancio instance (see the second
# paragraph of the «Description» section).
# If set to «true», GancioFF will instead always add a link to the original
# If set to «true», GancioF2F will instead always add a link to the original
# Gancio announcement.
always_link_gancio_post = true
--- End of example configuration file ---
@ -107,29 +108,29 @@ always_link_gancio_post = true
Show this help text and exit.
-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 or changed announcements it
may find in the feed; if set to «n» («no»), GancioFF will not try to post
means that GancioF2F will try to post all the new or changed announcements it
may find in the feed; if set to «n» («no»), GancioF2F will not try to post
them, but it will still record a reference to each of them into the state
file, so they won’t be posted again on subsequent runs (unless they were
changed in the meantime).
This option is mainly useful on GancioFF’s first run on a given feed, i.e.
This option is mainly useful on GancioF2F’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 announcements in the feed will be considered “new”: in this
case, GancioFF refuses to run unless you explicitly set this option to «y» or
case, GancioF2F 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’s «Local» timeline, and possibly your followers’ «Home» timelines,
with all the announcements in the feed.
When “test mode” is active (see the next option description), setting this
option has no effect.
-t / --test
Do a test: GancioFF will try as always to read the configuration file, fetch
Do a test: GancioF2F 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 of the announcements 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.
This option also activates “verbose mode” (see below).
-v / --verbose
When this option is not set GancioFF prints only warning and error messages;
When this option is not set GancioF2F prints only warning and error messages;
when it is set it also prints informational messages about what it’s doing.
-T / --timezones
List all the supported timezones.