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.
3 lines
19 KiB
HTML
3 lines
19 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>4 The big picture</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="tocviewlink" 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="tocviewselflink" 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="third-tutorial.html" class="tocviewlink" data-pltdoc="x">Third tutorial</a></td></tr><tr><td align="right">8 </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">9 </td><td><a href="File_formats.html" class="tocviewlink" data-pltdoc="x">File formats</a></td></tr><tr><td align="right">10 </td><td><a href="reader.html" class="tocviewlink" data-pltdoc="x">◊ command overview</a></td></tr><tr><td align="right">11 </td><td><a href="Module_reference.html" class="tocviewlink" data-pltdoc="x">Module reference</a></td></tr><tr><td align="right">12 </td><td><a href="Acknowledgments.html" class="tocviewlink" data-pltdoc="x">Acknowledgments</a></td></tr><tr><td align="right">13 </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>4 </td><td><a href="big-picture.html" class="tocviewselflink" data-pltdoc="x">The big picture</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">4.1 </td><td><a href="big-picture.html#%28part._the-book-is-a-program%29" class="tocviewlink" data-pltdoc="x">The book is a program</a></td></tr><tr><td align="right">4.2 </td><td><a href="big-picture.html#%28part._.One_language__multiple_dialects%29" class="tocviewlink" data-pltdoc="x">One language, multiple dialects</a></td></tr><tr><td align="right">4.3 </td><td><a href="big-picture.html#%28part._.Development_environment%29" class="tocviewlink" data-pltdoc="x">Development environment</a></td></tr><tr><td align="right">4.4 </td><td><a href="big-picture.html#%28part._.A_special_data_structure_for_.H.T.M.L%29" class="tocviewlink" data-pltdoc="x">A special data structure for HTML</a></td></tr><tr><td align="right">4.5 </td><td><a href="big-picture.html#%28part._.Pollen_command_syntax%29" class="tocviewlink" data-pltdoc="x">Pollen command syntax</a></td></tr><tr><td align="right">4.6 </td><td><a href="big-picture.html#%28part._.The_preprocessor%29" class="tocviewlink" data-pltdoc="x">The preprocessor</a></td></tr><tr><td align="right">4.7 </td><td><a href="big-picture.html#%28part._.Templated_source_files%29" class="tocviewlink" data-pltdoc="x">Templated source files</a></td></tr><tr><td align="right">4.8 </td><td><a href="big-picture.html#%28part._.Pagetrees%29" class="tocviewlink" data-pltdoc="x">Pagetrees</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">4.1<tt> </tt></span><a href="#%28part._the-book-is-a-program%29" class="tocsubseclink" data-pltdoc="x">The book is a program</a></td></tr><tr><td><span class="tocsublinknumber">4.2<tt> </tt></span><a href="#%28part._.One_language__multiple_dialects%29" class="tocsubseclink" data-pltdoc="x">One language, multiple dialects</a></td></tr><tr><td><span class="tocsublinknumber">4.3<tt> </tt></span><a href="#%28part._.Development_environment%29" class="tocsubseclink" data-pltdoc="x">Development environment</a></td></tr><tr><td><span class="tocsublinknumber">4.4<tt> </tt></span><a href="#%28part._.A_special_data_structure_for_.H.T.M.L%29" class="tocsubseclink" data-pltdoc="x">A special data structure for HTML</a></td></tr><tr><td><span class="tocsublinknumber">4.5<tt> </tt></span><a href="#%28part._.Pollen_command_syntax%29" class="tocsubseclink" data-pltdoc="x">Pollen command syntax</a></td></tr><tr><td><span class="tocsublinknumber">4.6<tt> </tt></span><a href="#%28part._.The_preprocessor%29" class="tocsubseclink" data-pltdoc="x">The preprocessor</a></td></tr><tr><td><span class="tocsublinknumber">4.7<tt> </tt></span><a href="#%28part._.Templated_source_files%29" class="tocsubseclink" data-pltdoc="x">Templated source files</a></td></tr><tr><td><span class="tocsublinknumber">4.8<tt> </tt></span><a href="#%28part._.Pagetrees%29" class="tocsubseclink" data-pltdoc="x">Pagetrees</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="version">6.1.0.5</span></div><div class="navsettop"><span class="navleft"><div class="nosearchform"></div> </span><span class="navright"> <a href="Backstory.html" title="backward to "3 Backstory"" 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="first-tutorial.html" title="forward to "5 First tutorial"" data-pltdoc="x">next →</a></span> </div><h3>4<tt> </tt><a name="(part._big-picture)"></a>The big picture</h3><p>A summary of the key components & concepts of the Pollen publishing system and how they fit together. If you’ve completed the <a href="quick-tour.html" data-pltdoc="x">Quick tour</a>, this will lend some context to what you saw. The next tutorials will make more sense if you read this first.</p><h4>4.1<tt> </tt><a name="(part._the-book-is-a-program)"></a>The book is a program</h4><p>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.</p><ul><li><p><span style="font-weight: bold">You are a programmer.</span> 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.)</p></li><li><p><span style="font-weight: bold">A Pollen project consists of source files + static files.</span> A <span style="font-style: italic">source file</span> is a file that can be compiled to produce certain output. A <span style="font-style: italic">static file</span> 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.</p></li><li><p><span style="font-weight: bold">Source control is a good idea.</span> Because Pollen projects are software projects, they can be easily managed with systems for source control and collaboration, like <a href="http://github.com">GitHub</a>. 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.</p></li></ul><h4>4.2<tt> </tt><a name="(part._.One_language__multiple_dialects)"></a>One language, multiple dialects</h4><ul><li><p><span style="font-weight: bold">Everything is Racket.</span> 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 <a href="http://docs.racket-lang.org/quick/index.html" data-pltdoc="x">Quick: An Introduction to Racket with Pictures</a>).</p></li><li><p><span style="font-weight: bold">The Pollen language is based on Scribble.</span> 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 <a href="https://en.wikipedia.org/wiki/TeX">TeX</a>). The Pollen language is adapted from Scribble. So most things that are true about Scribble are also true about Pollen (see <a href="http://docs.racket-lang.org/scribble/index.html" data-pltdoc="x">Scribble: The Racket Documentation Tool</a>).</p></li><li><p><span style="font-weight: bold">The Pollen language is divided into dialects.</span> 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.</p></li></ul><h4>4.3<tt> </tt><a name="(part._.Development_environment)"></a>Development environment</h4><p>The Pollen development environment has three main pieces: the DrRacket code editor, the project server, and the command-line tool.</p><ul><li><p><span style="font-weight: bold">Edit source files with DrRacket.</span> 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.</p></li><li><p><span style="font-weight: bold">Preview & test web pages with the Pollen project server.</span> Pollen has a built-in development web server called the <span style="font-style: italic">project server</span>. After you start the project server, you can preview your web pages within any web browser, allowing you to test them with maximum accuracy.</p></li><li><p><span style="font-weight: bold">Write the docs.</span> The project server can recognize and render Scribble files, so you can use it as a previewing tool while you’re writing your documentation.</p></li><li><p><span style="font-weight: bold">Render & deploy from the command line.</span> 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.</p></li></ul><h4>4.4<tt> </tt><a name="(part._.A_special_data_structure_for_.H.T.M.L)"></a>A special data structure for HTML</h4><p>Unlike other programming languages, Pollen (and Racket) internally represent HTML with something called an <span style="font-style: italic">X-expression</span>. An X-expression is simply a list that represents what in HTML is called an <span style="font-style: italic">element</span>, 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.</p><p>For example, consider this HTML element:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt"><body><h1>Hello world</h1><p>Nice to <i>see</i> you.</p></body></span></p></td></tr></table></blockquote><p>As a Racket X-expression, this would be written:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">(body (h1 "Hello world") (p "Nice to " (i "see") " you."))</span></p></td></tr></table></blockquote><p>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.</p><h4>4.5<tt> </tt><a name="(part._.Pollen_command_syntax)"></a>Pollen command syntax</h4><p>As mentioned above, a Pollen source file is not code with text embedded in it, but rather text with code embedded. (See <a href="reader.html" data-pltdoc="x">◊ command overview</a> for more.)</p><ul><li><p><div class="SIntrapara"><span style="font-weight: bold">If you can write text, you can program in Pollen.</span> Really. As you already found out in the <a href="quick-tour.html" data-pltdoc="x">Quick tour</a>, this is a valid Pollen program:
|
|
</div><div class="SIntrapara"><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><span class="hspace"> </span><span class="RktSym">how</span><span class="hspace"> </span><span class="RktSym">are</span><span class="hspace"> </span><span class="RktSym">you</span><span class="hspace"> </span><span class="RktSym">on</span><span class="hspace"> </span><span class="RktSym">this</span><span class="hspace"> </span><span class="RktSym">fine</span><span class="hspace"> </span><span class="RktSym">summer</span><span class="hspace"> </span><span class="RktSym">day?</span></td></tr></table></blockquote></div></p></li><li><p><span style="font-weight: bold">Commands start with ◊.</span> A simple rule: if a piece of text starts with <span class="RktInBG"><span class="hspace"></span><span class="RktIn">◊</span><span class="hspace"></span></span>, it’s treated as a command; otherwise it’s treated as ordinary text.</p></li><li><p><span style="font-weight: bold">Write commands in text mode or Racket mode.</span> Commands can use two equivalent notation systems: either Pollen’s text-mode command syntax, or standard Racket syntax.</p></li><li><p><span style="font-weight: bold">Everything in Racket is in Pollen too.</span> This isn’t some dimwit “template language.” Racket is a fully provisioned programming language, and every Racket function is available in Pollen.</p></li></ul><h4>4.6<tt> </tt><a name="(part._.The_preprocessor)"></a>The preprocessor</h4><p>The <span style="font-style: italic">preprocessor</span> is the simplest processing mode in Pollen.</p><ul><li><p><span style="font-weight: bold">Text output.</span> The preprocessor scans the source for any Pollen commands, resolves them, and outputs the whole file as text.</p></li><li><p><span style="font-weight: bold">Work with any text file.</span> 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).</p></li><li><p><span style="font-weight: bold">Start quickly.</span> 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.</p></li></ul><h4>4.7<tt> </tt><a name="(part._.Templated_source_files)"></a>Templated source files</h4><p>If you want to apply a particular page format to multiple sources of content — as you would in a book — you can use Pollen <span style="font-style: italic">templates</span>.</p><ul><li><p><span style="font-weight: bold">Templates can be any format.</span> Usually Pollen templates will be HTML. But they don’t have to be.</p></li><li><p><span style="font-weight: bold">Markdown support.</span> Pollen has a built-in Markdown parser, so you can import Markdown sources into a Pollen publication.</p></li><li><p><span style="font-weight: bold">Custom markup.</span> Pollen’s markup mode allows you the freedom to define your own markup tags and attach behavior to them.</p></li><li><p><span style="font-weight: bold">Mix source types.</span> 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.</p></li></ul><h4>4.8<tt> </tt><a name="(part._.Pagetrees)"></a>Pagetrees</h4><p>Similar to a table of contents, a <span style="font-style: italic">pagetree</span> is a special Pollen source file that gets turned into a hierarchical list of pages.</p><ul><li><p><span style="font-weight: bold">Navigation.</span> Pagetrees are used to provide navigation links within HTML templates (like previous, next, up, top).</p></li><li><p><span style="font-weight: bold">Organization.</span> Multiple pagetrees can be used to divide your project into subsets of pages that should be treated separately.</p></li></ul><div class="navsetbottom"><span class="navleft"><div class="nosearchform"></div> </span><span class="navright"> <a href="Backstory.html" title="backward to "3 Backstory"" 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="first-tutorial.html" title="forward to "5 First tutorial"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html> |