One curious aspect of free software is that you can appropriate the benefits of other people’s work while making it look like your own. No such legerdemain here. Whatever effort I’ve put into Pollen is dwarfed by the epic accomplishments of the Racket development team. I thank all of them — especially Matthew Flatt, Jay McCarthy, and Matthias Felleisen — for making this tremendous tool available, for adding several features I suggested, and for patiently answering my dumb questions over the months.
Thank you to Greg Hendershott for his Markdown parser.
The best software tools do more than get the job done. They create an incentive to undertake jobs you wouldn’t have attempted before. Racket encouraged me to become a better programmer so I could create Pollen. Likewise, I hope that Pollen encourages you to make things you couldn’t before.
One curious aspect of free software is that you can appropriate the benefits of other people’s work while making it look like your own. No such legerdemain here. Whatever effort I’ve put into Pollen is dwarfed by the epic accomplishments of the Racket development team. I thank all of them — especially Matthew Flatt, Jay McCarthy, and Matthias Felleisen — for making this tremendous tool available, for adding several features I suggested, and for patiently answering my dumb questions over the months.
Thank you to Greg Hendershott for his Markdown parser.
The best software tools do more than get the job done. They create an incentive to undertake jobs you wouldn’t have attempted before. Racket encouraged me to become a better programmer so I could create Pollen. Likewise, I hope that Pollen encourages you to make things you couldn’t before.
\ No newline at end of file
diff --git a/doc/Backstory.html b/doc/Backstory.html
index 7e58d9b..937adfd 100644
--- a/doc/Backstory.html
+++ b/doc/Backstory.html
@@ -1,2 +1,2 @@
-3 Backstory
I created Pollen to overcome limitations & frustrations I repeatedly encountered with existing web-publishing tools.
If you agree with my characterization of those problems, then you’ll probably like the solution that Pollen offers. If not, you probably won’t.
3.1Web development and its discontents
I made my first web page in 1994, shortly after the web was invented. I opened my text editor (at the time, BBEdit), pecked out <html><body>Helloworld</body></html>, then loaded it in Mosaic. So did a million other nerds.
If you weren’t around then, you didn’t miss much. Everything about the web was horrible: the web browsers, the computers running the browsers, the dial-up connections feeding the browsers, and of course HTML itself. At that point, the desktop-software experience was already slick and refined. By comparison, using the web felt like banging rocks together.
That’s no longer true. The web is now 20 years old. During that time, most parts of the web have improved dramatically — for instance, the connections are faster, the browsers are more sophisticated, the screens have more pixels.
But one part has not improved: the way we make web pages. Over the years, tools promising to simplify HTML development have come and mostly gone — from PageMill to Dreamweaver to WordPress to Jekyll. Meanwhile, true web jocks have remained loyal to the original HTML power tool: the humble text editor.
In one way, this makes sense. Web pages are mostly made of text-based data — HTML, CSS, JavaScript, and so on — and the simplest way to mainpulate this data is with a text editor. While HTML and CSS are not programming languages, they lend themselves to semantic and logical structure that’s most easily expressed by editing them as text. Furthermore, text-based editing makes debugging and performance improvements easier.
But text-based editing is also limited. Though the underlying description of a web page is notionally human-readable, it’s largely optimized to be readable by other software — namely, web browsers. HTML markup in particular is verbose and easily mistyped. And isn’t it fatally dull to manage all the boilerplate, like surrounding every paragraph with <p>...</p>? Yes, it is.
For these reasons, much of web development should lend itself to abstraction & automation. Abstraction means consolidating repetitve, complex patterns into simpler, parameterized forms. Automation means avoiding the manual drudgery of generating the output files. But in practice, tools that enable this abstraction & automation have been slow to arrive, and most have come hobbled with unacceptable deficiencies.
3.2The better idea: a programming model
Parallel with my HTML education, I also goofed around with various programming languages — C, C++, Perl, Java, PHP, JavaScript, Python. Unlike HTML, programming languages excel at abstraction and automation. This seemed like the obvious direction for web development to go.
What distinguishes the text-editing model from the programming model? It’s a matter of direct vs. indirect manipulation of output. The text-editing model treats HTML as something to be written directly with a text editor. Whereas the programming model treats HTML — or whatever the output is — as the result of compiling a set of source files, which are written in a programming language. The costs of working indirectly via the programming language are offset by the benefits of abstraction & automation.
On the early web, the text-editing model was appealingly precise and quick. On small projects, it worked well enough. But as projects grew, the text-editing model was going to lose steam. I wasn’t the only one to notice. Shortly after those million nerds made their first web page by hand, many of them set about devising ways to apply a programming model to web development.
3.3“Now you have two problems”
What followed was a steady stream of products, frameworks, tools, and content management systems that claimed to bring a programming model to web development. Some were better than others. But none of them displaced the text editor as the preferred tool of web developers.
Why not? All these tools promised a great leap forward in solving the web-development problem. In practice, they simply redistributed the pain. I needn’t bore you with enumerating the deficiencies of specific tools, because they’ve tended to fail in the same thematic ways:
No native data structure for HTML. Core to any programming model is data structures. Good data structures make processing easy; bad ones make it hard. Even though HTML has a well documented format, rarely has it been handled within a programming system with a native, intuitive data structure. Instead, it’s either been treated as a string (wrong), a tree (also wrong), or some magical parsed object. This has made working with HTML in programming environments needlessly difficult.
Mandatory separation of code, presentation, and content. This principle has often been held out as an ideal in web development. But it’s also counterintuitive, because an HTML page naturally contains all three. If you want to separate them, your tools should let you. But if you don’t, your tools shouldn’t make you.
Compromised template languages. Seems like every programming language has at least 10 templating systems for HTML, all of which require you to learn a new “template language” that offers the worst of both worlds: fewer features and different syntax than the underlying language.
Steep learning curves. Web programmers have often chided designers for not knowing how to code. But programming-based web-development tools have often had a high initial learning curve that requires you to throw out your existing workflow. Programmers built these tools — no surprise that programmers have been more comfortable with them.
I’ve tried a lot of these tools over the years. Some I liked. Some I didn’t. Invariably, however, whenever I could still make do with hand-editing an HTML project, I would. After trying to cajole the web framework du jour into doing my bidding, it was relaxing to trade off some efficiency for control.
3.4Rethinking the solution for digital books
In 2008, I launched a website called Typography for Lawyers. Initially, I’d conceived of it as a book. Then I thought “no one’s going to publish that.” So it became a website, that I aimed to make as book-like as possible. But hand-editing wasn’t going to be enough.
So I used WordPress. The major chore became scraping out all the crap that typically lives in blog templates. Largely because of this, people liked the site, because it was simpler & cleaner than the usual WordPress website.
Eventually, a publisher offered to release it as a paperback. Later came the inevitable request to make it into a Kindle book. As a fan of typography, I hate the Kindle. The layout controls are coarse, and so is the reading experience. But I didn’t run and hide. Basically a Kindle book is a little website made with 1995-era HTML. So I coded up some tools in Perl to convert my book to Kindle format while preserving the formatting and images as well as possible.
At that point, I noticed I had converted Typography for Lawyers into web format twice, using two different sets of tools. Before someone asked me to do it a third time, I started thinking about how I might create source code for the book that allowed me to render it into different formats.
This was the beginning of the Pollen project.
I wrote the initial version of Pollen in Python. I devised a simplified markup-notation language for the source files. This language was compiled into XML-ish data structures using ply (Python lex/yacc). These structures were parsed into trees using LXML. The trees were combined with templates made in Chameleon. These templates were rendered and previewed with the Bottle web server.
Did it work? Sort of. Source code went in; web pages came out. But it was also complicated and fragile. Moreover, though the automation was there, there wasn’t yet enough abstraction at the source layer. I started thinking about how I could add a source preprocessor.
3.5Enter Racket
I had come across Racket while researching languages suitable for HTML/XML processing. I had unexpectedly learned about the secret kinship of XML and Lisp: though XML is not a programming language, it uses a variant of Lisp syntax. Thus Lisp languages are particularly adept at handling XMLish structures. That was interesting.
After comparing some of the Lisp & Scheme variants, Racket stood out because it had a text-based dialect called Scribble. Scribble could be used to embed code within textual content. That was interesting too. Among other things, this meant Scribble could be used as a general-purpose preprocessor. So I thought I’d see if I could add it to Pollen.
It worked. So well, in fact, that I started thinking about whether I could reimplement other parts of Pollen in Racket. Then I started thinking about reimplementing all of it in Racket.
So I did. And here we are.
3.6What is Pollen?
Pollen is a publishing system built on top of Scribble and Racket. So far I’ve optimized Pollen for digital books, because that’s mainly what I use it for. But it can be used for small projects too.
As a publishing system, Pollen includes:
A programming language. The Pollen language is a variant of Scribble, with specific “dialects” tailored to different kinds of source files. You don’t need to use the programming features to do useful work, but they’re available when you need them.
A set of tools & libraries. Pollen targets HTML output. So it includes a variety of tools that cure common HTML annoyances, including a CSS preprocessor.
A development environment. Pollen works with the DrRacket IDE. It also includes a project web server so you can dynamically preview and revise your publication.
Pollen addresses the deficiencies I experienced with other tools:
Yes, we have a native data structure for HTML. Racket represents HTML structures as X-expressions, which are a variant of the standard Racket data structure, called S-expressions. In other words, not only is there a native representation for HTML, everything in the language is represented this way.
Flexible blending of code, presentation, and content. Pollen is a text-based language. So a Pollen source file might have no code at all. But as a dialect of Scribble & Racket, if you want to mix code with content, you can.
No template language. It’s not necessary, because you can use the whole Racket language, and all the usual Racket syntax, in every Pollen file.
Shallow learning curve. You don’t need to do a lot of setup and configuration to start doing useful work with Pollen. Programmers and non-programmers can easily collaborate. Yes, I concede that if you plan to get serious, you’ll need to learn some Racket. I don’t think you’ll regret it.
I created Pollen to overcome limitations & frustrations I repeatedly encountered with existing web-publishing tools.
If you agree with my characterization of those problems, then you’ll probably like the solution that Pollen offers. If not, you probably won’t.
3.1Web development and its discontents
I made my first web page in 1994, shortly after the web was invented. I opened my text editor (at the time, BBEdit), pecked out <html><body>Helloworld</body></html>, then loaded it in Mosaic. So did a million other nerds.
If you weren’t around then, you didn’t miss much. Everything about the web was horrible: the web browsers, the computers running the browsers, the dial-up connections feeding the browsers, and of course HTML itself. At that point, the desktop-software experience was already slick and refined. By comparison, using the web felt like banging rocks together.
That’s no longer true. The web is now 20 years old. During that time, most parts of the web have improved dramatically — for instance, the connections are faster, the browsers are more sophisticated, the screens have more pixels.
But one part has not improved: the way we make web pages. Over the years, tools promising to simplify HTML development have come and mostly gone — from PageMill to Dreamweaver to WordPress to Jekyll. Meanwhile, true web jocks have remained loyal to the original HTML power tool: the humble text editor.
In one way, this makes sense. Web pages are mostly made of text-based data — HTML, CSS, JavaScript, and so on — and the simplest way to mainpulate this data is with a text editor. While HTML and CSS are not programming languages, they lend themselves to semantic and logical structure that’s most easily expressed by editing them as text. Furthermore, text-based editing makes debugging and performance improvements easier.
But text-based editing is also limited. Though the underlying description of a web page is notionally human-readable, it’s largely optimized to be readable by other software — namely, web browsers. HTML markup in particular is verbose and easily mistyped. And isn’t it fatally dull to manage all the boilerplate, like surrounding every paragraph with <p>...</p>? Yes, it is.
For these reasons, much of web development should lend itself to abstraction & automation. Abstraction means consolidating repetitve, complex patterns into simpler, parameterized forms. Automation means avoiding the manual drudgery of generating the output files. But in practice, tools that enable this abstraction & automation have been slow to arrive, and most have come hobbled with unacceptable deficiencies.
3.2The better idea: a programming model
Parallel with my HTML education, I also goofed around with various programming languages — C, C++, Perl, Java, PHP, JavaScript, Python. Unlike HTML, programming languages excel at abstraction and automation. This seemed like the obvious direction for web development to go.
What distinguishes the text-editing model from the programming model? It’s a matter of direct vs. indirect manipulation of output. The text-editing model treats HTML as something to be written directly with a text editor. Whereas the programming model treats HTML — or whatever the output is — as the result of compiling a set of source files, which are written in a programming language. The costs of working indirectly via the programming language are offset by the benefits of abstraction & automation.
On the early web, the text-editing model was appealingly precise and quick. On small projects, it worked well enough. But as projects grew, the text-editing model was going to lose steam. I wasn’t the only one to notice. Shortly after those million nerds made their first web page by hand, many of them set about devising ways to apply a programming model to web development.
3.3“Now you have two problems”
What followed was a steady stream of products, frameworks, tools, and content management systems that claimed to bring a programming model to web development. Some were better than others. But none of them displaced the text editor as the preferred tool of web developers.
Why not? All these tools promised a great leap forward in solving the web-development problem. In practice, they simply redistributed the pain. I needn’t bore you with enumerating the deficiencies of specific tools, because they’ve tended to fail in the same thematic ways:
No native data structure for HTML. Core to any programming model is data structures. Good data structures make processing easy; bad ones make it hard. Even though HTML has a well documented format, rarely has it been handled within a programming system with a native, intuitive data structure. Instead, it’s either been treated as a string (wrong), a tree (also wrong), or some magical parsed object. This has made working with HTML in programming environments needlessly difficult.
Mandatory separation of code, presentation, and content. This principle has often been held out as an ideal in web development. But it’s also counterintuitive, because an HTML page naturally contains all three. If you want to separate them, your tools should let you. But if you don’t, your tools shouldn’t make you.
Compromised template languages. Seems like every programming language has at least 10 templating systems for HTML, all of which require you to learn a new “template language” that offers the worst of both worlds: fewer features and different syntax than the underlying language.
Steep learning curves. Web programmers have often chided designers for not knowing how to code. But programming-based web-development tools have often had a high initial learning curve that requires you to throw out your existing workflow. Programmers built these tools — no surprise that programmers have been more comfortable with them.
I’ve tried a lot of these tools over the years. Some I liked. Some I didn’t. Invariably, however, whenever I could still make do with hand-editing an HTML project, I would. After trying to cajole the web framework du jour into doing my bidding, it was relaxing to trade off some efficiency for control.
3.4Rethinking the solution for digital books
In 2008, I launched a website called Typography for Lawyers. Initially, I’d conceived of it as a book. Then I thought “no one’s going to publish that.” So it became a website, that I aimed to make as book-like as possible. But hand-editing wasn’t going to be enough.
So I used WordPress. The major chore became scraping out all the crap that typically lives in blog templates. Largely because of this, people liked the site, because it was simpler & cleaner than the usual WordPress website.
Eventually, a publisher offered to release it as a paperback. Later came the inevitable request to make it into a Kindle book. As a fan of typography, I hate the Kindle. The layout controls are coarse, and so is the reading experience. But I didn’t run and hide. Basically a Kindle book is a little website made with 1995-era HTML. So I coded up some tools in Perl to convert my book to Kindle format while preserving the formatting and images as well as possible.
At that point, I noticed I had converted Typography for Lawyers into web format twice, using two different sets of tools. Before someone asked me to do it a third time, I started thinking about how I might create source code for the book that allowed me to render it into different formats.
This was the beginning of the Pollen project.
I wrote the initial version of Pollen in Python. I devised a simplified markup-notation language for the source files. This language was compiled into XML-ish data structures using ply (Python lex/yacc). These structures were parsed into trees using LXML. The trees were combined with templates made in Chameleon. These templates were rendered and previewed with the Bottle web server.
Did it work? Sort of. Source code went in; web pages came out. But it was also complicated and fragile. Moreover, though the automation was there, there wasn’t yet enough abstraction at the source layer. I started thinking about how I could add a source preprocessor.
3.5Enter Racket
I had come across Racket while researching languages suitable for HTML/XML processing. I had unexpectedly learned about the secret kinship of XML and Lisp: though XML is not a programming language, it uses a variant of Lisp syntax. Thus Lisp languages are particularly adept at handling XMLish structures. That was interesting.
After comparing some of the Lisp & Scheme variants, Racket stood out because it had a text-based dialect called Scribble. Scribble could be used to embed code within textual content. That was interesting too. Among other things, this meant Scribble could be used as a general-purpose preprocessor. So I thought I’d see if I could add it to Pollen.
It worked. So well, in fact, that I started thinking about whether I could reimplement other parts of Pollen in Racket. Then I started thinking about reimplementing all of it in Racket.
So I did. And here we are.
3.6What is Pollen?
Pollen is a publishing system built on top of Scribble and Racket. So far I’ve optimized Pollen for digital books, because that’s mainly what I use it for. But it can be used for small projects too.
As a publishing system, Pollen includes:
A programming language. The Pollen language is a variant of Scribble, with specific “dialects” tailored to different kinds of source files. You don’t need to use the programming features to do useful work, but they’re available when you need them.
A set of tools & libraries. Pollen targets HTML output. So it includes a variety of tools that cure common HTML annoyances, including a CSS preprocessor.
A development environment. Pollen works with the DrRacket IDE. It also includes a project web server so you can dynamically preview and revise your publication.
Pollen addresses the deficiencies I experienced with other tools:
Yes, we have a native data structure for HTML. Racket represents HTML structures as X-expressions, which are a variant of the standard Racket data structure, called S-expressions. In other words, not only is there a native representation for HTML, everything in the language is represented this way.
Flexible blending of code, presentation, and content. Pollen is a text-based language. So a Pollen source file might have no code at all. But as a dialect of Scribble & Racket, if you want to mix code with content, you can.
No template language. It’s not necessary, because you can use the whole Racket language, and all the usual Racket syntax, in every Pollen file.
Shallow learning curve. You don’t need to do a lot of setup and configuration to start doing useful work with Pollen. Programmers and non-programmers can easily collaborate. Yes, I concede that if you plan to get serious, you’ll need to learn some Racket. I don’t think you’ll regret it.
\ No newline at end of file
diff --git a/doc/Cache.html b/doc/Cache.html
index 732495e..5baf7c2 100644
--- a/doc/Cache.html
+++ b/doc/Cache.html
@@ -1,2 +1,2 @@
-8.1 Cache
The slowest part of a render is parsing and decoding the source file. Often, previewing a single source file necessarily means decoding others (for instance templates, or other source files that are linked into the main source file). But usually, only one source file is changing at a time. Therefore, Pollen stores copies of the exports of source files — namely, whatever is stored in doc and metas — in the cache so they can be reused.
A parameter that refers to the current cache. It is initialized with make-cache.
The cache is a hash table that uses the complete path of a source file as its keys. The value associated with each of these keys is a subcache — another hash table with keys 'doc, 'metas (for storing the exports of the source file) and 'mod-time (for storing the modification time, provided by file-or-directory-modify-seconds).
Similar to (dynamic-requiresource-pathkey), except that it first tries to retrieve the requested value out of current-cache. If it’s not there, or out of date, dynamic-require is used to update the value.
The only keys supported are 'doc, 'metas, and 'mod-time.
If you want the speed benefit of the cache, you should always use cached-require to get data from Pollen source files. That doesn’t mean you can’t still use functions like require, local-require, and dynamic-require. They’ll just be slower.
The slowest part of a render is parsing and decoding the source file. Often, previewing a single source file necessarily means decoding others (for instance templates, or other source files that are linked into the main source file). But usually, only one source file is changing at a time. Therefore, Pollen stores copies of the exports of source files — namely, whatever is stored in doc and metas — in the cache so they can be reused.
A parameter that refers to the current cache. It is initialized with make-cache.
The cache is a hash table that uses the complete path of a source file as its keys. The value associated with each of these keys is a subcache — another hash table with keys 'doc, 'metas (for storing the exports of the source file) and 'mod-time (for storing the modification time, provided by file-or-directory-modify-seconds).
Similar to (dynamic-requiresource-pathkey), except that it first tries to retrieve the requested value out of current-cache. If it’s not there, or out of date, dynamic-require is used to update the value.
The only keys supported are 'doc, 'metas, and 'mod-time.
If you want the speed benefit of the cache, you should always use cached-require to get data from Pollen source files. That doesn’t mean you can’t still use functions like require, local-require, and dynamic-require. They’ll just be slower.
\ No newline at end of file
diff --git a/doc/Decode.html b/doc/Decode.html
index a6b3a5f..2807dfe 100644
--- a/doc/Decode.html
+++ b/doc/Decode.html
@@ -1,2 +1,2 @@
-8.2 Decode
The doc export of a Pollen markup file is a simple X-expression. Decoding refers to any post-processing of this X-expression. The pollen/decode module provides tools for creating decoders.
The decode step can happen separately from the compilation of the file. But you can also attach a decoder to the markup file’s root node, so the decoding happens automatically when the markup is compiled, and thus automatically incorporated into doc. (Following this approach, you could also attach multiple decoders to different tags within doc.)
You can, of course, embed function calls within Pollen markup. But since markup is optimized for authors, decoding is useful for operations that can or should be moved out of the authoring layer.
One example is presentation and layout. For instance, detect-paragraphs is a decoder function that lets authors mark paragraphs in their source simply by using two carriage returns.
Another example is conversion of output into a particular data format. Most Pollen functions are optimized for HTML output, but one could write a decoder that targets another format.
Recursively process a tagged-xexpr, usually the one exported from a Pollen source file as doc.
This function doesn’t do much on its own. Rather, it provides the hooks upon which harder-working functions can be hung.
Recall from [future link: Pollen mechanics] that any tag can have a function attached to it. By default, the tagged-xexpr from a source file is tagged with root. So the typical way to use decode is to attach your decoding functions to it, and then define root to invoke your decode function. Then it will be automatically applied to every doc during compile.
For instance, here’s how decode is attached to root in Butterick’s Practical Typography. There’s not much to it —
[update with actual code]
This illustrates another important point: even though decode presents an imposing list of arguments, you’re unlikely to use all of them at once. These represent possibilities, not requirements. For instance, let’s see what happens when decode is invoked without any of its optional arguments.
Right — nothing. That’s because the default value for the decoding arguments is the identity function, (λ(x)x). So all the input gets passed through intact unless another action is specified.
The *-proc arguments of decode take procedures that are applied to specific categories of elements within txexpr.
The txexpr-tag-proc argument is a procedure that handles X-expression tags.
Examples:
> (definetx'(p"I'm from a strange"(strong"namespace")))
;Tags are symbols, so a tag-proc should return a symbol
'(ns:p "I'm from a strange" (ns:strong "namespace"))
The txexpr-attrs-proc argument is a procedure that handles lists of X-expression attributes. (The txexpr module, included at no extra charge with Pollen, includes useful helper functions for dealing with these attribute lists.)
Examples:
> (definetx'(p[[id"first"]]"If I only had a brain."))
'(p ((class "PhD") (id "first")) "If I only had a brain.")
Note that txexpr-attrs-proc will change the attributes of every tagged X-expression, even those that don’t have attributes. This is useful, because sometimes you want to add attributes where none existed before. But be careful, because the behavior may make your processing function overinclusive.
Examples:
> (definetx'(div(p[[id"first"]]"If I only had a brain.")
'(div (p ((class "PhD") (id "first")) "If I only had a brain.") (p "Me too."))
The txexpr-elements-proc argument is a procedure that operates on the list of elements that represents the content of each tagged X-expression. Note that each element of an X-expression is subject to two passes through the decoder: once now, as a member of the list of elements, and also later, through its type-specific decoder (i.e., string-proc, symbol-proc, and so on).
So why do you need txexpr-elements-proc? Because some types of element decoding depend on context, thus it’s necessary to handle the elements as a group. For instance, the doubling function above, though useless, requires handling the element list as a whole, because elements are being added.
A more useful example: paragraph detection. The behavior is not merely a map across each element:
;Context matters. Trailing whitespace is ignored ...
> (paras'(body"The first paragraph.""\n\n"))
'(body "The first paragraph.")
;... but whitespace between strings is converted to a break.
> (paras'(body"The first paragraph.""\n\n""And another."))
'(body (p "The first paragraph.") (p "And another."))
;A combination of both types
> (paras'(body"The first paragraph.""\n\n""And another.""\n\n"))
'(body (p "The first paragraph.") (p "And another."))
The block-txexpr-proc argument and the inline-txexpr-proc arguments are procedures that operate on tagged X-expressions. If the X-expression meets the block-txexpr? test, it is processed by block-txexpr-proc. Otherwise, it is processed by inline-txexpr-proc. Thus every tagged X-expression will be handled by one or the other. Of course, if you want block and inline elements to be handled the same way, you can set block-txexpr-proc and inline-txexpr-proc to be the same procedure.
Examples:
> (definetx'(div"Please"(em"mind the gap")(h1"Tuesdays only")))
'(ns:div "Please" (ns:em "mind the gap") (ns:h1 "Tuesdays only"))
The string-proc, symbol-proc, valid-char-proc, and cdata-proc arguments are procedures that operate on X-expressions that are strings, symbols, valid-chars, and CDATA, respectively. Deliberately, the output contracts for these procedures accept any kind of X-expression (meaning, the procedure can change the X-expression type).
Examples:
;A div with string, entity, character, and cdata elements
Finally, the tags-to-exclude argument is a list of tags that will be exempted from decoding. Though you could get the same result by testing the input within the individual decoding functions, that’s tedious and potentially slower.
Examples:
> (definetx'(p"I really think"(em"italics")"should be lowercase."))
'(p "I REALLY THINK" (em "italics") "SHOULD BE LOWERCASE.")
The tags-to-exclude argument is useful if you’re decoding source that’s destined to become HTML. According to the HTML spec, material within a <style> or <script> block needs to be preserved literally. In this example, if the CSS and JavaScript blocks are capitalized, they won’t work. So exclude '(stylescript), and problem solved.
(script ((type "text/javascript")) "var area = h * w;"))
8.2.1Block
Because it’s convenient, Pollen categorizes tagged X-expressions into two categories: block and inline. Why is it convenient? When using decode, you often want to treat the two categories differently. Not that you have to. But this is how you can.
Adds a tag to project-block-tags so that block-txexpr? will report it as a block, and decode will process it with block-txexpr-proc rather than inline-txexpr-proc.
Pollen tries to do the right thing without being told. But this is the rare case where you have to be explicit. If you introduce a tag into your markup that you want treated as a block, you must use this function to identify it, or you will get spooky behavior later on.
For instance, detect-paragraphs knows that block elements in the markup shouldn’t be wrapped in a p tag. So if you introduce a new block element called bloq without registering it as a block, misbehavior will follow:
> (paras'(body"I want to be a paragraph.""\n\n"(bloq"But not me.")))
'(body (p "I want to be a paragraph.") (bloq "But not me."))
;Right: bloq is treated as a block
If you find the idea of registering block tags unbearable, good news. The project-block-tags include the standard HTML block tags by default. So if you just want to use things like div and p and h1–h6, you’ll get the right behavior for free.
Predicate that tests whether v is a tagged X-expression, and if so, whether the tag is among the project-block-tags. If not, it is treated as inline. To adjust how this test works, use register-block-tag.
8.2.2Typography
An assortment of typography & layout functions, designed to be used with decode. These aren’t hard to write. So if you like these, use them. If not, make your own.
A predicate that returns #t for any stringlike v that’s entirely whitespace, but also the empty string, as well as lists and vectors that are made only of whitespace? members. Following the regexp-match convention, whitespace? does not return #t for a nonbreaking space. If you prefer that behavior, use whitespace/nbsp?.
Within tagged-xexpr-elements, convert occurrences of linebreak-sep ("\n" by default) to linebreak, but only if linebreak-sep does not occur between blocks (see block-txexpr?). Why? Because block-level elements automatically display on a new line, so adding linebreak would be superfluous. In that case, linebreak-sep just disappears.
Find paragraphs within elements, as denoted by paragraph-sep, and wrap them with paragraph-tag, unless the element is already a block-txexpr? (because in that case, the wrapping is superfluous). Thus, as a consequence, if paragraph-sep occurs between two blocks, it’s ignored.
The paragraph-tag argument sets the tag used to wrap paragraphs.
The linebreak-proc argument allows you to use a different linebreaking procedure other than the usual detect-linebreaks.
The doc export of a Pollen markup file is a simple X-expression. Decoding refers to any post-processing of this X-expression. The pollen/decode module provides tools for creating decoders.
The decode step can happen separately from the compilation of the file. But you can also attach a decoder to the markup file’s root node, so the decoding happens automatically when the markup is compiled, and thus automatically incorporated into doc. (Following this approach, you could also attach multiple decoders to different tags within doc.)
You can, of course, embed function calls within Pollen markup. But since markup is optimized for authors, decoding is useful for operations that can or should be moved out of the authoring layer.
One example is presentation and layout. For instance, detect-paragraphs is a decoder function that lets authors mark paragraphs in their source simply by using two carriage returns.
Another example is conversion of output into a particular data format. Most Pollen functions are optimized for HTML output, but one could write a decoder that targets another format.
Recursively process a tagged-xexpr, usually the one exported from a Pollen source file as doc.
This function doesn’t do much on its own. Rather, it provides the hooks upon which harder-working functions can be hung.
Recall from [future link: Pollen mechanics] that any tag can have a function attached to it. By default, the tagged-xexpr from a source file is tagged with root. So the typical way to use decode is to attach your decoding functions to it, and then define root to invoke your decode function. Then it will be automatically applied to every doc during compile.
For instance, here’s how decode is attached to root in Butterick’s Practical Typography. There’s not much to it —
[update with actual code]
This illustrates another important point: even though decode presents an imposing list of arguments, you’re unlikely to use all of them at once. These represent possibilities, not requirements. For instance, let’s see what happens when decode is invoked without any of its optional arguments.
Right — nothing. That’s because the default value for the decoding arguments is the identity function, (λ(x)x). So all the input gets passed through intact unless another action is specified.
The *-proc arguments of decode take procedures that are applied to specific categories of elements within txexpr.
The txexpr-tag-proc argument is a procedure that handles X-expression tags.
Examples:
> (definetx'(p"I'm from a strange"(strong"namespace")))
;Tags are symbols, so a tag-proc should return a symbol
'(ns:p "I'm from a strange" (ns:strong "namespace"))
The txexpr-attrs-proc argument is a procedure that handles lists of X-expression attributes. (The txexpr module, included at no extra charge with Pollen, includes useful helper functions for dealing with these attribute lists.)
Examples:
> (definetx'(p[[id"first"]]"If I only had a brain."))
'(p ((class "PhD") (id "first")) "If I only had a brain.")
Note that txexpr-attrs-proc will change the attributes of every tagged X-expression, even those that don’t have attributes. This is useful, because sometimes you want to add attributes where none existed before. But be careful, because the behavior may make your processing function overinclusive.
Examples:
> (definetx'(div(p[[id"first"]]"If I only had a brain.")
'(div (p ((class "PhD") (id "first")) "If I only had a brain.") (p "Me too."))
The txexpr-elements-proc argument is a procedure that operates on the list of elements that represents the content of each tagged X-expression. Note that each element of an X-expression is subject to two passes through the decoder: once now, as a member of the list of elements, and also later, through its type-specific decoder (i.e., string-proc, symbol-proc, and so on).
So why do you need txexpr-elements-proc? Because some types of element decoding depend on context, thus it’s necessary to handle the elements as a group. For instance, the doubling function above, though useless, requires handling the element list as a whole, because elements are being added.
A more useful example: paragraph detection. The behavior is not merely a map across each element:
;Context matters. Trailing whitespace is ignored ...
> (paras'(body"The first paragraph.""\n\n"))
'(body "The first paragraph.")
;... but whitespace between strings is converted to a break.
> (paras'(body"The first paragraph.""\n\n""And another."))
'(body (p "The first paragraph.") (p "And another."))
;A combination of both types
> (paras'(body"The first paragraph.""\n\n""And another.""\n\n"))
'(body (p "The first paragraph.") (p "And another."))
The block-txexpr-proc argument and the inline-txexpr-proc arguments are procedures that operate on tagged X-expressions. If the X-expression meets the block-txexpr? test, it is processed by block-txexpr-proc. Otherwise, it is processed by inline-txexpr-proc. Thus every tagged X-expression will be handled by one or the other. Of course, if you want block and inline elements to be handled the same way, you can set block-txexpr-proc and inline-txexpr-proc to be the same procedure.
Examples:
> (definetx'(div"Please"(em"mind the gap")(h1"Tuesdays only")))
'(ns:div "Please" (ns:em "mind the gap") (ns:h1 "Tuesdays only"))
The string-proc, symbol-proc, valid-char-proc, and cdata-proc arguments are procedures that operate on X-expressions that are strings, symbols, valid-chars, and CDATA, respectively. Deliberately, the output contracts for these procedures accept any kind of X-expression (meaning, the procedure can change the X-expression type).
Examples:
;A div with string, entity, character, and cdata elements
Finally, the tags-to-exclude argument is a list of tags that will be exempted from decoding. Though you could get the same result by testing the input within the individual decoding functions, that’s tedious and potentially slower.
Examples:
> (definetx'(p"I really think"(em"italics")"should be lowercase."))
'(p "I REALLY THINK" (em "italics") "SHOULD BE LOWERCASE.")
The tags-to-exclude argument is useful if you’re decoding source that’s destined to become HTML. According to the HTML spec, material within a <style> or <script> block needs to be preserved literally. In this example, if the CSS and JavaScript blocks are capitalized, they won’t work. So exclude '(stylescript), and problem solved.
(script ((type "text/javascript")) "var area = h * w;"))
9.2.1Block
Because it’s convenient, Pollen categorizes tagged X-expressions into two categories: block and inline. Why is it convenient? When using decode, you often want to treat the two categories differently. Not that you have to. But this is how you can.
Adds a tag to project-block-tags so that block-txexpr? will report it as a block, and decode will process it with block-txexpr-proc rather than inline-txexpr-proc.
Pollen tries to do the right thing without being told. But this is the rare case where you have to be explicit. If you introduce a tag into your markup that you want treated as a block, you must use this function to identify it, or you will get spooky behavior later on.
For instance, detect-paragraphs knows that block elements in the markup shouldn’t be wrapped in a p tag. So if you introduce a new block element called bloq without registering it as a block, misbehavior will follow:
> (paras'(body"I want to be a paragraph.""\n\n"(bloq"But not me.")))
'(body (p "I want to be a paragraph.") (bloq "But not me."))
;Right: bloq is treated as a block
If you find the idea of registering block tags unbearable, good news. The project-block-tags include the standard HTML block tags by default. So if you just want to use things like div and p and h1–h6, you’ll get the right behavior for free.
Predicate that tests whether v is a tagged X-expression, and if so, whether the tag is among the project-block-tags. If not, it is treated as inline. To adjust how this test works, use register-block-tag.
9.2.2Typography
An assortment of typography & layout functions, designed to be used with decode. These aren’t hard to write. So if you like these, use them. If not, make your own.
A predicate that returns #t for any stringlike v that’s entirely whitespace, but also the empty string, as well as lists and vectors that are made only of whitespace? members. Following the regexp-match convention, whitespace? does not return #t for a nonbreaking space. If you prefer that behavior, use whitespace/nbsp?.
Within tagged-xexpr-elements, convert occurrences of linebreak-sep ("\n" by default) to linebreak, but only if linebreak-sep does not occur between blocks (see block-txexpr?). Why? Because block-level elements automatically display on a new line, so adding linebreak would be superfluous. In that case, linebreak-sep just disappears.
Find paragraphs within elements, as denoted by paragraph-sep, and wrap them with paragraph-tag, unless the element is already a block-txexpr? (because in that case, the wrapping is superfluous). Thus, as a consequence, if paragraph-sep occurs between two blocks, it’s ignored.
The paragraph-tag argument sets the tag used to wrap paragraphs.
The linebreak-proc argument allows you to use a different linebreaking procedure other than the usual detect-linebreaks.
\ No newline at end of file
diff --git a/doc/File_formats.html b/doc/File_formats.html
index 1e58b2f..741cfa4 100644
--- a/doc/File_formats.html
+++ b/doc/File_formats.html
@@ -1,2 +1,2 @@
-6 File formats
The Pollen language is divided into variants, or dialects, that are tailored to suit each of the core source formats.
These dialects can be invoked one of two ways: either by invoking a specific dialect in the first line of the file (also known as the #lang line), or by using the generic #lang pollen as the first line, and then the correct dialect will be automatically selected based on the source file extension.
If the #lang line specifies a dialect different from the one specified by the file extension, the #lang line will take precedence.
For ease of use, the behavior of the Pollen language departs from the standard Racket language in several ways. The differences are noted below.
6.1.1Command syntax using ◊
Commands must start with the special lozenge character ◊. Other material is interpreted as plain text. See ◊ command overview for more.
How is this different from Racket? In Racket, everything is a command, and plain text must be quoted.
6.1.2Any command is valid
There are no undefined commands in Pollen. If a command has not already been defined, it’s treated as a tag function. See ◊ command overview for more.
How is this different from Racket? In Racket, if you try to treat an identifier as a function before defining it with define, you’ll get an error.
6.1.3Standard exports
By default, every Pollen source file exports two symbols, which you can access by using the source file with require:
'doc contains the output of the file. The type of output depends on the source format (documented below).
'metas is a hash of key–value pairs with extra information that is extracted from the source. These 'metas will always contain the key 'here-path, which returns a string representation of the full path to the source file. Beyond that, the only 'metas are the ones that are specified within the source file (see the source formats below for more detail on how to specify metas).
How is this different from Racket? In Racket, you must explicitly define and then provide any values you want to export.
6.1.4Custom exports
Any value or function that is defined within the source file using define is automatically exported.
How is this different from Racket? In Racket, you must explicitly provide any values you want to export. Unlike Racket, every Pollen source file impliedly uses (provide(all-defined-out)).
6.1.5The project-require.rkt file
If a file called project-require.rkt exists in the same directory with a source file, it’s automatically imported when the source file is compiled.
How is this different from Racket? In Racket, you must explicitly import files using require.
6.1.6Preprocessor (.pp extension)
Invoke the preprocessor dialect by using #langpollen/pre as the first line of your source file, or by using #langpollen with a file extension of .pp. These forms are equivalent:
When no dialect is explicitly specified by either the #lang line or the file extension, Pollen will default to using the preprocessor dialect. For instance, this file will be treated as preprocessor source:
Of course, you’re better off specifying the preprocessor dialect explicitly rather than relying on this default behavior.
The output of the preprocessor dialect, provided by 'doc, is plain text.
6.1.7Markdown (.pmd extension)
Invoke the Markdown dialect by using #langpollen/markdown as the first line of your source file, or by using #langpollen with a file extension of .pmd. These forms are equivalent:
The output of the Markdown dialect, provided by 'doc, is a tagged X-expression.
6.1.8Markup (.pm extension)
Invoke the Pollen markup dialect by using #langpollen/markup as the first line of your source file, or by using #langpollen with a file extension of .pm. These forms are equivalent:
The output of the Pollen markup dialect, provided by 'doc, is a tagged X-expression.
6.1.9Pagetree (.ptree extension)
Invoke the pagetree dialect by using #langpollen/ptree as the first line of your source file, or by using #langpollen with a file extension of .ptree. These forms are equivalent:
The output of the pagetree dialect, provided by 'doc, is a pagetree? that is checked for correctness using validate-pagetree.
6.2Utility formats
These aren’t source formats because they don’t contain a #lang pollen line. But for convenience, they get special handling by the Pollen project server.
6.2.1Scribble (.scrbl extension)
Scribble files are recognized by the project server and can be compiled and previewed in single-page mode.
6.2.2Null (.p extension)
Files with the null extension are simply rendered as a copy of the file without the extension, so index.html.p becomes index.html.
This can be useful you’re managing your project with git. Most likely you’ll want to ignore *.html and other file types that are frequently regenerated by the project server. But if you have isolated static files — for instance, a index.html that doesn’t have source associated with it — they’ll be ignored too. You can cure this problem by appending the null extension to these static files, so they’ll be tracked in your source system without actually being source files.
The Pollen language is divided into variants, or dialects, that are tailored to suit each of the core source formats.
These dialects can be invoked one of two ways: either by invoking a specific dialect in the first line of the file (also known as the #lang line), or by using the generic #lang pollen as the first line, and then the correct dialect will be automatically selected based on the source file extension.
If the #lang line specifies a dialect different from the one specified by the file extension, the #lang line will take precedence.
For ease of use, the behavior of the Pollen language departs from the standard Racket language in several ways. The differences are noted below.
7.1.1Command syntax using ◊
Commands must start with the special lozenge character ◊. Other material is interpreted as plain text. See ◊ command overview for more.
How is this different from Racket? In Racket, everything is a command, and plain text must be quoted.
7.1.2Any command is valid
There are no undefined commands in Pollen. If a command has not already been defined, it’s treated as a tag function. See ◊ command overview for more.
How is this different from Racket? In Racket, if you try to treat an identifier as a function before defining it with define, you’ll get an error.
7.1.3Standard exports
By default, every Pollen source file exports two symbols, which you can access by using the source file with require:
'doc contains the output of the file. The type of output depends on the source format (documented below).
'metas is a hash of key–value pairs with extra information that is extracted from the source. These 'metas will always contain the key 'here-path, which returns a string representation of the full path to the source file. Beyond that, the only 'metas are the ones that are specified within the source file (see the source formats below for more detail on how to specify metas).
How is this different from Racket? In Racket, you must explicitly define and then provide any values you want to export.
7.1.4Custom exports
Any value or function that is defined within the source file using define is automatically exported.
How is this different from Racket? In Racket, you must explicitly provide any values you want to export. Unlike Racket, every Pollen source file impliedly uses (provide(all-defined-out)).
7.1.5The project-require.rkt file
If a file called project-require.rkt exists in the same directory with a source file, it’s automatically imported when the source file is compiled.
How is this different from Racket? In Racket, you must explicitly import files using require.
7.1.6Preprocessor (.pp extension)
Invoke the preprocessor dialect by using #langpollen/pre as the first line of your source file, or by using #langpollen with a file extension of .pp. These forms are equivalent:
When no dialect is explicitly specified by either the #lang line or the file extension, Pollen will default to using the preprocessor dialect. For instance, this file will be treated as preprocessor source:
Of course, you’re better off specifying the preprocessor dialect explicitly rather than relying on this default behavior.
The output of the preprocessor dialect, provided by 'doc, is plain text.
7.1.7Markdown (.pmd extension)
Invoke the Markdown dialect by using #langpollen/markdown as the first line of your source file, or by using #langpollen with a file extension of .pmd. These forms are equivalent:
The output of the Markdown dialect, provided by 'doc, is a tagged X-expression.
7.1.8Markup (.pm extension)
Invoke the Pollen markup dialect by using #langpollen/markup as the first line of your source file, or by using #langpollen with a file extension of .pm. These forms are equivalent:
The output of the Pollen markup dialect, provided by 'doc, is a tagged X-expression.
7.1.9Pagetree (.ptree extension)
Invoke the pagetree dialect by using #langpollen/ptree as the first line of your source file, or by using #langpollen with a file extension of .ptree. These forms are equivalent:
The output of the pagetree dialect, provided by 'doc, is a pagetree? that is checked for correctness using validate-pagetree.
7.2Utility formats
These aren’t source formats because they don’t contain a #lang pollen line. But for convenience, they get special handling by the Pollen project server.
7.2.1Scribble (.scrbl extension)
Scribble files are recognized by the project server and can be compiled and previewed in single-page mode.
7.2.2Null (.p extension)
Files with the null extension are simply rendered as a copy of the file without the extension, so index.html.p becomes index.html.
This can be useful you’re managing your project with git. Most likely you’ll want to ignore *.html and other file types that are frequently regenerated by the project server. But if you have isolated static files — for instance, a index.html that doesn’t have source associated with it — they’ll be ignored too. You can cure this problem by appending the null extension to these static files, so they’ll be tracked in your source system without actually being source files.
\ No newline at end of file
diff --git a/doc/First__a_poem.html b/doc/First__a_poem.html
new file mode 100644
index 0000000..4175130
--- /dev/null
+++ b/doc/First__a_poem.html
@@ -0,0 +1,10 @@
+
+5 First, a poem
In this tutorial, you’ll use Pollen to make a single HTML page with a poem. You’ll learn about:
The relationship of Racket & Pollen
DrRacket
The project server
The preprocessor
If you want the shortest possible introduction to Pollen, try the Quick tour.
5.1Prerequisites
I’m going to assume that you’ve already installed Racket and Pollen. If not, do that now.
I’m also going to assume you know the basics of using a command line to run programs and navigate the file system using commands like cd and ls. On Mac OS X, your command-line program is called Terminal; on Windows it’s the Windows Command Processor.
5.2The relationship of Racket & Pollen
As I mentioned in the The big picture, Pollen is built using Racket, and everything in Pollen ultimately becomes Racket code. If you’re comfortable with that idea, you may move along.
But if not, or if you’re just a curious character:
One of the key features of Racket as a programming language is that it provides tools to create other programming languages. These languages might look & behave like Racket. Or they might not. These languages might serve a general purpose, but more often they’re specialized for a particular purpose, in which case they’re known as domain-specific languages, or DSLs.
Racket exploits the fact that under the hood, all programming languages are basically doing the same thing. (CS jocks know this more formally as a side effect of Turing completeness.) Racket starts with the most general expression of a Turing-complete language — called the lambda calculus — and lets users build on that. In most programming languages, you can build functions, classes, and modules. But in Racket, you can alter anything about the language.
If you find this a strange idea, you’re not alone. Most programmers — and until recently, me too — have never made or used DSLs. If you have a programming problem to solve, you start with a general-purpose language like Python or Java or Ruby, and go from there. Nothing wrong with that.
But programming languages contain their own design choices and compromises. Sometimes the problem at hand is best solved by manipulating the language at a deeper level. When you make a DSL, you’re still programming in the underlying language, but doing so at a point of higher leverage.
Pollen is a DSL implemented in Racket. It is a close cousin of Scribble: The Racket Documentation Tool, another Racket DSL, which was designed for writing Racket documentation. The key feature of Scribble, and thus also of Pollen, is that it’s text-based. Meaning, whereas most languages have source files made of code with text embedded within, Pollen’s source files are text with code embedded within.
Moreover, Pollen is meant to be a small step away from Racket — you can think of it as a more convenient notation system for Racket code, similar to how Markdown is a more convenient notation for HTML. But unlike Markdown, which only lets you access a subset of HTML, anything that can be done in Racket can also be done in Pollen.
As you work more with Pollen, you’ll pick up more about how Pollen corresponds to Racket (see ◊ command overview) and easily be able to convert commands from one system to the other. In later tutorials, you’ll see how larger Pollen projects are made out of both Pollen and Racket source files.
But in smaller projects, like this one, you can just use Pollen.
5.3Starting a new file in DrRacket
DrRacket is the IDE for the Racket programming language, and other languages made with Racket (like Pollen). IDE stands for “Integrated Development Environment,” which is a fancy phrase for “a nice place to edit and run your code.” DrRacket is installed as part of the core Racket distribution.
If you’ve worked with languages like Perl, Python, or Ruby, you may be more familiar with using a general-purpose text editor to edit your code, and then running your program at the command line. You can do that with Racket too. But DrRacket is a considerately designed tool. I recommend it. For these tutorials, I’ll assume you’re using DrRacket. If you insist on using the command line, I trust you to figure out what you need to do to keep up.
Launch DrRacket. Start a new file. The code in the file will look like this:
Within the main window, you should also see an interactions window, which shows the output of the current file, and starts out looking something like this (details, like the version number, will vary):
Welcome to DrRacket, version 6.0.1.6--2013-11-26(-/f) [3m].
Language: racket; memory limit: 1000 MB.
>
If you don’t see the interactions window, select View|Show Interactions from the menu.
5.3.1Setting the #lang line
The first line of every Racket source file, and every Pollen source file, is called the #lang line. The #lang line identifies the language used to interpret the rest of the file.
When you start a new Pollen source file in DrRacket, you’ll need to change the #lang line to the Pollen language. The simplest way is to change the first line to this:
Then click Run again. DrRacket will print an error:
Module Language: invalid module text
+ standard-module-name-resolver: collection not found ...
Why? Because there’s no language called pollenxyz. Switch it back to pollen and let’s move on.
5.3.2Putting in the text of the poem
Here’s a short, bad poem I wrote about CSS.
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
Paste the text of this poem into your DrRacket editing window, below the #lang line, so it looks like this:
#lang pollen
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
Run the file again. In the interactions window, you’ll see:
The margin is 8em.
+ The border is blue.
+ The padding is 2em.
+ The border is too.
This shows you something important: by default, any plain text in a Pollen source file is simply printed as written when you Run the file (minus the #lang line, which is just for Racket’s benefit). If you like, edit the text of the poem and click Run again. You’ll see the updated text printed in the interactions window.
5.3.3Saving & naming your source file
File naming in Pollen is consequential.
Ultimately, every Pollen source file in your project will be rendered into an output file. Each Pollen source file corresponds to one output file. The name of this output file will be the name of the source file minus the Pollen source extension. So a source file called file.txt.pp will become file.txt.
Thus, to build the name of a source file, we take the name we want for the output file and add the appropriate Pollen file extension. Different Pollen source files use different extensions — but more about that later. For now, the extension you’ll use for your source is .pp.
In this case, let’s say we want to end up with a file called poem.html. Therefore, the name of our source file needs to be:
the output name poem.html + the source extension .pp = poem.html.pp
(If you want to name the file something-else.html.pp, be my guest. There’s no magic associated with the prefix.)
You’re welcome to change the name of your source files from the desktop. On Mac OS X and Windows, however, the desktop interface often hides file extensions, so check the properties of the file afterward to make sure you got the name you expected.
In a convenient location (e.g., your home directory or the desktop) create a new directory for your project called tutorial. In this new directory, save your DrRacket file as poem.html.pp.
"/path/to/tutorial/poem.html.pp"
#lang pollen
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
5.4Using the project server
The project server is a web server built into Pollen. Just as DrRacket lets you run individual files and see if they work as you expect, the project server lets you preview and test your project as a real website. While working on your Pollen project, you may find it convenient to have DrRacket open on half your screen, and on the other half, a web browser pointing at the project server.
“Why can’t I just open the HTML files directly in my browser?” If you want to keep making web pages the way we did in 1996, go ahead. But that approach has several shortcomings. First, when you open files directly in your browser, you’re cruising the local filesystem, and absolute URLs (the kind that start with a /) won’t work. Second, if you want to test your website on devices other than your own machine — well, you can’t. Third, you have to render your HTML files in advance, whereas the project server is clever about doing this dynamically.
So use the project server.
A note about security. The project server isn’t intended for real-world use, but rather as a development tool. That said, once you start the project server, it’s an actual web server running on your machine, and it will respond to requests from any computer. If you want to limit traffic to your local network, or certain machines on your local network, it’s your job — not mine — to configure your firewall or other network security measures accordingly.
5.4.1Starting the project server with raco pollen
Before we start the project server, a word about the raco pollen command.
When you installed Racket, Racket installed a utility program called raco. This name is short for Racket command, and raco acts as a hub for — you guessed it — Racket commands. You used it when you first installed Pollen:
> raco pkg install pollen
The first argument after raco is the subcommand. For instance, raco pkg ... lets you install, update, and remove packages like so:
> raco pkg update pollen
> raco pkg remove pollen
Likewise, raco pollen lets you issue commands relevant to Pollen, like starting the project server. (See Using raco pollen for a full description of available commands.)
Now we’ll start the project server. Go to your command line and enter the following:
> cd /path/to/tutorial
> raco pollen start
Windows users, I’ll trust you to convert raco into the appropriate command for your system — assuming defaults, it’s likely to be "C:\Program Files\Racket\raco" (include the surrounding quotes in the command).
After a moment, you’ll see a startup message like this:
Welcome to Pollen 0.001 (Racket 6.x.x.x)
Project root is /path/to/tutorial
Project server is http://localhost:8080 (Ctrl-C to exit)
Project dashboard is http://localhost:8080/index.ptree
Ready to rock
Project root means the directory that the project server was started in, and which it’s treating as its root directory. Any absolute URLs (i.e., those beginning with /) will resolve into this directory. So a URL like /styles.css will impliedly become /path/to/tutorial/styles.css.
If you use the bare command raco pollen start, the project server will start in the current directory. But if you want to start the project server elsewhere, you can add that directory as an argument like this:
> raco pollen start /some/other/path
The next line of the startup message tells you that the web address of the project server is http://localhost:8080. This is the address you put into your web browser to test your project. If you’re unfamiliar with this style of URL, localhost refers to your own machine, and 8080 is the network port where the project server will respond to browser requests.
If you want to access the project server from a different machine, you can’t use localhost. But you can use the IP address of the machine running the project server (e.g., http://192.168.1.10:8080) or any name for that machine available through local DNS (e.g., http://mb-laptop:8080).
Though port 8080 is the default, you can start the project server on any port you like by adding it as an argument to raco pollen start:
Note that when you pass a port argument, you also have to pass a path argument. If you want the project server to start in the current directory, you can use the usual . shorthand:
> cd /path/to/tutorial
> raco pollen start 8088
/path/to/tutorial/8088 is not a directory
> raco pollen start . 8088
You can run multiple project servers simultaneously. Just start them on different ports so they don’t conflict with each other.
Your terminal window will report status and error messages from the project server as it runs. Use Ctrl-C to stop the server.
5.4.2Using the dashboard
For each directory in your project, starting at the top, the project server displays a dashboard in your web browser. The dashboard gives you an overview of the files in the directory, and links to view them.
The address of the top-level dashboard is http://localhost:8080/index.ptree. Other dashboards follow the same pattern (e.g., http://localhost:8080/path/to/dir/index.ptree.)
Note that the dashboard is not at http://localhost:8080/ or its equivalent, http://localhost:8080/index.html. Why? So it doesn’t interfere with any index.html that you may want to put in your project.
Thus, index.ptree. The .ptree extension is short for pagetree. In Pollen, a pagetree is a hierarchical list of pages. We’ll do more with pagetrees in a later tutorial. For now, just be aware that to generate the dashboard, the project server will first look for an actual index.ptree file in each directory. If it doesn’t find one, it will generate a pagetree from a listing of files in the directory.
Let’s look at the root-level dashboard for our project. First, make sure your project server is running:
The top line tells us that we’re in the root directory of the project. We didn’t make an explicit index.ptree file, so the project server just shows us a directory listing.
5.4.3Source files in the dashboard
We see the only file, poem.html.pp. Note that the .pp extension is grayed out. The dashboard automatically consolidates references to source and output files into a single entry. What this entry says is “The directory contains a source file in .pp format for the output file poem.html.”
Every source-file entry in the dashboard has three links. The first link is attached to the filename itself, and takes you to a preview of the output file. If the output file doesn’t yet exist — as is the case here — it will be dynamically rendered. (This is true whether you click its name in the dashboard, or link to it from another page.) So click the filename. You’ll see in your web browser:
The margin is 42em. The border is red. The padding is 15em. The border is too.
Granted, this is a boring web page. The main point here is that you’re seeing the output from your source file, which didn’t exist before. Notice that the address bar says http://localhost:8080/poem.html, not poem.html.pp. And if you look in your tutorial directory, you’ll see a new file called poem.html.
In other words, when you clicked on the filename link in the dashboard, Pollen rendered the output file from your source file and saved it in your project directory. As promised earlier, the name of the output file (poem.html) is the name of the source file (poem.html.pp) minus the Pollen extension (.pp).
If you go back to the dashboard and click on the filename link again, you’ll see the same output file. If the source file hasn’t changed, Pollen will just show you the output file that’s already been rendered.
But if you like, open your poem.html.pp source file in DrRacket, edit the first line, and save the file:
#lang pollen
The cave is pitch black.
Look out for the grue.
The padding is 15em.
The border is too.
Go back to the dashboard and click on the filename. This time, you’ll see:
The cave is pitch black. Look out for the grue. The padding is 15em. The border is too.
Here, Pollen notices that the source file has changed, so it refreshes the output file. This makes it convenient to work between DrRacket and your web browser, editing source and then reloading to see the changes.
The other two links in the dashboard are labeled in and out.
The link labeled in will display the contents of the source file:
#lang pollen
The cave is pitch black.
Look out for the grue.
The padding is 15em.
The border is too.
The link labeled out will display the contents of the output file (just like the “view source” option in your web browser):
The cave is pitch black.
Look out for the grue.
The padding is 15em.
The border is too.
For now, the files are identical except for the #lang line. But let’s change that.
5.5Working with the preprocessor
Pollen can operate in several processing modes. One of these is preprocessor mode. A preprocessor is a tool for making systematic, automated changes to a file, often in contemplation of further processing (hence the pre-). You can use the Pollen preprocessor this way. Or you can just use it on its own, and leave your files in a finished state.
That’s how we’ll use it in this tutorial. We’ll build out our poem.html.pp source file so that it exits the preprocessor as a legit HTML file.
5.5.1Setting up a preprocessor source file
The file extension of a Pollen source file tells Pollen what kind of processing to apply to it. The “.pp” file extension stands for “Pollen preprocessor.” You can use the preprocessor with any text-based file by:
+
inserting #lang pollen as the first line,
adding the .pp file extension,
running it through Pollen.
For more about the Pollen processing modes and how to invoke them, see File.
“The preprocessor be used with any kind of text-based file?” Right. “But how?” The preprocessor reads the source file, handles any Pollen commands it finds, and lets the rest of the content pass through untouched. To the preprocessor, it’s all just text data. It doesn’t care whether that text represents HTML, CSS, JavaScript, or even TI-BASIC.
Because the preprocessor only deals in text, the Pollen commands you use in the preprocessor also have to produce text. Moreover, Pollen doesn’t enforce the semantics of the underlying file — that’s your responsibility. For instance, Pollen won’t stop you from doing nonsensical things like this:
"bad-poem.html.pp"
#lang pollen
The cave is pitch black.
Look out for the grue.
◊(insert-mp3-recording-of-scream)
Here, the result is not going to be valid HTML, because you can’t simply drop binary data in the middle of an HTML file. To paraphrase Mr. Babbage — garbage in, garbage out.
I’ve encouraged you to mess with the source file, but let’s return it to its original state:
"/path/to/tutorial/poem.html.pp"
#lang pollen
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
This file has #lang pollen as the first line, and .pp as the file extension, so it meets the minimum requirements for the preprocessor.
5.5.2Creating valid HTML output
Let’s update our source so it produces valid HTML. Edit the source as follows:
The margin is 42em. The border is red. The padding is 15em. The border is too.
But now, because of the <pre> tag, the poem will appear in a monospaced font, and the line breaks will be preserved:
The margin is 42em.
+ The border is red.
+ The padding is 15em.
+ The border is too.
As before, because the source has changed, Pollen refreshes the output file. From the dashboard, you can use the in and out links to inspect the source and output.
This is now a valid HTML page.
5.5.3Adding commands
I mentioned that the preprocessor reads the file and handles any Pollen commands it finds. But our source file doesn’t have any commands yet. Let’s add some.
Pollen commands can be embedded in your source file using one of two modes: Racket mode or text mode. We’ll try text mode in a later tutorial. For now, we’ll use Racket mode.
To make a Racket-mode Pollen command, just take any Racket expression and put the lozenge character (◊) in front of it. For instance, these are valid Racket expressions:
(define inner 2)
(define edge (* inner 4))
(define color "blue")
And these are the equivalent commands in Pollen:
◊(define inner 2)
◊(define edge (* inner 4))
◊(define color "blue")
5.5.4Racket basics (if you’re not familiar)
“But how am I supposed to know Racket?” You don’t. So we’ll start now. Here are the five basic rules of Racket:
The core building block of Racket is the expression. An expression can be a value (like 2 or "blue"), a variable (like edge), or a function call (like (*inner4)).
Every expression is evaluated to produce a value.
A variable evaluates to whatever value it holds (so inner would become 2). A function call evaluates to its return value (so (+11) would become 2).
Function calls go between parentheses. Unlike most languages, the function name comes first, followed by its arguments (so it’s (*inner4), not (inner*4)). This is called prefix notation.
Expressions can contain recursively nested expressions. Thus, (*inner4) could be written (*inner(+22)) or (*inner(+(+11)(+11))).
Newcomers to Racket often gripe about prefix notation and the parentheses. If you need to get it out of your system, go ahead. Keep in mind, however, that it’s not some peculiar affectation, but rather a necessary consequence of rule #1. As you’ll come to learn, rule #1 is where the magic happens.
That should tell you enough to infer what’s going on in the Pollen commands above:
◊(define inner 2)
◊; create a variable 'inner' that holds the value 2
◊(define edge (* inner 4))
◊; create a variable 'edge' that's four times the value of 'inner'
◊(define color "blue")
◊; create a variable 'color' that holds the value "blue"
Let’s use commands to define variables that will hold some values for our page. First, add a <head> tag to your source file, and three commmands to define three variables:
"/path/to/tutorial/poem.html.pp"
#lang pollen
<!DOCTYPE html>
<html>
<head>
◊(define inner 2)
◊(define edge (* inner 4))
◊(define color "blue")
</head>
<body>
<pre>
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
</pre>
</body>
</html>
Then look at http://localhost:8080/poem.html again. Does it look the same? Not a trick question — it should. If you click the Out link on the dashboard, you’ll see this:
<!DOCTYPE html>
<html>
<head>
</head>
<body>
<pre>
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
</pre>
</body>
</html>
What’s happening here? Our ◊(define ...) commands just define variables, so they don’t evaluate to any value. Instead, we get blank lines. So far, so good.
5.5.6Inserting values from variables
To insert the value of a variable in our file, we use the command ◊|variable-name|. Let’s do that now:
"/path/to/tutorial/poem.html.pp"
#lang pollen
<!DOCTYPE html>
<html>
<head>
◊(define inner 2)
◊(define edge (* inner 4))
◊(define color "blue")
</head>
<body>
<pre>
The margin is ◊|edge|em.
The border is ◊|color|.
The padding is ◊|inner|em.
The border is too.
</pre>
</body>
</html>
Here, we’re replacing three values in the poem with the variables containing those values — ◊|edge|, ◊|color|, and ◊|inner|. Reload the file in the project server, and you’ll see:
The margin is 8em.
The border is blue.
The padding is 2em.
The border is too.
Hey, look at that — the text of the poem changed. Now it even rhymes.
If you like, in the source file, edit the variable definitions with different values and reload the page in the project server. The page will be rendered afresh with the new values. In particular, if you update inner, you’ll also see edge change, since its value depends on inner.
5.5.7Inserting variables within CSS
Our poem makes claims about the margin, border, and padding of the page that aren’t yet true. To fix this, we’ll rely on the same basic technique of inserting variables into our HTML file. But instead of putting them in the <body> of the page, we’ll put them in a CSS <style> tag.
Update the <head> section of the page with a new <style> tag that defines a style for pre like so, using our variables for the relevant values:
"/path/to/tutorial/poem.html.pp"
#lang pollen
<!DOCTYPE html>
<html>
<head>
◊(define inner 2)
◊(define edge (* inner 4))
◊(define color "blue")
<style type="text/css">
pre {
margin: ◊|edge|em;
border: ◊|inner|em solid ◊|color|;
padding: ◊|inner|em;
}
</style>
</head>
<body>
<pre>
The margin is ◊|edge|em.
The border is ◊|color|.
The padding is ◊|inner|em.
The border is too.
</pre>
</body>
</html>
Notice that we’re using the same ◊|variable-name| pattern as before to insert the variable values.
What do we expect to see? We expect that the padding and border will be 2em wide, because inner is 2. We expect the margin to be 8em, because it’s equal to edge, which is inner multiplied by 4. And we expect the color of the border to be "blue", because that’s the value of the variable color.
And indeed, when you reload the file in the project server, you’ll see exactly that:
As before, if you edit the values of the variables in the source file and reload in the project server, you’ll see both the text and the layout change.
5.6First tutorial complete
This was a sneaky tutorial. The HTML page we made was very simple, but in building it, we covered many important points about how Pollen works.
Feel free to go back and experiment with what you’ve learned. The next tutorial will assume that you’re comfortable with all the material here.
\ No newline at end of file
diff --git a/doc/First_tutorial.html b/doc/First_tutorial.html
new file mode 100644
index 0000000..bc457e4
--- /dev/null
+++ b/doc/First_tutorial.html
@@ -0,0 +1,10 @@
+
+5 First tutorial
In this tutorial, you’ll use Pollen to make a single HTML page with a poem. You’ll learn about:
The relationship of Racket & Pollen
DrRacket
The project server
The preprocessor
If you want the shortest possible introduction to Pollen, try the Quick tour.
5.1Prerequisites
I’m going to assume that you’ve already installed Racket and Pollen. If not, do that now.
I’m also going to assume you know the basics of using a command line to run programs and navigate the file system using commands like cd and ls. On Mac OS X, your command-line program is called Terminal; on Windows it’s the Windows Command Processor.
5.2The relationship of Racket & Pollen
As I mentioned in the The big picture, Pollen is built using Racket, and everything in Pollen ultimately becomes Racket code. If you’re comfortable with that idea, you may move along.
But if not, or if you’re just a curious character:
One of the key features of Racket as a programming language is that it provides tools to create other programming languages. These languages might look & behave like Racket. Or they might not. These languages might serve a general purpose, but more often they’re specialized for a particular purpose, in which case they’re known as domain-specific languages, or DSLs.
Racket exploits the fact that under the hood, all programming languages are basically doing the same thing. (CS jocks know this more formally as a side effect of Turing completeness.) Racket starts with the most general expression of a Turing-complete language — called the lambda calculus — and lets users build on that. In most programming languages, you can build functions, classes, and modules. But in Racket, you can alter anything about the language.
If you find this a strange idea, you’re not alone. Most programmers — and until recently, me too — have never made or used DSLs. If you have a programming problem to solve, you start with a general-purpose language like Python or Java or Ruby, and go from there. Nothing wrong with that.
But programming languages contain their own design choices and compromises. Sometimes the problem at hand is best solved by manipulating the language at a deeper level. When you make a DSL, you’re still programming in the underlying language, but doing so at a point of higher leverage.
Pollen is a DSL implemented in Racket. It is a close cousin of Scribble: The Racket Documentation Tool, another Racket DSL, which was designed for writing Racket documentation. The key feature of Scribble, and thus also of Pollen, is that it’s text-based. Meaning, whereas most languages have source files made of code with text embedded within, Pollen’s source files are text with code embedded within.
Moreover, Pollen is meant to be a small step away from Racket — you can think of it as a more convenient notation system for Racket code, similar to how Markdown is a more convenient notation for HTML. But unlike Markdown, which only lets you access a subset of HTML, anything that can be done in Racket can also be done in Pollen.
As you work more with Pollen, you’ll pick up more about how Pollen corresponds to Racket (see ◊ command overview) and easily be able to convert commands from one system to the other. In later tutorials, you’ll see how larger Pollen projects are made out of both Pollen and Racket source files.
But in smaller projects, like this one, you can just use Pollen.
5.3Starting a new file in DrRacket
DrRacket is the IDE for the Racket programming language, and other languages made with Racket (like Pollen). IDE stands for “Integrated Development Environment,” which is a fancy phrase for “a nice place to edit and run your code.” DrRacket is installed as part of the core Racket distribution.
If you’ve worked with languages like Perl, Python, or Ruby, you may be more familiar with using a general-purpose text editor to edit your code, and then running your program at the command line. You can do that with Racket too. But DrRacket is a considerately designed tool. I recommend it. For these tutorials, I’ll assume you’re using DrRacket. If you insist on using the command line, I trust you to figure out what you need to do to keep up.
Launch DrRacket. Start a new file. The code in the file will look like this:
Within the main window, you should also see an interactions window, which shows the output of the current file, and starts out looking something like this (details, like the version number, will vary):
Welcome to DrRacket, version 6.0.1.6--2013-11-26(-/f) [3m].
Language: racket; memory limit: 1000 MB.
>
If you don’t see the interactions window, select View|Show Interactions from the menu.
5.3.1Setting the #lang line
The first line of every Racket source file, and every Pollen source file, is called the #lang line. The #lang line identifies the language used to interpret the rest of the file.
When you start a new Pollen source file in DrRacket, you’ll need to change the #lang line to the Pollen language. The simplest way is to change the first line to this:
Now run your file by clicking the Run button in the upper-right corner, or select Racket|Run from the menu. You’ll get something like:
Welcome to DrRacket, version 6.0.1.6--2013-11-26(-/f) [3m].
Language: pollen; memory limit: 1000 MB.
>
Notice that the language is now reported as pollen. If you like, change the #lang line to this:
#lang pollenxyz
Then click Run again. DrRacket will print an error:
Module Language: invalid module text
+ standard-module-name-resolver: collection not found ...
Why? Because there’s no language called pollenxyz. Switch it back to pollen and let’s move on.
5.3.2Putting in the text of the poem
Here’s a short, bad poem I wrote about CSS.
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
Paste the text of this poem into your DrRacket editing window, below the #lang line, so it looks like this:
#lang pollen
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
Run the file again. In the interactions window, you’ll see:
The margin is 8em.
+ The border is blue.
+ The padding is 2em.
+ The border is too.
This shows you something important: by default, any plain text in a Pollen source file is simply printed as written when you Run the file (minus the #lang line, which is just for Racket’s benefit). If you like, edit the text of the poem and click Run again. You’ll see the updated text printed in the interactions window.
5.3.3Saving & naming your source file
File naming in Pollen is consequential.
Ultimately, every Pollen source file in your project will be rendered into an output file. Each Pollen source file corresponds to one output file. The name of this output file will be the name of the source file minus the Pollen source extension. So a source file called file.txt.pp will become file.txt.
Thus, to build the name of a source file, we take the name we want for the output file and add the appropriate Pollen file extension. Different Pollen source files use different extensions — but more about that later. For now, the extension you’ll use for your source is .pp.
In this case, let’s say we want to end up with a file called poem.html. Therefore, the name of our source file needs to be:
the output name poem.html + the source extension .pp = poem.html.pp
(If you want to name the file something-else.html.pp, be my guest. There’s no magic associated with the prefix.)
You’re welcome to change the name of your source files from the desktop. On Mac OS X and Windows, however, the desktop interface often hides file extensions, so check the properties of the file afterward to make sure you got the name you expected.
In a convenient location (e.g., your home directory or the desktop) create a new directory for your project called tutorial. In this new directory, save your DrRacket file as poem.html.pp.
"/path/to/tutorial/poem.html.pp"
#lang pollen
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
5.4Using the project server
The project server is a web server built into Pollen. Just as DrRacket lets you run individual files and see if they work as you expect, the project server lets you preview and test your project as a real website. While working on your Pollen project, you may find it convenient to have DrRacket open on half your screen, and on the other half, a web browser pointing at the project server.
“Why can’t I just open the HTML files directly in my browser?” If you want to keep making web pages the way we did in 1996, go ahead. But that approach has several shortcomings. First, when you open files directly in your browser, you’re cruising the local filesystem, and absolute URLs (the kind that start with a /) won’t work. Second, if you want to test your website on devices other than your own machine — well, you can’t. Third, you have to render your HTML files in advance, whereas the project server is clever about doing this dynamically.
So use the project server.
A note about security. The project server isn’t intended for real-world use, but rather as a development tool. That said, once you start the project server, it’s an actual web server running on your machine, and it will respond to requests from any computer. If you want to limit traffic to your local network, or certain machines on your local network, it’s your job — not mine — to configure your firewall or other network security measures accordingly.
5.4.1Starting the project server with raco pollen
Before we start the project server, a word about the raco pollen command.
When you installed Racket, Racket installed a utility program called raco. This name is short for Racket command, and raco acts as a hub for — you guessed it — Racket commands. You used it when you first installed Pollen:
> raco pkg install pollen
The first argument after raco is the subcommand. For instance, raco pkg ... lets you install, update, and remove packages like so:
> raco pkg update pollen
> raco pkg remove pollen
Likewise, raco pollen lets you issue commands relevant to Pollen, like starting the project server. (See Using raco pollen for a full description of available commands.)
Now we’ll start the project server. Go to your command line and enter the following:
> cd /path/to/tutorial
> raco pollen start
Windows users, I’ll trust you to convert raco into the appropriate command for your system — assuming defaults, it’s likely to be "C:\Program Files\Racket\raco" (include the surrounding quotes in the command).
After a moment, you’ll see a startup message like this:
Welcome to Pollen 0.001 (Racket 6.x.x.x)
Project root is /path/to/tutorial
Project server is http://localhost:8080 (Ctrl-C to exit)
Project dashboard is http://localhost:8080/index.ptree
Ready to rock
Project root means the directory that the project server was started in, and which it’s treating as its root directory. Any absolute URLs (i.e., those beginning with /) will resolve into this directory. So a URL like /styles.css will impliedly become /path/to/tutorial/styles.css.
If you use the bare command raco pollen start, the project server will start in the current directory. But if you want to start the project server elsewhere, you can add that directory as an argument like this:
> raco pollen start /some/other/path
The next line of the startup message tells you that the web address of the project server is http://localhost:8080. This is the address you put into your web browser to test your project. If you’re unfamiliar with this style of URL, localhost refers to your own machine, and 8080 is the network port where the project server will respond to browser requests.
If you want to access the project server from a different machine, you can’t use localhost. But you can use the IP address of the machine running the project server (e.g., http://192.168.1.10:8080) or any name for that machine available through local DNS (e.g., http://mb-laptop:8080).
Though port 8080 is the default, you can start the project server on any port you like by adding it as an argument to raco pollen start:
Note that when you pass a port argument, you also have to pass a path argument. If you want the project server to start in the current directory, you can use the usual . shorthand:
> cd /path/to/tutorial
> raco pollen start 8088
/path/to/tutorial/8088 is not a directory
> raco pollen start . 8088
You can run multiple project servers simultaneously. Just start them on different ports so they don’t conflict with each other.
Your terminal window will report status and error messages from the project server as it runs. Use Ctrl-C to stop the server.
5.4.2Using the dashboard
For each directory in your project, starting at the top, the project server displays a dashboard in your web browser. The dashboard gives you an overview of the files in the directory, and links to view them.
The address of the top-level dashboard is http://localhost:8080/index.ptree. Other dashboards follow the same pattern (e.g., http://localhost:8080/path/to/dir/index.ptree.)
Note that the dashboard is not at http://localhost:8080/ or its equivalent, http://localhost:8080/index.html. Why? So it doesn’t interfere with any index.html that you may want to put in your project.
Thus, index.ptree. The .ptree extension is short for pagetree. In Pollen, a pagetree is a hierarchical list of pages. We’ll do more with pagetrees in a later tutorial. For now, just be aware that to generate the dashboard, the project server will first look for an actual index.ptree file in each directory. If it doesn’t find one, it will generate a pagetree from a listing of files in the directory.
Let’s look at the root-level dashboard for our project. First, make sure your project server is running:
The top line tells us that we’re in the root directory of the project. We didn’t make an explicit index.ptree file, so the project server just shows us a directory listing.
5.4.3Source files in the dashboard
We see the only file, poem.html.pp. Note that the .pp extension is grayed out. The dashboard automatically consolidates references to source and output files into a single entry. What this entry says is “The directory contains a source file in .pp format for the output file poem.html.”
Every source-file entry in the dashboard has three links. The first link is attached to the filename itself, and takes you to a preview of the output file. If the output file doesn’t yet exist — as is the case here — it will be dynamically rendered. (This is true whether you click its name in the dashboard, or link to it from another page.) So click the filename. You’ll see in your web browser:
The margin is 42em. The border is red. The padding is 15em. The border is too.
Granted, this is a boring web page. The main point here is that you’re seeing the output from your source file, which didn’t exist before. Notice that the address bar says http://localhost:8080/poem.html, not poem.html.pp. And if you look in your tutorial directory, you’ll see a new file called poem.html.
In other words, when you clicked on the filename link in the dashboard, Pollen rendered the output file from your source file and saved it in your project directory. As promised earlier, the name of the output file (poem.html) is the name of the source file (poem.html.pp) minus the Pollen extension (.pp).
If you go back to the dashboard and click on the filename link again, you’ll see the same output file. If the source file hasn’t changed, Pollen will just show you the output file that’s already been rendered.
But if you like, open your poem.html.pp source file in DrRacket, edit the first line, and save the file:
#lang pollen
The cave is pitch black.
Look out for the grue.
The padding is 15em.
The border is too.
Go back to the dashboard and click on the filename. This time, you’ll see:
The cave is pitch black. Look out for the grue. The padding is 15em. The border is too.
Here, Pollen notices that the source file has changed, so it refreshes the output file. This makes it convenient to work between DrRacket and your web browser, editing source and then reloading to see the changes.
The other two links in the dashboard are labeled in and out.
The link labeled in will display the contents of the source file:
#lang pollen
The cave is pitch black.
Look out for the grue.
The padding is 15em.
The border is too.
The link labeled out will display the contents of the output file (just like the “view source” option in your web browser):
The cave is pitch black.
Look out for the grue.
The padding is 15em.
The border is too.
For now, the files are identical except for the #lang line. But let’s change that.
5.5Working with the preprocessor
Pollen can operate in several processing modes. One of these is preprocessor mode. A preprocessor is a tool for making systematic, automated changes to a file, often in contemplation of further processing (hence the pre-). You can use the Pollen preprocessor this way. Or you can just use it on its own, and leave your files in a finished state.
That’s how we’ll use it in this tutorial. We’ll build out our poem.html.pp source file so that it exits the preprocessor as a legit HTML file.
5.5.1Setting up a preprocessor source file
The file extension of a Pollen source file tells Pollen what kind of processing to apply to it. The “.pp” file extension stands for “Pollen preprocessor.” You can use the preprocessor with any text-based file by:
+
inserting #lang pollen as the first line,
adding the .pp file extension,
running it through Pollen.
For more about the Pollen processing modes and how to invoke them, see File.
“The preprocessor be used with any kind of text-based file?” Right. “But how?” The preprocessor reads the source file, handles any Pollen commands it finds, and lets the rest of the content pass through untouched. To the preprocessor, it’s all just text data. It doesn’t care whether that text represents HTML, CSS, JavaScript, or even TI-BASIC.
Because the preprocessor only deals in text, the Pollen commands you use in the preprocessor also have to produce text. Moreover, Pollen doesn’t enforce the semantics of the underlying file — that’s your responsibility. For instance, Pollen won’t stop you from doing nonsensical things like this:
"bad-poem.html.pp"
#lang pollen
The cave is pitch black.
Look out for the grue.
◊(insert-mp3-recording-of-scream)
Here, the result is not going to be valid HTML, because you can’t simply drop binary data in the middle of an HTML file. To paraphrase Mr. Babbage — garbage in, garbage out.
I’ve encouraged you to mess with the source file, but let’s return it to its original state:
"/path/to/tutorial/poem.html.pp"
#lang pollen
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
This file has #lang pollen as the first line, and .pp as the file extension, so it meets the minimum requirements for the preprocessor.
5.5.2Creating valid HTML output
Let’s update our source so it produces valid HTML. Edit the source as follows:
The margin is 42em. The border is red. The padding is 15em. The border is too.
But now, because of the <pre> tag, the poem will appear in a monospaced font, and the line breaks will be preserved:
The margin is 42em.
+ The border is red.
+ The padding is 15em.
+ The border is too.
As before, because the source has changed, Pollen refreshes the output file. From the dashboard, you can use the in and out links to inspect the source and output.
This is now a valid HTML page.
5.5.3Adding commands
I mentioned that the preprocessor reads the file and handles any Pollen commands it finds. But our source file doesn’t have any commands yet. Let’s add some.
Pollen commands can be embedded in your source file using one of two modes: Racket mode or text mode. We’ll try text mode in a later tutorial. For now, we’ll use Racket mode.
To make a Racket-mode Pollen command, just take any Racket expression and put the lozenge character (◊) in front of it. For instance, these are valid Racket expressions:
(define inner 2)
(define edge (* inner 4))
(define color "blue")
And these are the equivalent commands in Pollen:
◊(define inner 2)
◊(define edge (* inner 4))
◊(define color "blue")
5.5.4Racket basics (if you’re not familiar)
“But how am I supposed to know Racket?” You don’t. So we’ll start now. Here are the five basic rules of Racket:
The core building block of Racket is the expression. An expression can be a value (like 2 or "blue"), a variable (like edge), or a function call (like (*inner4)).
Every expression is evaluated to produce a value.
A variable evaluates to whatever value it holds (so inner would become 2). A function call evaluates to its return value (so (+11) would become 2).
Function calls go between parentheses. Unlike most languages, the function name comes first, followed by its arguments (so it’s (*inner4), not (inner*4)). This is called prefix notation.
Expressions can contain recursively nested expressions. Thus, (*inner4) could be written (*inner(+22)) or (*inner(+(+11)(+11))).
Newcomers to Racket often gripe about prefix notation and the parentheses. If you need to get it out of your system, go ahead. Keep in mind, however, that it’s not some peculiar affectation, but rather a necessary consequence of rule #1. As you’ll come to learn, rule #1 is where the magic happens.
That should tell you enough to infer what’s going on in the Pollen commands above:
◊(define inner 2)
◊; create a variable 'inner' that holds the value 2
◊(define edge (* inner 4))
◊; create a variable 'edge' that's four times the value of 'inner'
◊(define color "blue")
◊; create a variable 'color' that holds the value "blue"
Let’s use commands to define variables that will hold some values for our page. First, add a <head> tag to your source file, and three commmands to define three variables:
"/path/to/tutorial/poem.html.pp"
#lang pollen
<!DOCTYPE html>
<html>
<head>
◊(define inner 2)
◊(define edge (* inner 4))
◊(define color "blue")
</head>
<body>
<pre>
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
</pre>
</body>
</html>
Then look at http://localhost:8080/poem.html again. Does it look the same? Not a trick question — it should. If you click the Out link on the dashboard, you’ll see this:
<!DOCTYPE html>
<html>
<head>
</head>
<body>
<pre>
The margin is 42em.
The border is red.
The padding is 15em.
The border is too.
</pre>
</body>
</html>
What’s happening here? Our ◊(define ...) commands just define variables, so they don’t evaluate to any value. Instead, we get blank lines. So far, so good.
5.5.6Inserting values from variables
To insert the value of a variable in our file, we use the command ◊|variable-name|. Let’s do that now:
"/path/to/tutorial/poem.html.pp"
#lang pollen
<!DOCTYPE html>
<html>
<head>
◊(define inner 2)
◊(define edge (* inner 4))
◊(define color "blue")
</head>
<body>
<pre>
The margin is ◊|edge|em.
The border is ◊|color|.
The padding is ◊|inner|em.
The border is too.
</pre>
</body>
</html>
Here, we’re replacing three values in the poem with the variables containing those values — ◊|edge|, ◊|color|, and ◊|inner|. Reload the file in the project server, and you’ll see:
The margin is 8em.
The border is blue.
The padding is 2em.
The border is too.
Hey, look at that — the text of the poem changed. Now it even rhymes.
If you like, in the source file, edit the variable definitions with different values and reload the page in the project server. The page will be rendered afresh with the new values. In particular, if you update inner, you’ll also see edge change, since its value depends on inner.
5.5.7Inserting variables within CSS
Our poem makes claims about the margin, border, and padding of the page that aren’t yet true. To fix this, we’ll rely on the same basic technique of inserting variables into our HTML file. But instead of putting them in the <body> of the page, we’ll put them in a CSS <style> tag.
Update the <head> section of the page with a new <style> tag that defines a style for pre like so, using our variables for the relevant values:
"/path/to/tutorial/poem.html.pp"
#lang pollen
<!DOCTYPE html>
<html>
<head>
◊(define inner 2)
◊(define edge (* inner 4))
◊(define color "blue")
<style type="text/css">
pre {
margin: ◊|edge|em;
border: ◊|inner|em solid ◊|color|;
padding: ◊|inner|em;
}
</style>
</head>
<body>
<pre>
The margin is ◊|edge|em.
The border is ◊|color|.
The padding is ◊|inner|em.
The border is too.
</pre>
</body>
</html>
Notice that we’re using the same ◊|variable-name| pattern as before to insert the variable values.
What do we expect to see? We expect that the padding and border will be 2em wide, because inner is 2. We expect the margin to be 8em, because it’s equal to edge, which is inner multiplied by 4. And we expect the color of the border to be "blue", because that’s the value of the variable color.
And indeed, when you reload the file in the project server, you’ll see exactly that:
As before, if you edit the values of the variables in the source file and reload in the project server, you’ll see both the text and the layout change.
5.6First tutorial complete
This was a sneaky tutorial. The HTML page we made was very simple, but in building it, we covered many important points about how Pollen works.
Feel free to go back and experiment with what you’ve learned. The next tutorial will assume that you’re comfortable with all the material here.
\ No newline at end of file
diff --git a/doc/Installation.html b/doc/Installation.html
index 231b26a..231352a 100644
--- a/doc/Installation.html
+++ b/doc/Installation.html
@@ -1,4 +1,4 @@
-1 Installation
\ No newline at end of file
diff --git a/doc/Module_reference.html b/doc/Module_reference.html
index e5bfa04..d054df2 100644
--- a/doc/Module_reference.html
+++ b/doc/Module_reference.html
@@ -1,2 +1,2 @@
-8 Module reference
\ No newline at end of file
diff --git a/doc/Pagetree.html b/doc/Pagetree.html
index 82c89e6..d59fd16 100644
--- a/doc/Pagetree.html
+++ b/doc/Pagetree.html
@@ -1,2 +1,2 @@
-8.4 Pagetree
A pagetree is a hierarchical list of Pollen output files. A pagetree source file has the extension .ptree. A pagetree provides a convenient way of separating the structure of the pages from the page sources, and navigating around this structure.
Pagetrees are made of pagenodes. Usually these pagenodes will be names of output files in your project. (If you think it would’ve been more logical to just call them “pages,” perhaps. When I think of a web page, I think of a file on a disk. Whereas pagenodes may — and often do — refer to files that don’t yet exist.)
Books and other long documents are usually organized in a structured way — at minimum they have a sequence of pages, but more often they have sections with subsequences within. Individual Pollen source files don’t know anything about how they’re connected to other files. In theory, you could maintain this information within each source file. This would be a poor use of human energy. Let the pagetree figure it out.
Test whether possible-pagetree is a valid pagetree. It must be a txexpr? where all elements are pagenode?, and each is unique within possible-pagetree (not counting the root node).
Test whether possible-pagenode is a valid pagenode. A pagenode can be any symbol? that is not whitespace/nbsp? Every leaf of a pagetree is a pagenode. In practice, your pagenodes will likely be names of output files.
Pagenodes are symbols (rather than strings) so that pagetrees will be valid tagged X-expressions, which is a more convenient format for validation & processing.
A parameter that defines the default pagetree used by pagetree navigation functions (e.g., parent-pagenode, chidren, et al.) if another is not explicitly specified. Initialized to #f.
Return the pagenode immediately before p. For previous*, return all the pagenodes before p, in sequence. In both cases, return #f if there aren’t any pagenodes. The root pagenode is ignored.
Return the pagenode immediately after p. For next*, return all the pagenodes after p, in sequence. In both cases, return #f if there aren’t any pagenodes. The root pagenode is ignored.
Convert path p to a pagenode — meaning, make it relative to current-project-root, run it through ->output-path, and convert it to a symbol. Does not tell you whether the resultant pagenode actually exists in the current pagetree (for that, use in-pagetree?).
A pagetree is a hierarchical list of Pollen output files. A pagetree source file has the extension .ptree. A pagetree provides a convenient way of separating the structure of the pages from the page sources, and navigating around this structure.
Pagetrees are made of pagenodes. Usually these pagenodes will be names of output files in your project. (If you think it would’ve been more logical to just call them “pages,” perhaps. When I think of a web page, I think of a file on a disk. Whereas pagenodes may — and often do — refer to files that don’t yet exist.)
Books and other long documents are usually organized in a structured way — at minimum they have a sequence of pages, but more often they have sections with subsequences within. Individual Pollen source files don’t know anything about how they’re connected to other files. In theory, you could maintain this information within each source file. This would be a poor use of human energy. Let the pagetree figure it out.
Test whether possible-pagetree is a valid pagetree. It must be a txexpr? where all elements are pagenode?, and each is unique within possible-pagetree (not counting the root node).
Test whether possible-pagenode is a valid pagenode. A pagenode can be any symbol? that is not whitespace/nbsp? Every leaf of a pagetree is a pagenode. In practice, your pagenodes will likely be names of output files.
Pagenodes are symbols (rather than strings) so that pagetrees will be valid tagged X-expressions, which is a more convenient format for validation & processing.
A parameter that defines the default pagetree used by pagetree navigation functions (e.g., parent-pagenode, chidren, et al.) if another is not explicitly specified. Initialized to #f.
Return the pagenode immediately before p. For previous*, return all the pagenodes before p, in sequence. In both cases, return #f if there aren’t any pagenodes. The root pagenode is ignored.
Return the pagenode immediately after p. For next*, return all the pagenodes after p, in sequence. In both cases, return #f if there aren’t any pagenodes. The root pagenode is ignored.
Convert path p to a pagenode — meaning, make it relative to current-project-root, run it through ->output-path, and convert it to a symbol. Does not tell you whether the resultant pagenode actually exists in the current pagetree (for that, use in-pagetree?).
\ No newline at end of file
diff --git a/doc/Render.html b/doc/Render.html
index 1cb2c0c..bbd3e06 100644
--- a/doc/Render.html
+++ b/doc/Render.html
@@ -1,4 +1,4 @@
-8.5 Render
Renders source-path. The rendering behavior depends on the type of source file:
A [pollen/pre] file is rendered without a template.
A [pollen/markup] or [pollen/markdown] file is rendered with a template. If no template is provided with template-path, Pollen finds one using get-template-for.
Be aware that rendering with a template uses include-template within eval. For complex pages, it can be slow the first time. Caching is used to make subsequent requests faster.
For those panicked at the use of eval, please don’t be. As the author of include-template has already advised, “If you insist on dynamicism” — and yes, I do insist — “there is always eval.”
Like render, but saves the file to output-path, overwriting whatever was already there. If no output-path is provided, it’s derived from source-path using ->output-path.
Renders source-path. The rendering behavior depends on the type of source file:
A [pollen/pre] file is rendered without a template.
A [pollen/markup] or [pollen/markdown] file is rendered with a template. If no template is provided with template-path, Pollen finds one using get-template-for.
Be aware that rendering with a template uses include-template within eval. For complex pages, it can be slow the first time. Caching is used to make subsequent requests faster.
For those panicked at the use of eval, please don’t be. As the author of include-template has already advised, “If you insist on dynamicism” — and yes, I do insist — “there is always eval.”
Like render, but saves the file to output-path, overwriting whatever was already there. If no output-path is provided, it’s derived from source-path using ->output-path.
Render multiple source-paths in one go. This can be faster than (for-eachrendersource-paths) if your source-paths rely on a common set of templates. Templates may have their own source files that need to be compiled. If you use render, the templates will be repeatedly (and needlessly) re-compiled. Whereas if you use render-batch, each template will only be compiled once.
Find a template file for source-path, with the following priority:
-
If the metas for source-path have a key for template, then use the value of this key.
If this key doesn’t exist, or if it points to a nonexistent file, look for a default template in the project directory with the name template.[outputextension].pt. Meaning, if source-path is intro.html.pm, the output path would be intro.html, so the default template would be template.html.pt.
If this file doesn’t exist, use the fallback template as a last resort.
This function is called when a template is needed, but a template-path argument is missing (for instance, in render or render-to-file).
If the metas for source-path have a key for template, then use the value of this key.
If this key doesn’t exist, or if it points to a nonexistent file, look for a default template in the project directory with the name template.[outputextension].pt. Meaning, if source-path is intro.html.pm, the output path would be intro.html, so the default template would be template.html.pt.
If this file doesn’t exist, use the fallback template as a last resort.
This function is called when a template is needed, but a template-path argument is missing (for instance, in render or render-to-file).
\ No newline at end of file
diff --git a/doc/Tag.html b/doc/Tag.html
index d4270a7..58ba169 100644
--- a/doc/Tag.html
+++ b/doc/Tag.html
@@ -1,2 +1,2 @@
-8.7 Tag
Make a tag function for id. As arguments, a tag function takes an optional set of X-expression attributes (txexpr-attrs?) followed by X-expression elements (txexpr-elements?). From these, the tag function creates a tagged X-expression using id as the tag.
Entering attributes this way can be cumbersome. So for convenience, a tag function provides an alternative: any symbol + string pairs at the front of your expression will be interpreted as attributes, if the symbols are followed by a colon. If you leave out the colon, the symbols will be interpreted as part of the content of the tag.
Make a tag function for id. As arguments, a tag function takes an optional set of X-expression attributes (txexpr-attrs?) followed by X-expression elements (txexpr-elements?). From these, the tag function creates a tagged X-expression using id as the tag.
Entering attributes this way can be cumbersome. So for convenience, a tag function provides an alternative: any symbol + string pairs at the front of your expression will be interpreted as attributes, if the symbols are followed by a colon. If you leave out the colon, the symbols will be interpreted as part of the content of the tag.
\ No newline at end of file
diff --git a/doc/Template.html b/doc/Template.html
index 01f3748..8d18106 100644
--- a/doc/Template.html
+++ b/doc/Template.html
@@ -1,2 +1,2 @@
-8.6 Template
Convert xexpr to an HTML string. Similar to xexpr->string, but consistent with the HTML spec, text that appears within script or style blocks will not be escaped.
"<root><script>3 > 2</script>Why is 3 > 2?</root>"
> (->htmltx)
"<root><script>3 > 2</script>Why is 3 > 2?</root>"
Be careful not to pass existing HTML strings into this function, because the angle brackets will be escaped. Fine if that’s what you want, but you probably don’t.
Find matches for key in value-source, first by looking in its metas (using select-from-metas) and then by looking in its doc (using select-from-doc). With select, you get the first result; with select*, you get them all. In both cases, you get #f if there are no matches.
Look up the value of key in meta-source. The meta-source argument can be either a set of metas (i.e., a hash) or a pagenode?, from which metas are pulled. If no value exists for key, you get #f.
Look up the value of key in doc-source. The doc-source argument can be either be a doc (i.e., a txexpr) or a pagenode?, from which doc is pulled. If no value exists for key, you get #f.
Convert xexpr to an HTML string. Similar to xexpr->string, but consistent with the HTML spec, text that appears within script or style blocks will not be escaped.
"<root><script>3 > 2</script>Why is 3 > 2?</root>"
> (->htmltx)
"<root><script>3 > 2</script>Why is 3 > 2?</root>"
Be careful not to pass existing HTML strings into this function, because the angle brackets will be escaped. Fine if that’s what you want, but you probably don’t.
Find matches for key in value-source, first by looking in its metas (using select-from-metas) and then by looking in its doc (using select-from-doc). With select, you get the first result; with select*, you get them all. In both cases, you get #f if there are no matches.
Look up the value of key in meta-source. The meta-source argument can be either a set of metas (i.e., a hash) or a pagenode?, from which metas are pulled. If no value exists for key, you get #f.
Look up the value of key in doc-source. The doc-source argument can be either be a doc (i.e., a txexpr) or a pagenode?, from which doc is pulled. If no value exists for key, you get #f.
\ No newline at end of file
diff --git a/doc/Top.html b/doc/Top.html
index 3871278..dc3536d 100644
--- a/doc/Top.html
+++ b/doc/Top.html
@@ -1,2 +1,2 @@
-8.8 Top
You’ll probably never invoke this module directly. But it’s implicitly imported into every Pollen markup file. And if you don’t know what it does, you might end up surprised by some of the behavior you get.
In the Pollen markup environment, however, this behavior is annoying. Because when you’re writing X-expressions, you don’t necessarily want to define all your tags ahead of time.
So Pollen redefines #%top. For convenience, Pollen’s version of #%top assumes that an undefined tag should just refer to an X-expression beginning with that tag (and uses make-tag-function to provide this behavior):
Examples:
;Again, let's call em without defining it, but using pollen/top
The good news is that this behavior means you use any tag you want in your markup without defining it in advance. You can still attach a function to the tag later, which will automatically supersede #%top.
This isn’t a bug. It’s just a natural consequence of how Pollen’s #%top works. It can, however, make debugging difficult sometimes. Let’s suppose my markup depends on very-important-function, which I don’t import correctly.
So the undefined-function bug goes unreported. Again, that’s not a bug in Pollen — there’s just no way for it to tell the difference between an identifier that’s deliberately undefined and one that’s inadvertently undefined. If you want to guarantee that you’re invoking a defined identifier, use def/c.
syntax
(def/cid)
Invoke id if it’s a defined identifier, otherwise raise an error. This form reverses the behavior of #%top (in other words, it restores default Racket behavior).
Recall this example from before. In standard Racket, you get an undefined-identifier error.
You’ll probably never invoke this module directly. But it’s implicitly imported into every Pollen markup file. And if you don’t know what it does, you might end up surprised by some of the behavior you get.
In the Pollen markup environment, however, this behavior is annoying. Because when you’re writing X-expressions, you don’t necessarily want to define all your tags ahead of time.
So Pollen redefines #%top. For convenience, Pollen’s version of #%top assumes that an undefined tag should just refer to an X-expression beginning with that tag (and uses make-tag-function to provide this behavior):
Examples:
;Again, let's call em without defining it, but using pollen/top
The good news is that this behavior means you use any tag you want in your markup without defining it in advance. You can still attach a function to the tag later, which will automatically supersede #%top.
This isn’t a bug. It’s just a natural consequence of how Pollen’s #%top works. It can, however, make debugging difficult sometimes. Let’s suppose my markup depends on very-important-function, which I don’t import correctly.
So the undefined-function bug goes unreported. Again, that’s not a bug in Pollen — there’s just no way for it to tell the difference between an identifier that’s deliberately undefined and one that’s inadvertently undefined. If you want to guarantee that you’re invoking a defined identifier, use def/c.
syntax
(def/cid)
Invoke id if it’s a defined identifier, otherwise raise an error. This form reverses the behavior of #%top (in other words, it restores default Racket behavior).
Recall this example from before. In standard Racket, you get an undefined-identifier error.
\ No newline at end of file
diff --git a/doc/World.html b/doc/World.html
index 846fedf..a2985d7 100644
--- a/doc/World.html
+++ b/doc/World.html
@@ -1,5 +1,5 @@
-8.9 World
A parameter that determines whether the world:project-require file is checked for changes on every pass through render. (Can be faster to turn this off if you don’t need it.) Initialized to #t.
A parameter that reports the path to the directory of support files for the project server. Initialized to #f, but set to a proper value when the server runs.
A parameter that determines whether the world:project-require file is checked for changes on every pass through render. (Can be faster to turn this off if you don’t need it.) Initialized to #t.
A parameter that reports the path to the directory of support files for the project server. Initialized to #f, but set to a proper value when the server runs.
Name of the root node in a decoded pagetree. It’s ignored by the code, so its only role is to clue you in that you’re looking at something that came out of the pagetree decoder. Initialized to 'pagetree-root.
Name of the fallback template (i.e., the template used to render a Pollen markup file when no other template can be found). Initialized to "fallback.html.pt".
Name of the root node in a decoded pagetree. It’s ignored by the code, so its only role is to clue you in that you’re looking at something that came out of the pagetree decoder. Initialized to 'pagetree-root.
Name of the fallback template (i.e., the template used to render a Pollen markup file when no other template can be found). Initialized to "fallback.html.pt".
\ No newline at end of file
diff --git a/doc/big-picture.html b/doc/big-picture.html
new file mode 100644
index 0000000..ec37a32
--- /dev/null
+++ b/doc/big-picture.html
@@ -0,0 +1,3 @@
+
+4 The big picture
A summary of the key components & concepts of the Pollen publishing system and how they fit together. If you’ve completed the Quick tour, this will lend some context to what you saw. The next tutorials will make more sense if you read this first.
4.1The book is a program
This is the core design principle of Pollen. Consistent with this principle, Pollen adopts the habits of software development in its functionality, workflow, and project management.
You are a programmer. Don’t panic. But let’s just admit it — if your book is a program, then you are, in part, programming it. You don’t have to know any programming to start using Pollen. But you’ll have to be willing to learn a few programming ideas. (Those who have programmed other template-based HTML generators may have to forget a few things.)
A Pollen project consists of source files + static files. A source file is a file that can be compiled to produce certain output. A static file is usable as it stands (e.g., an SVG file or webfont). Generally, the textual content of your book will live in source files, and other elements will be static files.
Source control is a good idea. Because Pollen projects are software projects, they can be easily managed with systems for source control and collaboration, like GitHub. If you’re a writer at heart, don’t fear these systems — the learning curve is repaid by revision & edit tracking that’s much easier than it is with Word or PDF files.
4.2One language, multiple dialects
Everything is Racket. The Pollen system is built entirely in the Racket programming language. Some of your source files will be in Racket. Others will be in one of the Pollen language dialects. But under the hood, everything becomes Racket code. So if you plan to do any serious work in Pollen, you’ll want to learn some basics about Racket too (for instance Quick: An Introduction to Racket with Pictures).
The Pollen language is based on Scribble. Scribble is a variant of the Racket language that flips the usual programming syntax: instead of code with embedded textual content, a Scribble source file is text with embedded code (an idea borrowed from TeX). The Pollen language is adapted from Scribble. So most things that are true about Scribble are also true about Pollen (see Scribble: The Racket Documentation Tool).
The Pollen language is divided into dialects. The Pollen dialects share a common syntax and structure. But they’re different in details that makes them better adapted to certain types of source files (for instance, one dialect of Pollen understands Markdown; the others don’t). Use whichever suits the task at hand.
4.3Development environment
The Pollen development environment has three main pieces: the DrRacket code editor, the project server, and the command-line tool.
Edit source files with DrRacket. DrRacket is Racket’s GUI code editor. Sure, you can also use a generic text editor. But DrRacket lets you immediately run your source and see if it works.
Preview & test web pages with the Pollen project server. Pollen has a built-in development web server called the project server. After you start the project server, you can preview your web pages within any web browser, allowing you to test them with maximum accuracy.
Write the docs. The project server can recognize and render Scribble files, so you can use it as a previewing tool while you’re writing your documentation.
Render & deploy from the command line. Your Pollen project ultimately gets rendered to a set of static files (usually HTML and related assets). This can be controlled from the command line, so you can integrate it into other scripts.
4.4A special data structure for HTML
Unlike other programming languages, Pollen (and Racket) internally represent HTML with something called an X-expression. An X-expression is simply a list that represents what in HTML is called an element, meaning a thing with an opening tag, a closing tag, and content in between. Like HTML elements, X-expressions can be nested. Unlike HTML elements, X-expressions have no closing tag, they use parentheses to denote the start and end, and text elements are put inside quotes.
For example, consider this HTML element:
<body><h1>Hello world</h1><p>Nice to <i>see</i> you.</p></body>
As a Racket X-expression, this would be written:
(body (h1 "Hello world") (p "Nice to " (i "see") " you."))
More will be said about X-expressions. But a couple advantages should be evident already. First, without the redundant angle brackets, the X-expression is more readable than the equivalent HTML. Second, an X-expression is preferable to representing HTML as a simple string, because it preserves the internal structure of the element.
4.5Pollen command syntax
As mentioned above, a Pollen source file is not code with text embedded in it, but rather text with code embedded. (See ◊ command overview for more.)
If you can write text, you can program in Pollen. Really. As you already found out in the Quick tour, this is a valid Pollen program:
+
Commands start with ◊. A simple rule: if a piece of text starts with ◊, it’s treated as a command; otherwise it’s treated as ordinary text.
Write commands in text mode or Racket mode. Commands can use two equivalent notation systems: either Pollen’s text-mode command syntax, or standard Racket syntax.
Everything in Racket is in Pollen too. This isn’t some dimwit “template language.” Racket is a fully provisioned programming language, and every Racket function is available in Pollen.
4.6The preprocessor
The preprocessor is the simplest processing mode in Pollen.
Text output. The preprocessor scans the source for any Pollen commands, resolves them, and outputs the whole file as text.
Work with any text file. I hope this blows your mind a teeny bit. You can use the preprocessor with HTML, CSS, Markdown, JavaScript, XML, SVG, or any other text-based file (including source files of other programming languages).
Start quickly. Because it works with any text file, the preprocessor is an easy way to try out Pollen, because you can mix it into your workflow on an existing project, or even just one file.
4.7Templated source files
If you want to apply a particular page format to multiple sources of content — as you would in a book — you can use Pollen templates.
Templates can be any format. Usually Pollen templates will be HTML. But they don’t have to be.
Markdown support. Pollen has a built-in Markdown parser, so you can import Markdown sources into a Pollen publication.
Custom markup. Pollen’s markup mode allows you the freedom to define your own markup tags and attach behavior to them.
Mix source types. Every text source is converted to an X-expression before going into a template. So it’s fine to have multiple kinds of text source in one project.
4.8Pagetrees
Similar to a table of contents, a pagetree is a special Pollen source file that gets turned into a hierarchical list of pages.
Navigation. Pagetrees are used to provide navigation links within HTML templates (like previous, next, up, top).
Organization. Multiple pagetrees can be used to divide your project into subsets of pages that should be treated separately.
\ No newline at end of file
diff --git a/doc/dashboard.png b/doc/dashboard.png
new file mode 100644
index 0000000..6380e23
Binary files /dev/null and b/doc/dashboard.png differ
diff --git a/doc/doc-index.html b/doc/doc-index.html
index 72eaf36..d25eb8a 100644
--- a/doc/doc-index.html
+++ b/doc/doc-index.html
@@ -1,2 +1,2 @@
-Index
\ No newline at end of file
diff --git a/doc/file-types.html b/doc/file-types.html
new file mode 100644
index 0000000..1236041
--- /dev/null
+++ b/doc/file-types.html
@@ -0,0 +1,2 @@
+
+9.3 File
A utility module that provides functions for working with Pollen source and output files. The tests rely on file extensions specified in pollen/world.
Pollen handles six kinds of source files:
Preprocessor, with file extension .pp.
Markup, with file extension .pm.
Template, with file extension .pt.
Null, with file extension .p.
Scribble, with file extension .scrbl.
For each kind of Pollen source file, the corresponding output file is generated by removing the extension from the name of the source file. So the preprocessor source file default.css.pp would become default.css. Scribble files work differently — the corresponding output file is the source file but with an html extension rather than scrbl. So pollen.scrbl would become pollen.html.
Test whether v is a path representing a source file of the specified type, or is the output path for an existing source file of the specified type. In other words, has/is-preproc-source? is equivalent to (or(preproc-source?v)(has-preproc-source?v)).
Convert an output path p into the source path of the specified type that would produce this output path. This function simply generates a path for a file — it does not ask whether the file exists.
Convert a source path p into its corresponding output path. This function simply generates a path for a file — it does not ask whether the file exists.
\ No newline at end of file
diff --git a/doc/index.html b/doc/index.html
index 9b63327..1081500 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -1,3 +1,3 @@
-Pollen: the book is a program
Pollen is a publishing system that helps authors create beautiful and functional web-based books. Pollen includes tools for writing, designing, programming, testing, and publishing.
I used Pollen to create my book Butterick’s Practical Typography. Sure, go take a look. Is it better than the last digital book you encountered? Yes it is. Would you like your book to look like that? If so, keep reading.
At the core of Pollen is an argument:
-
First, that digital books should be the best books we’ve ever had. So far, they’re not even close.
Second, that because digital books are software, an author shouldn’t think of a book as merely data. The book is a program.
Third, that 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 use 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 while the idea for Pollen had been with me for several years, it simply wasn’t possible to build it with other languages. So if it’s unfamiliar to you, don’t panic. It was unfamiliar to me. Once you see what you can do with Pollen & Racket, 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.
Pollen is a publishing system that helps authors create beautiful and functional web-based books. Pollen includes tools for writing, designing, programming, testing, and publishing.
I used Pollen to create my book Butterick’s Practical Typography. Sure, go take a look. Is it better than the last digital book you encountered? Yes it is. Would you like your book to look like that? If so, keep reading.
At the core of Pollen is an argument:
+
First, that digital books should be the best books we’ve ever had. So far, they’re not even close.
Second, that because digital books are software, an author shouldn’t think of a book as merely data. The book is a program.
Third, that 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 use 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 while the idea for Pollen had been with me for several years, it simply wasn’t possible to build it with other languages. So if it’s unfamiliar to you, don’t panic. It was unfamiliar to me. Once you see what you can do with Pollen & Racket, 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.
\ No newline at end of file
diff --git a/doc/project-server.png b/doc/project-server.png
new file mode 100644
index 0000000..19131b1
Binary files /dev/null and b/doc/project-server.png differ
diff --git a/doc/quick-tour.html b/doc/quick-tour.html
index 684b6fd..3359998 100644
--- a/doc/quick-tour.html
+++ b/doc/quick-tour.html
@@ -1,2 +1,2 @@
-2 Quick tour
You don’t have to use Supertramp song titles. Any text will do. When you click Run again, you’ll see whatever you typed:
Goodbye Stranger Breakfast in America Take the Long Way Home
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 is. You never have to perform the incantations of typical programming languages:
print "Hello world"
document.write('Hello world');
printf("Hello world");
In Pollen, what you write is what you get.
2.3Naming, saving, and rendering a source file
Save this file with the name hello.txt.pp in any convenient directory. The desktop is fine.
Open a terminal window and issue two commands:
> cd [directory containing your 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
Goodbye Stranger
Breakfast in America
Take the Long Way Home
You’ve just learned three things:
Pollen commands in the terminal begin with raco pollen, followed by a specific command (in this case render) and sometimes an argument (in this case hello.txt.pp).
The render command takes the ouput from your source file — meaning, the result you previewed in DrRacket in the previous step — and saves it to another file.
The name of the output file is the same as the source file, minus the Pollen source extension. So hello.txt.pp becomes hello.txt.
Try editing the text in the hello.txt.pp source file and running raco pollen render hello.txt.pp again. The old hello.txt will be replaced with a new one showing your changes. And so you’ve learned a fourth thing:
Pollen works by rendering output files from source files. Output files can be overwritten. Therefore, you should only make edits to your source files.
2.4The project server
You’ve just learned two ways to see the output of a Pollen source file — first, you ran it in DrRacket. Then, you rendered it to an output file.
Now here’s a third: the Pollen project server. Here’s how you start it. Return to your terminal window and issue two commands:
> cd [directory containing your hello.txt.pp file]
> raco pollen start
After a moment, you’ll see the startup message:
Welcome to Pollen 0.001 (Racket 6.0.0.5)
Project root is /path/to/your/directory
Project server is http://localhost:8080 (Ctrl-C to exit)
Project dashboard is http://localhost:8080/index.ptree
Ready to rock
Open a web browser and point it at http://localhost:8080/index.ptree. The top of the window will say Project root. 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:
Goodbye Stranger
Breakfast in America
Take the Long Way Home
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:
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.
2.5Intermission
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 server (the main URL is http://localhost:8080/index.ptree) and the DrRacket editing window.
2.6Pollen 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:
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 on margin.html. You should see a black box containing the text “5em is the inset.”
Let’s 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:
The ◊ character is called a lozenge. In Pollen, the lozenge is a special character that marks anything Pollen should interpret as a command (rather than plain text). The whole command ◊define[my-inset]{30%} means “create a variable called my-inset and give it the value 30%.”
Then put the variable into the HTML like so, this time using the ◊ character with the variable name in the two places the value appears:
Now 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 math functions, text manipulation, and so on.
2.7Markdown 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 it as a source decoder.
For instance, Markdown mode. Markdown is a simplified notation system for HTML. You can use Pollen’s Markdown decoder 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:
As usual, you’re welcome to edit downtown.html.pmd and then refresh the web browser to see the changes.
In Markdown 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:
Pollen is handling two tasks here: interpreting the commands in the source, and then converting the Markdown to HTML. 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.
2.8Markup mode
If all you need to do is produce basic HTML, Markdown is great. 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 Pollen markup mode. To use Pollen markup, insert #lang pollen as the first line of your source file, and add a .pm file extension.
Compared to Markdown mode, Pollen markup mode is wide open. Markdown mode gives you a limited set of formatting tools (i.e., the ones supported by Markdown). But in markup mode, you can use any tags you want. Markdown mode decodes the source in a fixed way (i.e., with the Markdown decoder). But markup mode lets you build any decoder you want.
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:
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 project-require.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:
Markup mode 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.
2.9Templates
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 Markdown or markup 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]. For uptown.html.pm, the output extension will be .html, thus Pollen will look for template.html.
So let’s create template.html. Make a new file that with the following lines and save it to the same directory as uptown.html.pm:
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 a Pollen function called ->html.
Go back 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.10PS for Scribble users
Pollen can also be used as a dynamic preview server for Scribble files. From your terminal, do the following:
> cd [directory containing your Scribble files]
> raco pollen start
On the project dashboard, you’ll see your [filename].scrbl files listed as [filename].html. 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.11The end of the beginning
Now you’ve seen the key features of Pollen. What do you think?
“So it’s like WordPress, but harder to use?” I was a happy WordPress user for several years. If you need a blog, it’s great. But the farther you get from blogs, the more it becomes like teaching an elephant to pirouette. And for those who like to solve problems with programming, PHP is, um, limited.
“What about pairing a Python template system and Python web server?” Good idea. I even tried it. But Python template systems don’t offer you Python — they offer you pidgin dialects that ain’t very Pythonic. Also, Python’s handing of markup-based data structures is cumbersome.
“Haven’t you heard of Jekyll?” Yes. If everything you need to write is expressible in Markdown, it’s great. If you need more than that, you’re stuck.
“Sounds a lot like LaTeX. Why not use that?” Also a good idea. LaTeX gets a lot of things right. But it wasn’t designed for web publishing.
“Eh, there are plenty of adequate options. Why should I learn a system written in Racket, which I’ve never used?” A salient objection. It’s also the question I asked myself before I committed to Racket. But publishing systems that are author- or designer-friendly tend to be programmer-hostile, and vice versa. Racket is the only language I found that could meet my requirements.
But don’t take my word for it. The rest of this documentation will show you the cool, 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. 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.
You don’t have to use Supertramp song titles. Any text will do. When you click Run again, you’ll see whatever you typed:
Goodbye Stranger Breakfast in America Take the Long Way Home
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 is. You never have to perform the incantations of typical programming languages:
print "Hello world"
document.write('Hello world');
printf("Hello world");
In Pollen, what you write is what you get.
2.3Naming, saving, and rendering a source file
Save this file with the name hello.txt.pp in any convenient directory. The desktop is fine.
Open a terminal window and issue two commands:
> cd [directory containing your 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
Goodbye Stranger
Breakfast in America
Take the Long Way Home
You’ve just learned three things:
Pollen commands in the terminal begin with raco pollen, followed by a specific command (in this case render) and sometimes an argument (in this case hello.txt.pp).
The render command takes the ouput from your source file — meaning, the result you previewed in DrRacket in the previous step — and saves it to another file.
The name of the output file is the same as the source file, minus the Pollen source extension. So hello.txt.pp becomes hello.txt.
Try editing the text in the hello.txt.pp source file and running raco pollen render hello.txt.pp again. The old hello.txt will be replaced with a new one showing your changes. And so you’ve learned a fourth thing:
Pollen works by rendering output files from source files. Output files can be overwritten. Therefore, you should only make edits to your source files.
2.4The project server
You’ve just learned two ways to see the output of a Pollen source file — first, you ran it in DrRacket. Then, you rendered it to an output file.
Now here’s a third: the Pollen project server. Here’s how you start it. Return to your terminal window and issue two commands:
> cd [directory containing your hello.txt.pp file]
> raco pollen start
After a moment, you’ll see the startup message:
Welcome to Pollen 0.001 (Racket 6.0.0.5)
Project root is /path/to/your/directory
Project server is http://localhost:8080 (Ctrl-C to exit)
Project dashboard is http://localhost:8080/index.ptree
Ready to rock
Open a web browser and point it at http://localhost:8080/index.ptree. The top of the window will say Project root. 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:
Goodbye Stranger
Breakfast in America
Take the Long Way Home
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:
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.
2.5Intermission
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 server (the main URL is http://localhost:8080/index.ptree) and the DrRacket editing window.
2.6Pollen 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:
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 on margin.html. You should see a black box containing the text “5em is the inset.”
Let’s 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:
The ◊ character is called a lozenge. In Pollen, the lozenge is a special character that marks anything Pollen should interpret as a command (rather than plain text). The whole command ◊define[my-inset]{30%} means “create a variable called my-inset and give it the value 30%.”
Then put the variable into the HTML like so, this time using the ◊ character with the variable name in the two places the value appears:
Now 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 math functions, text manipulation, and so on.
2.7Markdown 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 it as a source decoder.
For instance, Markdown mode. Markdown is a simplified notation system for HTML. You can use Pollen’s Markdown decoder 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:
As usual, you’re welcome to edit downtown.html.pmd and then refresh the web browser to see the changes.
In Markdown 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:
Pollen is handling two tasks here: interpreting the commands in the source, and then converting the Markdown to HTML. 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.
2.8Markup mode
If all you need to do is produce basic HTML, Markdown is great. 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 Pollen markup mode. To use Pollen markup, insert #lang pollen as the first line of your source file, and add a .pm file extension.
Compared to Markdown mode, Pollen markup mode is wide open. Markdown mode gives you a limited set of formatting tools (i.e., the ones supported by Markdown). But in markup mode, you can use any tags you want. Markdown mode decodes the source in a fixed way (i.e., with the Markdown decoder). But markup mode lets you build any decoder you want.
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:
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 project-require.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:
Markup mode 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.
2.9Templates
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 Markdown or markup 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]. For uptown.html.pm, the output extension will be .html, thus Pollen will look for template.html.
So let’s create template.html. Make a new file that with the following lines and save it to the same directory as uptown.html.pm:
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 a Pollen function called ->html.
Go back 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.10PS for Scribble users
Pollen can also be used as a dynamic preview server for Scribble files. From your terminal, do the following:
> cd [directory containing your Scribble files]
> raco pollen start
On the project dashboard, you’ll see your [filename].scrbl files listed as [filename].html. 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.11The end of the beginning
Now you’ve seen the key features of Pollen. What do you think?
“So it’s like WordPress, but harder to use?” I was a happy WordPress user for several years. If you need a blog, it’s great. But the farther you get from blogs, the more it becomes like teaching an elephant to pirouette. And for those who like to solve problems with programming, PHP is, um, limited.
“What about pairing a Python template system and Python web server?” Good idea. I even tried it. But Python template systems don’t offer you Python — they offer you pidgin dialects that ain’t very Pythonic. Also, Python’s handing of markup-based data structures is cumbersome.
“Haven’t you heard of Jekyll?” Yes. If everything you need to write is expressible in Markdown, it’s great. If you need more than that, you’re stuck.
“Sounds a lot like LaTeX. Why not use that?” Also a good idea. LaTeX gets a lot of things right. But it wasn’t designed for web publishing.
“Eh, there are plenty of adequate options. Why should I learn a system written in Racket, which I’ve never used?” A salient objection. It’s also the question I asked myself before I committed to Racket. But publishing systems that are author- or designer-friendly tend to be programmer-hostile, and vice versa. Racket is the only language I found that could meet my requirements.
But don’t take my word for it. The rest of this documentation will show you the cool, 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. 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.
\ No newline at end of file
diff --git a/doc/raco-pollen.html b/doc/raco-pollen.html
new file mode 100644
index 0000000..f6ba693
--- /dev/null
+++ b/doc/raco-pollen.html
@@ -0,0 +1,2 @@
+
+6 Using raco pollen
Racket provides centralized command-line options through raco (short for racketcommand, see raco: Racket Command-Line Tools).
Once you install Pollen, you can access the following Pollen-specific commands through raco using the subcommand raco pollen.
6.1Making sure racopollen works
Open a terminal window and type:
> raco pollen test
If racopollen is installed correctly, you’ll see:
raco pollen is installed correctly
But if you get:
raco: Unrecognized command: pollen
You’ll need to fix the problem before proceeding, most likely by reinstalling Pollen (see Installation).
Pro tip: I have an alias in my .bash_profile like so: alias polcom='raco pollen'
6.2racopollen
Same as racopollenhelp.
6.3racopollenhelp
Displays a list of available commands.
6.4racopollenstart
Starts the project server from the current directory using the default port, which is the value of the parameter world:current-server-port (by default, port 8080).
This command can be invoked with two optional arguments.
racopollenstartpath will start the project server in path rather than the current directory.
> raco pollen start ~/path/to/project/
racopollenstartpathport will start the project server in path using port rather than world:current-server-port. This is useful if you want to have multiple project servers running simultaneously.
If you want to start in the current directory but with a different port, use . as the path:
> raco pollen start . 8088
6.5racopollenrender
Renders all preprocessor source files and then all pagetree files found in the current directory.
This command can be invoked with extra arguments.
racopollenrenderdirectory will render the preprocessor source files and pagetree files in the specified directory.
Alternatively, the command can take a variable number of path arguments. racopollenrenderpath... will render only the paths specified in path.... Consistent with the usual command-line idiom, this can be a single path, a list of paths, or a pattern:
Pollen uses a special character — the lozenge, which looks like this: ◊ — to mark commands within a Pollen source file. So when you put a ◊ in your source, whatever comes next will be treated as a command. If you don’t, it will just be interpreted as plain text.
7.2The lozenge glyph (◊)
I chose the lozenge as the command marker because a) it appears in almost every font, b) it’s barely used in ordinary typesetting, c) it’s not used in any programming language that I know of, and d) its shape and color allow it to stand out easily in code without being distracting.
Pollen uses a special character — the lozenge, which looks like this: ◊ — to mark commands within a Pollen source file. So when you put a ◊ in your source, whatever comes next will be treated as a command. If you don’t, it will just be interpreted as plain text.
8.2The lozenge glyph (◊)
I chose the lozenge as the command marker because a) it appears in almost every font, b) it’s barely used in ordinary typesetting, c) it’s not used in any programming language that I know of, and d) its shape and color allow it to stand out easily in code without being distracting.
Here’s how you type it:
Mac: option + shift + V
Windows:
-Ubuntu:
Still, if you don’t want to use the lozenge as your command marker, you can use something else. Set Pollen’s world:command-marker value to whatever character you want.
Scribble uses the @ sign as a delimiter. It’s not a bad choice if you only work with Racket files. But as you use Pollen to work on other kinds of text-based files that commonly contain @ signs — HTML pages especially — it gets cumbersome. So I changed it.
But don’t knock the lozenge till you try it.
7.3The two command modes: text mode & Racket mode
Pollen commands can be entered in one of two modes: text mode or Racket mode. Both modes start with a lozenge (◊):
A text-mode command has the three possible parts after the ◊:
The command name appears immediately after the ◊. Typically it’s a short word.
The Racket arguments appear between square brackets. Pollen is partly an interface to the Racket programming language. These arguments are entered using Racket conventions — e.g., a string of text needs to be put in quotes as a "stringoftext". If you like programming, you’ll end up using these frequently. If you don’t, you won’t.
The text argument appears between braces (aka curly brackets). You can put any ordinary text here. Unlike with the Racket arguments, you don’t put quotes around the text.
Each of the three parts is optional. You can also nest commands within each other. However:
You can never have spaces between the three parts.
Whatever parts you use must always appear in the order above.
Here are a few examples of correct text-mode commands:
The next section describes each of these parts in detail.
Racket-mode commands
If you’re familiar with Racket expressions, you can use the Racket-mode commands to embed them within Pollen source files. It’s simple: any Racket expression can become a Pollen command by adding ◊ to the front. So in Racket, this code:
Beyond that, there’s not much to say about Racket mode — any valid expression you can write in Racket will also be a valid Racket-mode Pollen command.
The relationship of text mode and Racket mode
Even if you don’t plan to write a lot of Racket-mode commands, you should be aware that under the hood, Pollen is converting all commands in text mode to Racket mode. So a text-mode command that looks like this:
◊headline[#:size'enormous]{ManBitesDog!}
Is actually being turned into a Racket-mode command like this:
(headline#:size'enormous"Man Bites Dog!")
Thus a text-mode command is just an alternate way of writing a Racket-mode command. (More broadly, all of Pollen is just an alternate way of using Racket.)
The corollary is that you can always write Pollen commands using whichever mode is more convenient or readable. For instance, the earlier example, written in the Racket mode:
In Pollen, you’ll typically use the command name for one of four purposes:
To invoke a tag function.
To invoke another function.
To insert the value of a variable.
To insert a comment.
7.3.1.1Invoking tag functions
By default, Pollen treats every command name as a tag function. As the name implies, a tag function creates a tagged X-expression with the command name as the tag, and the text argument as the content.
To streamline markup, Pollen doesn’t restrict you to a certain set of tags, nor does it make you define your tag functions ahead of time. Just type a tag, and you can start using it.
The one restriction is that you can’t invent names for tag functions that are already being used for other commands. For instance, map is a name permanently reserved by the Racket function map. It’s also a rarely-used HTML tag. But gosh, you really want to use it. Problem is, if you invoke it directly, Pollen will think you mean the other map:
Still, if you don’t want to use the lozenge as your command marker, you can use something else. Set Pollen’s world:command-marker value to whatever character you want.
Scribble uses the @ sign as a delimiter. It’s not a bad choice if you only work with Racket files. But as you use Pollen to work on other kinds of text-based files that commonly contain @ signs — HTML pages especially — it gets cumbersome. So I changed it.
But don’t knock the lozenge till you try it.
8.3The two command modes: text mode & Racket mode
Pollen commands can be entered in one of two modes: text mode or Racket mode. Both modes start with a lozenge (◊):
A text-mode command has the three possible parts after the ◊:
The command name appears immediately after the ◊. Typically it’s a short word.
The Racket arguments appear between square brackets. Pollen is partly an interface to the Racket programming language. These arguments are entered using Racket conventions — e.g., a string of text needs to be put in quotes as a "stringoftext". If you like programming, you’ll end up using these frequently. If you don’t, you won’t.
The text argument appears between braces (aka curly brackets). You can put any ordinary text here. Unlike with the Racket arguments, you don’t put quotes around the text.
Each of the three parts is optional. You can also nest commands within each other. However:
You can never have spaces between the three parts.
Whatever parts you use must always appear in the order above.
Here are a few examples of correct text-mode commands:
The next section describes each of these parts in detail.
Racket-mode commands
If you’re familiar with Racket expressions, you can use the Racket-mode commands to embed them within Pollen source files. It’s simple: any Racket expression can become a Pollen command by adding ◊ to the front. So in Racket, this code:
Beyond that, there’s not much to say about Racket mode — any valid expression you can write in Racket will also be a valid Racket-mode Pollen command.
The relationship of text mode and Racket mode
Even if you don’t plan to write a lot of Racket-mode commands, you should be aware that under the hood, Pollen is converting all commands in text mode to Racket mode. So a text-mode command that looks like this:
◊headline[#:size'enormous]{ManBitesDog!}
Is actually being turned into a Racket-mode command like this:
(headline#:size'enormous"Man Bites Dog!")
Thus a text-mode command is just an alternate way of writing a Racket-mode command. (More broadly, all of Pollen is just an alternate way of using Racket.)
The corollary is that you can always write Pollen commands using whichever mode is more convenient or readable. For instance, the earlier example, written in the Racket mode:
In Pollen, you’ll typically use the command name for one of four purposes:
To invoke a tag function.
To invoke another function.
To insert the value of a variable.
To insert a comment.
8.3.1.1Invoking tag functions
By default, Pollen treats every command name as a tag function. As the name implies, a tag function creates a tagged X-expression with the command name as the tag, and the text argument as the content.
To streamline markup, Pollen doesn’t restrict you to a certain set of tags, nor does it make you define your tag functions ahead of time. Just type a tag, and you can start using it.
The one restriction is that you can’t invent names for tag functions that are already being used for other commands. For instance, map is a name permanently reserved by the Racket function map. It’s also a rarely-used HTML tag. But gosh, you really want to use it. Problem is, if you invoke it directly, Pollen will think you mean the other map:
map: arity mismatch;
the expected number of arguments does not match the given number
given: 1
arguments...:
- "Fancy Sauce, $1"
What to do? Read on.
7.3.1.2Invoking other functions
Though every command name starts out as a tag function, it doesn’t necessarily end there. You have two options for invoking other functions: defining your own , or invoking others from Racket.
Defining your own functions
Use the define command to create your own function for a command name. After that, when you use the command name, you’ll get the new behavior. For instance, recall this example showing the default tag-function behavior:
The replacement function has to accept any arguments that might get passed along, but it doesn’t have to do anything with them. For instance, this function definition won’t work because strong is going to get a text argument that it’s not defined to handle:
Though every command name starts out as a tag function, it doesn’t necessarily end there. You have two options for invoking other functions: defining your own , or invoking others from Racket.
Defining your own functions
Use the define command to create your own function for a command name. After that, when you use the command name, you’ll get the new behavior. For instance, recall this example showing the default tag-function behavior:
The replacement function has to accept any arguments that might get passed along, but it doesn’t have to do anything with them. For instance, this function definition won’t work because strong is going to get a text argument that it’s not defined to handle:
You can attach any behavior to a command name. As your project evolves, you can also update the behavior of a command name. In that way, Pollen commands become a set of hooks to which you can attach more elaborate processing.
Using Racket functions
You aren’t limited to functions you define. Any function from Racket, or any Racket library, can be invoked directly by using it as a command name. Here’s the function range, which creates a list of numbers:
Hold on — that’s not what we want. Where’s the list of numbers? The problem here is that we didn’t explicitly import the racket/list library, which contains the definition for range. (If you need to find out what library contains a certain function, the Racket documentation will tell you.) Without racket/list, Pollen just thinks we’re trying to use range as a tag function (and if we had been, then '(range 1 20) would’ve been the right result).
We fix this by using the require command to bring in the racket/list library, which contains the range we want:
Let’s return to the problem that surfaced in the last section — the fact that some command names can’t be used as tag functions because they’re already being used for other things. You can work around this by defining your own tag function with a non-conflicting name.
For instance, suppose we want to use map as a tag even though Racket is using it for its own function called map. First, we invent a command name that doesn’t conflict. Let’s call it my-map. As you learned above, Pollen will treat a new command name as a tag function by default:
But my-map is not the tag we want. We need to define my-map to be a tag function for map. We can do this with the Pollen helper make-tag-function. That function lives in pollen/tag, so we require that too:
A Pollen command name usually refers to a function, but it can also refer to a variable, which is a data value. Once you define the variable, you can insert it into your source by using the ◊ notation without any other arguments:
Be careful — if you include arguments, even blank ones, Pollen will treat the command name as a function. This won’t work, because a variable is not a function:
To understand what happens here, recall the relationship between Pollen’s command modes. The text-mode command ◊foo[] becomes the Racket-mode command (foo), which after variable substitution becomes ("bar"). If you try to evaluate ("bar") — e.g., in DrRacket — you’ll get the same error.
You can attach any behavior to a command name. As your project evolves, you can also update the behavior of a command name. In that way, Pollen commands become a set of hooks to which you can attach more elaborate processing.
Using Racket functions
You aren’t limited to functions you define. Any function from Racket, or any Racket library, can be invoked directly by using it as a command name. Here’s the function range, which creates a list of numbers:
Hold on — that’s not what we want. Where’s the list of numbers? The problem here is that we didn’t explicitly import the racket/list library, which contains the definition for range. (If you need to find out what library contains a certain function, the Racket documentation will tell you.) Without racket/list, Pollen just thinks we’re trying to use range as a tag function (and if we had been, then '(range 1 20) would’ve been the right result).
We fix this by using the require command to bring in the racket/list library, which contains the range we want:
Let’s return to the problem that surfaced in the last section — the fact that some command names can’t be used as tag functions because they’re already being used for other things. You can work around this by defining your own tag function with a non-conflicting name.
For instance, suppose we want to use map as a tag even though Racket is using it for its own function called map. First, we invent a command name that doesn’t conflict. Let’s call it my-map. As you learned above, Pollen will treat a new command name as a tag function by default:
But my-map is not the tag we want. We need to define my-map to be a tag function for map. We can do this with the Pollen helper make-tag-function. That function lives in pollen/tag, so we require that too:
A Pollen command name usually refers to a function, but it can also refer to a variable, which is a data value. Once you define the variable, you can insert it into your source by using the ◊ notation without any other arguments:
Be careful — if you include arguments, even blank ones, Pollen will treat the command name as a function. This won’t work, because a variable is not a function:
To understand what happens here, recall the relationship between Pollen’s command modes. The text-mode command ◊foo[] becomes the Racket-mode command (foo), which after variable substitution becomes ("bar"). If you try to evaluate ("bar") — e.g., in DrRacket — you’ll get the same error.
application: not a procedure;
expected a procedure that can be applied to arguments
given: "bar"
- arguments...: [none]
The reason we can simply drop ◊foo into the text argument of another Pollen command is that the variable foo holds a string (i.e., a text value). When appropriate, Pollen will convert a variable to a string in a sensible way. For instance, numbers are easily converted:
If the variable holds a container datatype (like a list, hash, or vector), Pollen will produce the Racket text representation of the item. Here, zam is a list of integers:
This feature is included for your convenience as an author. But in general, your readers won’t want to see the Racket representation of a container. So in these cases, you should convert to a string manually in some sensible way. Here, the integers in the list are converted to strings, which are then combined using string-join from the racket/string library:
Pollen decoder: can’t convert #<procedure:+> to string
One special case to know about. In the examples above, there’s a word space between the variable and the other text. But suppose you need to insert a variable into text so that there’s no space in between. The simple ◊ notation won’t work, because it won’t be clear where the variable name ends and the text begins.
For instance, suppose we want to use a variable edge next to the string px:
Pollen decoder: can’t convert #<procedure:...t/pollen/tag.rkt:6:2> to string
The example fails because Pollen reads the whole string after the ◊ as the single variable name edgepx. Since edgepx isn’t defined, it’s treated as a tag function, and since Pollen can’t convert a function to a string, we get an error.
In these situations, surround the variable name with vertical bars ◊|like so| to explicitly indicate where the variable name ends. The bars are not treated as part of the name, nor are they included in the result. Once we do that, we get what we intended:
The middle part of a text-mode Pollen command contains the Racket arguments[between square brackets.] Most often, you’ll see these used to pass extra information to commands that operate on text.
For instance, tag functions. Recall from before that any not-yet-defined command name in Pollen is treated as a tag function:
'(title ((class "red") (id "first")) "The Beginning of the End")
But that’s a lot of parentheses to think about. So here’s the easy way. Anytime you use a tag function, there’s a shortcut for inserting attributes. You can enter them as a series of symbol / string pairs between the Racket-argument brackets. The only caveat is that the symbols have to begin with a quote mark ' and end with a colon :. So taken together, they look like this:
'(title ((class "42") (id "first")) "The Beginning of the End")
Since Pollen commands are really just Racket arguments underneath, you can use those too. Here, we’ll define a variable called name and use it in the Racket arguments of title:
'(title ((class "read") (id "Brennan")) "The Beginning of the End")
You can also use this area for keyword arguments. Keyword arguments can be used to provide options for a particular Pollen command, to avoid redundancy. Suppose that instead of using the h1 ... h6 tags, you want to consolidate them into one command called heading and select the level separately. You can do this with a keyword, in this case #:level, which is passed as a Racket argument:
The reason we can simply drop ◊foo into the text argument of another Pollen command is that the variable foo holds a string (i.e., a text value). When appropriate, Pollen will convert a variable to a string in a sensible way. For instance, numbers are easily converted:
If the variable holds a container datatype (like a list, hash, or vector), Pollen will produce the Racket text representation of the item. Here, zam is a list of integers:
This feature is included for your convenience as an author. But in general, your readers won’t want to see the Racket representation of a container. So in these cases, you should convert to a string manually in some sensible way. Here, the integers in the list are converted to strings, which are then combined using string-join from the racket/string library:
Pollen decoder: can’t convert #<procedure:+> to string
One special case to know about. In the examples above, there’s a word space between the variable and the other text. But suppose you need to insert a variable into text so that there’s no space in between. The simple ◊ notation won’t work, because it won’t be clear where the variable name ends and the text begins.
For instance, suppose we want to use a variable edge next to the string px:
Pollen decoder: can’t convert #<procedure:...t/pollen/tag.rkt:6:2> to string
The example fails because Pollen reads the whole string after the ◊ as the single variable name edgepx. Since edgepx isn’t defined, it’s treated as a tag function, and since Pollen can’t convert a function to a string, we get an error.
In these situations, surround the variable name with vertical bars ◊|like so| to explicitly indicate where the variable name ends. The bars are not treated as part of the name, nor are they included in the result. Once we do that, we get what we intended:
The middle part of a text-mode Pollen command contains the Racket arguments[between square brackets.] Most often, you’ll see these used to pass extra information to commands that operate on text.
For instance, tag functions. Recall from before that any not-yet-defined command name in Pollen is treated as a tag function:
'(title ((class "red") (id "first")) "The Beginning of the End")
But that’s a lot of parentheses to think about. So here’s the easy way. Anytime you use a tag function, there’s a shortcut for inserting attributes. You can enter them as a series of symbol / string pairs between the Racket-argument brackets. The only caveat is that the symbols have to begin with a quote mark ' and end with a colon :. So taken together, they look like this:
'(title ((class "42") (id "first")) "The Beginning of the End")
Since Pollen commands are really just Racket arguments underneath, you can use those too. Here, we’ll define a variable called name and use it in the Racket arguments of title:
'(title ((class "read") (id "Brennan")) "The Beginning of the End")
You can also use this area for keyword arguments. Keyword arguments can be used to provide options for a particular Pollen command, to avoid redundancy. Suppose that instead of using the h1 ... h6 tags, you want to consolidate them into one command called heading and select the level separately. You can do this with a keyword, in this case #:level, which is passed as a Racket argument:
The third part of a text-mode Pollen command is the text argument. The text argument {appears between curly braces}. It can contain any text you want. The text argument can also contain other Pollen commands with their own text arguments. And they can contain other Pollen commands ... and so on, all the way down.
Three small details to know about the text argument.
First, the only character that needs special handling in a text argument is the lozenge ◊. A lozenge ordinarily marks a new command. So if you want an actual lozenge to appear in the text, you have to escape it by typing ◊"◊".
Second, the whitespace-trimming policy. Here’s the short version: if there’s a carriage return at either end of the text argument, it is trimmed, and whitespace at the end of each line is selectively trimmed in an intelligent way. So this text argument, with carriage returns on the ends:
For the long version, please see [future link: Spaces, Newlines, and Indentation].
Third, within a multiline text argument, newline characters become individual strings that are not merged with adjacent text. So what you end up with is a list of strings, not a single string. That’s why in the last example, we got this:
'(div "Roomy!" "\n" "\n" "I agree.")
Instead of this:
'(div "Roomy!\n\nI agree.")
Under most circumstances, these two tagged X-expressions will behave the same way. The biggest exception is with functions. A function that operates on multiline text arguments needs to be able to handle an indefinite number of strings. For instance, this jejune function only accepts a single argument. It will work with a single-line text argument, because that produces a single string:
The third part of a text-mode Pollen command is the text argument. The text argument {appears between curly braces}. It can contain any text you want. The text argument can also contain other Pollen commands with their own text arguments. And they can contain other Pollen commands ... and so on, all the way down.
Three small details to know about the text argument.
First, the only character that needs special handling in a text argument is the lozenge ◊. A lozenge ordinarily marks a new command. So if you want an actual lozenge to appear in the text, you have to escape it by typing ◊"◊".
Second, the whitespace-trimming policy. Here’s the short version: if there’s a carriage return at either end of the text argument, it is trimmed, and whitespace at the end of each line is selectively trimmed in an intelligent way. So this text argument, with carriage returns on the ends:
For the long version, please see [future link: Spaces, Newlines, and Indentation].
Third, within a multiline text argument, newline characters become individual strings that are not merged with adjacent text. So what you end up with is a list of strings, not a single string. That’s why in the last example, we got this:
'(div "Roomy!" "\n" "\n" "I agree.")
Instead of this:
'(div "Roomy!\n\nI agree.")
Under most circumstances, these two tagged X-expressions will behave the same way. The biggest exception is with functions. A function that operates on multiline text arguments needs to be able to handle an indefinite number of strings. For instance, this jejune function only accepts a single argument. It will work with a single-line text argument, because that produces a single string:
jejune: arity mismatch;
the expected number of arguments does not match the given number
expected: 1
given: 3
arguments...:
"Deeply"
"\n"
- "chastened"
The answer is to use a rest argument in the function, which takes the “rest” of the arguments — however many there may be — and combines them into a single list. If we rewrite jejune with a rest argument, we can fix the problem:
The Pollen language is a variant of Racket’s own text-processing language, called Scribble. So many things that are true about Scribble are also true about Pollen. For the sake of clarity & brevity, I’ve omitted them from this summary. But if you want the full story, see @ Syntax in the Scribble documentation.
The answer is to use a rest argument in the function, which takes the “rest” of the arguments — however many there may be — and combines them into a single list. If we rewrite jejune with a rest argument, we can fix the problem:
The Pollen language is a variant of Racket’s own text-processing language, called Scribble. So many things that are true about Scribble are also true about Pollen. For the sake of clarity & brevity, I’ve omitted them from this summary. But if you want the full story, see @ Syntax in the Scribble documentation.
\ No newline at end of file
diff --git a/doc/result.png b/doc/result.png
new file mode 100644
index 0000000..929afc5
Binary files /dev/null and b/doc/result.png differ
diff --git a/scribblings/big-picture.scrbl b/scribblings/big-picture.scrbl
index 20c963a..4c278cd 100644
--- a/scribblings/big-picture.scrbl
+++ b/scribblings/big-picture.scrbl
@@ -1,6 +1,6 @@
#lang scribble/manual
-@title{The big picture}
+@title[#:tag "big-picture"]{The big picture}
A summary of the key components & concepts of the Pollen publishing system and how they fit together. If you've completed the @secref["quick-tour"], this will lend some context to what you saw. The next tutorials will make more sense if you read this first.
diff --git a/scribblings/dashboard.png b/scribblings/dashboard.png
new file mode 100644
index 0000000..6380e23
Binary files /dev/null and b/scribblings/dashboard.png differ
diff --git a/scribblings/file.scrbl b/scribblings/file.scrbl
index 72ccb69..1869af1 100644
--- a/scribblings/file.scrbl
+++ b/scribblings/file.scrbl
@@ -5,7 +5,7 @@
@(define my-eval (make-base-eval))
@(my-eval `(require pollen pollen/file))
-@title{File}
+@title[#:tag "file-types"]{File}
@defmodule[pollen/file]
diff --git a/scribblings/poem.scrbl b/scribblings/poem.scrbl
new file mode 100644
index 0000000..46c0c8e
--- /dev/null
+++ b/scribblings/poem.scrbl
@@ -0,0 +1,598 @@
+#lang scribble/manual
+
+@(require (for-label pollen/world))
+
+@title{First tutorial}
+
+In this tutorial, you'll use Pollen to make a single HTML page with a poem. You'll learn about:
+
+@itemlist[
+
+@item{The relationship of Racket & Pollen}
+
+@item{DrRacket}
+
+@item{The project server}
+
+@item{The preprocessor}
+
+]
+
+If you want the shortest possible introduction to Pollen, try the @secref["quick-tour"].
+
+@section{Prerequisites}
+
+I'm going to assume that you've already installed Racket and Pollen. If not, do that now.
+
+I'm also going to assume you know the basics of using a command line to run programs and navigate the file system using commands like @tt{cd} and @tt{ls}. On Mac OS X, your command-line program is called Terminal; on Windows it's the Windows Command Processor.
+
+@section{The relationship of Racket & Pollen}
+
+As I mentioned in the @secref["big-picture"], Pollen is built using Racket, and everything in Pollen ultimately becomes Racket code. If you're comfortable with that idea, you may move along.
+
+But if not, or if you're just a curious character:
+
+One of the key features of Racket as a programming language is that it provides tools to create @italic{other} programming languages. These languages might look & behave @link["http://docs.racket-lang.org/ts-guide/index.html"]{like Racket}. Or they @link["http://hashcollision.org/brainfudge/"]{might not}. These languages might serve a general purpose, but more often they're specialized for a particular purpose, in which case they're known as @italic{domain-specific languages}, or @italic{DSLs}.
+
+@margin-note{Racket exploits the fact that under the hood, all programming languages are basically doing the same thing. (CS jocks know this more formally as a side effect of @link["https://en.wikipedia.org/wiki/Turing_completeness"]{Turing completeness}.) Racket starts with the most general expression of a Turing-complete language — called @link["https://en.wikipedia.org/wiki/Lambda_calculus"]{the lambda calculus} — and lets users build on that. In most programming languages, you can build functions, classes, and modules. But in Racket, you can alter anything about the language.}
+
+If you find this a strange idea, you're not alone. Most programmers — and until recently, me too — have never made or used DSLs. If you have a programming problem to solve, you start with a general-purpose language like Python or Java or Ruby, and go from there. Nothing wrong with that.
+
+But programming languages contain their own design choices and compromises. Sometimes the problem at hand is best solved by manipulating the language at a deeper level. When you make a DSL, you're still programming in the underlying language, but doing so at a point of higher leverage.
+
+Pollen is a DSL implemented in Racket. It is a close cousin of @other-doc['(lib "scribblings/scribble/scribble.scrbl")], another Racket DSL, which was designed for writing Racket documentation. The key feature of Scribble, and thus also of Pollen, is that it's text-based. Meaning, whereas most languages have source files made of code with text embedded within, Pollen's source files are text with code embedded within.
+
+Moreover, Pollen is meant to be a small step away from Racket — you can think of it as a more convenient notation system for Racket code, similar to how Markdown is a more convenient notation for HTML. But unlike Markdown, which only lets you access a subset of HTML, anything that can be done in Racket can also be done in Pollen.
+
+As you work more with Pollen, you'll pick up more about how Pollen corresponds to Racket (see @secref["reader"]) and easily be able to convert commands from one system to the other. In later tutorials, you'll see how larger Pollen projects are made out of both Pollen and Racket source files.
+
+But in smaller projects, like this one, you can just use Pollen.
+
+@section{Starting a new file in DrRacket}
+
+DrRacket is the IDE for the Racket programming language, and other languages made with Racket (like Pollen). IDE stands for ``Integrated Development Environment,'' which is a fancy phrase for ``a nice place to edit and run your code.'' DrRacket is installed as part of the core Racket distribution.
+
+@margin-note{If you've worked with languages like Perl, Python, or Ruby, you may be more familiar with using a general-purpose text editor to edit your code, and then running your program at the command line. You can do that with Racket too. But DrRacket is a considerately designed tool. I recommend it. For these tutorials, I'll assume you're using DrRacket. If you insist on using the command line, I trust you to figure out what you need to do to keep up.}
+
+Launch DrRacket. Start a new file. The code in the file will look like this:
+
+@racketmod[racket]
+
+Within the main window, you should also see an @italic{interactions window}, which shows the output of the current file, and starts out looking something like this (details, like the version number, will vary):
+
+@verbatim{
+Welcome to DrRacket, version 6.0.1.6--2013-11-26(-/f) [3m].
+Language: racket; memory limit: 1000 MB.
+> }
+
+If you don't see the interactions window, select @menuitem["View"
+"Show Interactions"] from the menu.
+
+@subsection{Setting the @racketfont{#lang} line}
+
+The first line of every Racket source file, and every Pollen source file, is called the @italic{@racketfont{#lang} line}. The @racketfont{#lang} line identifies the language used to interpret the rest of the file.
+
+@margin-note{For more about the @racketfont{#lang} line, see @secref[#:doc '(lib "scribblings/guide/guide.scrbl") "hash-lang"].}
+
+When you start a new Pollen source file in DrRacket, you'll need to change the @racketfont{#lang} line to the Pollen language. The simplest way is to change the first line to this:
+
+@racketmod[pollen]
+
+Now run your file by clicking the @onscreen["Run"] button in the upper-right corner, or select @menuitem["Racket" "Run"] from the menu. You'll get something like:
+
+@verbatim{
+Welcome to DrRacket, version 6.0.1.6--2013-11-26(-/f) [3m].
+Language: pollen; memory limit: 1000 MB.
+>
+}
+
+Notice that the language is now reported as @racketfont{pollen}. If you like, change the @racketfont{#lang} line to this:
+
+@nested[#:style 'code-inset]{@verbatim{
+#lang pollenxyz}}
+
+Then click @onscreen["Run"] again. DrRacket will print an error:
+
+@verbatim{@racketerror{Module Language: invalid module text
+@(linebreak)standard-module-name-resolver: collection not found ...}}
+
+Why? Because there's no language called @racketfont{pollenxyz}. Switch it back to @racketfont{pollen} and let's move on.
+
+@subsection{Putting in the text of the poem}
+
+Here's a short, bad poem I wrote about CSS.
+
+@verbatim{
+The margin is 42em.
+The border is red.
+The padding is 15em.
+The border is too.
+}
+
+Paste the text of this poem into your DrRacket editing window, below the @racketfont{#lang} line, so it looks like this:
+
+@nested[#:style 'code-inset]{@verbatim{
+#lang pollen
+
+The margin is 42em.
+The border is red.
+The padding is 15em.
+The border is too.}}
+
+@onscreen["Run"] the file again. In the interactions window, you'll see:
+
+@racketvalfont{
+The margin is 8em.
+@(linebreak)The border is blue.
+@(linebreak)The padding is 2em.
+@(linebreak)The border is too.}
+
+This shows you something important: by default, any plain text in a Pollen source file is simply printed as written when you @onscreen["Run"] the file (minus the @racketfont{#lang} line, which is just for Racket's benefit). If you like, edit the text of the poem and click @onscreen["Run"] again. You'll see the updated text printed in the interactions window.
+
+@subsection{Saving & naming your source file}
+
+File naming in Pollen is consequential.
+
+Ultimately, every Pollen source file in your project will be @italic{rendered} into an output file. Each Pollen source file corresponds to one output file. @bold{The name of this output file will be the name of the source file minus the Pollen source extension.} So a source file called @racketfont{file.txt.pp} will become @racketfont{file.txt}.
+
+Thus, to build the name of a source file, we take the name we want for the output file and add the appropriate Pollen file extension. Different Pollen source files use different extensions — but more about that later. For now, the extension you'll use for your source is @racketfont{.pp}.
+
+In this case, let's say we want to end up with a file called @racketfont{poem.html}. Therefore, the name of our source file needs to be:
+
+the output name @racketfont{poem.html} + the source extension @racketfont{.pp} = @racketfont{poem.html.pp}
+
+(If you want to name the file @racketfont{something-else.html.pp}, be my guest. There's no magic associated with the prefix.)
+
+@margin-note{You're welcome to change the name of your source files from the desktop. On Mac OS X and Windows, however, the desktop interface often hides file extensions, so check the properties of the file afterward to make sure you got the name you expected.}
+
+In a convenient location (e.g., your home directory or the desktop) create a new directory for your project called @racketfont{tutorial}. In this new directory, save your DrRacket file as @racketfont{poem.html.pp}.
+
+@filebox["/path/to/tutorial/poem.html.pp"]{@verbatim{
+#lang pollen
+
+The margin is 42em.
+The border is red.
+The padding is 15em.
+The border is too.}}
+
+
+@section{Using the project server}
+
+The project server is a web server built into Pollen. Just as DrRacket lets you run individual files and see if they work as you expect, the project server lets you preview and test your project as a real website. While working on your Pollen project, you may find it convenient to have DrRacket open on half your screen, and on the other half, a web browser pointing at the project server.
+
+@image["scribblings/project-server.png" #:scale 0.7]
+
+``Why can't I just open the HTML files directly in my browser?'' If you want to keep making web pages the way we did in 1996, go ahead. But that approach has several shortcomings. First, when you open files directly in your browser, you're cruising the local filesystem, and absolute URLs (the kind that start with a @litchar{/}) won't work. Second, if you want to test your website on devices other than your own machine — well, you can't. Third, you have to render your HTML files in advance, whereas the project server is clever about doing this dynamically.
+
+So use the project server.
+
+A note about security. The project server isn't intended for real-world use, but rather as a development tool. That said, once you start the project server, it's an actual web server running on your machine, and it will respond to requests from any computer. If you want to limit traffic to your local network, or certain machines on your local network, it's your job — not mine — to configure your firewall or other network security measures accordingly.
+
+
+
+@subsection{Starting the project server with @racketfont{raco pollen}}
+
+Before we start the project server, a word about the @racketfont{raco pollen} command.
+
+When you installed Racket, Racket installed a utility program called @racketfont{raco}. This name is short for @bold{Ra}cket @bold{co}mmand, and @racketfont{raco} acts as a hub for — you guessed it — Racket commands. You used it when you first installed Pollen:
+
+@verbatim{
+> raco pkg install pollen
+}
+
+The first argument after @racketfont{raco} is the subcommand. For instance, @racketfont{raco pkg ...} lets you install, update, and remove packages like so:
+
+@verbatim{
+> raco pkg update pollen
+> raco pkg remove pollen
+}
+
+Likewise, @racketfont{raco pollen} lets you issue commands relevant to Pollen, like starting the project server. (See @secref["raco-pollen"] for a full description of available commands.)
+
+Now we'll start the project server. Go to your command line and enter the following:
+
+@verbatim{
+> cd /path/to/tutorial
+> raco pollen start}
+
+@margin-note{Windows users, I'll trust you to convert @racketfont{raco} into the appropriate command for your system — assuming defaults, it's likely to be @racketfont{"C:\Program Files\Racket\raco"} (include the surrounding quotes in the command).}
+
+After a moment, you'll see a startup message like this:
+
+@verbatim{
+Welcome to Pollen 0.001 (Racket 6.x.x.x)
+Project root is /path/to/tutorial
+Project server is http://localhost:8080 (Ctrl-C to exit)
+Project dashboard is http://localhost:8080/index.ptree
+Ready to rock}
+
+@italic{Project root} means the directory that the project server was started in, and which it's treating as its root directory. Any absolute URLs (i.e., those beginning with @litchar{/}) will resolve into this directory. So a URL like @racketfont{/styles.css} will impliedly become @racketfont{/path/to/tutorial/styles.css}.
+
+If you use the bare command @racketfont{raco pollen start}, the project server will start in the current directory. But if you want to start the project server elsewhere, you can add that directory as an argument like this:
+
+@verbatim{
+> raco pollen start /some/other/path
+}
+
+The next line of the startup message tells you that the web address of the project server is @racketfont{http://localhost:8080}. This is the address you put into your web browser to test your project. If you're unfamiliar with this style of URL, @racketfont{localhost} refers to your own machine, and @racketfont{8080} is the network port where the project server will respond to browser requests.
+
+If you want to access the project server from a different machine, you can't use @racketfont{localhost}. But you can use the IP address of the machine running the project server (e.g., @racketfont{http://192.168.1.10:8080}) or any name for that machine available through local DNS (e.g., @racketfont{http://mb-laptop:8080}).
+
+Though port @racketfont{8080} is the default, you can start the project server on any port you like by adding it as an argument to @racketfont{raco pollen start}:
+
+@verbatim{
+> raco pollen start /path/to/tutorial
+> raco pollen start /path/to/tutorial 8088
+}
+
+@margin-note{You can also change the default port by altering @racket[world:default-port], or parameterizing it with @racket[world:current-server-port].}
+
+Note that when you pass a port argument, you also have to pass a path argument. If you want the project server to start in the current directory, you can use the usual @litchar{.} shorthand:
+
+@verbatim{
+> cd /path/to/tutorial
+> raco pollen start 8088
+@racketerror{/path/to/tutorial/8088 is not a directory}
+> raco pollen start . 8088
+}
+
+@margin-note{You can run multiple project servers simultaneously. Just start them on different ports so they don't conflict with each other.}
+
+Your terminal window will report status and error messages from the project server as it runs. Use @onscreen{Ctrl-C} to stop the server.
+
+
+@subsection{Using the dashboard}
+
+For each directory in your project, starting at the top, the project server displays a @italic{dashboard} in your web browser. The dashboard gives you an overview of the files in the directory, and links to view them.
+
+The address of the top-level dashboard is @racketfont{http://localhost:8080/index.ptree}. Other dashboards follow the same pattern (e.g., @racketfont{http://localhost:8080/path/to/dir/index.ptree}.)
+
+Note that the dashboard is @bold{not} at @racketfont{http://localhost:8080/} or its equivalent, @racketfont{http://localhost:8080/index.html}. Why? So it doesn’t interfere with any @racketfont{index.html} that you may want to put in your project.
+
+Thus, @racketfont{index.ptree}. The @racketfont{.ptree} extension is short for @italic{pagetree}. In Pollen, a pagetree is a hierarchical list of pages. We'll do more with pagetrees in a later tutorial. For now, just be aware that to generate the dashboard, the project server will first look for an actual @racketfont{index.ptree} file in each directory. If it doesn't find one, it will generate a pagetree from a listing of files in the directory.
+
+Let's look at the root-level dashboard for our project. First, make sure your project server is running:
+
+@verbatim{
+> cd /path/to/tutorial
+> raco pollen start
+}
+
+Then, in your web browser, visit @link["http://localhost:8080/index.ptree"]{@racketfont{http://localhost:8080/index.ptree}}.
+
+You should see something like this:
+
+@image["scribblings/dashboard.png" #:scale 1]
+
+The top line tells us that we're in the root directory of the project. We didn't make an explicit @racketfont{index.ptree} file, so the project server just shows us a directory listing.
+
+
+@subsection{Source files in the dashboard}
+
+We see the only file, @racketfont{poem.html.pp}. Note that the @racketfont{.pp} extension is grayed out. The dashboard automatically consolidates references to source and output files into a single entry. What this entry says is ``The directory contains a source file in @racketfont{.pp} format for the output file @racketfont{poem.html}.''
+
+Every source-file entry in the dashboard has three links. The first link is attached to the filename itself, and takes you to a preview of the output file. If the output file doesn't yet exist — as is the case here — it will be dynamically rendered. (This is true whether you click its name in the dashboard, or link to it from another page.) So click the filename. You'll see in your web browser:
+
+@nested[#:style 'code-inset]{
+The margin is 42em. The border is red. The padding is 15em. The border is too.}
+
+Granted, this is a boring web page. The main point here is that you're seeing the @italic{output} from your source file, which didn't exist before. Notice that the address bar says @racketfont{http://localhost:8080/poem.html}, not @racketfont{poem.html.pp}. And if you look in your @racketfont{tutorial} directory, you'll see a new file called @racketfont{poem.html}.
+
+In other words, when you clicked on the filename link in the dashboard, Pollen rendered the output file from your source file and saved it in your project directory. As promised earlier, the name of the output file (@racketfont{poem.html}) is the name of the source file (@racketfont{poem.html.pp}) minus the Pollen extension (@racketfont{.pp}).
+
+If you go back to the dashboard and click on the filename link again, you'll see the same output file. If the source file hasn't changed, Pollen will just show you the output file that's already been rendered.
+
+But if you like, open your @racketfont{poem.html.pp} source file in DrRacket, edit the first line, and save the file:
+
+@nested[#:style 'code-inset]{@verbatim{
+#lang pollen
+
+The cave is pitch black.
+Look out for the grue.
+The padding is 15em.
+The border is too.}}
+
+Go back to the dashboard and click on the filename. This time, you'll see:
+
+@nested[#:style 'code-inset]{
+The cave is pitch black. Look out for the grue. The padding is 15em. The border is too.}
+
+Here, Pollen notices that the source file has changed, so it refreshes the output file. This makes it convenient to work between DrRacket and your web browser, editing source and then reloading to see the changes.
+
+The other two links in the dashboard are labeled @racketfont{in} and @racketfont{out}.
+
+The link labeled @racketfont{in} will display the contents of the source file:
+
+@nested[#:style 'code-inset]{@verbatim{
+#lang pollen
+
+The cave is pitch black.
+Look out for the grue.
+The padding is 15em.
+The border is too.}}
+
+The link labeled @racketfont{out} will display the contents of the output file (just like the ``view source'' option in your web browser):
+
+@nested[#:style 'code-inset]{@verbatim{
+The cave is pitch black.
+Look out for the grue.
+The padding is 15em.
+The border is too.}}
+
+For now, the files are identical except for the @racketfont{#lang} line. But let's change that.
+
+@section{Working with the preprocessor}
+
+Pollen can operate in several processing modes. One of these is @italic{preprocessor} mode. A preprocessor is a tool for making systematic, automated changes to a file, often in contemplation of further processing (hence the @italic{pre-}). You can use the Pollen preprocessor this way. Or you can just use it on its own, and leave your files in a finished state.
+
+That's how we'll use it in this tutorial. We'll build out our @racketfont{poem.html.pp} source file so that it exits the preprocessor as a legit HTML file.
+
+@subsection{Setting up a preprocessor source file}
+
+The file extension of a Pollen source file tells Pollen what kind of processing to apply to it. The ``@racketfont{.pp}'' file extension stands for ``Pollen preprocessor.'' You can use the preprocessor with any text-based file by:
+@itemlist[
+
+@item{inserting @racketfont{#lang pollen} as the first line,}
+
+@item{adding the @racketfont{.pp} file extension,}
+
+@item{running it through Pollen.}
+]
+
+@margin-note{For more about the Pollen processing modes and how to invoke them, see @secref["file-types"].}
+
+``The preprocessor be used with @bold{any} kind of text-based file?'' Right. ``But how?'' The preprocessor reads the source file, handles any Pollen commands it finds, and lets the rest of the content pass through untouched. To the preprocessor, it's all just text data. It doesn't care whether that text represents HTML, CSS, JavaScript, or even @link["https://en.wikipedia.org/wiki/TI-BASIC"]{TI-BASIC}.
+
+Because the preprocessor only deals in text, the Pollen commands you use in the preprocessor also have to produce text. Moreover, Pollen doesn't enforce the semantics of the underlying file — that's your responsibility. For instance, Pollen won't stop you from doing nonsensical things like this:
+
+@filebox["bad-poem.html.pp"]{@verbatim{
+#lang pollen
+
+The cave is pitch black.
+Look out for the grue.
+◊(insert-mp3-recording-of-scream)
+ }}
+
+Here, the result is not going to be valid HTML, because you can't simply drop binary data in the middle of an HTML file. To paraphrase Mr. Babbage — garbage in, garbage out.
+
+I've encouraged you to mess with the source file, but let's return it to its original state:
+
+@filebox["/path/to/tutorial/poem.html.pp"]{@verbatim{
+#lang pollen
+
+The margin is 42em.
+The border is red.
+The padding is 15em.
+The border is too.}}
+
+This file has @racketfont{#lang pollen} as the first line, and @racketfont{.pp} as the file extension, so it meets the minimum requirements for the preprocessor.
+
+@subsection{Creating valid HTML output}
+
+Let's update our source so it produces valid HTML. Edit the source as follows:
+
+@filebox["/path/to/tutorial/poem.html.pp"]{@verbatim{
+#lang pollen
+
+
+
+
+The margin is 42em.
+The border is red.
+The padding is 15em.
+The border is too.
+
+
+}}
+
+Return to the project server and view @link["http://localhost:8080/poem.html" "http://localhost:8080/poem.html"]. Earlier, the output looked like this:
+
+@nested[#:style 'code-inset]{
+The margin is 42em. The border is red. The padding is 15em. The border is too.}
+
+
+But now, because of the @racketfont{
} tag, the poem will appear in a monospaced font, and the line breaks will be preserved:
+
+@nested[#:style 'code-inset]{
+@tt{The margin is 42em.
+@(linebreak)The border is red.
+@(linebreak)The padding is 15em.
+@(linebreak)The border is too.}}
+
+As before, because the source has changed, Pollen refreshes the output file. From the dashboard, you can use the @racketfont{in} and @racketfont{out} links to inspect the source and output.
+
+This is now a valid HTML page.
+
+@subsection{Adding commands}
+
+I mentioned that the preprocessor reads the file and handles any Pollen commands it finds. But our source file doesn't have any commands yet. Let's add some.
+
+Pollen commands can be embedded in your source file using one of two modes: @italic{Racket mode} or @italic{text mode}. We'll try text mode in a later tutorial. For now, we'll use Racket mode.
+
+To make a Racket-mode Pollen command, just take any Racket expression and put the lozenge character (@litchar["◊"]) in front of it. For instance, these are valid Racket expressions:
+
+@nested[#:style 'code-inset]{@verbatim{
+ (define inner 2)
+ (define edge (* inner 4))
+ (define color "blue")
+}}
+
+And these are the equivalent commands in Pollen:
+
+@nested[#:style 'code-inset]{@verbatim{
+ ◊(define inner 2)
+ ◊(define edge (* inner 4))
+ ◊(define color "blue")
+}}
+
+@subsection{Racket basics (if you're not familiar)}
+
+
+``But how am I supposed to know Racket?'' You don't. So we'll start now. Here are the five basic rules of Racket:
+
+@itemlist[#:style 'ordered
+
+@item{The core building block of Racket is the @italic{expression}. An expression can be a value (like @racket[2] or @racket{blue}), a variable (like @racketfont{edge}), or a function call (like @racket[(* inner 4)]).}
+
+@item{Every expression is @italic{evaluated} to produce a value.}
+
+@item{A variable evaluates to whatever value it holds (so @racketfont{inner} would become @racket[2]). A function call evaluates to its return value (so @racket[(+ 1 1)] would become @racket[2]).}
+
+@item{Function calls go between parentheses. Unlike most languages, the function name comes @italic{first}, followed by its arguments (so it's @racket[(* inner 4)], not @racket[(inner * 4)]). This is called @italic{prefix notation}.}
+
+@item{Expressions can contain recursively nested expressions. Thus, @racket[(* inner 4)] could be written @racket[(* inner (+ 2 2))] or @racket[(* inner (+ (+ 1 1) (+ 1 1)))].}
+
+]
+
+@margin-note{Newcomers to Racket often gripe about prefix notation and the parentheses. If you need to get it out of your system, go ahead. Keep in mind, however, that it's not some peculiar affectation, but rather a necessary consequence of rule #1. As you'll come to learn, rule #1 is where the magic happens.}
+
+That should tell you enough to infer what's going on in the Pollen commands above:
+
+@nested[#:style 'code-inset]{@verbatim{
+ ◊(define inner 2)
+ ◊; create a variable 'inner' that holds the value 2
+ ◊(define edge (* inner 4))
+ ◊; create a variable 'edge' that's four times the value of 'inner'
+ ◊(define color "blue")
+ ◊; create a variable 'color' that holds the value "blue"
+}}
+
+To learn more about Racket syntax, consider a detour through the excellent @other-doc['(lib "scribblings/quick/quick.scrbl")].
+
+
+@subsection{Defining variables with commands}
+
+Let's use commands to define variables that will hold some values for our page. First, add a @racketfont{} tag to your source file, and three commmands to define three variables:
+
+@filebox["/path/to/tutorial/poem.html.pp"]{@verbatim{
+#lang pollen
+
+
+
+◊(define inner 2)
+◊(define edge (* inner 4))
+◊(define color "blue")
+
+
+
+The margin is 42em.
+The border is red.
+The padding is 15em.
+The border is too.
+
+
+}}
+
+Then look at @link["http://localhost:8080/poem.html" "http://localhost:8080/poem.html"] again. Does it look the same? Not a trick question — it should. If you click the @onscreen{Out} link on the dashboard, you'll see this:
+
+@nested[#:style 'code-inset]{@verbatim{
+
+
+
+
+
+
+
+
+
+The margin is 42em.
+The border is red.
+The padding is 15em.
+The border is too.
+
+
+}}
+
+What's happening here? Our @racketfont{◊(define ...)} commands just define variables, so they don't evaluate to any value. Instead, we get blank lines. So far, so good.
+
+@subsection{Inserting values from variables}
+
+To insert the value of a variable in our file, we use the command @litchar{◊|}@italic{variable-name}@litchar{|}. Let's do that now:
+
+@filebox["/path/to/tutorial/poem.html.pp"]{@verbatim{
+#lang pollen
+
+
+
+◊(define inner 2)
+◊(define edge (* inner 4))
+◊(define color "blue")
+
+
+
+The margin is ◊|edge|em.
+The border is ◊|color|.
+The padding is ◊|inner|em.
+The border is too.
+
+
+}}
+
+Here, we're replacing three values in the poem with the variables containing those values — @racketfont{◊|edge|}, @racketfont{◊|color|}, and @racketfont{◊|inner|}. @link["http://localhost:8080/poem.html"]{Reload the file} in the project server, and you'll see:
+
+@nested[#:style 'code-inset]{@verbatim{
+The margin is 8em.
+The border is blue.
+The padding is 2em.
+The border is too.}}
+
+Hey, look at that — the text of the poem changed. Now it even rhymes.
+
+If you like, in the source file, edit the variable definitions with different values and reload the page in the project server. The page will be rendered afresh with the new values. In particular, if you update @racketfont{inner}, you'll also see @racketfont{edge} change, since its value depends on @racketfont{inner}.
+
+@subsection{Inserting variables within CSS}
+
+Our poem makes claims about the @racketfont{margin}, @racketfont{border}, and @racketfont{padding} of the page that aren't yet true. To fix this, we'll rely on the same basic technique of inserting variables into our HTML file. But instead of putting them in the @racketfont{} of the page, we'll put them in a CSS @racketfont{
+
+
+
+The margin is ◊|edge|em.
+The border is ◊|color|.
+The padding is ◊|inner|em.
+The border is too.
+
+
+}}
+
+Notice that we're using the same @litchar{◊|}@italic{variable-name}@litchar{|} pattern as before to insert the variable values.
+
+What do we expect to see? We expect that the @racketfont{padding} and @racketfont{border} will be 2em wide, because @racketfont{inner} is 2. We expect the @racketfont{margin} to be 8em, because it's equal to @racketfont{edge}, which is @racketfont{inner} multiplied by 4. And we expect the color of the border to be @racket["blue"], because that's the value of the variable @racketfont{color}.
+
+And indeed, when you @link["http://localhost:8080/poem.html"]{reload the file} in the project server, you'll see exactly that:
+
+@image["scribblings/result.png" #:scale 0.7]
+
+
+As before, if you edit the values of the variables in the source file and reload in the project server, you'll see both the text and the layout change.
+
+
+@section{First tutorial complete}
+
+This was a sneaky tutorial. The HTML page we made was very simple, but in building it, we covered many important points about how Pollen works.
+
+Feel free to go back and experiment with what you've learned. The next tutorial will assume that you're comfortable with all the material here.
+
+
+
+
+
+
diff --git a/scribblings/pollen.scrbl b/scribblings/pollen.scrbl
index a5d111e..50c6072 100644
--- a/scribblings/pollen.scrbl
+++ b/scribblings/pollen.scrbl
@@ -47,6 +47,8 @@ Or, if you can find a better digital-publishing tool, use that. But I'm never go
@include-section["big-picture.scrbl"]
+@include-section["poem.scrbl"]
+
@include-section["raco.scrbl"]
@include-section["formats.scrbl"]
diff --git a/scribblings/project-server.png b/scribblings/project-server.png
new file mode 100644
index 0000000..19131b1
Binary files /dev/null and b/scribblings/project-server.png differ
diff --git a/scribblings/raco.scrbl b/scribblings/raco.scrbl
index aff982d..5d67b34 100644
--- a/scribblings/raco.scrbl
+++ b/scribblings/raco.scrbl
@@ -6,7 +6,7 @@
@(my-eval `(require pollen pollen/file))
-@title{Using @exec{raco pollen}}
+@title[#:tag "raco-pollen"]{Using @exec{raco pollen}}
Racket provides centralized command-line options through @racket[raco] (short for @code{racket command}, see @other-doc['(lib "scribblings/raco/raco.scrbl")]).
@@ -30,6 +30,8 @@ But if you get:
You'll need to fix the problem before proceeding, most likely by reinstalling Pollen (see @racket[Installation]).
+@margin-note{Pro tip: I have an alias in my @racketfont{.bash_profile} like so: @racketfont{alias polcom=@literal{'}raco pollen@literal{'}}}
+
@section{@racket[raco pollen]}
Same as @racket[raco pollen help].
diff --git a/scribblings/result.png b/scribblings/result.png
new file mode 100644
index 0000000..929afc5
Binary files /dev/null and b/scribblings/result.png differ
diff --git a/tutorial/index.html b/tutorial/index.html
new file mode 100644
index 0000000..455575b
--- /dev/null
+++ b/tutorial/index.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+
+
Introduction
This tutorial provides a brief introduction to the Racket programming language by using one of its picture-drawing libraries. Even if you don’t intend to use Racket for your artistic endeavours, the picture library supports interesting and enlightening examples. After all, a picture is worth five hundred "hello world"s.
Along the same lines, we assume that you will run the examples using DrRacket. Using DrRacket is the fastest way to get a sense of what the language and system feels like, even if you eventually use Racket with Emacs, vi, or some other editor.
To draw pictures, we must first load some picture functions, which are part of a library for creating slide presentations. Copy the following into the definitions area, which is the top text area that you see in DrRacket:
#lang slideshow
Then click the Run button. You’ll see the text caret move to the bottom text area, which is the interactions area.
If you’ve used DrRacket before, you might need to reset DrRacket to use the language declared in the source via the Language|Choose Language… menu item before clicking Run.
Go!
When you type an expression after the > in the interactions window and hit Enter, DrRacket evaluates the expression and prints its result. An expression can be just a value, such as the number 5 or the string “art gallery”:
> 5
+5
+> "art gallery"
+"art gallery"
An expression can also be a function call. To call a function, put an open parenthesis before the function name, then expressions for the function arguments, and then a close parenthesis.
+
+
\ No newline at end of file
diff --git a/tutorial/index.html.pmd b/tutorial/index.html.pmd
new file mode 100644
index 0000000..2014549
--- /dev/null
+++ b/tutorial/index.html.pmd
@@ -0,0 +1,41 @@
+#lang pollen
+
+
+
+Introduction
+============
+
+This tutorial provides a brief introduction to the Racket programming language by using one of its picture-drawing libraries. Even if you don’t intend to use Racket for your artistic endeavours, the picture library supports interesting and enlightening examples. After all, a picture is worth five hundred "hello world"s.
+
+Along the same lines, we assume that you will run the examples using [DrRacket](http://racket-lang.org/). Using DrRacket is the fastest way to get a sense of what the language and system feels like, even if you eventually use Racket with Emacs, vi, or some other editor.
+
+## Ready...
+
+[Download Racket](http://racket-lang.org/), install, and then start DrRacket.
+
+## Set...
+
+> See [the DrRacket documentation](file:///Users/MB/git/racket/racket/doc/drracket/interface-essentials.html) for a brief overview of the DrRacket IDE.
+
+To draw pictures, we must first load some picture functions, which are part of a library for creating slide presentations. Copy the following into the *definitions area*, which is the top text area that you see in DrRacket:
+
+```
+#lang slideshow
+```
+
+Then click the Run button. You’ll see the text caret move to the bottom text area, which is the *interactions area*.
+
+If you’ve used DrRacket before, you might need to reset DrRacket to use the language declared in the source via the **Language|Choose Language...** menu item before clicking **Run**.
+
+## Go!
+
+When you type an expression after the > in the interactions window and hit Enter, DrRacket evaluates the expression and prints its result. An expression can be just a value, such as the number 5 or the string "art gallery":
+
+```
+> 5
+5
+> "art gallery"
+"art gallery"
+```
+
+An expression can also be a function call. To call a function, put an open parenthesis before the function name, then expressions for the function arguments, and then a close parenthesis.
\ No newline at end of file
diff --git a/tutorial/play/act 1.pmd b/tutorial/play/act 1.pmd
new file mode 100644
index 0000000..34a485a
--- /dev/null
+++ b/tutorial/play/act 1.pmd
@@ -0,0 +1,199 @@
+#lang pollen
+
+Morning-room in Algernon’s flat in Half-Moon Street. The room is luxuriously and artistically furnished. The sound of a piano is heard in the adjoining room.
+
+[**Lane** is arranging afternoon tea on the table, and after the music has ceased, **Algernon** enters.]
+
+**Algernon.** Did you hear what I was playing, Lane?
+
+**Lane.** I didn’t think it polite to listen, sir.
+
+**Algernon.** I’m sorry for that, for your sake. I don’t play accurately—any one can play accurately—but I play with wonderful expression. As far as the piano is concerned, sentiment is my forte. I keep science for Life.
+
+**Lane.** Yes, sir.
+
+**Algernon.** And, speaking of the science of Life, have you got the cucumber sandwiches cut for Lady Bracknell?
+
+**Lane.** Yes, sir. [Hands them on a salver.]
+
+**Algernon.** [Inspects them, takes two, and sits down on the sofa.] Oh! . . . by the way, Lane, I see from your book that on Thursday night, when Lord Shoreman and Mr. Worthing were dining with me, eight bottles of champagne are entered as having been consumed.
+
+**Lane.** Yes, sir; eight bottles and a pint.
+
+**Algernon.** Why is it that at a bachelor’s establishment the servants invariably drink the champagne? I ask merely for information.
+
+**Lane.** I attribute it to the superior quality of the wine, sir. I have often observed that in married households the champagne is rarely of a first-rate brand.
+
+**Algernon.** Good heavens! Is marriage so demoralising as that?
+
+**Lane.** I believe it _is_ a very pleasant state, sir. I have had very little experience of it myself up to the present. I have only been married once. That was in consequence of a misunderstanding between myself and a young person.
+
+**Algernon.** [Languidly.] I don’t know that I am much interested in your family life, Lane.
+
+**Lane.** No, sir; it is not a very interesting subject. I never think of it myself.
+
+**Algernon.** Very natural, I am sure. That will do, Lane, thank you.
+
+**Lane.** Thank you, sir. [**Lane** goes out.]
+
+**Algernon.** Lane's views on marriage seem somewhat lax. Really, if the lower orders don’t set us a good example, what on earth is the use of them? They seem, as a class, to have absolutely no sense of moral responsibility.
+
+[Enter **Lane**.]
+
+**Lane.** Mr. Ernest Worthing.
+
+[Enter **Jack**.]
+
+[**Lane** goes out.]
+
+**Algernon.** How are you, my dear Ernest? What brings you up to town?
+
+**Jack.** Oh, pleasure, pleasure! What else should bring one anywhere? Eating as usual, I see, Algy!
+
+**Algernon.** [Stiffly.] I believe it is customary in good society to take some slight refreshment at five o’clock. Where have you been since last Thursday?
+
+**Jack.** [Sitting down on the sofa.] In the country.
+
+**Algernon.** What on earth do you do there?
+
+**Jack.** [Pulling off his gloves.] When one is in town one amuses oneself. When one is in the country one amuses other people. It is excessively boring.
+
+**Algernon.** And who are the people you amuse?
+
+**Jack.** [Airily.] Oh, neighbours, neighbours.
+
+**Algernon.** Got nice neighbours in your part of Shropshire?
+
+**Jack.** Perfectly horrid! Never speak to one of them.
+
+**Algernon.** How immensely you must amuse them! [Goes over and takes sandwich.] By the way, Shropshire is your county, is it not?
+
+**Jack.** Eh? Shropshire? Yes, of course. Hallo! Why all these cups? Why cucumber sandwiches? Why such reckless extravagance in one so young? Who is coming to tea?
+
+**Algernon.** Oh! merely Aunt Augusta and Gwendolen.
+
+**Jack.** How perfectly delightful!
+
+**Algernon.** Yes, that is all very well; but I am afraid Aunt Augusta won’t quite approve of your being here.
+
+**Jack.** May I ask why?
+
+**Algernon.** My dear fellow, the way you flirt with Gwendolen is perfectly disgraceful. It is almost as bad as the way Gwendolen flirts with you.
+
+**Jack.** I am in love with Gwendolen. I have come up to town expressly to propose to her.
+
+**Algernon.** I thought you had come up for pleasure? . . . I call that business.
+
+**Jack.** How utterly unromantic you are!
+
+**Algernon.** I really don’t see anything romantic in proposing. It is very romantic to be in love. But there is nothing romantic about a definite proposal. Why, one may be accepted. One usually is, I believe. Then the excitement is all over. The very essence of romance is uncertainty. If ever I get married, I’ll certainly try to forget the fact.
+
+**Jack.** I have no doubt about that, dear Algy. The Divorce Court was specially invented for people whose memories are so curiously constituted.
+
+**Algernon.** Oh! there is no use speculating on that subject. Divorces are made in Heaven—[**Jack** puts out his hand to take a sandwich. **Algernon** at once interferes.] Please don’t touch the cucumber sandwiches. They are ordered specially for Aunt Augusta. [Takes one and eats it.]
+
+**Jack.** Well, you have been eating them all the time.
+
+**Algernon.** That is quite a different matter. She is my aunt. [Takes plate from below.] Have some bread and butter. The bread and butter is for Gwendolen. Gwendolen is devoted to bread and butter.
+
+**Jack.** [Advancing to table and helping himself.] And very good bread and butter it is too.
+
+**Algernon.** Well, my dear fellow, you need not eat as if you were going to eat it all. You behave as if you were married to her already. You are not married to her already, and I don’t think you ever will be.
+
+**Jack.** Why on earth do you say that?
+
+**Algernon.** Well, in the first place girls never marry the men they flirt with. Girls don’t think it right.
+
+**Jack.** Oh, that is nonsense!
+
+**Algernon.** It isn’t. It is a great truth. It accounts for the extraordinary number of bachelors that one sees all over the place. In the second place, I don’t give my consent.
+
+**Jack.** Your consent!
+
+**Algernon.** My dear fellow, Gwendolen is my first cousin. And before I allow you to marry her, you will have to clear up the whole question of Cecily. [Rings bell.]
+
+**Jack.** Cecily! What on earth do you mean? What do you mean, Algy, by Cecily! I don’t know any one of the name of Cecily.
+
+[Enter **Lane**.]
+
+**Algernon.** Bring me that cigarette case Mr. Worthing left in the smoking-room the last time he dined here.
+
+**Lane.** Yes, sir. [**Lane** goes out.]
+
+**Jack.** Do you mean to say you have had my cigarette case all this time? I wish to goodness you had let me know. I have been writing frantic letters to Scotland Yard about it. I was very nearly offering a large reward.
+
+**Algernon.** Well, I wish you would offer one. I happen to be more than usually hard up.
+
+**Jack.** There is no good offering a large reward now that the thing is found.
+
+[Enter **Lane** with the cigarette case on a salver. **Algernon** takes it at once. **Lane** goes out.]
+
+**Algernon.** I think that is rather mean of you, Ernest, I must say. [Opens case and examines it.] However, it makes no matter, for, now that I look at the inscription inside, I find that the thing isn’t yours after all.
+
+**Jack.** Of course it’s mine. [Moving to him.] You have seen me with it a hundred times, and you have no right whatsoever to read what is written inside. It is a very ungentlemanly thing to read a private cigarette case.
+
+**Algernon.** Oh! it is absurd to have a hard and fast rule about what one should read and what one shouldn’t. More than half of modern culture depends on what one shouldn’t read.
+
+**Jack.** I am quite aware of the fact, and I don’t propose to discuss modern culture. It isn’t the sort of thing one should talk of in private. I simply want my cigarette case back.
+
+**Algernon.** Yes; but this isn’t your cigarette case. This cigarette case is a present from some one of the name of Cecily, and you said you didn’t know any one of that name.
+
+**Jack.** Well, if you want to know, Cecily happens to be my aunt.
+
+**Algernon.** Your aunt!
+
+**Jack.** Yes. Charming old lady she is, too. Lives at Tunbridge Wells. Just give it back to me, Algy.
+
+**Algernon.** [Retreating to back of sofa.] But why does she call herself little Cecily if she is your aunt and lives at Tunbridge Wells? [Reading.] ‘From little Cecily with her fondest love.’
+
+**Jack.** [Moving to sofa and kneeling upon it.] My dear fellow, what on earth is there in that? Some aunts are tall, some aunts are not tall. That is a matter that surely an aunt may be allowed to decide for herself. You seem to think that every aunt should be exactly like your aunt! That is absurd! For Heaven’s sake give me back my cigarette case. [Follows **Algernon** round the room.]
+
+**Algernon.** Yes. But why does your aunt call you her uncle? ‘From little Cecily, with her fondest love to her dear Uncle Jack.’ There is no objection, I admit, to an aunt being a small aunt, but why an aunt, no matter what her size may be, should call her own nephew her uncle, I can’t quite make out. Besides, your name isn’t Jack at all; it is Ernest.
+
+**Jack.** It isn’t Ernest; it’s Jack.
+
+**Algernon.** You have always told me it was Ernest. I have introduced you to every one as Ernest. You answer to the name of Ernest. You look as if your name was Ernest. You are the most earnest-looking person I ever saw in my life. It is perfectly absurd your saying that your name isn’t Ernest. It’s on your cards. Here is one of them. [Taking it from case.] ‘Mr. Ernest Worthing, B. 4, The Albany.’ I’ll keep this as a proof that your name is Ernest if ever you attempt to deny it to me, or to Gwendolen, or to any one else. [Puts the card in his pocket.]
+
+**Jack.** Well, my name is Ernest in town and Jack in the country, and the cigarette case was given to me in the country.
+
+**Algernon.** Yes, but that does not account for the fact that your small Aunt Cecily, who lives at Tunbridge Wells, calls you her dear uncle. Come, old boy, you had much better have the thing out at once.
+
+**Jack.** My dear Algy, you talk exactly as if you were a dentist. It is very vulgar to talk like a dentist when one isn’t a dentist. It produces a false impression,
+
+**Algernon.** Well, that is exactly what dentists always do. Now, go on! Tell me the whole thing. I may mention that I have always suspected you of being a confirmed and secret Bunburyist; and I am quite sure of it now.
+
+**Jack.** Bunburyist? What on earth do you mean by a Bunburyist?
+
+**Algernon.** I’ll reveal to you the meaning of that incomparable expression as soon as you are kind enough to inform me why you are Ernest in town and Jack in the country.
+
+**Jack.** Well, produce my cigarette case first.
+
+**Algernon.** Here it is. [Hands cigarette case.] Now produce your explanation, and pray make it improbable. [Sits on sofa.]
+
+**Jack.** My dear fellow, there is nothing improbable about my explanation at all. In fact it’s perfectly ordinary. Old Mr. Thomas Cardew, who adopted me when I was a little boy, made me in his will guardian to his grand-daughter, Miss Cecily Cardew. Cecily, who addresses me as her uncle from motives of respect that you could not possibly appreciate, lives at my place in the country under the charge of her admirable governess, Miss Prism.
+
+**Algernon.** Where is that place in the country, by the way?
+
+**Jack.** That is nothing to you, dear boy. You are not going to be invited . . . I may tell you candidly that the place is not in Shropshire.
+
+**Algernon.** I suspected that, my dear fellow! I have Bunburyed all over Shropshire on two separate occasions. Now, go on. Why are you Ernest in town and Jack in the country?
+
+**Jack.** My dear Algy, I don’t know whether you will be able to understand my real motives. You are hardly serious enough. When one is placed in the position of guardian, one has to adopt a very high moral tone on all subjects. It’s one’s duty to do so. And as a high moral tone can hardly be said to conduce very much to either one’s health or one’s happiness, in order to get up to town I have always pretended to have a younger brother of the name of Ernest, who lives in the Albany, and gets into the most dreadful scrapes. That, my dear Algy, is the whole truth pure and simple.
+
+**Algernon.** The truth is rarely pure and never simple. Modern life would be very tedious if it were either, and modern literature a complete impossibility!
+
+**Jack.** That wouldn’t be at all a bad thing.
+
+**Algernon.** Literary criticism is not your forte, my dear fellow. Don’t try it. You should leave that to people who haven’t been at a University. They do it so well in the daily papers. What you really are is a Bunburyist. I was quite right in saying you were a Bunburyist. You are one of the most advanced Bunburyists I know.
+
+**Jack.** What on earth do you mean?
+
+**Algernon.** You have invented a very useful younger brother called Ernest, in order that you may be able to come up to town as often as you like. I have invented an invaluable permanent invalid called Bunbury, in order that I may be able to go down into the country whenever I choose. Bunbury is perfectly invaluable. If it wasn’t for Bunbury’s extraordinary bad health, for instance, I wouldn’t be able to dine with you at Willis’s to-night, for I have been really engaged to Aunt Augusta for more than a week.
+
+**Jack.** I haven’t asked you to dine with me anywhere to-night.
+
+**Algernon.** I know. You are absurdly careless about sending out invitations. It is very foolish of you. Nothing annoys people so much as not receiving invitations.
+
+**Jack.** You had much better dine with your Aunt Augusta.
+
+**Algernon.** I haven’t the smallest intention of doing anything of the kind. To begin with, I dined there on Monday, and once a week is quite enough to dine with one’s own relations. In the second place, whenever I do dine there I am always treated as a member of the family, and sent down with either no woman at all, or two. In the third place, I know perfectly well whom she will place me next to, to-night. She will place me next Mary Farquhar, who always flirts with her own husband across the dinner-table. That is not very pleasant. Indeed, it is not even decent . . . and that sort of thing is enormously on the increase. The amount of women in London who flirt with their own husbands is perfectly scandalous. It looks so bad. It is simply washing one’s clean linen in public. Besides, now that I know you to be a confirmed Bunburyist I naturally want to talk to you about Bunburying. I want to tell you the rules.
\ No newline at end of file
diff --git a/tutorial/play/act 2.pmd b/tutorial/play/act 2.pmd
new file mode 100644
index 0000000..a3bc9a3
--- /dev/null
+++ b/tutorial/play/act 2.pmd
@@ -0,0 +1,249 @@
+#lang pollen
+
+Garden at the Manor House. A flight of grey stone steps leads up to the house. The garden, an old-fashioned one, full of roses. Time of year, July. Basket chairs, and a table covered with books, are set under a large yew-tree.
+
+[**Miss Prism** discovered seated at the table. **Cecily** is at the back watering flowers.]
+
+**Miss Prism.** [Calling.] Cecily, Cecily! Surely such a utilitarian occupation as the watering of flowers is rather Moulton’s duty than yours? Especially at a moment when intellectual pleasures await you. Your German grammar is on the table. Pray open it at page fifteen. We will repeat yesterday’s lesson.
+
+**Cecily.** [Coming over very slowly.] But I don’t like German. It isn’t at all a becoming language. I know perfectly well that I look quite plain after my German lesson.
+
+**Miss Prism.** Child, you know how anxious your guardian is that you should improve yourself in every way. He laid particular stress on your German, as he was leaving for town yesterday. Indeed, he always lays stress on your German when he is leaving for town.
+
+**Cecily.** Dear Uncle Jack is so very serious! Sometimes he is so serious that I think he cannot be quite well.
+
+**Miss Prism.** [Drawing herself up.] Your guardian enjoys the best of health, and his gravity of demeanour is especially to be commended in one so comparatively young as he is. I know no one who has a higher sense of duty and responsibility.
+
+**Cecily.** I suppose that is why he often looks a little bored when we three are together.
+
+**Miss Prism.** Cecily! I am surprised at you. Mr. Worthing has many troubles in his life. Idle merriment and triviality would be out of place in his conversation. You must remember his constant anxiety about that unfortunate young man his brother.
+
+**Cecily.** I wish Uncle Jack would allow that unfortunate young man, his brother, to come down here sometimes. We might have a good influence over him, Miss Prism. I am sure you certainly would. You know German, and geology, and things of that kind influence a man very much. [**Cecily** begins to write in her diary.]
+
+**Miss Prism.** [Shaking her head.] I do not think that even I could produce any effect on a character that according to his own brother’s admission is irretrievably weak and vacillating. Indeed I am not sure that I would desire to reclaim him. I am not in favour of this modern mania for turning bad people into good people at a moment’s notice. As a man sows so let him reap. You must put away your diary, Cecily. I really don’t see why you should keep a diary at all.
+
+**Cecily.** I keep a diary in order to enter the wonderful secrets of my life. If I didn’t write them down, I should probably forget all about them.
+
+**Miss Prism.** Memory, my dear Cecily, is the diary that we all carry about with us.
+
+**Cecily.** Yes, but it usually chronicles the things that have never happened, and couldn’t possibly have happened. I believe that Memory is responsible for nearly all the three-volume novels that Mudie sends us.
+
+**Miss Prism.** Do not speak slightingly of the three-volume novel, Cecily. I wrote one myself in earlier days.
+
+**Cecily.** Did you really, Miss Prism? How wonderfully clever you are! I hope it did not end happily? I don’t like novels that end happily. They depress me so much.
+
+**Miss Prism.** The good ended happily, and the bad unhappily. That is what Fiction means.
+
+**Cecily.** I suppose so. But it seems very unfair. And was your novel ever published?
+
+**Miss Prism.** Alas! no. The manuscript unfortunately was abandoned. [**Cecily** starts.] I use the word in the sense of lost or mislaid. To your work, child, these speculations are profitless.
+
+**Cecily.** [Smiling.] But I see dear Dr. Chasuble coming up through the garden.
+
+**Miss Prism.** [Rising and advancing.] Dr. Chasuble! This is indeed a pleasure.
+
+[Enter **Canon Chasuble**.]
+
+**Chasuble.** And how are we this morning? Miss Prism, you are, I trust, well?
+
+**Cecily.** Miss Prism has just been complaining of a slight headache. I think it would do her so much good to have a short stroll with you in the Park, Dr. Chasuble.
+
+**Miss Prism.** Cecily, I have not mentioned anything about a headache.
+
+**Cecily.** No, dear Miss Prism, I know that, but I felt instinctively that you had a headache. Indeed I was thinking about that, and not about my German lesson, when the Rector came in.
+
+**Chasuble.** I hope, Cecily, you are not inattentive.
+
+**Cecily.** Oh, I am afraid I am.
+
+**Chasuble.** That is strange. Were I fortunate enough to be Miss Prism’s pupil, I would hang upon her lips. [**Miss Prism** glares.] I spoke metaphorically.—My metaphor was drawn from bees. Ahem! Mr. Worthing, I suppose, has not returned from town yet?
+
+**Miss Prism.** We do not expect him till Monday afternoon.
+
+**Chasuble.** Ah yes, he usually likes to spend his Sunday in London. He is not one of those whose sole aim is enjoyment, as, by all accounts, that unfortunate young man his brother seems to be. But I must not disturb Egeria and her pupil any longer.
+
+**Miss Prism.** Egeria? My name is Lætitia, Doctor.
+
+**Chasuble.** [Bowing.] A classical allusion merely, drawn from the Pagan authors. I shall see you both no doubt at Evensong?
+
+**Miss Prism.** I think, dear Doctor, I will have a stroll with you. I find I have a headache after all, and a walk might do it good.
+
+**Chasuble.** With pleasure, Miss Prism, with pleasure. We might go as far as the schools and back.
+
+**Miss Prism.** That would be delightful. Cecily, you will read your Political Economy in my absence. The chapter on the Fall of the Rupee you may omit. It is somewhat too sensational. Even these metallic problems have their melodramatic side.
+
+[Goes down the garden with **Dr. Chasuble**.]
+
+**Cecily.** [Picks up books and throws them back on table.] Horrid Political Economy! Horrid Geography! Horrid, horrid German!
+
+[Enter **Merriman** with a card on a salver.]
+
+**Merriman**. Mr. Ernest Worthing has just driven over from the station. He has brought his luggage with him.
+
+**Cecily.** [Takes the card and reads it.] ‘Mr. Ernest Worthing, B. 4, The Albany, W.’ Uncle Jack’s brother! Did you tell him Mr. Worthing was in town?
+
+**Merriman**. Yes, Miss. He seemed very much disappointed. I mentioned that you and Miss Prism were in the garden. He said he was anxious to speak to you privately for a moment.
+
+**Cecily.** Ask Mr. Ernest Worthing to come here. I suppose you had better talk to the housekeeper about a room for him.
+
+**Merriman**. Yes, Miss.
+
+[**Merriman** goes off.]
+
+**Cecily.** I have never met any really wicked person before. I feel rather frightened. I am so afraid he will look just like every one else.
+
+[Enter **Algernon**, very gay and debonnair.] He does!
+
+**Algernon.** [Raising his hat.] You are my little cousin Cecily, I’m sure.
+
+**Cecily.** You are under some strange mistake. I am not little. In fact, I believe I am more than usually tall for my age. [**Algernon** is rather taken aback.] But I am your cousin Cecily. You, I see from your card, are Uncle Jack’s brother, my cousin Ernest, my wicked cousin Ernest.
+
+**Algernon.** Oh! I am not really wicked at all, cousin Cecily. You mustn’t think that I am wicked.
+
+**Cecily.** If you are not, then you have certainly been deceiving us all in a very inexcusable manner. I hope you have not been leading a double life, pretending to be wicked and being really good all the time. That would be hypocrisy.
+
+**Algernon.** [Looks at her in amazement.] Oh! Of course I have been rather reckless.
+
+**Cecily.** I am glad to hear it.
+
+**Algernon.** In fact, now you mention the subject, I have been very bad in my own small way.
+
+**Cecily.** I don’t think you should be so proud of that, though I am sure it must have been very pleasant.
+
+**Algernon.** It is much pleasanter being here with you.
+
+**Cecily.** I can’t understand how you are here at all. Uncle Jack won’t be back till Monday afternoon.
+
+**Algernon.** That is a great disappointment. I am obliged to go up by the first train on Monday morning. I have a business appointment that I am anxious . . . to miss?
+
+**Cecily.** Couldn’t you miss it anywhere but in London?
+
+**Algernon.** No: the appointment is in London.
+
+**Cecily.** Well, I know, of course, how important it is not to keep a business engagement, if one wants to retain any sense of the beauty of life, but still I think you had better wait till Uncle Jack arrives. I know he wants to speak to you about your emigrating.
+
+**Algernon.** About my what?
+
+**Cecily.** Your emigrating. He has gone up to buy your outfit.
+
+**Algernon.** I certainly wouldn’t let Jack buy my outfit. He has no taste in neckties at all.
+
+**Cecily.** I don’t think you will require neckties. Uncle Jack is sending you to Australia.
+
+**Algernon.** Australia! I’d sooner die.
+
+**Cecily.** Well, he said at dinner on Wednesday night, that you would have to choose between this world, the next world, and Australia.
+
+**Algernon.** Oh, well! The accounts I have received of Australia and the next world, are not particularly encouraging. This world is good enough for me, cousin Cecily.
+
+**Cecily.** Yes, but are you good enough for it?
+
+**Algernon.** I’m afraid I’m not that. That is why I want you to reform me. You might make that your mission, if you don’t mind, cousin Cecily.
+
+**Cecily.** I’m afraid I’ve no time, this afternoon.
+
+**Algernon.** Well, would you mind my reforming myself this afternoon?
+
+**Cecily.** It is rather Quixotic of you. But I think you should try.
+
+**Algernon.** I will. I feel better already.
+
+**Cecily.** You are looking a little worse.
+
+**Algernon.** That is because I am hungry.
+
+**Cecily.** How thoughtless of me. I should have remembered that when one is going to lead an entirely new life, one requires regular and wholesome meals. Won’t you come in?
+
+**Algernon.** Thank you. Might I have a buttonhole first? I never have any appetite unless I have a buttonhole first.
+
+**Cecily.** A Marechal Niel? [Picks up scissors.]
+
+**Algernon.** No, I’d sooner have a pink rose.
+
+**Cecily.** Why? [Cuts a flower.]
+
+**Algernon.** Because you are like a pink rose, Cousin Cecily.
+
+**Cecily.** I don’t think it can be right for you to talk to me like that. Miss Prism never says such things to me.
+
+**Algernon.** Then Miss Prism is a short-sighted old lady. [**Cecily** puts the rose in his buttonhole.] You are the prettiest girl I ever saw.
+
+**Cecily.** Miss Prism says that all good looks are a snare.
+
+**Algernon.** They are a snare that every sensible man would like to be caught in.
+
+**Cecily.** Oh, I don’t think I would care to catch a sensible man. I shouldn’t know what to talk to him about.
+
+[They pass into the house. **Miss Prism** and **Dr. Chasuble** return.]
+
+**Miss Prism.** You are too much alone, dear Dr. Chasuble. You should get married. A misanthrope I can understand—a womanthrope, never!
+
+**Chasuble.** [With a scholar’s shudder.] Believe me, I do not deserve so neologistic a phrase. The precept as well as the practice of the Primitive Church was distinctly against matrimony.
+
+**Miss Prism.** [Sententiously.] That is obviously the reason why the Primitive Church has not lasted up to the present day. And you do not seem to realise, dear Doctor, that by persistently remaining single, a man converts himself into a permanent public temptation. Men should be more careful; this very celibacy leads weaker vessels astray.
+
+**Chasuble.** But is a man not equally attractive when married?
+
+**Miss Prism.** No married man is ever attractive except to his wife.
+
+**Chasuble.** And often, I’ve been told, not even to her.
+
+**Miss Prism.** That depends on the intellectual sympathies of the woman. Maturity can always be depended on. Ripeness can be trusted. Young women are green. [**Dr. Chasuble** starts.] I spoke horticulturally. My metaphor was drawn from fruits. But where is Cecily?
+
+**Chasuble.** Perhaps she followed us to the schools.
+
+[Enter **Jack** slowly from the back of the garden. He is dressed in the deepest mourning, with crape hatband and black gloves.]
+
+**Miss Prism.** Mr. Worthing!
+
+**Chasuble.** Mr. Worthing?
+
+**Miss Prism.** This is indeed a surprise. We did not look for you till Monday afternoon.
+
+**Jack.** [Shakes **Miss Prism’s** hand in a tragic manner.] I have returned sooner than I expected. Dr. Chasuble, I hope you are well?
+
+**Chasuble.** Dear Mr. Worthing, I trust this garb of woe does not betoken some terrible calamity?
+
+**Jack.** My brother.
+
+**Miss Prism.** More shameful debts and extravagance?
+
+**Chasuble.** Still leading his life of pleasure?
+
+**Jack.** [Shaking his head.] Dead!
+
+**Chasuble.** Your brother Ernest dead?
+
+**Jack.** Quite dead.
+
+**Miss Prism.** What a lesson for him! I trust he will profit by it.
+
+**Chasuble.** Mr. Worthing, I offer you my sincere condolence. You have at least the consolation of knowing that you were always the most generous and forgiving of brothers.
+
+**Jack.** Poor Ernest! He had many faults, but it is a sad, sad blow.
+
+**Chasuble.** Very sad indeed. Were you with him at the end?
+
+**Jack.** No. He died abroad; in Paris, in fact. I had a telegram last night from the manager of the Grand Hotel.
+
+**Chasuble.** Was the cause of death mentioned?
+
+**Jack.** A severe chill, it seems.
+
+**Miss Prism.** As a man sows, so shall he reap.
+
+**Chasuble.** [Raising his hand.] Charity, dear Miss Prism, charity! None of us are perfect. I myself am peculiarly susceptible to draughts. Will the interment take place here?
+
+**Jack.** No. He seems to have expressed a desire to be buried in Paris.
+
+**Chasuble.** In Paris! [Shakes his head.] I fear that hardly points to any very serious state of mind at the last. You would no doubt wish me to make some slight allusion to this tragic domestic affliction next Sunday. [**Jack** presses his hand convulsively.] My sermon on the meaning of the manna in the wilderness can be adapted to almost any occasion, joyful, or, as in the present case, distressing. [All sigh.] I have preached it at harvest celebrations, christenings, confirmations, on days of humiliation and festal days. The last time I delivered it was in the Cathedral, as a charity sermon on behalf of the Society for the Prevention of Discontent among the Upper Orders. The Bishop, who was present, was much struck by some of the analogies I drew.
+
+**Jack.** Ah! that reminds me, you mentioned christenings I think, Dr. Chasuble? I suppose you know how to christen all right? [**Dr. Chasuble** looks astounded.] I mean, of course, you are continually christening, aren’t you?
+
+**Miss Prism.** It is, I regret to say, one of the Rector’s most constant duties in this parish. I have often spoken to the poorer classes on the subject. But they don’t seem to know what thrift is.
+
+**Chasuble.** But is there any particular infant in whom you are interested, Mr. Worthing? Your brother was, I believe, unmarried, was he not?
+
+**Jack.** Oh yes.
+
+**Miss Prism.** [Bitterly.] People who live entirely for pleasure usually are.
\ No newline at end of file
diff --git a/tutorial/play/act 3.pmd b/tutorial/play/act 3.pmd
new file mode 100644
index 0000000..87505fc
--- /dev/null
+++ b/tutorial/play/act 3.pmd
@@ -0,0 +1,211 @@
+#lang pollen
+
+Morning-room at the Manor House.
+
+[**Gwendolen** and **Cecily** are at the window, looking out into the garden.]
+
+**Gwendolen.** The fact that they did not follow us at once into the house, as any one else would have done, seems to me to show that they have some sense of shame left.
+
+**Cecily.** They have been eating muffins. That looks like repentance.
+
+**Gwendolen.** [After a pause.] They don’t seem to notice us at all. Couldn’t you cough?
+
+**Cecily.** But I haven’t got a cough.
+
+**Gwendolen.** They’re looking at us. What effrontery!
+
+**Cecily.** They’re approaching. That’s very forward of them.
+
+**Gwendolen.** Let us preserve a dignified silence.
+
+**Cecily.** Certainly. It’s the only thing to do now. [Enter **Jack** followed by **Algernon**. They whistle some dreadful popular air from a British Opera.]
+
+**Gwendolen.** This dignified silence seems to produce an unpleasant effect.
+
+**Cecily.** A most distasteful one.
+
+**Gwendolen.** But we will not be the first to speak.
+
+**Cecily.** Certainly not.
+
+**Gwendolen.** Mr. Worthing, I have something very particular to ask you. Much depends on your reply.
+
+**Cecily.** Gwendolen, your common sense is invaluable. Mr. Moncrieff, kindly answer me the following question. Why did you pretend to be my guardian’s brother?
+
+**Algernon.** In order that I might have an opportunity of meeting you.
+
+**Cecily.** [To **Gwendolen**.] That certainly seems a satisfactory explanation, does it not?
+
+**Gwendolen.** Yes, dear, if you can believe him.
+
+**Cecily.** I don’t. But that does not affect the wonderful beauty of his answer.
+
+**Gwendolen.** True. In matters of grave importance, style, not sincerity is the vital thing. Mr. Worthing, what explanation can you offer to me for pretending to have a brother? Was it in order that you might have an opportunity of coming up to town to see me as often as possible?
+
+**Jack.** Can you doubt it, Miss Fairfax?
+
+**Gwendolen.** I have the gravest doubts upon the subject. But I intend to crush them. This is not the moment for German scepticism. [Moving to **Cecily**.] Their explanations appear to be quite satisfactory, especially Mr. Worthing’s. That seems to me to have the stamp of truth upon it.
+
+**Cecily.** I am more than content with what Mr. Moncrieff said. His voice alone inspires one with absolute credulity.
+
+**Gwendolen.** Then you think we should forgive them?
+
+**Cecily.** Yes. I mean no.
+
+**Gwendolen.** True! I had forgotten. There are principles at stake that one cannot surrender. Which of us should tell them? The task is not a pleasant one.
+
+**Cecily.** Could we not both speak at the same time?
+
+**Gwendolen.** An excellent idea! I nearly always speak at the same time as other people. Will you take the time from me?
+
+**Cecily.** Certainly. [**Gwendolen** beats time with uplifted finger.]
+
+**Gwendolen** and **Cecily** [Speaking together.] Your Christian names are still an insuperable barrier. That is all!
+
+**Jack** and **Algernon** [Speaking together.] Our Christian names! Is that all? But we are going to be christened this afternoon.
+
+**Gwendolen.** [To **Jack**.] For my sake you are prepared to do this terrible thing?
+
+**Jack.** I am.
+
+**Cecily.** [To **Algernon**.] To please me you are ready to face this fearful ordeal?
+
+**Algernon.** I am!
+
+**Gwendolen.** How absurd to talk of the equality of the sexes! Where questions of self-sacrifice are concerned, men are infinitely beyond us.
+
+**Jack.** We are. [Clasps hands with **Algernon**.]
+
+**Cecily.** They have moments of physical courage of which we women know absolutely nothing.
+
+**Gwendolen.** [To **Jack**.] Darling!
+
+**Algernon.** [To **Cecily**.] Darling! [They fall into each other’s arms.]
+
+[Enter **Merriman**. When he enters he coughs loudly, seeing the situation.]
+
+**Merriman.** Ahem! Ahem! Lady Bracknell!
+
+**Jack.** Good heavens!
+
+[Enter **Lady Bracknell**. The couples separate in alarm. Exit **Merriman**.]
+
+**Lady Bracknell.** Gwendolen! What does this mean?
+
+**Gwendolen.** Merely that I am engaged to be married to Mr. Worthing, mamma.
+
+**Lady Bracknell.** Come here. Sit down. Sit down immediately. Hesitation of any kind is a sign of mental decay in the young, of physical weakness in the old. [Turns to **Jack**.] Apprised, sir, of my daughter’s sudden flight by her trusty maid, whose confidence I purchased by means of a small coin, I followed her at once by a luggage train. Her unhappy father is, I am glad to say, under the impression that she is attending a more than usually lengthy lecture by the University Extension Scheme on the Influence of a permanent income on Thought. I do not propose to undeceive him. Indeed I have never undeceived him on any question. I would consider it wrong. But of course, you will clearly understand that all communication between yourself and my daughter must cease immediately from this moment. On this point, as indeed on all points, I am firm.
+
+**Jack.** I am engaged to be married to Gwendolen Lady Bracknell!
+
+**Lady Bracknell.** You are nothing of the kind, sir. And now, as regards Algernon! . . . Algernon!
+
+**Algernon.** Yes, Aunt Augusta.
+
+**Lady Bracknell.** May I ask if it is in this house that your invalid friend Mr. Bunbury resides?
+
+**Algernon.** [Stammering.] Oh! No! Bunbury doesn’t live here. Bunbury is somewhere else at present. In fact, Bunbury is dead,
+
+**Lady Bracknell.** Dead! When did Mr. Bunbury die? His death must have been extremely sudden.
+
+**Algernon.** [Airily.] Oh! I killed Bunbury this afternoon. I mean poor Bunbury died this afternoon.
+
+**Lady Bracknell.** What did he die of?
+
+**Algernon.** Bunbury? Oh, he was quite exploded.
+
+**Lady Bracknell.** Exploded! Was he the victim of a revolutionary outrage? I was not aware that Mr. Bunbury was interested in social legislation. If so, he is well punished for his morbidity.
+
+**Algernon.** My dear Aunt Augusta, I mean he was found out! The doctors found out that Bunbury could not live, that is what I mean—so Bunbury died.
+
+**Lady Bracknell.** He seems to have had great confidence in the opinion of his physicians. I am glad, however, that he made up his mind at the last to some definite course of action, and acted under proper medical advice. And now that we have finally got rid of this Mr. Bunbury, may I ask, Mr. Worthing, who is that young person whose hand my nephew Algernon is now holding in what seems to me a peculiarly unnecessary manner?
+
+**Jack.** That lady is Miss Cecily Cardew, my ward. [**Lady Bracknell** bows coldly to **Cecily**.]
+
+**Algernon.** I am engaged to be married to Cecily, Aunt Augusta.
+
+**Lady Bracknell.** I beg your pardon?
+
+**Cecily.** Mr. Moncrieff and I are engaged to be married, Lady Bracknell.
+
+**Lady Bracknell.** [With a shiver, crossing to the sofa and sitting down.] I do not know whether there is anything peculiarly exciting in the air of this particular part of Hertfordshire, but the number of engagements that go on seems to me considerably above the proper average that statistics have laid down for our guidance. I think some preliminary inquiry on my part would not be out of place. Mr. Worthing, is Miss Cardew at all connected with any of the larger railway stations in London? I merely desire information. Until yesterday I had no idea that there were any families or persons whose origin was a Terminus. [**Jack** looks perfectly furious, but restrains himself.]
+
+**Jack.** [In a clear, cold voice.] Miss Cardew is the grand-daughter of the late Mr. Thomas Cardew of 149 Belgrave Square, S.W.; Gervase Park, Dorking, Surrey; and the Sporran, Fifeshire, N.B.
+
+**Lady Bracknell.** That sounds not unsatisfactory. Three addresses always inspire confidence, even in tradesmen. But what proof have I of their authenticity?
+
+**Jack.** I have carefully preserved the Court Guides of the period. They are open to your inspection, Lady Bracknell.
+
+**Lady Bracknell.** [Grimly.] I have known strange errors in that publication.
+
+**Jack.** Miss Cardew’s family solicitors are Messrs. Markby, Markby, and Markby.
+
+**Lady Bracknell.** Markby, Markby, and Markby? A firm of the very highest position in their profession. Indeed I am told that one of the Mr. Markby’s is occasionally to be seen at dinner parties. So far I am satisfied.
+
+**Jack.** [Very irritably.] How extremely kind of you, Lady Bracknell! I have also in my possession, you will be pleased to hear, certificates of Miss Cardew’s birth, baptism, whooping cough, registration, vaccination, confirmation, and the measles; both the German and the English variety.
+
+**Lady Bracknell.** Ah! A life crowded with incident, I see; though perhaps somewhat too exciting for a young girl. I am not myself in favour of premature experiences. [Rises, looks at her watch.] Gwendolen! the time approaches for our departure. We have not a moment to lose. As a matter of form, Mr. Worthing, I had better ask you if Miss Cardew has any little fortune?
+
+**Jack.** Oh! about a hundred and thirty thousand pounds in the Funds. That is all. Goodbye, Lady Bracknell. So pleased to have seen you.
+
+**Lady Bracknell.** [Sitting down again.] A moment, Mr. Worthing. A hundred and thirty thousand pounds! And in the Funds! Miss Cardew seems to me a most attractive young lady, now that I look at her. Few girls of the present day have any really solid qualities, any of the qualities that last, and improve with time. We live, I regret to say, in an age of surfaces. [To **Cecily**.] Come over here, dear. [**Cecily** goes across.] Pretty child! your dress is sadly simple, and your hair seems almost as Nature might have left it. But we can soon alter all that. A thoroughly experienced French maid produces a really marvellous result in a very brief space of time. I remember recommending one to young Lady Lancing, and after three months her own husband did not know her.
+
+**Jack.** And after six months nobody knew her.
+
+**Lady Bracknell.** [Glares at **Jack** for a few moments. Then bends, with a practised smile, to **Cecily**.] Kindly turn round, sweet child. [**Cecily** turns completely round.] No, the side view is what I want. [**Cecily** presents her profile.] Yes, quite as I expected. There are distinct social possibilities in your profile. The two weak points in our age are its want of principle and its want of profile. The chin a little higher, dear. Style largely depends on the way the chin is worn. They are worn very high, just at present. Algernon!
+
+**Algernon.** Yes, Aunt Augusta!
+
+**Lady Bracknell.** There are distinct social possibilities in Miss Cardew’s profile.
+
+**Algernon.** Cecily is the sweetest, dearest, prettiest girl in the whole world. And I don’t care twopence about social possibilities.
+
+**Lady Bracknell.** Never speak disrespectfully of Society, Algernon. Only people who can’t get into it do that. [To **Cecily**.] Dear child, of course you know that Algernon has nothing but his debts to depend upon. But I do not approve of mercenary marriages. When I married Lord Bracknell I had no fortune of any kind. But I never dreamed for a moment of allowing that to stand in my way. Well, I suppose I must give my consent.
+
+**Algernon.** Thank you, Aunt Augusta.
+
+**Lady Bracknell.** Cecily, you may kiss me!
+
+**Cecily.** [Kisses her.] Thank you, Lady Bracknell.
+
+**Lady Bracknell.** You may also address me as Aunt Augusta for the future.
+
+**Cecily.** Thank you, Aunt Augusta.
+
+**Lady Bracknell.** The marriage, I think, had better take place quite soon.
+
+**Algernon.** Thank you, Aunt Augusta.
+
+**Cecily.** Thank you, Aunt Augusta.
+
+**Lady Bracknell.** To speak frankly, I am not in favour of long engagements. They give people the opportunity of finding out each other’s character before marriage, which I think is never advisable.
+
+**Jack.** I beg your pardon for interrupting you, Lady Bracknell, but this engagement is quite out of the question. I am Miss Cardew’s guardian, and she cannot marry without my consent until she comes of age. That consent I absolutely decline to give.
+
+**Lady Bracknell.** Upon what grounds may I ask? Algernon is an extremely, I may almost say an ostentatiously, eligible young man. He has nothing, but he looks everything. What more can one desire?
+
+**Jack.** It pains me very much to have to speak frankly to you, Lady Bracknell, about your nephew, but the fact is that I do not approve at all of his moral character. I suspect him of being untruthful. [**Algernon** and **Cecily** look at him in indignant amazement.]
+
+**Lady Bracknell.** Untruthful! My nephew Algernon? Impossible! He is an Oxonian.
+
+**Jack.** I fear there can be no possible doubt about the matter. This afternoon during my temporary absence in London on an important question of romance, he obtained admission to my house by means of the false pretence of being my brother. Under an assumed name he drank, I’ve just been informed by my butler, an entire pint bottle of my Perrier-Jouet, Brut, ’89; wine I was specially reserving for myself. Continuing his disgraceful deception, he succeeded in the course of the afternoon in alienating the affections of my only ward. He subsequently stayed to tea, and devoured every single muffin. And what makes his conduct all the more heartless is, that he was perfectly well aware from the first that I have no brother, that I never had a brother, and that I don’t intend to have a brother, not even of any kind. I distinctly told him so myself yesterday afternoon.
+
+**Lady Bracknell.** Ahem! Mr. Worthing, after careful consideration I have decided entirely to overlook my nephew’s conduct to you.
+
+**Jack.** That is very generous of you, Lady Bracknell. My own decision, however, is unalterable. I decline to give my consent.
+
+**Lady Bracknell.** [To **Cecily**.] Come here, sweet child. [**Cecily** goes over.] How old are you, dear?
+
+**Cecily.** Well, I am really only eighteen, but I always admit to twenty when I go to evening parties.
+
+**Lady Bracknell.** You are perfectly right in making some slight alteration. Indeed, no woman should ever be quite accurate about her age. It looks so calculating . . . [In a meditative manner.] Eighteen, but admitting to twenty at evening parties. Well, it will not be very long before you are of age and free from the restraints of tutelage. So I don’t think your guardian’s consent is, after all, a matter of any importance.
+
+**Jack.** Pray excuse me, Lady Bracknell, for interrupting you again, but it is only fair to tell you that according to the terms of her grandfather’s will Miss Cardew does not come legally of age till she is thirty-five.
+
+**Lady Bracknell.** That does not seem to me to be a grave objection. Thirty-five is a very attractive age. London society is full of women of the very highest birth who have, of their own free choice, remained thirty-five for years. Lady Dumbleton is an instance in point. To my own knowledge she has been thirty-five ever since she arrived at the age of forty, which was many years ago now. I see no reason why our dear Cecily should not be even still more attractive at the age you mention than she is at present. There will be a large accumulation of property.
+
+**Cecily.** Algy, could you wait for me till I was thirty-five?
+
+**Algernon.** Of course I could, Cecily. You know I could.
+
+**Cecily.** Yes, I felt it instinctively, but I couldn’t wait all that time. I hate waiting even five minutes for anybody. It always makes me rather cross. I am not punctual myself, I know, but I do like punctuality in others, and waiting, even to be married, is quite out of the question.
diff --git a/tutorial/poem/ulysses.html b/tutorial/poem/ulysses.html
new file mode 100644
index 0000000..6d47432
--- /dev/null
+++ b/tutorial/poem/ulysses.html
@@ -0,0 +1,81 @@
+
+
+
+
+
+
+"Ulysses" by Alfred Tennyson
+
+It little profits that an idle king,
+By this still hearth, among these barren crags,
+Match'd with an aged wife, I mete and dole
+Unequal laws unto a savage race,
+That hoard, and sleep, and feed, and know not me.
+
+I cannot rest from travel: I will drink
+Life to the lees; all times I have enjoy'd
+Greatly, have suffer'd greatly, both with those
+That loved me, and alone; on shore, and when
+Thro' scudding drifts the rainy Hyades
+Vext the dim sea: I am become a name;
+For always roaming with a hungry heart
+Much have I seen and known; cities of men
+And manners, climates, councils, governments,
+Myself not least, but honour'd of them all;
+And drunk delight of battle with my peers,
+Far on the ringing plains of windy Troy,
+I am a part of all that I have met;
+Yet all experience is an arch wherethro'
+Gleams that untravell'd world, whose margin fades
+For ever and for ever when I move.
+How dull it is to pause, to make an end,
+To rust unburnish'd, not to shine in use!
+As tho' to breathe were life. Life piled on life
+Were all too little, and of one to me
+Little remains: but every hour is saved
+From that eternal silence, something more,
+A bringer of new things; and vile it were
+For some three suns to store and hoard myself,
+And this gray spirit yearning in desire
+To follow knowledge like a sinking star,
+Beyond the utmost bound of human thought.
+
+ This is my son, mine own Telemachus,
+To whom I leave the scepter and the isle—
+Well-loved of me, discerning to fulfil
+This labour, by slow prudence to make mild
+A rugged people, and thro' soft degrees
+Subdue them to the useful and the good.
+Most blameless is he, centred in the sphere
+Of common duties, decent not to fail
+In offices of tenderness, and pay
+Meet adoration to my household gods,
+When I am gone. He works his work, I mine.
+
+ There lies the port; the vessel puffs her sail:
+There gloom the dark broad seas. My mariners,
+Souls that have toil'd, and wrought, and thought with me—
+That ever with a frolic welcome took
+The thunder and the sunshine, and opposed
+Free hearts, free foreheads—you and I are old;
+Old age hath yet his honour and his toil;
+Death closes all: but something ere the end,
+Some work of noble note, may yet be done,
+Not unbecoming men that strove with Gods.
+The lights begin to twinkle from the rocks:
+The long day wanes: the slow moon climbs: the deep
+Moans round with many voices. Come, my friends,
+'Tis not too late to seek a newer world.
+Push off, and sitting well in order smite
+The sounding furrows; for my purpose holds
+To sail beyond the sunset, and the baths
+Of all the western stars, until I die.
+It may be that the gulfs will wash us down:
+It may be we shall touch the Happy Isles,
+And see the great Achilles, whom we knew.
+Tho' much is taken, much abides; and tho'
+We are not now that strength which in old days
+Moved earth and heaven; that which we are, we are;
+One equal temper of heroic hearts,
+Made weak by time and fate, but strong in will
+To strive, to seek, to find, and not to yield.
diff --git a/tutorial/poem/ulysses.html.pp b/tutorial/poem/ulysses.html.pp
new file mode 100644
index 0000000..9f399d3
--- /dev/null
+++ b/tutorial/poem/ulysses.html.pp
@@ -0,0 +1,89 @@
+#lang pollen
+
+<<<<<<< HEAD
+
+
+
+
+
+=======
+>>>>>>> squash! earnest
+"Ulysses" by Alfred Tennyson
+
+It little profits that an idle king,
+By this still hearth, among these barren crags,
+Match'd with an aged wife, I mete and dole
+Unequal laws unto a savage race,
+That hoard, and sleep, and feed, and know not me.
+
+I cannot rest from travel: I will drink
+Life to the lees; all times I have enjoy'd
+Greatly, have suffer'd greatly, both with those
+That loved me, and alone; on shore, and when
+Thro' scudding drifts the rainy Hyades
+Vext the dim sea: I am become a name;
+For always roaming with a hungry heart
+Much have I seen and known; cities of men
+And manners, climates, councils, governments,
+Myself not least, but honour'd of them all;
+And drunk delight of battle with my peers,
+Far on the ringing plains of windy Troy,
+I am a part of all that I have met;
+Yet all experience is an arch wherethro'
+Gleams that untravell'd world, whose margin fades
+For ever and for ever when I move.
+How dull it is to pause, to make an end,
+To rust unburnish'd, not to shine in use!
+As tho' to breathe were life. Life piled on life
+Were all too little, and of one to me
+Little remains: but every hour is saved
+From that eternal silence, something more,
+A bringer of new things; and vile it were
+For some three suns to store and hoard myself,
+And this gray spirit yearning in desire
+To follow knowledge like a sinking star,
+Beyond the utmost bound of human thought.
+
+ This is my son, mine own Telemachus,
+To whom I leave the scepter and the isle—
+Well-loved of me, discerning to fulfil
+This labour, by slow prudence to make mild
+A rugged people, and thro' soft degrees
+Subdue them to the useful and the good.
+Most blameless is he, centred in the sphere
+Of common duties, decent not to fail
+In offices of tenderness, and pay
+Meet adoration to my household gods,
+When I am gone. He works his work, I mine.
+
+ There lies the port; the vessel puffs her sail:
+There gloom the dark broad seas. My mariners,
+Souls that have toil'd, and wrought, and thought with me—
+That ever with a frolic welcome took
+The thunder and the sunshine, and opposed
+Free hearts, free foreheads—you and I are old;
+Old age hath yet his honour and his toil;
+Death closes all: but something ere the end,
+Some work of noble note, may yet be done,
+Not unbecoming men that strove with Gods.
+The lights begin to twinkle from the rocks:
+The long day wanes: the slow moon climbs: the deep
+Moans round with many voices. Come, my friends,
+'Tis not too late to seek a newer world.
+Push off, and sitting well in order smite
+The sounding furrows; for my purpose holds
+To sail beyond the sunset, and the baths
+Of all the western stars, until I die.
+It may be that the gulfs will wash us down:
+It may be we shall touch the Happy Isles,
+And see the great Achilles, whom we knew.
+Tho' much is taken, much abides; and tho'
+We are not now that strength which in old days
+Moved earth and heaven; that which we are, we are;
+One equal temper of heroic hearts,
+Made weak by time and fate, but strong in will
+<<<<<<< HEAD
+To strive, to seek, to find, and not to yield.
+=======
+To strive, to seek, to find, and not to yield.
+>>>>>>> squash! earnest
diff --git a/tutorial/poem/waste-land.html.pp b/tutorial/poem/waste-land.html.pp
new file mode 100644
index 0000000..a367979
--- /dev/null
+++ b/tutorial/poem/waste-land.html.pp
@@ -0,0 +1,81 @@
+#lang pollen
+
+APRIL is the cruellest month, breeding
+Lilacs out of the dead land, mixing
+Memory and desire, stirring
+Dull roots with spring rain.
+Winter kept us warm, covering
+Earth in forgetful snow, feeding
+A little life with dried tubers.
+Summer surprised us, coming over the Starnbergersee
+With a shower of rain; we stopped in the colonnade,
+And went on in sunlight, into the Hofgarten,
+And drank coffee, and talked for an hour.
+Bin gar keine Russin, stamm’ aus Litauen, echt deutsch.
+And when we were children, staying at the archduke’s,
+My cousin’s, he took me out on a sled,
+And I was frightened. He said, Marie,
+Marie, hold on tight. And down we went.
+In the mountains, there you feel free.
+I read, much of the night, and go south in the winter.
+
+What are the roots that clutch, what branches grow
+Out of this stony rubbish? Son of man,
+You cannot say, or guess, for you know only
+A heap of broken images, where the sun beats,
+And the dead tree gives no shelter, the cricket no relief,
+And the dry stone no sound of water. Only
+There is shadow under this red rock,
+(Come in under the shadow of this red rock),
+And I will show you something different from either
+Your shadow at morning striding behind you
+Or your shadow at evening rising to meet you;
+I will show you fear in a handful of dust.
+ Frisch weht der Wind
+ Der Heimat zu,
+ Mein Irisch Kind,
+ Wo weilest du?
+“You gave me hyacinths first a year ago;
+They called me the hyacinth girl.”
+—Yet when we came back, late, from the Hyacinth garden,
+Your arms full, and your hair wet, I could not
+Speak, and my eyes failed, I was neither
+Living nor dead, and I knew nothing,
+Looking into the heart of light, the silence.
+Öd’ und leer das Meer.
+
+Madame Sosostris, famous clairvoyante,
+Had a bad cold, nevertheless
+Is known to be the wisest woman in Europe,
+With a wicked pack of cards. Here, said she,
+Is your card, the drowned Phoenician Sailor,
+(Those are pearls that were his eyes. Look!)
+Here is Belladonna, the Lady of the Rocks,
+The lady of situations.
+Here is the man with three staves, and here the Wheel,
+And here is the one-eyed merchant, and this card,
+Which is blank, is something he carries on his back,
+Which I am forbidden to see. I do not find
+The Hanged Man. Fear death by water.
+I see crowds of people, walking round in a ring.
+Thank you. If you see dear Mrs. Equitone,
+Tell her I bring the horoscope myself:
+One must be so careful these days.
+
+Unreal City,
+Under the brown fog of a winter dawn,
+A crowd flowed over London Bridge, so many,
+I had not thought death had undone so many.
+Sighs, short and infrequent, were exhaled,
+And each man fixed his eyes before his feet.
+Flowed up the hill and down King William Street,
+To where Saint Mary Woolnoth kept the hours
+With a dead sound on the final stroke of nine.
+There I saw one I knew, and stopped him, crying “Stetson!
+You who were with me in the ships at Mylae!
+That corpse you planted last year in your garden,
+Has it begun to sprout? Will it bloom this year?
+Or has the sudden frost disturbed its bed?
+Oh keep the Dog far hence, that’s friend to men,
+Or with his nails he’ll dig it up again!
+You! hypocrite lecteur!—mon semblable,—mon frère!”
\ No newline at end of file
diff --git a/tutorial/space.jpg b/tutorial/space.jpg
new file mode 100644
index 0000000..a60f400
Binary files /dev/null and b/tutorial/space.jpg differ
diff --git a/tutorial/styles.css b/tutorial/styles.css
new file mode 100644
index 0000000..a273fed
--- /dev/null
+++ b/tutorial/styles.css
@@ -0,0 +1,48 @@
+
+body {
+ margin: 0 auto 0 auto;
+ padding: 0;
+}
+
+
+h1 {
+ font-size: 40px;
+ font-family: "Alegreya Sans";
+ font-weight: 700;
+ color: white;
+ margin-top: -5rem;
+ margin-left: 15%;
+ margin-right: 15%;
+}
+
+
+h2 {
+ font-size: 22px;
+ font-family: "Alegreya Sans";
+ font-weight: 700;
+ margin-left: 15%;
+ margin-right: 15%;
+}
+
+
+p {
+ color: #333;
+ font-size: 22px;
+ line-height: 1.4;
+ font-family: "Alegreya";
+ margin-left: 15%;
+ margin-right: 15%;
+}
+
+pre {
+ margin-left: 15%;
+ margin-right: 15%;
+}
+
+code {
+ font-family: "Source Code Pro";
+}
+
+img {
+ width: 100%;
+}
\ No newline at end of file
diff --git a/tutorial/template.html b/tutorial/template.html
new file mode 100644
index 0000000..d3612aa
--- /dev/null
+++ b/tutorial/template.html
@@ -0,0 +1,9 @@
+
+
+
+
+
+
+◊(->html doc)
+
+
\ No newline at end of file
