On this page:
Pollen:   the book is a program
7.1

Pollen: the book is a program

Matthew Butterick <[email protected]>

 #lang pollen package: pollen

Pollen is a publishing system that helps authors make functional and beautiful digital books.

I created Pollen so I could make my web-based books Practical Typography, Typography for Lawyers, and Beautiful Racket. Sure, go take a look. Are they better than the last digital books you encountered? Yes they are. Would you like your next digital book to work like that? If so, keep reading.

At the core of Pollen is an argument:

  1. Digital books should be the best books we’ve ever had. So far, they’re not even close.

  2. Because digital books are software, an author shouldn’t think of a book as merely data. The book is a program.

  3. The way we make digital books better than their predecessors is by exploiting this programmability.

That’s what Pollen is for.

Not that you need to be a programmer to start using 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 it has some unique features that made Pollen possible. So if it’s unfamiliar to you, don’t panic. It was unfamiliar to me. Once you see what you can do with Racket & Pollen, you may be persuaded. I was.

Or, if you can find a better digital-publishing tool, use that. But I’m never going back to the way I used to work.

    1 Installation

      1.1 Prerequisites

      1.2 How to install

      1.3 Beyond that

    2 Quick tour

      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

    3 Backstory

      3.1 Web development and its discontents

      3.2 The better idea: a programming model

      3.3 “Now you have two problems”

      3.4 Rethinking the solution for digital books

      3.5 Enter Racket

      3.6 What is Pollen?

    4 The big picture

      4.1 The book is a program

      4.2 One language, multiple dialects

      4.3 Development environment

      4.4 A special data structure for HTML

      4.5 Pollen command syntax

      4.6 The preprocessor

      4.7 Templated source files

      4.8 Pagetrees

    5 First tutorial: the project server & preprocessor

      5.1 Prerequisites

      5.2 Optional reading: the relationship of Racket & Pollen

      5.3 Starting a new file in DrRacket

        5.3.1 Setting the #lang line

        5.3.2 Putting in the text of the poem

        5.3.3 Saving & naming your source file

      5.4 Using the project server

        5.4.1 Starting the project server with raco pollen

        5.4.2 The project dashboard

        5.4.3 Source files in the dashboard

      5.5 Working with the preprocessor

        5.5.1 Setting up a preprocessor source file

        5.5.2 Creating valid HTML output

        5.5.3 Adding Pollen commands

        5.5.4 Racket basics (if you’re not familiar)

        5.5.5 Defining variables with Racket-style commands

        5.5.6 Inserting values from variables

        5.5.7 Inserting variables within CSS

      5.6 First tutorial complete

    6 Second tutorial: Markdown, templates, & pagetrees

      6.1 Prerequisites

      6.2 Optional reading: the case against Markdown

      6.3 Markdown in Pollen: two options

        6.3.1 Using Markdown with the preprocessor

        6.3.2 Authoring mode

        6.3.3 X-expressions

        6.3.4 Markdown authoring mode

        6.3.5 Review: authoring mode vs. preprocessor mode

      6.4 Templates

        6.4.1 The doc export and the ->html function

        6.4.2 Making a custom template

        6.4.3 Inserting specific source data into templates

        6.4.4 Linking to an external CSS file

      6.5 Intermission

      6.6 Pagetrees

        6.6.1 Pagetree navigation

        6.6.2 Using the automatic pagetree

        6.6.3 Adding navigation links to the template with here

        6.6.4 Handling navigation boundaries with conditionals

        6.6.5 Making a pagetree file

        6.6.6 index.ptree & the project server

      6.7 Second tutorial complete

    7 Third tutorial: Pollen markup & tag functions

      7.1 Prerequisites

      7.2 Optional reading: Pollen markup vs. XML

        7.2.1 The XML problem

        7.2.2 What Pollen markup does differently

        7.2.3 “But I really need XML…”

      7.3 Writing with Pollen markup

        7.3.1 Creating a Pollen markup file

        7.3.2 Tags & tag functions

        7.3.3 Attributes

        7.3.4 Optional reading: What are custom tags good for?

          7.3.4.1 Semantic markup

          7.3.4.2 Format independence

        7.3.5 Using custom tags

        7.3.6 Choosing custom tags

      7.4 Tags are functions

        7.4.1 Attaching behavior to tags

      7.5 Intermission

      7.6 Organizing functions

        7.6.1 Using Racket’s function libraries

        7.6.2 Introducing "pollen.rkt"

      7.7 Decoding markup with a root tag function

      7.8 Putting it all together

        7.8.1 The "pollen.rkt" file

        7.8.2 The template

        7.8.3 The pagetree

        7.8.4 A CSS stylesheet using the preprocessor

        7.8.5 The content source files using Pollen markup

        7.8.6 The result

      7.9 Third tutorial complete

    8 Fourth tutorial: multiple output targets

      8.1 Prerequisites

      8.2 Optional reading: Multiple-output publishing and its discontents

        8.2.1 And let’s not leave out programmability

        8.2.2 One source, multiple outputs

        8.2.3 Scribble vs. Pollen

      8.3 Making a multiple-output project

        8.3.1 The poly output type

        8.3.2 Poly sources in the project server

        8.3.3 Adding output targets for poly sources

          8.3.3.1 Using the setup submodule

        8.3.4 Adding support for another output format

          8.3.4.1 Adding a template for .txt

          8.3.4.2 Branching tag functions

        8.3.5 Adding support for LaTeX output

        8.3.6 Adding support for PDF output

      8.4 Using raco pollen render with poly sources

      8.5 Fourth tutorial complete

    9 Mini tutorials

      9.1 Syntax highlighting

        9.1.1 Using Pygments with Pollen

        9.1.2 Using Highlight.js with Pollen

      9.2 Math typesetting with MathJax

    10 Using raco pollen

      10.1 Making sure raco pollen works

      10.2 raco pollen

      10.3 raco pollen help

      10.4 raco pollen start

      10.5 raco pollen render

      10.6 raco pollen publish

      10.7 raco pollen setup

      10.8 raco pollen reset

      10.9 raco pollen version

      10.10 The POLLEN environment variable

    11 File formats

      11.1 Source formats

        11.1.1 Command syntax using ◊

        11.1.2 Any command is valid

        11.1.3 Standard exports

        11.1.4 Custom exports

        11.1.5 The "pollen.rkt" file

        11.1.6 Preprocessor (.pp extension)

        11.1.7 Markdown (.pmd extension)

        11.1.8 Markup (.pm extension)

        11.1.9 Pagetree (.ptree extension)

      11.2 Utility formats

        11.2.1 Scribble (.scrbl extension)

        11.2.2 Null (.p extension)

      11.3 Escaping output-file extensions within source-file names

    12 Pollen command syntax

      12.1 The golden rule

      12.2 The lozenge (◊)

        12.2.1 “But I don’t want to use it ...”

        12.2.2 Lozenge helpers

          12.2.2.1 How MB types the lozenge

          12.2.2.2 DrRacket toolbar button

          12.2.2.3 DrRacket key shortcut

          12.2.2.4 AHK script for Windows

          12.2.2.5 Emacs script

          12.2.2.6 Emacs input method

          12.2.2.7 Vim (and Evil) digraph sequence

          12.2.2.8 Compose key

      12.3 The two command styles: Pollen style & Racket style

        12.3.1 The command name

          12.3.1.1 Invoking tag functions

          12.3.1.2 Invoking other functions

          12.3.1.3 Inserting the value of a variable

          12.3.1.4 Inserting metas

          12.3.1.5 Retrieving metas

          12.3.1.6 Inserting a comment

        12.3.2 The Racket arguments

        12.3.3 The text body

      12.4 Embedding character entities

      12.5 Adding Pollen-style commands to a Racket file

      12.6 Further reading

    13 Programming Pollen

      13.1 Tag functions

        13.1.1 Tag-function syntax

        13.1.2 Point of no return

        13.1.3 Multiple input values & rest arguments

        13.1.4 Returning an X-expression

        13.1.5 Using variables within strings

        13.1.6 Parsing attributes

    14 Module reference

      14.1 Cache

        14.1.1 Preloading and reseting

        14.1.2 Disabling the cache

        14.1.3 Scope of dependency tracking

        14.1.4 Functions

      14.2 Core

        14.2.1 Metas

        14.2.2 Splicing

        14.2.3 Data helpers

        14.2.4 Parameters

      14.3 Decode

      14.4 File

      14.5 Pagetree

        14.5.1 Making pagetrees with a source file

        14.5.2 Making pagetrees by hand

        14.5.3 Nesting pagetrees

        14.5.4 The automatic pagetree

        14.5.5 Using pagetrees for navigation

        14.5.6 Using "index.ptree" in the dashboard

        14.5.7 Using pagetrees with raco pollen render

        14.5.8 Functions

          14.5.8.1 Predicates & validation

          14.5.8.2 Navigation

          14.5.8.3 Utilities

      14.6 Render

      14.7 Setup

        14.7.1 How to override setup values

        14.7.2 Values

        14.7.3 Parameters

      14.8 Tag

      14.9 Template

        14.9.1 HTML

      14.10 Top

    15 Unstable module reference

      15.1 Pygments

      15.2 Typography

      15.3 Convert

    16 Getting more help

      16.1 Bugs and feature requests

      16.2 Mailing list

      16.3 Utilities & libraries

      16.4 Can I see the source for Practical Typography or Typography for Lawyers?

      16.5 More projects & guides

    17 Acknowledgments

    18 License & source code

    19 Version notes (1.5.1936.1431)

      19.1 What the version number means

      19.2 Source code

      19.3 Development policy

      19.4 Changelog

        19.4.1 Version 1.5

        19.4.2 Version 1.4

        19.4.3 Version 1.3

        19.4.4 Version 1.2

        19.4.5 Version 1.1

        19.4.6 Version 1.0

    Index