pollen/scribblings/quick.scrbl

#lang scribble/manual

@title{Quick start}



@section{Creating a source file}

Assuming you've installed Racket & Pollen, launch DrRacket. 

Open a new document. Change the top line to:

@racketmod[pollen]

The first line of every Pollen source file will start with @tt{#lang pollen}.


@section{Running a source file}

Add a second line to your source file so it reads:

@racketmod[pollen
Hello world]

Click the @onscreen{Run} button. In the interactions window, you'll see the result:

@nested[#:style 'code-inset]{@racketvalfont{Hello world}}

Not bad. I think Pollen just won the @link["http://en.wikipedia.org/wiki/List_of_Hello_world_program_examples"]{Hello World Competition}.

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.

Try editing your source file:

@racketmod[pollen
Goodbye Stranger
Breakfast in America
Take the Long Way Home]

You don't have to use Supertramp song titles. Any text will do. When you click @onscreen{Run} again, you'll see whatever you typed:

@nested[#:style 'code-inset]{@racketvalfont{Goodbye Stranger}@(linebreak)@racketvalfont{Breakfast in America}@(linebreak)@racketvalfont{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:

@verbatim{
print "Hello world"
document.write('Hello world');
printf("Hello world");
}

In Pollen, what you write is what you get.


@section{Naming, saving, and rendering a source file}

Save this file with the name @tt{hello.txt.pp} in any convenient directory. The desktop is fine.

Open a terminal window and issue two commands:

@verbatim{
> cd [directory containing your file]
> raco pollen render hello.txt.pp}

After a moment, a new file will appear called @tt{hello.txt}. Let's see what's in it:

@verbatim{
> cat hello.txt
Goodbye Stranger
Breakfast in America
Take the Long Way Home
}

You've just learned three things:

@itemlist[

@item{Pollen commands in the terminal begin with @tt{raco pollen}, followed by a specific command (in this case @tt{render}) and sometimes an argument (in this case @tt{hello.txt.pp}).}

@item{The @tt{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.}

@item{The name of the output file is the same as the source file, minus the Pollen source extension. So @tt{hello.txt.pp} becomes @tt{hello.txt}.}
]

Try editing the text in the @tt{hello.txt.pp} source file and running @tt{raco pollen render hello.txt.pp} again. The old @tt{hello.txt} will be replaced with a new one showing your changes. And so you've learned a fourth thing:

@itemlist[
@item{Pollen works by rendering output files from source files. Output files can be overwritten. Therefore, you should only make edits to your source files.}
]


@section{The 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:

@verbatim{
> cd [directory containing your hello.txt.pp file]
> raco pollen start}

After a moment, you'll see the startup message:

@verbatim{
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 @tt{http://localhost:8080/index.ptree}. The top of the window will say @tt{Project root}. Below that will be a listing of the files in the directory. 

Among them will be @tt{hello.txt}, with a greyed-out @tt{.pp} extension. Click on it, and you'll be taken to @tt{http://localhost:8080/hello.txt}, where you'll see:

@verbatim{
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:

@racketmod[pollen
Mean Street
Panama
Hear About It Later]

Go back to your web browser and reload @tt{http://localhost:8080/hello.txt}. Now you'll see this:

@verbatim{
Mean Street
Panama
Hear About It Later}

The Pollen project server dyamically regenerates output files as you need them, including any time the underlying source file changes. If you like, try making some more changes to your @tt{hello.txt.pp} source file, and reloading the browser to see the updates.


@section{Intermission}

That's it for input & output. Now let's circle back and see what Pollen source files can do, other than printing plain text.

For the rest of this tutorial, I recommend keeping two windows on screen: a browser window with your project server, and the DrRacket editing window.

@section{Preprocessor files}


@section{Markup files}



@section{The plot thickens}

Start a new Pollen document. Remember to change the top line.

Underneath, type @code{Hello ◊(+ 1 2) Worlds}. The character before the left parenthesis is called a lozenge. Type it by [doing such and such].

Ask yourself: what are you likely to get when you run the file?

OK, now run the file.

The result will be @code{Hello 3 Worlds}. Hopefully, that's what you expected. 

Feel free to change the numbers inside the parenthesized expression and run the file again. The printed sum will change. You can also change the @code{+} sign to a @code{*} sign and make really big numbers. If you want to see your first stupid Pollen trick, type @code{Hello ◊(/ 38 57) of a World} and watch what happens.

Erase everything but the top line.

Type this: @code{
◊(define name "Roxy")

Hello ◊name}. 

What do you suppose you'll get this time?

Run the file. You'll see @code{Hello Roxy}.

The lozenge character (◊) tells Pollen to interpret what follows as code rather than plain text. This character is therefore the gateway to all the programming functions available in Pollen. In the first case, it denoted a math expression. In the second case, it denoted the definition of a variable, and then the variable itself.


@section{Making an HTML page with Pollen}

By default, Pollen operates in preprocessor mode. That means it evaluates all the expressions in your document, renders each as text, and then outputs the whole document as a text file. 

In this tutorial, you're going to make an HTML file. But you can use Pollen as a preprocessor for any kind of text file.

@margin-note{That means Pollen can act as a preprocessor for CSS, JavaScript, XML — and even source files for other programming languages.}


@subsection{Making an HTML page with Pollen in decoder mode}

@subsection{Using the Pollen dashboard}