From c13f44abe895fd771bcc35daf0c65427031d5929 Mon Sep 17 00:00:00 2001 From: Joel Dueck Date: Sun, 14 Nov 2021 16:02:44 -0600 Subject: [PATCH 1/2] 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]. -- 2.25.1 From 4254889cc9c17ce60af3aab1c901b7affe083f63 Mon Sep 17 00:00:00 2001 From: Matthew Butterick Date: Tue, 16 Nov 2021 12:59:19 -0800 Subject: [PATCH 2/2] bump to v3.2 --- info.rkt | 2 +- pollen/scribblings/setup.scrbl | 8 ++++---- pollen/scribblings/version-history.scrbl | 4 ++++ 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/info.rkt b/info.rkt index 8ad1df8..fd72bac 100644 --- a/info.rkt +++ b/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"] diff --git a/pollen/scribblings/setup.scrbl b/pollen/scribblings/setup.scrbl index 0042c42..2c8a495 100644 --- a/pollen/scribblings/setup.scrbl +++ b/pollen/scribblings/setup.scrbl @@ -153,15 +153,15 @@ 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. +@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"]} + @history[#:added "3.2"]} @section{Parameters} diff --git a/pollen/scribblings/version-history.scrbl b/pollen/scribblings/version-history.scrbl index 74dcb41..37b9091 100644 --- a/pollen/scribblings/version-history.scrbl +++ b/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]. -- 2.25.1