<html><head><metahttp-equiv="content-type"content="text/html; charset=utf-8"/><title>5 First tutorial</title><linkrel="stylesheet"type="text/css"href="scribble.css"title="default"/><linkrel="stylesheet"type="text/css"href="racket.css"title="default"/><linkrel="stylesheet"type="text/css"href="manual-style.css"title="default"/><linkrel="stylesheet"type="text/css"href="manual-racket.css"title="default"/><scripttype="text/javascript"src="scribble-common.js"></script><scripttype="text/javascript"src="manual-racket.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><bodyid="scribble-racket-lang-org"><divclass="tocset"><divclass="tocview"><divclass="tocviewlist tocviewlisttopspace"><divclass="tocviewtitle"><tablecellspacing="0"cellpadding="0"><tr><tdstyle="width: 1em;"><ahref="javascript:void(0);"title="Expand/Collapse"class="tocviewtoggle"onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><ahref="index.html"class="tocviewlink"data-pltdoc="x">Pollen:<spanclass="mywbr"> </span> the book is a program</a></td></tr></table></div><divclass="tocviewsublisttop"style="display: block;"id="tocview_0"><tablecellspacing="0"cellpadding="0"><tr><tdalign="right">1 </td><td><ahref="Installation.html"class="tocviewlink"data-pltdoc="x">Installation</a></td></tr><tr><tdalign="right">2 </td><td><ahref="quick-tour.html"class="tocviewlink"data-pltdoc="x">Quick tour</a></td></tr><tr><tdalign="right">3 </td><td><ahref="Backstory.html"class="tocviewlink"data-pltdoc="x">Backstory</a></td></tr><tr><tdalign="right">4 </td><td><ahref="big-picture.html"class="tocviewlink"data-pltdoc="x">The big picture</a></td></tr><tr><tdalign="right">5 </td><td><ahref="first-tutorial.html"class="tocviewselflink"data-pltdoc="x">First tutorial</a></td></tr><tr><tdalign="right">6 </td><td><ahref="second-tutorial.html"class="tocviewlink"data-pltdoc="x">Second tutorial</a></td></tr><tr><tdalign="right">7 </td><td><ahref="raco-pollen.html"class="tocviewlink"data-pltdoc="x">Using <spanclass="stt">raco pollen</span></a></td></tr><tr><tdalign="right">8 </td><td><ahref="File_formats.html"class="tocviewlink"data-pltdoc="x">File formats</a></td></tr><tr><tdalign="right">9 </td><td><ahref="reader.html"class="tocviewlink"data-pltdoc="x">◊ command overview</a></td></tr><tr><tdalign="right">10 </td><td><ahref="Module_reference.html"class="tocviewlink"data-pltdoc="x">Module reference</a></td></tr><tr><tdalign="right">11 </td><td><ahref="Acknowledgments.html"class="tocviewlink"data-pltdoc="x">Acknowledgments</a></td></tr><tr><tdalign="right">12 </td><td><ahref="License___source_code.html"class="tocviewlink"data-pltdoc="x">License & source code</a></td></tr><tr><tdalign="right"></td><td><ahref="doc-index.html"class="tocviewlink"data-pltdoc="x">Index</a></td></tr></table></div></div><divclass="tocviewlist"><tablecellspacing="0"cellpadding="0"><tr><tdstyle="width: 1em;"><ahref="javascript:void(0);"title="Expand/Collapse"class="tocviewtoggle"onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>5 </td><td><ahref="first-tutorial.html"class="tocviewselflink"data-pltdoc="x">First tutorial</a></td></tr></table><divclass="tocviewsublistbottom"style="display: none;"id="tocview_1"><tablecellspacing="0"cellpadding="0"><tr><tdalign="right">5.1 </td><td><ahref="first-tutorial.html#%28part._tutorial-1._.Prerequisites%29"class="tocviewlink"data-pltdoc="x">Prerequisites</a></td></tr><tr><tdalign="right">5.2 </td><td><ahref="first-tutorial.html#%28part._.The_relationship_of_.Racket___.Pollen%29"class="tocviewlink"data-pltdoc="x">The relationship of Racket & Pollen</a></td></tr><tr><tdalign="right">5.3 </td><td><ahref="first-tutorial.html#%28part._.Starting_a_new_file_in_.Dr.Racket%29"class="tocviewlink"data-pltdoc="x">Starting a new file in Dr<spanclass="mywbr"> </span
<br/>standard-module-name-resolver: collection not found ...</span></p></td></tr></table></p><p>Why? Because there’s no language called <spanclass="stt">pollenxyz</span>. Switch it back to <spanclass="stt">pollen</span> and let’s move on.</p><h5>5.3.2<tt> </tt><aname="(part._.Putting_in_the_text_of_the_poem)"></a>Putting in the text of the poem</h5><p>Here’s a short, bad poem I wrote about CSS.</p><p><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">The margin is 42em.</span></p></td></tr><tr><td><p><spanclass="stt">The border is red.</span></p></td></tr><tr><td><p><spanclass="stt">The padding is 15em.</span></p></td></tr><tr><td><p><spanclass="stt">The border is too.</span></p></td></tr></table></p><p>Paste the text of this poem into your DrRacket editing window, below the <spanclass="stt">#lang</span> line, so it looks like this:</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">#lang pollen</span></p></td></tr><tr><td><p><spanclass="stt"></span><spanclass="hspace"> </span></p></td></tr><tr><td><p><spanclass="stt">The margin is 42em.</span></p></td></tr><tr><td><p><spanclass="stt">The border is red.</span></p></td></tr><tr><td><p><spanclass="stt">The padding is 15em.</span></p></td></tr><tr><td><p><spanclass="stt">The border is too.</span></p></td></tr></table></blockquote><p><spanclass="ssansserif">Run</span> the file again. In the interactions window, you’ll see:</p><p><spanclass="RktVal">The margin is 8em.
<br/>The border is blue.
<br/>The padding is 2em.
<br/>The border is too.</span></p><p>This shows you something important: by default, any plain text in a Pollen source file is simply printed as written when you <spanclass="ssansserif">Run</span> the file (minus the <spanclass="stt">#lang</span> line, which is just for Racket’s benefit). If you like, edit the text of the poem and click <spanclass="ssansserif">Run</span> again. You’ll see the updated text printed in the interactions window.</p><h5>5.3.3<tt> </tt><aname="(part._.Saving___naming_your_source_file)"></a>Saving & naming your source file</h5><p>File naming in Pollen is consequential.</p><p>Ultimately, every Pollen source file in your project will be <spanstyle="font-style: italic">rendered</span> into an output file. Each Pollen source file corresponds to one output file. <spanstyle="font-weight: bold">The name of this output file will be the name of the source file minus the Pollen source extension.</span> So a source file called <spanclass="stt">file.txt.pp</span> will become <spanclass="stt">file.txt</span>.</p><p>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 <spanclass="stt">.pp</span>.</p><p>In this case, let’s say we want to end up with a file called <spanclass="stt">poem.html</span>. Therefore, the name of our source file needs to be:</p><p>the output name <spanclass="stt">poem.html</span> + the source extension <spanclass="stt">.pp</span> = <spanclass="stt">poem.html.pp</span></p><p>(If you want to name the file <spanclass="stt">something-else.html.pp</span>, be my guest. There’s no magic associated with the prefix.)</p><blockquoteclass="refpara"><blockquoteclass="refcolumn"><blockquoteclass="refcontent"><p>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.</p></blockquote></blockquote></blockquote><p>In a convenient location (e.g., your home directory or the desktop) create a new directory for your project called <spanclass="stt">tutorial</span>. In this new directory, save your DrRacket file as <spanclass="stt">poem.html.pp</span>.</p><blockquoteclass="Rfilebox"><pclass="Rfiletitle"><spanclass="Rfilename"><spanclass="stt">"/path/to/tutorial/poem.html.pp"</span></span></p><blockquoteclass="Rfilecontent"><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">#lang pollen</span></p></td></tr><tr><td><p><spanclass="stt"></span><spanclass="hspace"> </span></p></td></tr><tr><td><p><spanclass="stt">The margin is 42em.</span></p></td></tr><tr><td><p><spanclass="stt">The border is red.</span></p></td></tr><tr><td><p><spanclass="stt">The padding is 15em.</span></p></td></tr><tr><td><p><spanclass="stt">The border is too.</span></p></td></tr></table></blockquote></blockquote><h4>5.4<tt> </tt><aname="(part._.Using_the_project_server)"></a>Using the project server</h4><p>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.</p><p><imgsrc="project-server.png"alt=""width="670"height="412"/></p><p>“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 <spanclass="RktInBG"><spanclass="
</div><divclass="SIntrapara"><ul><li><p>inserting <spanclass="stt">#lang pollen</span> as the first line,</p></li><li><p>adding the <spanclass="stt">.pp</span> file extension,</p></li><li><p>running it through Pollen.</p></li></ul></div></p><blockquoteclass="refpara"><blockquoteclass="refcolumn"><blockquoteclass="refcontent"><p>For more about the Pollen processing modes and how to invoke them, see <ahref="file-types.html"data-pltdoc="x">File</a>.</p></blockquote></blockquote></blockquote><p>“The preprocessor be used with <spanstyle="font-weight: bold">any</span> 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 <ahref="https://en.wikipedia.org/wiki/TI-BASIC">TI-BASIC</a>.</p><p>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:</p><blockquoteclass="Rfilebox"><pclass="Rfiletitle"><spanclass="Rfilename"><spanclass="stt">"bad-poem.html.pp"</span></span></p><blockquoteclass="Rfilecontent"><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">#lang pollen</span></p></td></tr><tr><td><p><spanclass="stt"></span><spanclass="hspace"> </span></p></td></tr><tr><td><p><spanclass="stt">The cave is pitch black.</span></p></td></tr><tr><td><p><spanclass="stt">Look out for the grue.</span></p></td></tr><tr><td><p><spanclass="stt">◊(insert-mp3-recording-of-scream)</span></p></td></tr></table></blockquote></blockquote><p>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.</p><p>I’ve encouraged you to mess with the source file, but let’s return it to its original state:</p><blockquoteclass="Rfilebox"><pclass="Rfiletitle"><spanclass="Rfilename"><spanclass="stt">"/path/to/tutorial/poem.html.pp"</span></span></p><blockquoteclass="Rfilecontent"><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">#lang pollen</span></p></td></tr><tr><td><p><spanclass="stt"></span><spanclass="hspace"> </span></p></td></tr><tr><td><p><spanclass="stt">The margin is 42em.</span></p></td></tr><tr><td><p><spanclass="stt">The border is red.</span></p></td></tr><tr><td><p><spanclass="stt">The padding is 15em.</span></p></td></tr><tr><td><p><spanclass="stt">The border is too.</span></p></td></tr></table></blockquote></blockquote><p>This file has <spanclass="stt">#lang pollen</span> as the first line, and <spanclass="stt">.pp</span> as the file extension, so it meets the minimum requirements for the preprocessor.</p><h5>5.5.2<tt> </tt><aname="(part._.Creating_valid_.H.T.M.L_output)"></a>Creating valid HTML output</h5><p>Let’s update our source so it produces valid HTML. Edit the source as follows:</p><blockquoteclass="Rfilebox"><pclass="Rfiletitle"><spanclass="Rfilename"><spanclass="stt">"/path/to/tutorial/poem.html.pp"</span></span></p><blockquoteclass="Rfilecontent"><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">#lang pollen</span></p></td></tr><tr><td><p><spanclass="stt"><!DOCTYPE html></span></p></td></tr><tr><td><p><spanclass="stt"><html></span></p></td></tr><tr><td><p><spanclass="stt"><body></span></p></td></tr><tr><td><p><spanclass="stt"><pre></span></p></td></tr><tr><td><p><spanclass="stt">The margin is 42em.</span></p></td></tr><tr><td><p><spanclass="stt">The border is red.</span></p></td></tr><tr><td><p><spanclass="stt">The padding is 15em.</span></p></td></tr><tr><td><p><spanclass="stt">The border is too.</span></p></td></t
</span><br/><spanclass="stt">The border is red.</span><spanclass="stt">
</span><br/><spanclass="stt">The padding is 15em.</span><spanclass="stt">
</span><br/><spanclass="stt">The border is too.</span></p></blockquote><p>As before, because the source has changed, Pollen refreshes the output file. From the dashboard, you can use the <spanclass="stt">in</span> and <spanclass="stt">out</span> links to inspect the source and output.</p><p>This is now a valid HTML page.</p><h5>5.5.3<tt> </tt><aname="(part._.Adding_commands)"></a>Adding commands</h5><p>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.</p><p>Pollen commands can be embedded in your source file using one of two modes: <spanstyle="font-style: italic">Racket mode</span> or <spanstyle="font-style: italic">text mode</span>. We’ll try text mode in a later tutorial. For now, we’ll use Racket mode.</p><p>To make a Racket-mode Pollen command, just take any Racket expression and put the lozenge character (<spanclass="RktInBG"><spanclass="hspace"></span><spanclass="RktIn">◊</span><spanclass="hspace"></span></span>) in front of it. For instance, these are valid Racket expressions:</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">(define inner 2)</span></p></td></tr><tr><td><p><spanclass="stt">(define edge (* inner 4))</span></p></td></tr><tr><td><p><spanclass="stt">(define color "blue")</span></p></td></tr></table></blockquote><p>And these are the equivalent commands in Pollen:</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">◊(define inner 2)</span></p></td></tr><tr><td><p><spanclass="stt">◊(define edge (* inner 4))</span></p></td></tr><tr><td><p><spanclass="stt">◊(define color "blue")</span></p></td></tr></table></blockquote><p>How to type a lozenge:
<br/><spanstyle="font-weight: bold">Mac</span>: option + shift + V
<br/><spanstyle="font-weight: bold">Windows</span>: holding down alt, type 9674 on the num pad
<br/><spanstyle="font-weight: bold">Ubuntu</span>: ctrl + shift + U, then 25CA</p><h5>5.5.4<tt> </tt><aname="(part._.Racket_basics__if_you_re_not_familiar_)"></a>Racket basics (if you’re not familiar)</h5><p>“But how am I supposed to know Racket?” You don’t. So we’ll start now. Here are the five basic rules of Racket:</p><ol><li><p>The core building block of Racket is the <spanstyle="font-style: italic">expression</span>. An expression can be a value (like <spanclass="RktVal">2</span> or <spanclass="RktVal">"blue"</span>), a variable (like <spanclass="stt">edge</span>), or a function call (like <spanclass="RktPn">(</span><spanclass="RktSym">*</span><spanclass="stt"></span><spanclass="RktSym">inner</span><spanclass="stt"></span><spanclass="RktVal">4</span><spanclass="RktPn">)</span>).</p></li><li><p>Every expression is <spanstyle="font-style: italic">evaluated</span> to produce a value.</p></li><li><p>A variable evaluates to whatever value it holds (so <spanclass="stt">inner</span> would become <spanclass="RktVal">2</span>). A function call evaluates to its return value (so <spanclass="RktPn">(</span><spanclass="RktSym">+</span><spanclass="stt"></span><spanclass="RktVal">1</span><spanclass="stt"></span><spanclass="RktVal">1</span><spanclass="RktPn">)</span> would become <spanclass="RktVal">2</span>).</p></li><li><p>Function calls go between parentheses. Unlike most languages, the function name comes <spanstyle="font-style: italic">first</span>, followed by its arguments (so it’s <spanclass="RktPn">(</span><spanclass="RktSym">*</span><spanclass="stt"></span><spanclass="RktSym">inner</span><spanclass="stt"></span><spanclass="RktVal">4</span><spanclass="RktPn">)</span>, not <spanclass="RktPn">(</span><spanclass="RktSym">inner</span><spanclass="stt"></span><spanclass="RktSym">*</span><spanclass="stt"></span><spanclass="RktVal">4</span><spanclass="RktPn">)</span>). This is called <spanstyle="font-style: italic">prefix notation</span>.</p></li><li><p>Expressions can contain recursively nested expressions. Thus, <spanclass="RktPn">(</span><spanclass="RktSym">*</span><spanclass="stt"></span><spanclass="RktSym">inner</span><spanclass="stt"></span><spanclass="RktVal">4</span><spanclass="RktPn">)</span> could be written <spanclass="RktPn">(</span><spanclass="RktSym">*</span><spanclass="stt"></span><spanclass="RktSym">inner</span><spanclass="stt"></span><spanclass="RktPn">(</span><spanclass="RktSym">+</span><spanclass="stt"></span><spanclass="RktVal">2</span><spanclass="stt"></span><spanclass="RktVal">2</span><spanclass="RktPn">)</span><spanclass="RktPn">)</span> or <spanclass="RktPn">(</span><spanclass="RktSym">*</span><spanclass="stt"></span><spanclass="RktSym">inner</span><spanclass="stt"></span><spanclass="RktPn">(</span><spanclass="RktSym">+</span><spanclass="stt"></span><spanclass="RktPn">(</span><spanclass="RktSym">+</span><spanclass="stt"></span><spanclass="RktVal">1</span><spanclass="stt"></span><spanclass="RktVal">1</span><spanclass="RktPn">)</span><spanclass="stt"></span><spanclass="RktPn">(</span><spanclass="RktSym">+</span><spanclass="stt"></span><spanclass="RktVal">1</span><spanclass="stt"></span><spanclass="RktVal">1</span><spanclass="RktPn">)</span><spanclass="RktPn">)</span><spanclass="RktPn">)</span>.</p></li></ol><blockquoteclass="refpara"><blockquoteclass="refcolumn"><blockquoteclass="refcontent"><p>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.</p></blockquote></blockquote></blockquote><p>That should tell you enough to infer what’s going on in the Pollen commands above:</p><blockquoteclass="SCodeFlow"><tablecellspacing="0"cellpadding="0"><tr><td><p><spanclass="stt">◊(define inner 2)</span>
