Updated to help text as in “gancioff” commit 41cae16

README.md

@@ -6,26 +6,22 @@ gancioff [options] <configuration file>
 [[[ DESCRIPTION ]]]
 
 This is GancioFF v0.1, a CLI PHP script that can be used to periodically
-fetch the RSS feed from a Gancio¹ instance and post its entries – the events –
-on the fediverse through a Mastodon account, keeping track of already posted
-events in order to post only the new ones. 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 quite
-a 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 to 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 corresponding Mastdon post.
- 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 sample «gancioff.service» in the «systemd» directory).
- In order to work, GancioFF needs a configuration file to be passed to it
-as an argument on the command line, and the directory containing the specified
-configuration file needs to be not only readable, but also writeable by the
-user running GancioFF, because that’s where it will save the corresponding
-state file that it will use to keep track of already posted events.
-
-¹ https://gancio.org
+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 to be passed to it as
+an argument on the command line.
 
 [[[ CONFIGURATION FILE ]]]
 
@@ -34,50 +30,69 @@ 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,
+# «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
 # 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:statuses» privilege, and 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:
+# application should have at least the «write:statuses» privilege; 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:
+# posts shorter than they would be otherwise; for example:
 max_post_length = 840
 --- End of example configuration file ---
 
 [[[ OPTIONS ]]]
 
 -h / --help
- Show this help text and exit.
--p / --do-post
- By default the first run with a given configuration file, i.e. when there’s
- no corresponding state file yet, will be a “dry run”, that is: the script
- will automatically avoid posting the events it finds in the feed, to avoid
- flooding the timelines, but save their IDs in the state filejust as if «--do-not-post» or «-P» were given (see next option description). With «-p»
- or «--do-post» it will post them, instead.
- Also, if given after «-P» or «--do-not-post», it turns posting back on.
--I / --ignore-ids
- Ignore events’ IDs, that is: don’t try to load and save already posted
- events’ IDs from and to the state file.
--P / --do-not-post
- Don’t post new events that could be found in the feed. Unless you also
- specify «-I» or «--ignore-guids» (see previous option), this will add the IDs
- of possible new events to the state file, just as if they were posted, so
- those events will never be posted.
+  Show this help text and exit.
+-p / --do-post <y|n>
+ Setting this option to «n» («no») will make GancioFF skip posting. Note that
+ even in this case it will save into the state file the GUIDs of new events
+ it may find in the feed, so it won’t post them even on the subsequent runs.
+ You may want to set this option to «n» on the first run on a given feed, i.e.
+ when the state file doesn’t exist yet and all events in the feed will be
+ considered new, to avoid flooding the timeline of the given Mastodon
+ instance. That’s why when the state file doesn’t exist yet, GancioFF refuses
+ to run unless you explicitly set this option to «n» («no») or «y» («yes»).
+ When the state file exists, this option defaults to «y» («yes»).
 -v / --verbose
  Show some more messages about what the script is doing.
 --
@@ -88,6 +103,7 @@ max_post_length = 840
 
 0: regular run
 1: some error occurred
+99: killed with signal (ctrl+c, etc.)
 
 [[[ DISCLAIMER AND LICENSE ]]]