On this page:
2.1 Creating a source file
2.2 Running a source file
2.3 Naming, saving, and rendering a source file
2.4 The project server
2.5 Intermission
2.6 Pollen as a preprocessor
2.7 Markdown mode
2.8 Pollen markup
2.9 Templates
2.10 PS for Scribble users
2.11 The end of the beginning

2 Quick tour

2.1 Creating a source file

Assuming you’ve installed Racket & Pollen, launch DrRacket.

Start a new document. Change the top line to:

#lang pollen

The first line of every Pollen source file will start with #lang pollen.

2.2 Running a source file

Add a second line to your source file so it reads:

#lang pollen
Hello world

Click the Run button. In the interactions window, you’ll see the result:

Hello world

Not bad. I think Pollen just won the Hello World Tournament.

You can work with Pollen source files in any text editor, including Emacs or Sublime Text. The key advantage of DrRacket is that you can preview the results by running the file.

Try editing your source file:

#lang pollen
Era Vulgaris
Songs for the Deaf
Like Clockwork

You don’t have to use Queens of the Stone Age albums. Any text will do. When you click Run again, you’ll see whatever you typed:

Era Vulgaris
Songs for the Deaf
Like Clockwork

We won’t do it a third time. You get the point — any plain text is valid within a Pollen source file, and gets printed as typed. What you write is what you get. You never have to perform the incantations often required by other programming languages:

print "Hello world"

document.write('Hello world');

printf("Hello world");

2.3 Naming, saving, and rendering a source file

Save this file as "hello.txt.pp" in any convenient directory. The desktop is fine.

Open a terminal window and issue two commands:

> cd /directory/containing/your/hello-file

> raco pollen render hello.txt.pp

After a moment, a new file will appear called "hello.txt". Let’s see what’s in it:

> cat hello.txt

Era Vulgaris

Songs for the Deaf

Like Clockwork

If raco doesn’t work, it’s probably because the PATH wasn’t set up correctly during Installation.

You’ve just learned three things:

Try editing the text in "hello.txt.pp" and running the command again:

  raco pollen render hello.txt.pp

The old "hello.txt" will be replaced with a new one showing your changes. So now you’ve learned a fourth thing:

2.4 The project server

You just saw two ways to view the output of a Pollen source file — first, you ran it in DrRacket. Second, you rendered it to an output file.

Now here’s a third: the Pollen project server. To start the project server, return to your terminal and issue two commands:

> cd /directory/containing/your/hello-file

> raco pollen start

After a moment, you’ll see the startup message:

pollen: welcome to Pollen 2.2.2419.786 (Racket 7.6)

pollen: project root is /path/to/your/directory

pollen: project server is http://localhost:8080 (Ctrl+C to exit)

pollen: project dashboard is http://localhost:8080/index.ptree

pollen: ready to rock

Open a web browser and point it at the project dashboard, which by default is http://localhost:8080/index.ptree. The top line of the window will say Project root and show the name of the starting directory. Below that will be a listing of the files in the directory.

Among them will be "hello.txt", with a greyed-out ".pp" extension. Click on it, and you’ll be taken to http://localhost:8080/hello.txt, where you’ll see:

Era Vulgaris

Songs for the Deaf

Like Clockwork

That’s the boring part. Here’s the good part. Leave the project server running. Open your source file again in DrRacket and edit it as follows:

#lang pollen
Grand Illusion
Pieces of Eight
Paradise Theatre

Go back to your web browser and reload http://localhost:8080/hello.txt. Now you’ll see this:

Grand Illusion

Pieces of Eight

Paradise Theatre

Notice what happened — the Pollen project server dynamically regenerated the output file ("hello.txt") from the source file ("hello.txt.pp") after you edited the source. If you like, try making some more changes to "hello.txt.pp", and reloading the browser to see the updates in "hello.txt". The project server will regenerate the file whenever it changes.

2.5 Intermission

That covers input & output. Now let’s circle back and look at what else you can do with Pollen (beyond the epic achievement of displaying plain text in a web browser).

For the rest of this tutorial, I recommend keeping two windows on screen: a web-browser window pointed at your project dashboard, and the DrRacket editing window.

2.6 Pollen as a preprocessor

