Pollen: the book is a program

6.3.90.900

top ← prev up next →

Pollen: the book is a program

Matthew Butterick <mb@mbtype.com>

package: pollen

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

I created Pollen so I could make my web-based books Butterick’s Practical Typography and Typography for Lawyers. 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 look like that? If so, keep reading.

The core idea of Pollen is an argument:

Digital books should be the best books we’ve ever had. So far, they’re not even close.
Because digital books are software, an author shouldn’t think of a book as merely data. The book is a program.
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.1 Prerequisites

1.2 How to install

1.3 Beyond that

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.10 PS for Scribble users

2.11 The end of the beginning

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

5 First tutorial: the project server & preprocessor

5.1 Prerequisites

5.2 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 Using the 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 commands

5.5.4 Racket basics (if you’re not familiar)

5.5.5 Defining variables with 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 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.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.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 source 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 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 What are custom tags good for?

7.3.5 Semantic markup

7.3.6 Format independence

7.3.7 Using custom tags

7.3.8 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 Using the "pollen.rkt" file

7.7 Decoding markup via the root tag

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 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 glyph (◊)

12.2.1 Lozenge helpers

12.2.1.1 DrRacket

12.2.1.2 AHK script

12.2.1.3 Emacs script

12.3 The two command modes: Pollen mode & Racket mode

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 argument

12.4 Embedding character entities

12.5 Adding Pollen-mode 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.1 Preloading and reseting

14.1.2 Disabling the cache

14.1.3 Scope of dependency tracking

14.1.4 Functions

14.2.1 Syntactic forms

14.2.2 Data helpers

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.7.1 How to override setup values

14.7.3 Parameters

15 Unstable module reference

15.2 Typography

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

19.1 What the version number means

19.2 Source code

19.3 Development policy

19.4.1 Version 1.0

top ← prev up next →