commit 83c817b4332bd0c91a432dfbf5c617898a2b5fd9
from: Omar Polo <op@omarpolo.com>
date: Wed Oct 13 16:05:48 2021 UTC

improve the README

commit - 1d126b158f872e4cad8db4a9bd5ac8a9d9cb6355
commit + 83c817b4332bd0c91a432dfbf5c617898a2b5fd9
blob - 3267c8bbfaa4c9343ea1a2383dfd3b8c3bbc776b
blob + 960728bfab9ffee399d41c8f6b124f4db4b2208d
--- README.md
+++ README.md
@@ -1,21 +1,22 @@
-# Gemini library for clojure
+# gemini.core
 
-`gemini.core` is a clojure library to make Gemini requests.
+A Clojure library to make Gemini requests.
 
 
 ## Usage
 
+Import the library for e.g. with:
+
 ```clojure
 user=> (require '[gemini.core :as gemini])
 ```
 
-#### fetch
+### Documentation
 
 `fetch` makes a Gemini request and returns a map with `:request`,
 `:meta`, `:code` and `:body` as keys, or `:error` if an error occur.
 
-The request needs to be closed afterwards using `close`, or calling
-the `.close` method on the `:request` object.
+The request needs to be closed afterwards using `close`.
 
 ```clojure
 user=> (gemini/fetch "gemini://gemini.circumlunar.space/")
@@ -27,26 +28,63 @@ user=> (gemini/fetch "gemini://gemini.circumlunar.spac
  #object[java.io.BufferedReader 0x49358b66 "java.io.BufferedReader@49358b66"]}
 ```
 
-#### body-as-string!
+`body-as-string!` reads all the response into a string and returns it.
+It also closes the request automatically.
 
-Read all the response into a string and returns it.  It also closes
-the request automatically.
-
 ```clojure
 user=> (-> (gemini/fetch "gemini://gemini.circumlunar.space/")
            gemini/body-as-string!)
 "# Project Gemini\n\n## Overview\n\nGemini is a new internet protocol which..."
 ```
 
-#### close
+`close` closes a request.  It needs to be called after every
+(successful) request.
 
-Closes a request.
+```clojure
+user=> (let [req (gemini/fetch "...")]
+         (when-not (:error req)
+		   ;; do something with req
+		   ,,,
+		   (gemini/close req)))
+```
 
-#### with-request
+`with-request` is a macro like `with-open` to making connection
+easily.  It automatically closes the request and evaluates the body
+only when the request is successful, otherwise throws an exception.
 
-Like `with-open`, but specifically for the requests:
-
 ```clojure
-user=> (with-request [req (fetch "gemini://gemini.circumlunar.space/")]
+user=> (with-request [req (gemini/fetch "gemini://gemini.circumlunar.space/")]
          ,,,)
 ```
+
+
+## Streaming content
+
+The `:body` keyword in the returned map is an instance of a Java
+BufferedReader, so streaming content is easy.
+
+However, `body-as-string!` needs to materialise the full reply, so in
+case of a streaming request it will never return!
+
+
+## text/gemini
+
+This library only implements the network part of Gemini, it doesn't
+try to handle any kind of content.  To handle text/gemini you can use
+e.g. the [gemtext][gemtext] library:
+
+```clojure
+user=> (require '[gemtext.core :as gemtext])
+nil
+user=> (gemini/with-request [req (gemini/fetch "gemini://gemini.circumlunar.space/")]
+         (gemtext/parse (:body req)))
+[[:header-1 "Project Gemini"]
+ [:text ""]
+ [:header-2 "Overview"]
+ [:text ""]
+ [:text "Gemini is a new internet protocol which:"]
+ ,,,]
+```
+
+
+[gemtext]: https://github.com/omar-polo/gemtext