@italic{Pollen is a dialect of Scribble, so I've adapted this section from Matthew Flatt and Eli Barzilay's excellent documentation for Scribble. If you think this section is good, it's because of them. If you don't, it's because of me.}
Pollen's command notation is designed to be a convenient system for embedding Pollen commands within free-form text.
@section{The golden rule}
Pollen uses a special character — the @italic{lozenge}, which looks like this: ◊ — as its command character. Meaning, when you put the ◊ in front of a word or expression, it will it be interpreted as a Pollen command.
Pollen uses a special character — the @italic{lozenge}, which looks like this: ◊ — to mark commands within a Pollen source file. So when you put a ◊ in your source, whatever comes next will be treated as a command. If you don't, it will just be interpreted as plain text.
@section{About that lozenge}
I chose the lozenge as the command marker because a) it appears in almost every font, b) it's barely used in ordinary typesetting, c) it's not used in any programming language that I know of, and d) its shape and color allow it to stand out easily in code without being distracting.
@margin-note{Scribble itself uses the @"@" sign as a delimiter. It's not a bad choice if you only work with Racket files. But as you use Pollen to work on other kinds of text-based files that commonly contain @"@" signs — HTML pages especially — it gets cumbersome. So I changed it.}
Still, if you don't want to use the lozenge as your command marker, you can use something else. Set Pollen's @racket[world:command-marker] value to whatever character you want.
But don't knock the lozenge till you try it. Here's how you type it:
Typically, ◊ notation is enabled through
@racketmodname[scribble/base] or similar languages, but you can also
add ◊ notation to an S-expression-based language using the
@racketmodname[at-exp] meta-language. For example,
Every Pollen command is built using one of two basic forms: either @italic{native form} or @italic{Racket form}. Both forms start with a lozenge (@litchar["◊"]):
A native-form command has the three possible parts after the @litchar["◊"]:
@itemlist[
@item{The @italic{command name} appears immediately after the @litchar["◊"]. Typically it's a short word.}
@item{The @italic{Racket arguments} appear between square brackets. Pollen is an interface to the Racket programming language. These arguments are interpreted according to Racket conventions. So if you like programming, you'll end up using these frequently. If you don't, you won't.}
@item{The @italic{text argument} appears between braces (aka curly brackets). You can put any free-form text here.}
]
These parts are combined according to three rules:
@itemlist[
@item{Each part is optional.}
@item{You cannot have spaces between the three parts.}
@item{They must appear in the order shown.}
]
Here are a few examples of correct native-form commands:
@verbatim[#:indent 2]|{
#lang at-exp racket
(define v '@op{str})
#lang pollen
◊variable-name
◊tag{Text inside the tag.}
◊tag['attr: "value"]{Text inside the tag}
◊get-customer-id["Brennan Huff"]
}|
And here are some incorrect ones:
@verbatim[#:indent 2]|{
#lang pollen
◊tag {Text inside the tag.} ; space between first and second parts
◊tag[Text inside the tag] ; text argument needs to be within braces
◊tag{Text inside the tag}['attr: "value"] ; wrong order
}|
The next section describes each of these parts in detail.
@bold{Racket-form commands}
If you're familiar with Racket expressions, you can use the Racket-form commands to embed them within Pollen source files. It's simple: any Racket expression can become a Pollen expression by adding @litchar["◊"] to the front. So in Racket, this code:
Beyond that, there's not much to say about Racket form —any valid expression you can write in Racket will also be a valid Racket-form Pollen command.
@racketmod[
racket
(define v '(op "str"))
@bold{The relationship of native form and Racket form}
Even if you don't plan to write a lot of Racket expressions, you should be aware that under the hood, Pollen is converting all native-form commands into Racket-form commands. So a native-form command that looks like this:
@racketblock[
◊headline[#:size 'enormous]{Man Bites Dog!}
]
Using @at-exp-racket[] is probably the easiest way to try the examples
in this chapter.
Is actually being turned into a Racket-form command like this:
@racketblock[
(headline #:size 'enormous "Man Bites Dog!")
]
Thus a native-form command is just an alternate way of writing a Racket-form command. (More broadly, all of Pollen is just an alternate way of using Racket.)
@section{About that lozenge}
The corollary is that you can always write Pollen commands using whichever form is more convenient or readable. For instance, the earlier example, written in the Racket form:
I picked the lozenge glyph as the delimiter — meaning this thing: ◊ — because a) it appears in almost every font, b) it's barely used in ordinary typesetting, and c) its shape and color allow it to stand out easily in code without being distracting.
@verbatim[#:indent 2]|{
#lang pollen
◊(define song "Revolution")
◊(format "~a #~a" song (* 3 3))
}|
Can be rewritten using native form:
Scribble itself uses the @"@" sign as a delimiter. Not a bad choice if all you do is Racket. But as you use Pollen to work on other kinds of text-based files that commonly contain @"@" signs — you know, like things with email addresses — a small headache starts to form. That's why I changed it.
@verbatim[#:indent 2]|{
#lang pollen
◊define[song]{Revolution}
◊format["~a #~a" song (* 3 3)]
}|
And it will work the same way.
Still, if you don't want to use the lozenge as your delimiter, you can use something else. Set Pollen's @racket[world:expression-delimiter] value to whatever character you want. But don't knock the lozenge till you try it.
@ -66,8 +66,8 @@ Pagetree that Pollen dashboard loads by default in each directory.
Name of the root node in a decoded pagetree. It's ignored by the code, so its only role is to clue you in that you're looking at something that came out of the pagetree decoder.
