You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
5 lines
48 KiB
HTML
5 lines
48 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><title>2 Quick tour</title><link rel="stylesheet" type="text/css" href="scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="racket.css" title="default"/><link rel="stylesheet" type="text/css" href="manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="manual-racket.css" title="default"/><script type="text/javascript" src="scribble-common.js"></script><script type="text/javascript" src="manual-racket.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="scribble-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">Pollen:<span class="mywbr"> </span> the book is a program</a></td></tr></table></div><div class="tocviewsublisttop" style="display: block;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="Installation.html" class="tocviewlink" data-pltdoc="x">Installation</a></td></tr><tr><td align="right">2 </td><td><a href="quick-tour.html" class="tocviewselflink" data-pltdoc="x">Quick tour</a></td></tr><tr><td align="right">3 </td><td><a href="Backstory.html" class="tocviewlink" data-pltdoc="x">Backstory</a></td></tr><tr><td align="right">4 </td><td><a href="big-picture.html" class="tocviewlink" data-pltdoc="x">The big picture</a></td></tr><tr><td align="right">5 </td><td><a href="first-tutorial.html" class="tocviewlink" data-pltdoc="x">First tutorial</a></td></tr><tr><td align="right">6 </td><td><a href="second-tutorial.html" class="tocviewlink" data-pltdoc="x">Second tutorial</a></td></tr><tr><td align="right">7 </td><td><a href="raco-pollen.html" class="tocviewlink" data-pltdoc="x">Using <span class="stt">raco pollen</span></a></td></tr><tr><td align="right">8 </td><td><a href="File_formats.html" class="tocviewlink" data-pltdoc="x">File formats</a></td></tr><tr><td align="right">9 </td><td><a href="reader.html" class="tocviewlink" data-pltdoc="x">◊ command overview</a></td></tr><tr><td align="right">10 </td><td><a href="Module_reference.html" class="tocviewlink" data-pltdoc="x">Module reference</a></td></tr><tr><td align="right">11 </td><td><a href="Acknowledgments.html" class="tocviewlink" data-pltdoc="x">Acknowledgments</a></td></tr><tr><td align="right">12 </td><td><a href="License___source_code.html" class="tocviewlink" data-pltdoc="x">License & source code</a></td></tr><tr><td align="right"></td><td><a href="doc-index.html" class="tocviewlink" data-pltdoc="x">Index</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>2 </td><td><a href="quick-tour.html" class="tocviewselflink" data-pltdoc="x">Quick tour</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">2.1 </td><td><a href="quick-tour.html#%28part._.Creating_a_source_file%29" class="tocviewlink" data-pltdoc="x">Creating a source file</a></td></tr><tr><td align="right">2.2 </td><td><a href="quick-tour.html#%28part._.Running_a_source_file%29" class="tocviewlink" data-pltdoc="x">Running a source file</a></td></tr><tr><td align="right">2.3 </td><td><a href="quick-tour.html#%28part._.Naming__saving__and_rendering_a_source_file%29" class="tocviewlink" data-pltdoc="x">Naming, saving, and rendering a source file</a></td></tr><tr><td align="right">2.4 </td><td><a href="quick-tour.html#%28part._.The_project_server%29" class="tocviewlink" data-pltdoc="x">The project server</a></td></tr><tr><td align="right">2.5 </td><td><a href="quick-tour.html#%28part._.Intermission%29" class="tocviewlink" data-pltdoc="x">Intermission</a></td></tr><tr><td align="right">2.6 </td><td><a href="quick-tour.html#%28part._.Pollen_as_a_preprocessor%29" class="tocviewlink" data-pltdoc="x">Pollen as a preprocessor</a></td></tr><tr><td align="right">2.7 </td><td><a href="quick-tour.html#%28part._.Markdown_mode%29" class="tocviewlink" data-pltdoc="x">Markdown mode</a></td></tr><tr><td align="right">2.8 </td><td><a href="quick-tour.html#%28part._.Markup_mode%29" class="tocviewlink" data-pltdoc="x">Markup mode</a></td></tr><tr><td align="right">2.9 </td><td><a href="quick-tour.html#%28part._.Templates%29" class="tocviewlink" data-pltdoc="x">Templates</a></td></tr><tr><td align="right">2.10 </td><td><a href="quick-tour.html#%28part._.P.S_for_.Scribble_users%29" class="tocviewlink" data-pltdoc="x">PS for Scribble users</a></td></tr><tr><td align="right">2.11 </td><td><a href="quick-tour.html#%28part._.The_end_of_the_beginning%29" class="tocviewlink" data-pltdoc="x">The end of the beginning</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber">2.1<tt> </tt></span><a href="#%28part._.Creating_a_source_file%29" class="tocsubseclink" data-pltdoc="x">Creating a source file</a></td></tr><tr><td><span class="tocsublinknumber">2.2<tt> </tt></span><a href="#%28part._.Running_a_source_file%29" class="tocsubseclink" data-pltdoc="x">Running a source file</a></td></tr><tr><td><span class="tocsublinknumber">2.3<tt> </tt></span><a href="#%28part._.Naming__saving__and_rendering_a_source_file%29" class="tocsubseclink" data-pltdoc="x">Naming, saving, and rendering a source file</a></td></tr><tr><td><span class="tocsublinknumber">2.4<tt> </tt></span><a href="#%28part._.The_project_server%29" class="tocsubseclink" data-pltdoc="x">The project server</a></td></tr><tr><td><span class="tocsublinknumber">2.5<tt> </tt></span><a href="#%28part._.Intermission%29" class="tocsubseclink" data-pltdoc="x">Intermission</a></td></tr><tr><td><span class="tocsublinknumber">2.6<tt> </tt></span><a href="#%28part._.Pollen_as_a_preprocessor%29" class="tocsubseclink" data-pltdoc="x">Pollen as a preprocessor</a></td></tr><tr><td><span class="tocsublinknumber">2.7<tt> </tt></span><a href="#%28part._.Markdown_mode%29" class="tocsubseclink" data-pltdoc="x">Markdown mode</a></td></tr><tr><td><span class="tocsublinknumber">2.8<tt> </tt></span><a href="#%28part._.Markup_mode%29" class="tocsubseclink" data-pltdoc="x">Markup mode</a></td></tr><tr><td><span class="tocsublinknumber">2.9<tt> </tt></span><a href="#%28part._.Templates%29" class="tocsubseclink" data-pltdoc="x">Templates</a></td></tr><tr><td><span class="tocsublinknumber">2.10<tt> </tt></span><a href="#%28part._.P.S_for_.Scribble_users%29" class="tocsubseclink" data-pltdoc="x">PS for Scribble users</a></td></tr><tr><td><span class="tocsublinknumber">2.11<tt> </tt></span><a href="#%28part._.The_end_of_the_beginning%29" class="tocsubseclink" data-pltdoc="x">The end of the beginning</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="version">6.0.1.13</span></div><div class="navsettop"><span class="navleft"><div class="nosearchform"></div> </span><span class="navright"> <a href="Installation.html" title="backward to "1 Installation"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Pollen: the book is a program"" data-pltdoc="x">up</a> <a href="Backstory.html" title="forward to "3 Backstory"" data-pltdoc="x">next →</a></span> </div><h3>2<tt> </tt><a name="(part._quick-tour)"></a>Quick tour</h3><h4>2.1<tt> </tt><a name="(part._.Creating_a_source_file)"></a>Creating a source file</h4><p>Assuming you’ve installed Racket & Pollen, launch DrRacket.</p><p>Open a new document. Change the top line to:</p><blockquote class="SCodeFlow"><p><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a></p></blockquote><p>The first line of every Pollen source file will start with <span class="stt">#lang pollen</span>.</p><h4>2.2<tt> </tt><a name="(part._.Running_a_source_file)"></a>Running a source file</h4><p>Add a second line to your source file so it reads:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a></td></tr><tr><td><span class="RktSym">Hello</span><span class="hspace"> </span><span class="RktSym">world</span></td></tr></table></blockquote><p>Click the <span class="ssansserif">Run</span> button. In the interactions window, you’ll see the result:</p><blockquote class="SCodeFlow"><p><span class="RktVal">Hello world</span></p></blockquote><p>Not bad. I think Pollen just won the <a href="http://en.wikipedia.org/wiki/List_of_Hello_world_program_examples">Hello World Tournament</a>.</p><p>You can work with Pollen source files in any text editor. The key advantage of DrRacket is that you can preview the results by running the file.</p><p>Try editing your source file:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a></td></tr><tr><td><span class="RktSym">Goodbye</span><span class="hspace"> </span><span class="RktSym">Stranger</span></td></tr><tr><td><span class="RktSym">Breakfast</span><span class="hspace"> </span><span class="RktSym">in</span><span class="hspace"> </span><span class="RktSym">America</span></td></tr><tr><td><span class="RktSym">Take</span><span class="hspace"> </span><span class="RktSym">the</span><span class="hspace"> </span><span class="RktSym">Long</span><span class="hspace"> </span><span class="RktSym">Way</span><span class="hspace"> </span><span class="RktSym">Home</span></td></tr></table></blockquote><p>You don’t have to use Supertramp song titles. Any text will do. When you click <span class="ssansserif">Run</span> again, you’ll see whatever you typed:</p><blockquote class="SCodeFlow"><p><span class="RktVal">Goodbye Stranger</span><br/><span class="RktVal">Breakfast in America</span><br/><span class="RktVal">Take the Long Way Home</span></p></blockquote><p>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:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">print "Hello world"</span></p></td></tr><tr><td><p><span class="stt">document.write('Hello world');</span></p></td></tr><tr><td><p><span class="stt">printf("Hello world");</span></p></td></tr></table></p><p>In Pollen, what you write is what you get.</p><h4>2.3<tt> </tt><a name="(part._.Naming__saving__and_rendering_a_source_file)"></a>Naming, saving, and rendering a source file</h4><p>Save this file with the name <span class="stt">hello.txt.pp</span> in any convenient directory. The desktop is fine.</p><p>Open a terminal window and issue two commands:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">> cd [directory containing your file]</span></p></td></tr><tr><td><p><span class="stt">> raco pollen render hello.txt.pp</span></p></td></tr></table></p><p>After a moment, a new file will appear called <span class="stt">hello.txt</span>. Let’s see what’s in it:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">> cat hello.txt</span></p></td></tr><tr><td><p><span class="stt">Goodbye Stranger</span></p></td></tr><tr><td><p><span class="stt">Breakfast in America</span></p></td></tr><tr><td><p><span class="stt">Take the Long Way Home</span></p></td></tr></table></p><p>You’ve just learned three things:</p><ul><li><p>Pollen commands in the terminal begin with <span class="stt">raco pollen</span>, followed by a specific command (in this case <span class="stt">render</span>) and sometimes an argument (in this case <span class="stt">hello.txt.pp</span>).</p></li><li><p>The <span class="stt">render</span> 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.</p></li><li><p>The name of the output file is the same as the source file, minus the Pollen source extension. So <span class="stt">hello.txt.pp</span> becomes <span class="stt">hello.txt</span>.</p></li></ul><p>Try editing the text in the <span class="stt">hello.txt.pp</span> source file and running <span class="stt">raco pollen render hello.txt.pp</span> again. The old <span class="stt">hello.txt</span> will be replaced with a new one showing your changes. And so you’ve learned a fourth thing:</p><ul><li><p>Pollen works by rendering output files from source files. Output files can be overwritten. Therefore, you should only make edits to your source files.</p></li></ul><h4>2.4<tt> </tt><a name="(part._.The_project_server)"></a>The project server</h4><p>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.</p><p>Now here’s a third: the Pollen project server. Here’s how you start it. Return to your terminal window and issue two commands:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">> cd [directory containing your hello.txt.pp file]</span></p></td></tr><tr><td><p><span class="stt">> raco pollen start</span></p></td></tr></table></p><p>After a moment, you’ll see the startup message:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">Welcome to Pollen 0.001 (Racket 6.0.0.5)</span></p></td></tr><tr><td><p><span class="stt">Project root is /path/to/your/directory</span></p></td></tr><tr><td><p><span class="stt">Project server is http://localhost:8080 (Ctrl-C to exit)</span></p></td></tr><tr><td><p><span class="stt">Project dashboard is http://localhost:8080/index.ptree</span></p></td></tr><tr><td><p><span class="stt">Ready to rock</span></p></td></tr></table></p><p>Open a web browser and point it at <a href="http://localhost:8080/index.ptree"><span class="stt">http://localhost:8080/index.ptree</span></a>. The top of the window will say <span class="stt">Project root</span>. Below that will be a listing of the files in the directory.</p><p>Among them will be <span class="stt">hello.txt</span>, with a greyed-out <span class="stt">.pp</span> extension. Click on it, and you’ll be taken to <a href="http://localhost:8080/hello.txt"><span class="stt">http://localhost:8080/hello.txt</span></a>, where you’ll see:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">Goodbye Stranger</span></p></td></tr><tr><td><p><span class="stt">Breakfast in America</span></p></td></tr><tr><td><p><span class="stt">Take the Long Way Home</span></p></td></tr></table></p><p>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:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"hello.txt.pp"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a></td></tr><tr><td><span class="RktSym">Mean</span><span class="hspace"> </span><span class="RktSym">Street</span></td></tr><tr><td><span class="RktSym">Panama</span></td></tr><tr><td><span class="RktSym">Hear</span><span class="hspace"> </span><span class="RktSym">About</span><span class="hspace"> </span><span class="RktSym">It</span><span class="hspace"> </span><span class="RktSym">Later</span></td></tr></table></blockquote></blockquote></blockquote><p>Go back to your web browser and reload <a href="http://localhost:8080/hello.txt"><span class="stt">http://localhost:8080/hello.txt</span></a>. Now you’ll see this:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">Mean Street</span></p></td></tr><tr><td><p><span class="stt">Panama</span></p></td></tr><tr><td><p><span class="stt">Hear About It Later</span></p></td></tr></table></p><p>Notice what happened — the Pollen project server dynamically regenerated the output file (<span class="stt">hello.txt</span>) from the source file (<span class="stt">hello.txt.pp</span>) after you edited the source. If you like, try making some more changes to <span class="stt">hello.txt.pp</span>, and reloading the browser to see the updates in <span class="stt">hello.txt</span>.</p><h4>2.5<tt> </tt><a name="(part._.Intermission)"></a>Intermission</h4><p>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).</p><p>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 <a href="http://localhost:8080/index.ptree"><span class="stt">http://localhost:8080/index.ptree</span></a>) and the DrRacket editing window.</p><h4>2.6<tt> </tt><a name="(part._.Pollen_as_a_preprocessor)"></a>Pollen as a preprocessor</h4><p>A <span style="font-style: italic">preprocessor</span> 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.</p><p>For instance, HTML. In DrRacket, create a new file called <span class="stt">margin.html.pp</span> in your project directory:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"margin.html.pp"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a></td></tr><tr><td><span class="RktSym"><body</span><span class="hspace"> </span><span class="RktSym">style=</span><span class="RktVal">"margin: 5em; border:1px solid black"</span><span class="RktSym">></span></td></tr><tr><td><span class="RktSym">5em</span><span class="hspace"> </span><span class="RktSym">is</span><span class="hspace"> </span><span class="RktSym">the</span><span class="hspace"> </span><span class="RktSym">inset.</span></td></tr><tr><td><span class="RktSym"></body></span></td></tr></table></blockquote></blockquote></blockquote><p>The “<span class="stt">.pp</span>” file extension — which you saw before, with <span class="stt">hello.txt.pp</span> — stands for “Pollen preprocessor.” You can use the Pollen preprocessor with any text-based file by inserting <span class="stt">#lang pollen</span> as the first line, and adding the <span class="stt">.pp</span> file extension.</p><p>But for now, go to your <a href="http://localhost:8080/index.ptree">project dashboard</a> and click on <a href="http://localhost:8080/margin.html"><span class="stt">margin.html</span></a>. You should see a black box containing the text “5em is the inset.”</p><p>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 <span class="stt">my-inset</span> by using the <span class="RktSym">define</span> command:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"margin.html.pp"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a></td></tr><tr><td><span class="RktSym">◊define</span><span class="RktPn">[</span><span class="RktSym">my-inset</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktSym">30%</span><span class="RktPn">}</span></td></tr><tr><td><span class="RktSym"><body</span><span class="hspace"> </span><span class="RktSym">style=</span><span class="RktVal">"margin: 10em; border:1px solid black"</span><span class="RktSym">></span></td></tr><tr><td><span class="RktSym">10em</span><span class="hspace"> </span><span class="RktSym">is</span><span class="hspace"> </span><span class="RktSym">the</span><span class="hspace"> </span><span class="RktSym">inset.</span></td></tr><tr><td><span class="RktSym"></body></span></td></tr></table></blockquote></blockquote></blockquote><p>The ◊ character is called a <span style="font-style: italic">lozenge</span>. In Pollen, the lozenge is a special character that marks anything Pollen should interpret as a command (rather than plain text).</p><p>How to type a lozenge:
|
|
<br/><span style="font-weight: bold">Mac</span>: option + shift + V
|
|
<br/><span style="font-weight: bold">Windows</span>: holding down alt, type 9674 on the num pad
|
|
<br/><span style="font-weight: bold">Ubuntu</span>: ctrl + shift + U, then 25CA</p><p>The whole command <span class="stt">◊define[my-inset]{30%}</span> means “create a variable called <span class="stt">my-inset</span> and give it the value <span class="stt">30%</span>.”</p><p>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:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"margin.html.pp"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a></td></tr><tr><td><span class="RktSym">◊define</span><span class="RktPn">[</span><span class="RktSym">my-inset</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktSym">30%</span><span class="RktPn">}</span></td></tr><tr><td><span class="RktSym"><body</span><span class="hspace"> </span><span class="RktSym">style=</span><span class="RktVal">"margin: ◊my-inset; border:1px solid black"</span><span class="RktSym">></span></td></tr><tr><td><span class="RktSym">◊my-inset</span><span class="hspace"> </span><span class="RktSym">is</span><span class="hspace"> </span><span class="RktSym">the</span><span class="hspace"> </span><span class="RktSym">inset.</span></td></tr><tr><td><span class="RktSym"></body></span></td></tr></table></blockquote></blockquote></blockquote><p>Now reload <a href="http://localhost:8080/margin.html"><span class="stt">margin.html</span></a>. You’ll see that the size of the margin has changed (because of the change to the <span class="stt">style</span> attribute) and so has the text of the HTML. If you like, try editing <span class="stt">my-inset</span> with different values and reloading the page. You can also try using <span class="RktSym">define</span> to create another variable (for instance, to change the color of the box border).</p><p>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.</p><h4>2.7<tt> </tt><a name="(part._.Markdown_mode)"></a>Markdown mode</h4><p>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 <span class="stt"><tedious>tags</tedious></span>? You can make Pollen do the heavy lifting by using it as a source decoder.</p><p>For instance, Markdown mode. Markdown is a simplified <a href="https://daringfireball.net/projects/markdown/">notation system</a> for HTML. You can use Pollen’s Markdown decoder by inserting <span class="stt">#lang pollen</span> as the first line, and adding the <span class="stt">.pmd</span> file extension.</p><p>Try it. In DrRacket, create a file with the following lines and save it as <span class="stt">downtown.html.pmd</span>:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"downtown.html.pmd"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktSym">Pollen</span><span class="hspace"> </span><span class="RktSym">+</span><span class="hspace"> </span><span class="RktSym">Markdown</span></td></tr><tr><td><span class="RktSym"><span class="nobreak">-----------------</span></span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktSym">+</span><span class="hspace"> </span><span class="RktSym">You</span><span class="hspace"> </span><span class="RktSym">**wanted**</span><span class="hspace"> </span><span class="RktSym">it</span><span class="hspace"> </span><span class="RktSym">—</span><span class="hspace"> </span><span class="RktSym">you</span><span class="hspace"> </span><span class="stt">_got_</span><span class="hspace"> </span><span class="RktSym">it.</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktSym">+</span><span class="hspace"> </span><span class="RktPn">[</span><span class="RktSym">search</span><span class="hspace"> </span><span class="RktSym">for</span><span class="hspace"> </span><span class="RktSym">Racket</span><span class="RktPn">]</span><span class="RktPn">(</span><span class="RktSym">https://google.com/search?q=racket</span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote></blockquote><p>As before, go to the <a href="http://localhost:8080/index.ptree">dashboard</a> for the project server. This time, click the link for <a href="http://localhost:8080/downtown.html"><span class="stt">downtown.html</span></a>. You’ll see something like this:</p><blockquote class="SCodeFlow"><p><span style="font-weight: bold"><span class="Larger">Pollen + Markdown</span></span></p><blockquote><ul><li><p>You <span style="font-weight: bold">wanted</span> it — you <span style="font-style: italic">got</span> it.</p></li><li><p><a href="https://google.com/search?q=racket">search for Racket</a></p></li></ul></blockquote></blockquote><p>As usual, you’re welcome to edit <span class="stt">downtown.html.pmd</span> and then refresh the web browser to see the changes.</p><p>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 <span class="stt">define</span> to create a variable called <span class="stt">metal</span>, and insert it into the Markdown:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"downtown.html.pmd"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a></td></tr><tr><td><span class="RktSym">◊define</span><span class="RktPn">[</span><span class="RktSym">metal</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktSym">Plutonium</span><span class="RktPn">}</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktSym">Pollen</span><span class="hspace"> </span><span class="RktSym">+</span><span class="hspace"> </span><span class="RktSym">◊metal</span></td></tr><tr><td><span class="RktSym"><span class="nobreak">--------</span></span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktSym">+</span><span class="hspace"> </span><span class="RktSym">You</span><span class="hspace"> </span><span class="RktSym">**wanted**</span><span class="hspace"> </span><span class="RktSym">◊metal</span><span class="hspace"> </span><span class="RktSym">—</span><span class="hspace"> </span><span class="RktSym">you</span><span class="hspace"> </span><span class="stt">_got_</span><span class="hspace"> </span><span class="RktSym">it.</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktSym">+</span><span class="hspace"> </span><span class="RktPn">[</span><span class="RktSym">search</span><span class="hspace"> </span><span class="RktSym">for</span><span class="hspace"> </span><span class="RktSym">◊metal</span><span class="RktPn">]</span><span class="RktPn">(</span><span class="RktSym">https://google.com/search?q=◊metal</span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote></blockquote><p>Refresh <a href="http://localhost:8080/downtown.html"><span class="stt">downtown.html</span></a> in the browser:</p><blockquote class="SCodeFlow"><p><span style="font-weight: bold"><span class="Larger">Pollen + Plutonium</span></span></p><blockquote><ul><li><p>You <span style="font-weight: bold">wanted</span> Plutonium — you <span style="font-style: italic">got</span> it.</p></li><li><p><a href="https://google.com/search?q=Plutonium">search for Plutonium</a></p></li></ul></blockquote></blockquote><p>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 <span class="stt">downtown.html.pmd</span> to <span class="stt">downtown.md.pp</span>. Changing the extension from <span class="stt">.pmd</span> to <span class="stt">.pp</span> switches Pollen from Markdown mode back to preprocessor mode. And changing the base name from <span class="stt">downtown.html</span> to <span class="stt">downtown.md</span> updates the name of the output file.</p><h4>2.8<tt> </tt><a name="(part._.Markup_mode)"></a>Markup mode</h4><p>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.</p><p>In that case, you can use Pollen markup mode. To use Pollen markup, insert <span class="stt">#lang pollen</span> as the first line of your source file, and add a <span class="stt">.pm</span> file extension.</p><p>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.</p><p>Let’s convert our Markdown example into Pollen markup. Marking up content is simple: insert the lozenge character (<span class="stt">◊</span>) followed by the name of the tag (<span class="stt">◊tag</span>), followed by the content of the tag in curly braces (<span class="stt">◊tag{content}</span>). In DrRacket, create a new file called <span class="stt">uptown.html.pm</span> as follows:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"uptown.html.pm"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">pollen</span></a></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktSym">◊headline</span><span class="RktPn">{</span><span class="RktSym">Pollen</span><span class="hspace"> </span><span class="RktSym">markup</span><span class="RktPn">}</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktSym">◊items</span><span class="RktPn">{</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktSym">◊item</span><span class="RktPn">{</span><span class="RktSym">You</span><span class="hspace"> </span><span class="RktSym">◊strong</span><span class="RktPn">{</span><span class="RktSym">wanted</span><span class="RktPn">}</span><span class="hspace"> </span><span class="RktSym">it</span><span class="hspace"> </span><span class="RktSym">—</span><span class="hspace"> </span><span class="RktSym">you</span><span class="hspace"> </span><span class="RktSym">◊em</span><span class="RktPn">{</span><span class="RktSym">got</span><span class="RktPn">}</span><span class="hspace"> </span><span class="RktSym">it.</span><span class="RktPn">}</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktSym">◊item</span><span class="RktPn">{</span><span class="RktSym">◊link</span><span class="RktPn">[</span><span class="RktVal">"https://google.com/search?q=racket"</span><span class="RktPn">]</span><span class="RktPn">{</span><span class="RktSym">search</span><span class="hspace"> </span><span class="RktSym">for</span><span class="hspace"> </span><span class="RktSym">Racket</span><span class="RktPn">}</span><span class="RktPn">}</span><span class="RktPn">}</span></td></tr></table></blockquote></blockquote></blockquote><p>Go to the <a href="http://localhost:8080/index.ptree">project dashboard</a> and click on <a href="http://localhost:8080/uptown.html"><span class="stt">uptown.html</span></a>. You’ll see something like this:</p><blockquote class="SCodeFlow"><p>Pollen markup You <span style="font-weight: bold">wanted</span> it — you <span style="font-style: italic">got</span> it. https://google.com/search?q=racketsearch for Racket</p></blockquote><p>That’s not right. What happened?</p><p>We marked up the source using a combination of standard HTML tags (<span class="stt">strong</span>, <span class="stt">em</span>) and nonstandard ones (<span class="stt">headline</span>, <span class="stt">items</span>, <span class="stt">item</span>, <span class="stt">link</span>). This is valid Pollen markup. (In fact, if you look at <a href="http://localhost:8080/out/markup.html">the generated source</a>, 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.</p><p>For that, we’ll make a special file called <span class="stt">project-require.rkt</span>. 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:</p><blockquote class="SCodeFlow"><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"project-require.rkt"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="http://docs.racket-lang.org/reference/index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/base</span></a></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym">require</span><span class="hspace"> </span><span class="RktSym">pollen/tag</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym">provide</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">all-defined-out</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym">define</span><span class="hspace"> </span><span class="RktSym">headline</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">make-tag-function</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">h2</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym">define</span><span class="hspace"> </span><span class="RktSym">items</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">make-tag-function</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">ul</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym">define</span><span class="hspace"> </span><span class="RktSym">item</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">make-tag-function</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">li</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">p</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym">define</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">link</span><span class="hspace"> </span><span class="RktSym">url</span><span class="hspace"> </span><span class="RktSym">text</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">`</span><span class="RktVal">(</span><span class="RktVal">a</span><span class="hspace"> </span><span class="RktVal">[</span><span class="RktVal">[</span><span class="RktVal">href</span><span class="hspace"> </span><span class="RktRdr">,</span><span class="RktSym">url</span><span class="RktVal">]</span><span class="RktVal">]</span><span class="hspace"> </span><span class="RktRdr">,</span><span class="RktSym">text</span><span class="RktVal">)</span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote></blockquote><p>Return to the <a href="http://localhost:8080/index.ptree">project dashboard</a> and click on <a href="http://localhost:8080/uptown.html"><span class="stt">uptown.html</span></a>. Now you’ll get the right result:</p><blockquote class="SCodeFlow"><p><span style="font-weight: bold"><span class="Larger">Pollen markup</span></span></p><blockquote><ul><li><p>You <span style="font-weight: bold">wanted</span> it — you <span style="font-style: italic">got</span> it.</p></li><li><p><a href="https://google.com/search?q=racket">search for Racket</a></p></li></ul></blockquote></blockquote><p>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.</p><h4>2.9<tt> </tt><a name="(part._.Templates)"></a>Templates</h4><p>The HTML pages we just made looked pretty dull. For the last stop on the quick tour, let’s fix that.</p><p>Pollen source files that are written in Markdown or markup mode (i.e., <span class="stt">.pmd</span> or <span class="stt">.pm</span> files) are rendered with a <span style="font-style: italic">template</span>. 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 <span style="font-style: italic">template variables</span> that mark where values from the Pollen source file should be inserted.</p><p>When it needs a template, Pollen first looks for a file in the project directory named <span class="stt">template.[output extension of source]</span>. For <span class="stt">uptown.html.pm</span>, the output extension will be <span class="stt">.html</span>, thus Pollen will look for <span class="stt">template.html</span>.</p><p>So let’s create <span class="stt">template.html</span>. Make a new file that with the following lines and save it to the same directory as <span class="stt">uptown.html.pm</span>:</p><blockquote class="Rfilebox"><p class="Rfiletitle"><span class="Rfilename"><span class="stt">"template.html"</span></span></p><blockquote class="Rfilecontent"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt"><html><head><meta charset="UTF-8"/></head></span></p></td></tr><tr><td><p><span class="stt"><body style="background: #f6f6f6"></span></p></td></tr><tr><td><p><span class="stt"><div style="background: white; margin: 3em;</span></p></td></tr><tr><td><p><span class="stt">border:10px double gray; padding: 3em; font-size: 130%;"></span></p></td></tr><tr><td><p><span class="stt">This file is ◊here</span></p></td></tr><tr><td><p><span class="stt"><hr /></span></p></td></tr><tr><td><p><span class="stt">◊->html{◊doc}</span></p></td></tr><tr><td><p><span class="stt"></div></body></html></span></p></td></tr></table></blockquote></blockquote><p>This is a simple HTML file that should look familiar, except for the two template variables. The first, <span class="stt">here</span>, 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 <span class="stt">◊here</span>. The other command, <span class="stt">◊->html{◊doc}</span>, takes the content from the source file, which is contained in a variable called <span class="stt">doc</span>, and converts it to HTML with a Pollen function called <span class="stt">->html</span>.</p><p>Go back to your web browser and reload <a href="http://localhost:8080/uptown.html"><span class="stt">uptown.html</span></a>. (Or <a href="http://localhost:8080/downtown.html"><span class="stt">downtown.html</span></a> — both will work.) The page will be rendered with the new <span class="stt">template.html</span>. As before, you can edit the template or the source and the project server will dynamically update the output file.</p><h4>2.10<tt> </tt><a name="(part._.P.S_for_.Scribble_users)"></a>PS for Scribble users</h4><p>Pollen can also be used as a dynamic preview server for Scribble files. From your terminal, do the following:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">> cd [directory containing your Scribble files]</span></p></td></tr><tr><td><p><span class="stt">> raco pollen start</span></p></td></tr></table></p><p>On the <a href="http://localhost:8080/index.ptree">project dashboard</a>, you’ll see your <span class="stt">[filename].scrbl</span> files listed as <span class="stt">[filename].html</span>. 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.</p><h4>2.11<tt> </tt><a name="(part._.The_end_of_the_beginning)"></a>The end of the beginning</h4><p>Now you’ve seen the key features of Pollen. What do you think?</p><ul><li><p><span style="font-style: italic">“So it’s like WordPress, but harder to use?”</span> 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.</p></li><li><p><span style="font-style: italic">“What about pairing a Python template system and Python web server?”</span> 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.</p></li><li><p><span style="font-style: italic">“Haven’t you heard of Jekyll?”</span> Yes. If everything you need to write is expressible in Markdown, it’s great. If you need more than that, you’re stuck.</p></li><li><p><span style="font-style: italic">“Sounds a lot like LaTeX. Why not use that?”</span> Also a good idea. LaTeX gets a lot of things right. But it wasn’t designed for web publishing.</p></li><li><p><span style="font-style: italic">“Eh, there are plenty of adequate options. Why should I learn a system written in Racket, which I’ve never used?”</span> 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.</p></li></ul><p>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.</p><div class="navsetbottom"><span class="navleft"><div class="nosearchform"></div> </span><span class="navright"> <a href="Installation.html" title="backward to "1 Installation"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Pollen: the book is a program"" data-pltdoc="x">up</a> <a href="Backstory.html" title="forward to "3 Backstory"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html> |