doc improvements

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

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.