From f6dfbad0b53201d7d8d515ecf6339c6bae375eff Mon Sep 17 00:00:00 2001 From: nytpu Date: Tue, 16 Mar 2021 10:24:44 -0600 Subject: [PATCH] add man page --- doc/comitium.1.scd | 137 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 doc/comitium.1.scd diff --git a/doc/comitium.1.scd b/doc/comitium.1.scd new file mode 100644 index 0000000..3e138ac --- /dev/null +++ b/doc/comitium.1.scd @@ -0,0 +1,137 @@ +comitium(1) + +# NAME + +comitium - A feed aggregator for Gemini. + +# SYNOPSIS + +*comitium* <_COMMAND_> [_FLAGS_] [_ARGUMENTS_] + +# DESCRIPTION + +*comitium* is tool to subscribe to feeds on the Gemini protocol. It supports a +variety of feed formats: +- Gemini Feeds (https://gemini.circumlunar.space/docs/companion/subscription.gmi) +- Atom +- RSS +- JSON +- Watching pages for changes + +# COMMANDS + +*refresh* + Check for new updates to subscriptions and update aggregator page. + +*list* + List all subscriptions in a gemtext format suitable for remote bookmarking. + +*add* [_FLAGS_] <_LINK_> [_TITLE_] + Add a new subscription. _LINK_ is a link to the feed or watched URL. + _TITLE_ is an optional title for the feed, otherwise a title will be + automatically picked depending on the feed type. For Gemini feeds, the + first heading on a page is used as a title. For ATOM, RSS, and JSON feeds, + the provided title is used. For a page being watched for changes, the URL + itself is used. + +*remove* <_LINK_> + Remove a subscription at _LINK_. + +*help* + Print basic usage information, including a list of commands and flags with + abbreviated descriptions. + +*version* + Print version information. + +# FLAGS + +Global flags are recognized for all commands. The subsections are for +command-specific flags that are not universally recognized. + +## GLOBAL FLAGS + +*-d* _PATH_, *--data* _PATH_ + Set the data directory where *comitium* will store its files. + +## ADD FLAGS + +*-t* _TYPE_, *--type* _TYPE_ + Select which type a subscription is. Can be *g* for a Gemini feed; *a* for + Atom, RSS, & JSON; or *c* to watch the page for changes. Defaults to *g*. + +# ENVIRONMENT VARIABLES + +*COMITIUM_DATA* + Set the data directory. Equivalent to the *--data* flag. + +# FILES AND DIRECTORIES + +## DATA DIRECTORY + +All files used by comitium are stored in the data directory. The data path is +picked from the first available criterion in this list: + +. If provided, the *-d*/*--data* flag +. If set, the $*COMITIUM_DATA* environment variable. +. If $*XDG_DATA_HOME* is set, then _$XDG_DATA_HOME/comitium_ +. If $*HOME* is set and _$HOME/.local_ exists, then + _$HOME/.local/share/comitium_ +. If $*HOME* is set, then _$HOME/.comitium_ +. Otherwise, the current working directory is used as a last resort + +## FILES + +Within the data directory, the following files are used: + +*comitium.json* + A json file listing all of the feeds, their titles, their subscription + type, and subscription-type–specific information. If you need to modify a + subscription (change its title, update a link, etc) it should be trivial to + manually edit. + +*subscriptions.gmi* + The outputted text/gemini file containing the subscription items. Is what + should be linked or copied to your server directory to publish it. + +# EXAMPLES + +This will add a new Gemini feed subscripton: +``` +comitium add gemini://nytpu.com/gemlog/ +``` + +This will add a new atom subscription: +``` +comitium add -t a gemini://nytpu.com/flightlog/atom.xml +``` + +This will add a new subscription to watch for changes: +``` +comitium add --type a gemini://nytpu.com/photos/by-date.gmi nytpu's photos +``` +Note that when watching a page for changes, you should manually add a title, +otherwise the URL will be used. + +This will update all feeds and regenerate *subscriptions.gmi* if you use a +custom data directory: +``` +comitium refresh -d ~/comitium-test +``` +This also makes it possible to maintain multiple subscription "groups," for +instance if you want to separate different topics into their own feeds. + +# SEE ALSO + +For more information, see the README at +or in your local copy of the repository. + +For a tutorial, see the docs at or in +your local repository. + +# AUTHOR + +Maintained by nytpu . + +Source can be found at . Bugs & patches can +be sent to ~nytpu/public-inbox@lists.sr.ht.