A preprocessor is a tool for making systematic, automated changes to a source file before the main processing happens. A preprocessor can also be used to add programming logic to files that otherwise don’t support it.

For instance, HTML. In DrRacket, create a new file called "margin.html.pp" in your project directory:

#lang pollen
<body style="margin: 5em; border:1px solid black">
5em is the inset.

The ".pp" file extension — which you saw before, with "hello.txt.pp" — stands for “Pollen preprocessor.” You can use the Pollen preprocessor with any text-based file by inserting #lang pollen as the first line, and adding the ".pp" file extension.

But for now, go to your project dashboard and click "margin.html". You should see a black box containing the text “5em is the inset.

Suppose you want to change the inset to 30%. Without a preprocessor, you’d have to search & replace each value. But with a preprocessor, you can move the inset value into a variable, and update it from that one location. So first, introduce a variable called my-inset by using the define command:

#lang pollen
(define my-inset "30%")
<body style="margin: 10em; border:1px solid black">
10em is the inset.

The character is called a lozenge. In Pollen, the lozenge is a special character used to denote anything that Pollen should interpret as a command (rather than plain text).

If you’re using DrRacket, you can insert a lozenge by clicking the Insert command char ◊ button at the top of your source window. (If you’re not using DrRacket, see these instructions.)

Thus, the command (define my-inset "30%") means “create the variable my-inset and assign it the value "30%".”

Now you can insert the variable into the HTML, this time using the special ◊ character with the variable name in the two places the value needs to appear:

#lang pollen
(define my-inset "30%")
<body style="margin: my-inset; border:1px solid black">
my-inset is the inset.

In your web browser, reload "margin.html". You’ll see that the size of the margin has changed (because of the change to the style attribute) and so has the text of the HTML. If you like, try editing my-inset with different values and reloading the page. You can also try using define to create another variable (for instance, to change the color of the box border).

Still, this is the tiniest tip of the iceberg. The Pollen preprocessor gives you access to everything in the Racket programming language — including string manipulation, math functions, and so on.

2.7 Markdown mode

When used as a preprocessor, Pollen’s rule is that what you write is what you get. But if you’re targeting HTML, who wants to type out all those <tedious>tags</tedious>? You can make Pollen do the heavy lifting by using an authoring mode.

For instance, Markdown authoring mode. Markdown is a simplified notation system for HTML. You can use Markdown authoring mode in Pollen by inserting #lang pollen as the first line, and adding the ".pmd" file extension.

Try it. In DrRacket, create a file with the following lines and save it as "downtown.html.pmd":

