From 604ededefc234629a3a3b8d714625d54e6e47083 Mon Sep 17 00:00:00 2001 From: pezcurrel Date: Sun, 27 Oct 2024 06:53:08 +0100 Subject: [PATCH] Updated to help text as in b5b8c77 commit --- README.md | 98 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 50 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index da1c23c..56c7a77 100644 --- a/README.md +++ b/README.md @@ -5,19 +5,23 @@ gancioff [options] [[[ DESCRIPTION ]]] -This is GancioFF v0.4, a CLI PHP script that can be used to periodically + This is GancioFF v0.4.1, 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. +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. 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 +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, +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 +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, +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, +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 @@ -25,17 +29,17 @@ as an argument on the command line. [[[ CONFIGURATION FILE ]]] -The configuration file needs to be like this: + 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» 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: +# 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 @@ -49,15 +53,15 @@ 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 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 where GancioFF will store the references to already posted +# announcements (on every run, GancioFF 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 # «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: +# a complete list). For example: posts_language = it # «posts_visibility» is optional and lets you override the default “public” @@ -69,29 +73,25 @@ posts_language = it # «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: +# only from the Mastodon account in use, which may be good for testing). +# 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: +# 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). +# (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 -# Gancio post. +# Gancio announcement. always_link_gancio_post = true --- End of example configuration file --- @@ -101,30 +101,32 @@ always_link_gancio_post = true Show this help text and exit. -p / --do-post 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. + 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 + 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. + 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 + «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 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. + 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 it is set it also prints informational messages about what it’s doing. -- - Treat every possible subsequent argument as non-options. Useful only in the + 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 ]]] @@ -135,7 +137,7 @@ always_link_gancio_post = true [[[ 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 + 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 for details. ```