nytpu
165 lines
4.7 KiB
Markdown
165 lines
4.7 KiB
Markdown
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* [_FLAGS_]
|
|
Check for new updates to subscriptions and update aggregator page.
|
|
|
|
*regenerate*
|
|
Will regenerate all the files created by comitium using cached entries
|
|
without fetching any feeds.
|
|
|
|
*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.
|
|
Also to note: when adding a new subscription, you *do not* need to run
|
|
*refresh* afterwards, *add* will automatically fetch the entries and
|
|
regenerate the .gmi and .json files.
|
|
|
|
*remove* [_FLAGS_] <_LINK_>
|
|
Remove a subscription at _LINK_. Will remove from both subscribed feeds and
|
|
subscribed pages by default.
|
|
|
|
*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. See *FILES AND
|
|
DIRECTORIES* for more information.
|
|
|
|
## REFRESH FLAGS
|
|
|
|
*-n* _NUM_, *--num-workers* _NUM_
|
|
Number of worker threads to use when refreshing feeds. More is faster, but
|
|
there are more concurrent outgoing requests then, which can be not nice to
|
|
the servers you're hitting and to other people on your network. Defaults to
|
|
5.
|
|
|
|
## ADD FLAGS
|
|
|
|
*-w*, *--watch*
|
|
Watch a page for changes instead of adding as a feed. Useful for gophermaps,
|
|
or gemini/http resources with no parseable feed.
|
|
|
|
## REMOVE FLAGS
|
|
|
|
*-f*, *--feeds*
|
|
Remove the URL from subscribed feeds.
|
|
|
|
*-p*, *--pages*
|
|
Remove the URL from subscribed pages.
|
|
|
|
# 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.
|
|
|
|
*feed.gmi*
|
|
The outputted text/gemini file containing the subscription items. Is what
|
|
should be linked or copied to your server directory to publish it.
|
|
|
|
*subscriptions.gmi*
|
|
A text/gemini list of all the feeds being aggregated, suitable for remote
|
|
bookmarking, etc. Should also be linked or copied to your server directory.
|
|
|
|
# EXAMPLES
|
|
|
|
This will add a new feed subscripton:
|
|
```
|
|
comitium add gemini://nytpu.com/gemlog/
|
|
```
|
|
|
|
This will add a new subscription over http:
|
|
```
|
|
comitium add https://www.nytpu.com/files/atom.xml
|
|
```
|
|
|
|
This will add a new subscription to watch for changes:
|
|
```
|
|
comitium add --watch 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 <https://git.nytpu.com/comitium/about/>
|
|
or in your local copy of the repository.
|
|
|
|
For a tutorial, see the quickstart at
|
|
<https://git.nytpu.com/comitium/tree/doc/quickstart.md> or in *docs/* in your
|
|
local repository.
|
|
|
|
# AUTHOR
|
|
|
|
Maintained by nytpu <alex@nytpu.com>.
|
|
|
|
Source can be found at <https://git.nytpu.com/comitium>. Bugs & patches can
|
|
be sent to ~nytpu/public-inbox@lists.sr.ht.
|