doc updates

pull/160/merge
Matthew Butterick 7 years ago
parent a731428072
commit ffa234c348

@ -1 +1 @@
1513200079 1513201569

@ -1,6 +1,6 @@
#lang scribble/manual #lang scribble/manual
@(require scribble/eval pollen/render "mb-tools.rkt" pollen/setup (for-label pollen/cache (except-in pollen/top #%top def/c) racket (except-in pollen #%module-begin) pollen/setup sugar pollen/pagetree)) @(require scribble/eval pollen/render "mb-tools.rkt" pollen/setup (for-label pollen/core pollen/cache (except-in pollen/top #%top def/c) racket (except-in pollen #%module-begin) pollen/setup sugar pollen/pagetree))
@(define my-eval (make-base-eval)) @(define my-eval (make-base-eval))
@(my-eval `(require pollen pollen/file)) @(my-eval `(require pollen pollen/file))
@ -48,13 +48,13 @@ By default, every Pollen source file exports two identifiers:
@item{@id{metas} is a hashtable of keyvalue pairs with extra information that is extracted from the source. These @id{metas} will always contain the key @id{'here-path}, which returns a string representation of the full path to the source file. Beyond that, the only @id{metas} are the ones that are specified within the source file (see the source formats below for more detail on how to specify metas).} @item{@id{metas} is a hashtable of keyvalue pairs with extra information that is extracted from the source. These @id{metas} will always contain the key @id{'here-path}, which returns a string representation of the full path to the source file. Beyond that, the only @id{metas} are the ones that are specified within the source file (see the source formats below for more detail on how to specify metas).}
] ]
As usual, you can use @racket[require], @racket[local-require], or @racket[dynamic-require] to retrieve these values. But within a Pollen project, the faster way is to use @racket[cached-doc] and @racket[cached-metas]. As usual, you can use @racket[require], @racket[local-require], or @racket[dynamic-require] to retrieve these values. But within a Pollen project, the faster way is to use @racket[get-doc] and @racket[get-metas].
Pollen source files also make the @id{metas} hashtable available through a submodule, unsurprisingly called @id{metas}. So rather than importing a source file with @racket[(require "source.html.pm")], you can @racket[(require (submod "source.html.pm" metas))]. Accessing the metas this way avoids fully compiling the source file, and thus will usually be faster. Pollen source files also make the @id{metas} hashtable available through a submodule, unsurprisingly called @id{metas}. So rather than importing a source file with @racket[(require "source.html.pm")], you can @racket[(require (submod "source.html.pm" metas))]. Accessing the metas this way avoids fully compiling the source file, and thus will usually be faster.
The names @@id{doc} and @@id{metas} can be changed for a project by overriding @racket[default-main-export] and @racket[default-meta-export]. The names @@id{doc} and @@id{metas} can be changed for a project by overriding @racket[default-main-export] and @racket[default-meta-export].
@margin-note{The Pollen rendering system relies on these two identifiers, but otherwise doesn't care how they're generated. Meaning, the code inside your Pollen source file could be @tt{#lang racket} or @tt{#lang whatever}. As long as you manually @racket[provide] those two identifiers and follow the usual file-naming convention, your source file will be renderable.} @margin-note{The Pollen rendering system relies on these two exported identifiers, but otherwise doesn't care how they're generated. Thus, the code inside your Pollen source file could be written in @tt{#lang racket} or @tt{#lang whatever}. As long as you @racket[provide] those two identifiers and follow Pollen's file-naming conventions, your source file will be renderable.}
@bold{How is this different from Racket?} In Racket, you must explicitly @racket[define] and then @racket[provide] any values you want to export. @bold{How is this different from Racket?} In Racket, you must explicitly @racket[define] and then @racket[provide] any values you want to export.

@ -392,6 +392,6 @@ Now you've seen the key features of Pollen. What do you think?
] ]
But don't take my word for it. The rest of this documentation will show you the useful and sophisticated things you can do with Pollen. If there's another tool that suits you better, great. Keep in mind that I didn't make Pollen because I'm a programmer. I'm a writer who wants to make electronic books that are better than the ones we have now. And for that, I needed a better tool. But don't take my word for it. The rest of this documentation will show you the useful and sophisticated things you can do with Pollen. If there's another tool that suits you better, great. Keep in mind that I didn't make Pollen because I'm a programmer pushing some abstract fantasy of how writers ought to work. Rather, I'm a writer who wants to make electronic books that are better than the ones we have now. And for that, I needed a better tool.
Now I have it. Now I have it.

Loading…
Cancel
Save