add man page

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 <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
+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.