Updated to help text as in b5b8c77 commit

README.md

@@ -5,19 +5,23 @@ gancioff [options] <configuration file path>
 
 [[[ 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 <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.
+ 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 <http://www.gnu.org/licenses/> for details.
 ```