From c13f44abe895fd771bcc35daf0c65427031d5929 Mon Sep 17 00:00:00 2001 From: Joel Dueck Date: Sun, 14 Nov 2021 16:02:44 -0600 Subject: [PATCH] Add docs for `external-renderer` (closes #262) --- pollen/scribblings/setup.scrbl | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/pollen/scribblings/setup.scrbl b/pollen/scribblings/setup.scrbl index 3180c37..0042c42 100644 --- a/pollen/scribblings/setup.scrbl +++ b/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)) @@ -157,7 +157,12 @@ Both the names and the values of environment variables are case-insensitive, so @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.1"]} + @section{Parameters} I mean @italic{parameters} in the Racket sense, i.e. values that can be fed to @racket[parameterize].