nytpu
138 lines
3.8 KiB
Markdown
138 lines
3.8 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.
|
||
|
||
*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
|
||
|
||
*-w*, *--watch*
|
||
Watch a page for changes instead of adding as a feed. Useful for gophermaps,
|
||
or gemini/http resources with no parseable feed.
|
||
|
||
# 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 feed subscripton:
|
||
```
|
||
comitium add gemini://nytpu.com/gemlog/
|
||
```
|
||
|
||
This will add a new subscription over http:
|
||
```
|
||
comitium add -t a 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 docs at <https://git.nytpu.com/comitium/tree/doc/> 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.
|