We can write a @filepath{pollen.rkt} file in any @|lang|. @|lang| @racketmodname[racket] is more convenient because it loads more libraries by default. For the same reason, @|lang| @racketmodname[racket/base] — with a minimal set of libraries — is slightly faster to load. In general, the more virtuous habit is @|lang| @racketmodname[racket/base].
We can write a @filepath{pollen.rkt} file in any @|lang|. Most commonly, that will be is @|lang| @racketmodname[racket/base]. @|lang| @racketmodname[racket] is more convenient because it loads more libraries by default, but as a result it can be slightly slower to load. So @racketmodname[racket/base] is the more virtuous habit.
@racketmodname[pollen/mode] is a metalanguage that adds support for Pollen-mode commands in a source file.
So instead of @|lang| @racketmodname[racket/base] we write @|lang|@racketmodname[pollen/mode]@racketmodname[racket/base]. @racketmodname[pollen/mode] is optional.
This particular @filepath{pollen.rkt}, however, is written in @|lang| @racketmodname[scribble/lp2], which is the literate-programming variant of Racket's Scribble documentation language (which is also the basis of Pollen). @racketmodname[scribble/lp2] is like a text-based version of @racketmodname[racket/base]. The "literate programming" angle is that we can mix documentation and source code in one file. Probably not the option you'd choose for your own project, but in this teaching project, it's the right tool for the job.
BTW this file is heavily commented so it can serve as a Pollen learning tool. Rather than just read
along, you are encouraged to run this project with the project server active, and make changes to this
file and see how they affect the output.
Chunks of source code look like this:
We could avoid the next @racket[require] if we were using @|lang| @racketmodname[racket], because these libraries would
already be available.
@chunk[<chunk-name>
(define (racket-source-code ...) ...)]
There's nothing special about the chunk name —it's just a label that @racketmodname[scribble/lp2] will use to snap the code together @seclink["Finally"]{at the end}. The result is that if you @racket[require] this file normally, you'll get the usual functions and values; but if you run it with Scribble, it turns into the documentation you see here.
@section{What is @filepath{pollen.rkt} for?}
@chunk[<req>
The @filepath{pollen.rkt} source file is the main source of functions and values for the source files in a Pollen project. Everything provided from a @filepath{pollen.rkt} is automatically available to Pollen source files in the
same directory or subdirectories (unless superseded by another @filepath{pollen.rkt} below, for instance in the @filepath{fonts} subdirectory in this project).
For more, see @secref["Using_the__pollen_rkt__file"
#:tag-prefixes '("tutorial-3")
#:doc '(lib "pollen/scribblings/pollen.scrbl")] in the main Pollen docs.
@section{Imports}
If we were using @|lang| @racketmodname[racket], these next libraries would already be imported. But because we're using @racketmodname[racket/base] (via @racketmodname[scribble/lp2]), we need to @racket[require] them explicitly.
Check whether Pollen is running in development mode, which means that it was started from the command line with the environment variable @tt{POLLEN} set to the value @tt{DEV}:
@terminal{
> POLLEN=DEV raco pollen ...}
Rather than the ordinary:
@terminal{
> raco pollen ...}
This functions will be useful later when we want to change the behavior of certain functions when Pollen runs in dev mode. For instance, we might want to run certain functions in a higher speed / lower quality mode. Or output debug information about others.
@chunk[<dev-mode>
(define (dev-mode?)
(equal? (getenv "POLLEN") "DEV"))
]
Though the environment variable name is fixed as @tt{POLLEN}, there's no special magic to @tt{DEV}. We could pick any value we wanted to denote development mode:
@terminal{
> POLLEN=FLUGELHORN raco pollen ...}
@defproc[
(capitalize-first-letter
[str string?])
string?]
For use in our HTML templates. We could also define this function inside a template. But since we have more than one template in this project, we'll put it here, so it can be available to all the templates.
@chunk[<capitalize-first-letter>
(define (capitalize-first-letter str)
(regexp-replace #rx"^." str string-upcase))]
@section{Finally}
This last incantation is needed so @racketmodname[scribble/lp2] knows how to put together all the code chunks we've introduced in this file.
