Cleaned up and clarified documentation

README.md

@@ -1,11 +1,11 @@
 # comitium
 
-comitium is a [Gemini][] feed aggregator that supports Atom, RSS, JSON, and
-[Gemini feeds][], as well as tracking page changes.  Inspired by [gmisub][],
-[Lagrange’s built-in feeds][lagrange], [gemreader][] and many others.
+comitium is a [Gemini][], Gopher, and HTTP feed aggregator that supports Atom,
+RSS, JSON, and [Gemini feeds][], as well as tracking page changes, which is
+output into a simple static Gemini document that you can put anywhere.
 
 
-*Comitium* means “gathering” or “assembly” in latin.
+*Comitium* means “gathering” or “assembly” in Latin.
 
 
 [Gemini]: https://gemini.circumlunar.space/docs/faq.gmi
@@ -15,34 +15,38 @@ comitium is a [Gemini][] feed aggregator that supports Atom, RSS, JSON, and
 [gemreader]: https://sr.ht/~sircmpwn/gemreader/
 
 
+## why another aggregator?
+
+There sare many Gemini aggregators out there, and yet not one does everything I
+want it to.  I want an aggregator that:
+
+1. Works with Gemini and Gopher (and possibly http)
+2. Supports Atom, RSS, and Gemini feeds (and possibly JSON feeds)
+3. Can watch a page for changes
+4. Simple usage that doesn't get all tangled with my bookmarks
+   (\*cough\**Lagrange*\*cough\*)
+
+All of the aggregators always have really cool and unique features, and yet all
+that I've found don't meet one or more of these basic (IMO) criterion.  Hence,
+going and writing my own.
+
+Also, it's nice if it doesn't tie me to a specific browser/service; i.e.
+trivially self-hostable, ideally as CGI or static pages that can use an existing
+server setup.
+
+
 ## usage
 
-See `comitium help` for basic usage.  For more advanced usage, see
-[comitium(1)][comitium.1] and the [quickstart page][quickstart].
+See `comitium help` for basic usage.  For more detailed usage, see
+[comitium(1)][comitium.1].
+
+To get up and running, see the [quickstart page][quickstart].
 
 
 [comitium.1]: doc/comitium.1.scd
 [quickstart]: doc/quickstart.md
 
 
-## why another aggregator?
-
-There's many gemini aggregators out there, and yet not one does everything I
-want it to.  I want an aggregator that:
-
-1. works with gemini (and possibly gopher & http)
-2. supports atom (and possibly rss & json)
-3. supports gemini feeds
-4. can watch for page changes (and possibly watch for new gemtext headers as
-	 well)
-5. doesn't tie me to a specific browser/service; i.e. trivially self-hostable,
-	 ideally as cgi or static pages that can use an existing server setup.
-
-All of the aggregators always have really cool features (that I may or may not
-even use) and yet all (that I've found) don't meet one or more of these
-criterion.  Hence, going and writing my own.
-
-
 ## building
 
 Dependencies:
@@ -79,14 +83,32 @@ Send patches and issue reports to
 License, either version 3 of the License, or (at your option) any later
 version.  For more information, see [LICENSE][] or the [GNU website][agpl-3]
 
-`comitium` uses the [go-gemini][], [gofeed][], and [go-homedir][] libraries,
-all of which are covered under the terms of the MIT License].  It also uses the
-[pflag][] library, which is licensed terms of the BSD 3-Clause License.
-
 
 [LICENSE]: LICENSE
 [agpl-3]: https://www.gnu.org/licenses/agpl-3.0-standalone.html
+
+
+## attributions
+
+`comitium` took inspiration and small code snippets from:
+
+* [Amfora][] — how to structure saving subscriptions to JSON and refreshing
+  subscriptions with goroutines.
+* [gemreader][] — simple Gemini feed parsing.
+
+`comitium` gratefully makes use of the following libre libraries:
+
+* [go-gemini][] for fetching Gemini resources.
+* [go-gopher][] for fetching Gopher resources.
+* [gofeed][] for parsing Atom, RSS, and JSON feeds.
+* [pflag][] for parsing flags and arguments.
+* [go-homedir][] for locating configuration directories.
+
+
+[Amfora]: https://github.com/makeworld-the-better-one/amfora
+[gemreader]: https://git.sr.ht/~sircmpwn/gemreader
 [go-gemini]: https://git.sr.ht/~adnano/go-gemini
+[go-gopher]: https://github.com/prologic/go-gopher
 [gofeed]: https://github.com/mmcdole/gofeed
-[go-homedir]: https://github.com/mitchellh/go-homedir
 [pflag]: https://github.com/spf13/pflag
+[go-homedir]: https://github.com/mitchellh/go-homedir

doc/comitium.1.scd

@@ -54,6 +54,14 @@ command-specific flags that are not universally recognized.
 *-d* _PATH_, *--data* _PATH_
 	Set the data directory where *comitium* will store its files.
 
+## 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*
@@ -103,7 +111,7 @@ 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
+comitium add https://www.nytpu.com/files/atom.xml
 ```
 
 This will add a new subscription to watch for changes:
@@ -126,8 +134,9 @@ instance if you want to separate different topics into their own feeds.
 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.
+For a tutorial, see the quickstart at
+<https://git.nytpu.com/comitium/tree/doc/quickstart.md> or in *docs/* in your
+local repository.
 
 # AUTHOR