@ -80,7 +80,7 @@ Hello world: how are you on this fine summer day?
@item{@bold{Commands start with ◊.} A simple rule: if a piece of text starts with @litchar{◊}, it's treated as a command; otherwise it's treated as ordinary text.}
@item{@bold{Commands start with ◊.} A simple rule: if a piece of text starts with @litchar{◊}, it's treated as a command; otherwise it's treated as ordinary text.}
@item{@bold{Write commands in text mode or Racket mode.} Commands can use two equivalent notation systems: either Pollen's text-mode command syntax, or standard Racket syntax.}
@item{@bold{Write commands in Pollen mode or Racket mode.} Commands can use two equivalent notation systems: either Pollen's text-oriented command syntax, or standard Racket syntax.}
@item{@bold{Everything in Racket is in Pollen too.} Pollen isn't a watered-down ``template language.'' Racket is a fully provisioned programming language, and every Racket function is available in Pollen.}
@item{@bold{Everything in Racket is in Pollen too.} Pollen isn't a watered-down ``template language.'' Racket is a fully provisioned programming language, and every Racket function is available in Pollen.}
A text-mode command has the three possible parts after the @litchar["◊"]:
A Pollen-mode command has the three possible parts after the @litchar["◊"]:
@itemlist[
@itemlist[
@item{The @italic{command name} appears immediately after the @litchar["◊"]. Typically it's a short word.}
@item{The @italic{command name} appears immediately after the @litchar["◊"]. Typically it's a short word.}
@ -127,7 +127,7 @@ Each of the three parts is optional. You can also nest commands within each othe
@item{Whatever parts you use must always appear in the order above.}
@item{Whatever parts you use must always appear in the order above.}
]
]
Here are a few examples of correct text-mode commands:
Here are a few examples of correct Pollen-mode commands:
@codeblock{
@codeblock{
#lang pollen
#lang pollen
@ -174,9 +174,9 @@ And in DrRacket, they produce the same output:
Beyond that, there's not much to say about Racket mode —any valid expression you can write in Racket will also be a valid Racket-mode Pollen command.
Beyond that, there's not much to say about Racket mode —any valid expression you can write in Racket will also be a valid Racket-mode Pollen command.
@bold{The relationship of text mode and Racket mode}
@bold{The relationship of Pollen mode and Racket mode}
Even if you don't plan to write a lot of Racket-mode commands, you should be aware that under the hood, Pollen is converting all commands in text mode to Racket mode. So a text-mode command that looks like this:
Even if you don't plan to write a lot of Racket-mode commands, you should be aware that under the hood, Pollen is converting all commands in Pollen mode to Racket mode. So a Pollen-mode command that looks like this:
@codeblock[#:keep-lang-line? #f]{
@codeblock[#:keep-lang-line? #f]{
#lang pollen
#lang pollen
@ -191,7 +191,7 @@ Is actually being turned into a Racket-mode command like this:
(headline #:size 'enormous "Man Bites Dog!")
(headline #:size 'enormous "Man Bites Dog!")
}
}
Thus a text-mode command is just an alternate way of writing a Racket-mode command. (More broadly, all of Pollen is just an alternate way of using Racket.)
Thus a Pollen-mode command is just an alternate way of writing a Racket-mode command. (More broadly, all of Pollen is just an alternate way of using Racket.)
The corollary is that you can always write Pollen commands using whichever mode is more convenient or readable. For instance, the earlier example, written in the Racket mode:
The corollary is that you can always write Pollen commands using whichever mode is more convenient or readable. For instance, the earlier example, written in the Racket mode:
@ -201,7 +201,7 @@ The corollary is that you can always write Pollen commands using whichever mode
◊(format "~a #~a" song (* 3 3))
◊(format "~a #~a" song (* 3 3))
}
}
Can be rewritten using text mode:
Can be rewritten using Pollen mode:
@codeblock{
@codeblock{
#lang pollen
#lang pollen
@ -399,7 +399,7 @@ The value of foo is ◊foo
Be careful —if you include arguments, even blank ones, Pollen will treat the command name as a function. This won't work, because a variable is not a function:
Be careful —if you include arguments, even blank ones, Pollen will treat the command name as a function. This won't work, because a variable is not a function:
@margin-note{To understand what happens here, recall the relationship between Pollen's command modes. The text-mode command @code{◊foo[]} becomes the Racket-mode command @code{(foo)}, which after variable substitution becomes @code{("bar")}. If you try to evaluate @code{("bar")} — e.g., in DrRacket — you'll get the same error.}
@margin-note{To understand what happens here, recall the relationship between Pollen's command modes. The Pollen-mode command @code{◊foo[]} becomes the Racket-mode command @code{(foo)}, which after variable substitution becomes @code{("bar")}. If you try to evaluate @code{("bar")} — e.g., in DrRacket — you'll get the same error.}
@codeblock|{
@codeblock|{
@ -523,7 +523,7 @@ To make a meta, you create a tag with the special @code{define-meta} name. Then
The middle part of a text-mode Pollen command contains the @italic{Racket arguments} @litchar{[}between square brackets.@litchar{]} Most often, you'll see these used to pass extra information to commands that operate on text.
The middle part of a Pollen-mode command contains the @italic{Racket arguments} @litchar{[}between square brackets.@litchar{]} Most often, you'll see these used to pass extra information to commands that operate on text.
For instance, tag functions. Recall from before that any not-yet-defined command name in Pollen is treated as a tag function:
For instance, tag functions. Recall from before that any not-yet-defined command name in Pollen is treated as a tag function:
@ -753,7 +753,7 @@ You can also use this area for @italic{keyword arguments}. Keyword arguments can
The third part of a text-mode Pollen command is the text argument. The text argument @litchar{@"{"}appears between curly braces@litchar{@"}"}. It can contain any text you want. The text argument can also contain other Pollen commands with their own text arguments. And they can contain other Pollen commands ... and so on, all the way down.
The third part of a Pollen-mode command is the text argument. The text argument @litchar{@"{"}appears between curly braces@litchar{@"}"}. It can contain any text you want. The text argument can also contain other Pollen commands with their own text arguments. And they can contain other Pollen commands ... and so on, all the way down.
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.
I mentioned that the preprocessor reads the file and handles any Pollen commands it finds. But our source file doesn't have any commands yet. Let's add some.
Pollen commands can be embedded in your source file using one of two modes: @defterm{Racket mode} or @defterm{text mode}. We'll try text mode in a later tutorial. For now, we'll use Racket mode.
Pollen commands can be embedded in your source file using one of two modes: @defterm{Racket mode} or @defterm{Pollen mode}. We'll try Pollen mode in a later tutorial. For now, we'll use Racket mode.
To make a Racket-mode Pollen command, just take any Racket expression and put the lozenge character @litchar["◊"] in front of it. For instance, these are valid Racket expressions:
To make a Racket-mode command, just take any Racket expression and put the lozenge character @litchar["◊"] in front of it. For instance, these are valid Racket expressions:
@ -456,7 +456,7 @@ When you refresh the page in the project server, the page title will now appear
The page title will now be @onscreen{Deep Thought, by MB}.
The page title will now be @onscreen{Deep Thought, by MB}.
A couple notes on command syntax. We inserted the @racket[select] and @racket[->html] commands using Racket-mode syntax. We could also use text-mode syntax and write the commands this way:
A couple notes on command syntax. We inserted the @racket[select] and @racket[->html] commands using Racket-mode syntax. We could also use Pollen-mode syntax and write the commands this way:
@ -423,7 +423,7 @@ When you run this file, you indeed get:
@repl-output{'(root "I want to attend " (em "RacketCon " "BOOM" " year"))}
@repl-output{'(root "I want to attend " (em "RacketCon " "BOOM" " year"))}
How does this work? First, although you can define a function in Pollen command syntax using either of @secref["The_two_command_modes__text_mode___Racket_mode"], it tends to be easier to use Racket mode. I wrote the first one in text mode. But for clarity, I'm going to switch to Racket mode (run this file and convince yourself it comes out the same):
How does this work? First, although you can define a function using either of @secref["the-two-command-modes"], it tends to be easier to use Racket mode. I wrote the first one in Pollen mode. But for clarity, I'm going to switch to Racket mode (run this file and convince yourself it comes out the same):
