From fc039cd7415ba6a6ab98601637bcef03ec5c3111 Mon Sep 17 00:00:00 2001
From: Jack Rusher <jack@rusher.com>
Date: Wed, 20 Sep 2017 16:07:22 +0200
Subject: [PATCH] doc improvements

---
 README.md    |  5 +++++
 doc/intro.md | 17 +++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/README.md b/README.md
index a8a5762..a0e3201 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,11 @@ dependencies. I've found it to be a nice basis for testing web
 applications, scraping content from Javascript-heavy websites,
 automating interactions with services, and so on.
 
+**N.B.** While Oracle's JVM bundles JavaFX, the OpenJDK JVM does not
+come with it. If you're using OpenJDK (which is the default on
+_ubuntu_, for example), you must also install the OpenJFX package on
+your chosen platform in order to use this library.
+
 ## Quick Start
 
 ``` clojure
diff --git a/doc/intro.md b/doc/intro.md
index fe319b0..d8d5b2b 100644
--- a/doc/intro.md
+++ b/doc/intro.md
@@ -35,3 +35,20 @@ retrieves the text of one:
       text))
 ;;=> "I hope you find Clojure's combination of facilities elegant, powerful, practical and fun to use."
 ```
+
+### Laziness and resource management
+
+Note that we cannot return a lazy collection of elements from inside
+the `with-browser` macro, as the underlying browser will no longer
+exist by the time the collection is realized. So, for example, if we
+were to modify the above example to look like this:
+
+``` clojure
+(with-browser [browser (make-browser)]
+  (-> (fetch! browser "http://clojure.org")
+      (find-by-xpath* "//div[@class='clj-intro-message']/p")))
+;;=> "I hope you find Clojure's combination of facilities elegant, powerful, practical and fun to use."
+```
+
+The elements returned by `find-by-xpath` would be inaccessible outside
+of the `with-browser` macro.