#lang pollen
Pollen + Markdown
+ You **wanted** it  you _got_ it.
+ [search for Racket](https://google.com/search?q=racket)

As before, go to the project dashboard. This time, click the link for "downtown.html". You’ll see something like this:

Pollen + Markdown

       • You wanted it — you got it.

       • search for Racket

As usual, you’re welcome to edit "downtown.html.pmd" and then refresh the web browser to see the changes.

In Markdown authoring mode, you can still embed Pollen commands within the source as you did in preprocessor mode. Just keep in mind that your commands need to produce valid Markdown (as opposed to raw HTML). For instance, use define to create a variable called metal, and insert it into the Markdown:

#lang pollen
(define metal "Plutonium")
Pollen + metal
+ You **wanted** metal  you _got_ it.
+ [search for metal](https://google.com/search?q=metal)

Refresh "downtown.html" in the browser:

Pollen + Plutonium

       • You wanted Plutonium — you got it.

       • search for Plutonium

Pollen is handling three tasks here: interpreting the commands in the source, converting the source to Markdown, and then to HTML. (For more, see Markdown authoring mode.)

But what if you wanted to use Pollen as a preprocessor that outputs a Markdown file? No problem — just change the source name from "downtown.html.pmd" to "downtown.md.pp". Changing the extension from ".pmd" to ".pp" switches Pollen from Markdown mode back to preprocessor mode. And changing the base name from "downtown.html" to "downtown.md" updates the name of the output file (and thereby skips the HTML conversion).

2.8 Pollen markup

If all you need to do is produce basic HTML, Markdown is fine. But if you need to do semantic markup or other kinds of custom markup, it’s not flexible enough.

In that case, you can use a different authoring mode, called Pollen markup. To use Pollen markup, insert #lang pollen as the first line of your source as usual, but this time add a ".pm" file extension.

Compared to Markdown authoring mode, Pollen markup is wide open. Markdown authoring mode limits you to the formatting commands supported by Markdown. With Pollen markup, by contrast, you can use any tags you want. Markdown mode interprets the source in a fixed way (i.e., according to Markdown rules). But Pollen markup lets you attach any behavior you want to your tags.

To see how this works, let’s convert our Markdown example into Pollen markup. Marking up content is simple: insert the lozenge character () followed by the name of the tag (◊tag), followed by the content of the tag in curly braces (◊tag{content}). In DrRacket, create a new file called "uptown.html.pm" as follows:

#lang pollen
headline{Pollen markup}
  item{You strong{wanted} it  you em{got} it.}
  item{link["https://google.com/search?q=racket"]{search for Racket}}

Go to the project dashboard and click on "uptown.html". You’ll see something like this:

Pollen markup You wanted it — you got it. https://google.com/search?q=racketsearch for Racket

That’s not right. What happened?

We marked up the source using a combination of standard HTML tags (strong, em) and nonstandard ones (headline, items, item, link). This is valid Pollen markup. (In fact, if you look at the generated source, you’ll see that they didn’t disappear.) But since we’re targeting HTML, we need to convert our custom tags into valid HTML tags.

For that, we’ll make a special file called "pollen.rkt". This is a file in the standard Racket language that provides helper functions to decode the source. The definitions won’t make sense yet. But this is the quick tour, so all you need to do is copy, paste, and save:

#lang racket/base
(require pollen/tag)
(provide (all-defined-out))
(define headline (default-tag-function 'h2))
(define items (default-tag-function 'ul))
(define item (default-tag-function 'li 'p))
(define (link url text) `(a ((href ,url)) ,text))

Return to the project dashboard and click on "uptown.html". Now you’ll get the right result:

Pollen markup

       • You wanted it — you got it.

       • search for Racket

Pollen markup takes a little more effort to set up. But it also allows you more flexibility. If you want to do semantic markup, or convert your source into multiple output formats, or handle complex page layouts — it’s the way to go. (For more, see Writing with Pollen markup.)

2.9 Templates

The HTML pages we just made looked pretty dull. For the last stop on the quick tour, let’s fix that.

Pollen source files that are written in an authoring mode (i.e., ".pmd" or ".pm" files) are rendered with a template. A template is not a standalone Pollen source file. It’s a file of the output type — e.g., CSS, HTML, XML — where you put the stuff that needs to be consistent between output files. The template also contains template variables that mark where values from the Pollen source file should be inserted.

When it needs a template, Pollen first looks for a file in the project directory named "template.[output extension of source]". Thus, for "uptown.html.pm", the output extension will be ".html", and Pollen will first look for "template.html".

So let’s create "template.html". Make a new file with the following lines and save it to the same directory as "uptown.html.pm":

<html><head><meta charset="UTF-8"/></head>
<body style="background: #f6f6f6">
<div style="background: white; margin: 3em;
border:10px double gray; padding: 3em; font-size: 130%;">
This file is ◊here
<hr />
(->html ◊doc)

This is a simple HTML file that should look familiar, except for the two template variables. The first, here, contains the name of the current source file. As before, the lozenge character marks it as a Pollen command rather than text, so you write it as ◊here. The other command, (->html ◊doc), takes the content from the source file, which is contained in a variable called doc, and converts it to HTML with ->html.

Return to your web browser and reload "uptown.html". (Or "downtown.html" — both will work.) The page will be rendered with the new "template.html". As before, you can edit the template or the source and the project server will dynamically update the output file.

2.10 PS for Scribble users

Pollen can also be used as a dynamic preview server for Scribble files. From your terminal, do the following:

> cd /path/to/scribble/sources

> raco pollen start

On the project dashboard, you’ll see your "filename.scrbl" files listed as "filename.html". By clicking on these names, you can get a preview rendering of the Scribble source file. This may not represent the ultimate structure of your Scribble project — you may end up combining multiple Scribble source files into one HTML file, or making multiple HTML files from one Scribble source — but it’s handy for checking your work as you go.

2.11 The end of the beginning

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 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.