The slowest part of a @racket[render] is parsing and decoding Pollen source files. Often, previewing a single source file necessarily means decoding others (for instance templates, or other source files that are linked into the main source file). But usually, only one source file is changing at a time. Therefore, Pollen stores copies of the exports of source files —namely, whatever is stored in @code[(format "'~a" world:main-pollen-export)] and @code[(format "'~a" world:meta-pollen-export)] —in the cache so they can be reused.
@defproc[
(current-cache)
(or/c #f hash?)]
A parameter that refers to the current cache. It starts with a value of @racket[#f]. It has to be initialized with @racket[make-cache].
The cache is a hash table that uses the complete path of a source file as its keys. The value associated with each of these keys is another hash table with keys @code[(format "'~a" world:main-pollen-export)], @code[(format "'~a" world:meta-pollen-export)] (for storing the exports of the source file) and @racket['mod-time] (for storing the modification time).
@defproc[
(make-cache)
hash?]
Initializes @racket[current-cache].
@defproc[
(reset-cache)
void?]
Clears @racket[current-cache]. When only the nuclear option will do.
@defproc[
(cached-require
[source-path pathish?]
[key (or/c 'doc 'metas 'mod-time)])
void?]
Similar to @racket[(dynamic-require _source-path _key)], except that it tries to get the requested value out of @racket[current-cache]. If it's not there, or out of date, @racket[dynamic-require] is used to update the value.
If you want the speed benefit of the cache, you need to use @racket[cached-require] to get data from Pollen source files. That doesn't mean you can't still use functions like @racket[require], @racket[local-require], and @racket[dynamic-require]. They'll just be slower.
@defproc[
(cache-ref
[source-path pathish?])
hash?]
Returns the cached value associated with the key @racket[_source-path], which will itself be a hash table. See @racket[current-cache] for more.
@ -14,13 +14,13 @@ Pollen is a publishing system that helps authors create beautiful and functional
I used Pollen to make my book @link["http://practicaltypography.com"]{Butterick's Practical Typography}. If that looks better than the last digital book you encountered, read on.
Pollen is built around two ideas. First, that digital books should be the best books we've ever had. (So far, they're not even close.) Second, that if digital books are software, authors shouldn't think of a book as merely data. The book is a program.
Pollen is built around two ideas. First, that digital books should be the best books we've ever had. (So far, they're not even close.) Second, that if digital books are software, an author shouldn't think of their book as merely data. The book is a program.
Not that you need to be a programmer to use Pollen. On the contrary, the Pollen language is markup-based, so you can write & edit text naturally. But when you want to automate repetitive tasks or add other features, you can access a full programming language from within the text.
Not that you need to be a programmer to use Pollen. On the contrary, the Pollen language is markup-based, so you can write & edit text naturally. But when you want to automate repetitive tasks, add cross-references, or pull in data from other sources, you can access a full programming language from within the text.
That language is Racket. I chose Racket because while the idea for Pollen had been with me for several years, it simply wasn't possible to build it with other languages. So if it's unfamiliar to you, don't panic. It was unfamiliar to me. Once you see what you can do with Pollen & Racket, you may be persuaded. I was.
Or, if you can find a better digital book-publishing tool, use that. Personally, I'm never going back to the way I used to make web pages. After 20 years of web publishing, this is the best tool I've ever had.
Or, if you can find a better digital book-publishing tool, use that. Personally, I'm never going back to the way I used to work.
@section{Installation}
@ -54,10 +54,6 @@ If the file extension is ``@(format ".~a" world:markdown-source-ext)'', the sour
@ -31,7 +31,7 @@ For those panicked at the use of @racket[eval], please don't be. As the author o
[template-path (or/c #f complete-path?) #f]
[output-path (or/c #f complete-path?) #f])
void?]
Like @racket[render], but saves the file to @racket[_output-path], overwriting whatever is already there. If no @racket[_output-path] is provided, it's derived from @racket[_source-path] using @racket[->output-path].
Like @racket[render], but saves the file to @racket[_output-path], overwriting whatever was already there. If no @racket[_output-path] is provided, it's derived from @racket[_source-path] using @racket[->output-path].
@defproc[
(render-to-file-if-needed
@ -43,15 +43,15 @@ void?]
Like @racket[render-to-file], but the render only happens if one of these conditions exist:
@itemlist[#:style 'ordered
@item{The @racket[_force-render?] flag is not @racket[#f].}
@item{The @racket[_force-render?] flag —set with the @racket[#:force] keyword — is @racket[#t].}
@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.}}
@margin-note{Corollary: an easy way to force a render 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].}
@item{One or more of the project requires have changed.}]
If none of these conditions exist, @racket[_output-path] is assumed to be current, and the render is skipped.
If none of these conditions exist, @racket[_output-path] is deemed to be up to date, and the render is skipped.
