From a42abef3a241149a02933e8b834614bcba82fd0c Mon Sep 17 00:00:00 2001 From: Matthew Butterick Date: Wed, 5 Mar 2014 14:38:00 -0800 Subject: [PATCH] doc updates --- scribblings/pollen.scrbl | 6 +----- scribblings/render.scrbl | 26 ++++++++++++++++---------- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/scribblings/pollen.scrbl b/scribblings/pollen.scrbl index 5649145..5ad27d6 100644 --- a/scribblings/pollen.scrbl +++ b/scribblings/pollen.scrbl @@ -54,15 +54,11 @@ If the file extension is ``@(format ".~a" world:markdown-source-ext)'', the sour @defmodulelang[pollen/markdown] +@include-section["render.scrbl"] -@section{Rendering} - -@defmodule[pollen/render] - - @section{License & source code} This module is licensed under the LGPL. diff --git a/scribblings/render.scrbl b/scribblings/render.scrbl index ca5f1f7..6fc8df4 100644 --- a/scribblings/render.scrbl +++ b/scribblings/render.scrbl @@ -14,13 +14,13 @@ [source-path complete-path?] [template-path (or/c #f complete-path?) #f]) bytes?] -Renders the source file at @racket[_source-path]. The rendering behavior depends on the type of source file: +Renders @racket[_source-path]. The rendering behavior depends on the type of source file: A @racketmodname[pollen/pre] file is rendered without a template. -A @racketmodname[pollen/markup] or @racketmodname[pollen/markdown] file is rendered with a template. If no template is provided with @racket[_template-path], Pollen tries to find one using @racket[get-template-for]. If that doesn't work, Pollen uses the fallback template. +A @racketmodname[pollen/markup] or @racketmodname[pollen/markdown] file is rendered with a template. If no template is provided with @racket[_template-path], Pollen finds one using @racket[get-template-for]. -Be aware that rendering with a template uses @racket[include-template] within @racket[eval]. This is necessary to allow dynamic refresh of pages. For complex pages, it can be slow the first time. Caching is used to make subsequent requests faster. +Be aware that rendering with a template uses @racket[include-template] within @racket[eval]. For complex pages, it can be slow the first time. Caching is used to make subsequent requests faster. For those panicked at the use of @racket[eval], please don't be. As the author of @racket[include-template] has already advised, ``If you insist on dynamicism'' — and yes, I do insist — ``there is always @racket[eval].'' @secref["How do I use templates “dynamically\"?" #:doc '(lib "web-server/scribblings/faq.scrbl")] @@ -35,13 +35,17 @@ Like @racket[render], but saves the file to @racket[_output-path], overwriting w @defproc[ (render-to-file-if-needed -[source-or-output-path complete-path?] +[source-path complete-path?] [template-path (or/c #f complete-path?) #f] -[output-path (or/c #f complete-path?) #f]) +[output-path (or/c #f complete-path?) #f] +[#:force force-render? boolean? #f]) void?] -Like @racket[render-to-file], with two differences. First, the mandatory argument can be either a source or an output path, and the function will compute the other. Second, the render only happens if one of these conditions exist: +Like @racket[render-to-file], but the render only happens if one of these conditions exist: @itemlist[#:style 'ordered -@item{No file exists at @racket[_output-path]. (Corollary: an easy way to force a refresh of a particular @racket[_output-path] is to delete it.)} + +@item{The @racket[_force-render?] flag is not @racket[#f].} +@item{No file exists at @racket[_output-path]. +@margin-note{Corollary: an easy way to force a refresh of a particular @racket[_output-path] from the desktop is to delete it.}} @item{Either @racket[_source-path] or @racket[_template-path] have changed since the last trip through @racket[render].} @@ -56,7 +60,7 @@ If none of these conditions exist, @racket[_output-path] is assumed to be curren (render-batch [source-paths (listof pathish?)] ...) void?] -Render multiple @racket[_source-paths] in one go. This can be faster than @racket[(map render _source-paths)] if your @racket[_source-paths] rely on a common set of templates. Templates may have their own Pollen source files that need to be compiled. If you use @racket[render], the templates will be repeatedly (and needlessly) re-compiled. Whereas if you use @racket[render-batch], each template will only be compiled once. +Render multiple @racket[_source-paths] in one go. This can be faster than @racket[(for-each render _source-paths)] if your @racket[_source-paths] rely on a common set of templates. Templates may have their own source files that need to be compiled. If you use @racket[render], the templates will be repeatedly (and needlessly) re-compiled. Whereas if you use @racket[render-batch], each template will only be compiled once. @defproc[ @@ -67,6 +71,8 @@ Find a template file for @racket[_source-path], with the following priority: If the metas for @racket[_source-path] have a key for @code[(format "'~a" world:template-meta-key)], then use the value of this key. -If this key doesn't exist, or if it points to a nonexistent file, look for a default template in the project directory with the name @code[(format "~a.[output extension].~a" world:default-template-prefix world:template-source-ext)]. Meaning, if @racket[_source-path] is @code[(format "intro.html.~a" world:markup-source-ext)], the default template would be @code[(format "~a.html.~a" world:default-template-prefix world:template-source-ext)]. +If this key doesn't exist, or if it points to a nonexistent file, look for a default template in the project directory with the name @code[(format "~a.[output extension].~a" world:default-template-prefix world:template-source-ext)]. Meaning, if @racket[_source-path] is @code[(format "intro.html.~a" world:markup-source-ext)], the output path would be @code["intro.html"], so the default template would be @code[(format "~a.html.~a" world:default-template-prefix world:template-source-ext)]. + +If this file doesn't exist, the fallback template is used. -If this file doesn't exist, use the fallback template. \ No newline at end of file +This function is called when a template is needed, but a @racket[_template-path] argument is missing (for instance, in @racket[render] or @racket[render-to-file]). \ No newline at end of file