improve docs about caching (fixes #192)

pollen/private/ts.rktd

@@ -1 +1 @@
-1545591698
+1545665361

pollen/scribblings/cache.scrbl

@@ -43,13 +43,13 @@ Be warned that this will make your rendering much slower. But you will be guaran
 
 @section{Scope of dependency tracking}
 
-The compile cache tracks the modification date of the source file, the current setting of @secref["The_POLLEN_environment_variable"], and the modification dates of the template and @filepath{pollen.rkt} (if they exist). 
+The compile cache tracks the modification date of the source file, the current setting of @secref["The_POLLEN_environment_variable"], and the modification dates of the template and @filepath{pollen.rkt} (if they exist). For @tt{poly} source files, it also tracks the @racket[current-poly-target]. It also tracks any files you've listed in the optional setup value @racket[setup:cache-watchlist].
 
 It does not, however, track every possible dependency. So in a complex project, it's possible to create deep dependencies that aren't noticed by the cache. 
 
 Unfortunately, there's no way around this problem. For the cache to be useful, there has to be a limit on the horizon of dependency checking. To capture every possible dependency, the cache would have to recompile every file, every time — which would be equivalent to not caching at all.
 
-Those who need that kind of deep dynamism can disable the cache.
+Those who need that kind of deep dynamism can disable the cache (with the setup values @racket[setup:render-cache-active] and @racket[setup:compile-cache-active]).
 
 
 @section[#:tag-prefix "cache"]{Functions}

pollen/scribblings/setup.scrbl

@@ -1,6 +1,6 @@
 #lang scribble/manual
 @(require "mb-tools.rkt")
-@(require scribble/eval pollen/setup racket/string (for-label racket syntax/modresolve (except-in pollen #%module-begin) pollen/setup))
+@(require scribble/eval pollen/setup racket/string (for-label racket racket/runtime-path syntax/modresolve (except-in pollen #%module-begin) pollen/setup))
 
 @(define my-eval (make-base-eval))
 @(my-eval `(require pollen pollen/setup))
@@ -108,14 +108,16 @@ Default separators used in decoding.
 
 @defoverridable[cache-watchlist (listof (or/c path? path-string?))]{List of extra files that the cache (= render cache + compile cache, collectively) watches during a project-server session. If one of the files on the watchlist changes, the cache is invalidated (just as it would be if @racket["pollen.rkt"] changed).
 
-If the cache can't find a certain file on the watchlist, it will be ignored. Therefore, to avoid unexpected behavior, the best policy is to pass in complete paths (or path strings). An easy way to convert a module name into a complete path is with @racket[resolve-module-path]:
+If the cache can't find a certain file on the watchlist, no error will arise. The file will simply be ignored. Therefore, to avoid unexpected behavior, the best policy is to use complete paths (or path strings). One way to generate a complete path to a local file is with @racket[define-runtime-path]. Another way, if you're using a module that's already installed as part of a package, is with @racket[resolve-module-path]:
 
 @fileblock["pollen.rkt" 
 @codeblock{
 (module+ setup
-  (require syntax/modresolve)
   (provide (all-defined-out))
-  (define cache-watchlist (map resolve-module-path '("my-module.rkt"))))
+  (require racket/runtime-path syntax/modresolve)
+  (define-runtime-path my-local-mod "my-module.rkt")
+  (define my-installed-mod (resolve-module-path 'package/my-other-module))
+  (define cache-watchlist (list my-local-mod my-installed-mod)))
 }]
 
 @pollen-history[#:added "1.4"]