Add docs for `external-renderer` (closes #262) (#263)

info.rkt

@@ -1,7 +1,7 @@
 #lang info
 (define collection 'multi)
 
-(define version "3.1")
+(define version "3.2")
 (define deps '(["base" #:version "6.3"]
                ["txexpr" #:version "0.2"]
                ["sugar" #:version "0.2"]

pollen/scribblings/setup.scrbl

@@ -1,6 +1,6 @@
 #lang scribble/manual
 @(require "mb-tools.rkt")
-@(require scribble/eval pollen/setup racket/string (for-label (except-in racket #%top) racket/runtime-path syntax/modresolve (except-in pollen #%module-begin #%top) pollen/setup pollen/top))
+@(require scribble/eval pollen/setup racket/string (for-label (except-in racket #%top) racket/runtime-path syntax/modresolve (except-in pollen #%module-begin #%top) pollen/render pollen/setup pollen/top))
 
 @(define my-eval (make-base-eval))
 @(my-eval `(require pollen pollen/setup))
@@ -153,11 +153,16 @@ Both the names and the values of environment variables are case-insensitive, so
 
  @history[#:added "1.5"]}
 
-  @defoverridable[allow-unbound-ids? boolean?]{Predicate that controls whether Pollen converts unbound identifiers into default tags by altering the behavior of @racket[#%top] in @racketmodname[pollen/top].
+@defoverridable[allow-unbound-ids? boolean?]{Predicate that controls whether Pollen converts unbound identifiers into default tags by altering the behavior of @racket[#%top] in @racketmodname[pollen/top].
 
- @history[#:added "2.0"]}
+@history[#:added "2.0"]}
 
+@defoverridable[external-renderer (or/c (list/c module-path? symbol?) #f)]{A module path and identifier (suitable for use with @racket[dynamic-require]) that provide a function for Pollen to call instead of @racket[render] when rendering files needed by the @seclink["Using_the_project_server"]{project server} or when running @secref["raco_pollen_render"]. The function must accept the same arguments as @racket[render-to-file] and should return the final output as a @tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{string} or @tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{byte string}. Pollen will always write this return value out to the output file for you.
 
+Setting this value gives you full control over (and responsibility for) how Pollen converts the compiled @racketidfont{doc} and @racketidfont{metas} from source files into their final output. Your renderer should be able to handle any of Pollen’s @seclink["Source_formats"]{source formats} or @seclink["Utility_formats"]{utility formats}. The operation of Pollen’s @racket[render] function is not affected by setting this value, so your renderer can use it as a fallback.
+
+ @history[#:added "3.2"]}
+  
 @section{Parameters}
 
 I mean @italic{parameters} in the Racket sense, i.e. values that can be fed to @racket[parameterize]. 

pollen/scribblings/version-history.scrbl

@@ -24,6 +24,10 @@ Beyond keeping the commit history available, I make no promise to maintain the p
 
 @section{Changelog}
 
+@subsection{Version 3.2}
+
+Added the @racket[external-renderer] setup value.
+
 @subsection{Version 3.1}
 
 Downgraded the following @racket[pollen/setup] values from configurable to fixed: @racket[here-path-key], @racket[extension-escape-char].