https://docs.racket-lang.org/pollen/ V Pollen: the book is a program 1 Installation 2 Quick tour 3 Backstory 4 The big picture 5 First tutorial: the project server & preprocessor 6 Second tutorial: Markdown, templates, & pagetrees 7 Third tutorial: Pollen markup & tag functions 8 Fourth tutorial: multiple output targets 9 Mini tutorials 10 Using raco pollen 11 File formats 12 Pollen command syntax 13 Programming Pollen 14 Module reference 15 Unstable module reference 16 Acknowledgments 17 License & source code 18 Version notes (3.2.3877.60) Index On this page: Pollen: the book is a program 8.14 [ ] top contents - prev up next - Pollen: the book is a program Matthew Butterick #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 1.4 Getting more help 1.4.1 Bugs and feature requests 1.4.2 Questions & discussion 1.4.3 Can I see the source for Practical Typography or Typography for Lawyers? 1.4.4 Utilities & libraries 1.4.5 More projects & guides 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 10.11 Logging & the PLTSTDERR 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 the lozenge ..." 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 Acknowledgments 17 License & source code 18 Version notes (3.2.3877.60) 18.1 What the version number means 18.2 Source code 18.3 Development policy 18.4 Changelog 18.4.1 Version 3.2 18.4.2 Version 3.1 18.4.3 Version 3.0 18.4.4 Version 2.2 18.4.5 Version 2.1 18.4.6 Version 2.0 18.4.7 Version 1.5 18.4.8 Version 1.4 18.4.9 Version 1.3 18.4.10 Version 1.2 18.4.11 Version 1.1 18.4.12 Version 1.0 Index [ ] top contents - prev up next -