@ -59,9 +59,9 @@ Any value or function that is defined within the source file using @racket[defin
@bold{How is this different from Racket?} In Racket, you must explicitly @racket[provide] any values you want to export. Unlike Racket, every Pollen source file impliedly uses @racket[(provide (all-defined-out))].
If a file called @filepath{directory-require.rkt} exists in the same directory with a source file, or in a parent directory of that source file, it's automatically imported when the source file is compiled.
If a file called @filepath{pollen.rkt} exists in the same directory with a source file, or in a parent directory of that source file, it's automatically imported when the source file is compiled.
@bold{How is this different from Racket?} In Racket, you must explicitly import files using @racket[require].
@ -306,9 +306,9 @@ That's not right. What happened?
We marked up the source using a combination of standard HTML tags (@code{strong}, @code{em}) and nonstandard ones (@code{headline}, @code{items}, @code{item}, @code{link}). This is valid Pollen markup. (In fact, if you look at @link["http://localhost:8080/out/markup.html"]{the generated source}, 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.
For that, we'll make a special file called @filepath{directory-require.rkt}. 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:
For that, we'll make a special file called @filepath{pollen.rkt}. 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:
@ -27,7 +27,7 @@ I used @link["http://pygments.org/"]{Pygments} for syntax highlighting in @link[
@item{Make sure you have @code{pygments} already installed. @link["http://pygments.org/download/"]{Instructions here.} Pretty easy —for instance, on my OS X machine, I was able to get it done by doing @code{easy_install pygments} at the command line.}
@item{The @racketmodname[pollen/pygments] helper module provides a function called @racket[highlight]. To make @racket[highlight] available in your source file, you can either add the line @code{◊(require pollen/pygments)} to the source file itself, or put it in @racket["directory-require.rkt"] and @racket[provide] it from there.}
@item{The @racketmodname[pollen/pygments] helper module provides a function called @racket[highlight]. To make @racket[highlight] available in your source file, you can either add the line @code{◊(require pollen/pygments)} to the source file itself, or put it in @racket["pollen.rkt"] and @racket[provide] it from there.}
@item{To invoke Pygments, use @racket[highlight] by providing a language name like @racket['python] in the brackets (note quote mark at front of name) and then the code you want highlighted between curly braces.
@ -135,7 +135,7 @@ Then, add any configuration options. For instance, this will activate the dollar
]
Putting it together, here's a minimal working example in two files (obviously in a larger project, you'd move those tag functions to a @racket["directory-require.rkt"] file):
Putting it together, here's a minimal working example in two files (obviously in a larger project, you'd move those tag functions to a @racket["pollen.rkt"] file):
@ -18,7 +18,7 @@ Now you're getting to the good stuff. In this tutorial, you'll use Pollen to pub
@item{Attaching behavior to tag functions}
@item{the @filepath{directory-require.rkt} file}
@item{the @filepath{pollen.rkt} file}
@item{Using @racket[decode] with Pollen markup}
@ -644,23 +644,23 @@ And get this output:
@repl-output{'(root "A list of integers: " "0 1 2 3 4")}
@subsection[#:tag-prefix "tutorial-3"]{Using the @filepath{directory-require.rkt} file}
@subsection[#:tag-prefix "tutorial-3"]{Using the @filepath{pollen.rkt} file}
@(noskip-note)
As you get more comfortable attaching behavior to tags using tag functions, you'll likely want to create some functions that can be shared between multiple source files. The @filepath{directory-require.rkt} file is a special file that is automatically imported by Pollen source files in the same directory (including within subdirectories). So every function and value provided by @filepath{directory-require.rkt} can be used in these Pollen files.
As you get more comfortable attaching behavior to tags using tag functions, you'll likely want to create some functions that can be shared between multiple source files. The @filepath{pollen.rkt} file is a special file that is automatically imported by Pollen source files in the same directory (including within subdirectories). So every function and value provided by @filepath{pollen.rkt} can be used in these Pollen files.
First, using this file is not mandatory. You can always import functions and values from another file using @racket[require] (as seen in the previous section). The @filepath{directory-require.rkt} is just meant to cure the tedium of importing the same file into every Pollen source file in your project. In a small project, not much tedium; in a large project, more.
First, using this file is not mandatory. You can always import functions and values from another file using @racket[require] (as seen in the previous section). The @filepath{pollen.rkt} is just meant to cure the tedium of importing the same file into every Pollen source file in your project. In a small project, not much tedium; in a large project, more.
Second, notice from the @filepath{.rkt} suffix that @filepath{directory-require.rkt} is a source file containing Racket code, not Pollen code. This is the default because while Pollen is better for text-driven source files, Racket is better for code-driven source files.
Second, notice from the @filepath{.rkt} suffix that @filepath{pollen.rkt} is a source file containing Racket code, not Pollen code. This is the default because while Pollen is better for text-driven source files, Racket is better for code-driven source files.
Third, the @filepath{directory-} prefix represents the minimum scope for the file, not the maximum. Pollen source files nested in subdirectories will look for a @filepath{directory-require.rkt} in their own directory first. But if they can't find it, they'll look in the parent directory, then the next parent directory, and so on. Thus, by default, a @filepath{directory-require.rkt} in the root folder of a project will apply to all the source files in the project. But when you add a new @filepath{directory-require.rkt} to a subdirectory, it will apply to all files in that subdirectory and below.
Third, the @filepath{directory-} prefix represents the minimum scope for the file, not the maximum. Pollen source files nested in subdirectories will look for a @filepath{pollen.rkt} in their own directory first. But if they can't find it, they'll look in the parent directory, then the next parent directory, and so on. Thus, by default, a @filepath{pollen.rkt} in the root folder of a project will apply to all the source files in the project. But when you add a new @filepath{pollen.rkt} to a subdirectory, it will apply to all files in that subdirectory and below.
@margin-note{Though a subdirectory-specific @filepath{directory-require.rkt} will supersede the one in the enclosing directory, you can still use @racket[(require "../directory-require.rkt")] to pull in definitions from above, and @racket[provide] to propagate them into the current subdirectory. For instance, @racket[(provide (all-from-out "../directory-require.rkt"))] will re-export everything from the parent directory.}
@margin-note{Though a subdirectory-specific @filepath{pollen.rkt} will supersede the one in the enclosing directory, you can still use @racket[(require "../pollen.rkt")] to pull in definitions from above, and @racket[provide] to propagate them into the current subdirectory. For instance, @racket[(provide (all-from-out "../pollen.rkt"))] will re-export everything from the parent directory.}
Let's see how this works in practice. In the same directory as @filepath{article.html.pm}, create a new @filepath{directory-require.rkt} file as follows:
Let's see how this works in practice. In the same directory as @filepath{article.html.pm}, create a new @filepath{pollen.rkt} file as follows:
@fileblock["directory-require.rkt" @codeblock{
@fileblock["pollen.rkt" @codeblock{
#lang racket
(define author "Trevor Goodchild")
(provide author)
@ -692,11 +692,11 @@ Run this, and you'll get:
@repl-output{'(root "The author is really " "Trevor Goodchild" "?")}
That's all there is to it. Everything provided by @filepath{directory-require.rkt} is automatically available within each Pollen source file.
That's all there is to it. Everything provided by @filepath{pollen.rkt} is automatically available within each Pollen source file.
You can include functions, including tag functions, the same way. For instance, add a function for @racket[em]:
@fileblock["directory-require.rkt" @codeblock{
@fileblock["pollen.rkt" @codeblock{
#lang racket
(define author "Trevor Goodchild")
(define (em . parts) `(extra (big ,@"@"parts)))
@ -844,9 +844,9 @@ The second paragraph --- isn't it great.
}
Of course, in practice you wouldn't put your decoding function in a single source file. You'd make it available to all your source files by putting it in @filepath{directory-require.rkt}. So let's do that now:
Of course, in practice you wouldn't put your decoding function in a single source file. You'd make it available to all your source files by putting it in @filepath{pollen.rkt}. So let's do that now:
@fileblock["directory-require.rkt" @codeblock{
@fileblock["pollen.rkt" @codeblock{
#lang racket
(require pollen/decode txexpr)
(define (root . elements)
@ -881,7 +881,7 @@ Let's upgrade our decoder to take of those. Once again, we'll get lucky, because
This time, however, we're going to attach them to another part of @racket[decode-elements]. Smart-quote and smart-dash conversion only needs to look at the strings within the X-expression. So instead of attaching these functions to the @racket[#:txexpr-elements-proc] argument of @racket[decode-elements], we'll attach them to @racket[#:string-proc], which lets us specify a function to apply to strings:
@fileblock["directory-require.rkt" @codeblock{
@fileblock["pollen.rkt" @codeblock{
#lang racket/base
(require pollen/decode txexpr)
(define (root . elements)
@ -917,13 +917,13 @@ It also provides a recipe you can adapt for your own projects, whether small or
As we go through the ingredients, I'll review the purpose of each. Save these files into a single project directory with the project server running.
This file provides functions that are available to all Pollen source files in the same directory. It's written in standard Racket. The @filepath{directory-require.rkt} file is optional — without it, your tags will just be treated as default tag functions. But you'll probably find it a convenient way to make tag functions available within your project, including a @racket[decode] function attached to @code{root}.
This file provides functions that are available to all Pollen source files in the same directory. It's written in standard Racket. The @filepath{pollen.rkt} file is optional — without it, your tags will just be treated as default tag functions. But you'll probably find it a convenient way to make tag functions available within your project, including a @racket[decode] function attached to @code{root}.
Here, we'll use the @filepath{directory-require.rkt} we devised in the previous section to set up decoding for our source files:
Here, we'll use the @filepath{pollen.rkt} we devised in the previous section to set up decoding for our source files:
@fileblock["directory-require.rkt" @codeblock{
@fileblock["pollen.rkt" @codeblock{
#lang racket/base
(require pollen/decode txexpr)
(define (root . elements)
@ -983,7 +983,7 @@ Our template file above refers to a CSS file called @filepath{styles.css}. When
Or, if you make a preprocessor source file called @filepath{styles.css.pp}, it will be dynamically rendered into the requested @filepath{styles.css} file. The preprocessor will operate on any file with the @filepath{.pp} extension —so a preprocessor source called @filepath{filename.ext.pp} will be rendered into @filepath{filename.ext}. (The corollary is that preprocessor functionality can be added to @italic{any} kind of text-based file.)
Preprocessor source files, like authoring source files, get access to everything in @filepath{directory-require.rkt}, so you can share common functions and variables.
Preprocessor source files, like authoring source files, get access to everything in @filepath{pollen.rkt}, so you can share common functions and variables.
Let's use an improved version of the dynamic CSS file we made in the first tutorial.
@ -1093,13 +1093,13 @@ Now visit the project server and view @filepath{burial.html}, which should look
@image/rp["burial.png" #:scale 0.8]
Click the navigational links at the top to move between pages. You're encouraged to change the source files, the style sheet, the template, or @filepath{directory-require.rkt}, and see how these changes immediately affect the page rendering in the project server. (You can also change the sequence of the pages in @filepath{index.ptree}, but in that case, you'll need to restart the project server to see the change.)
Click the navigational links at the top to move between pages. You're encouraged to change the source files, the style sheet, the template, or @filepath{pollen.rkt}, and see how these changes immediately affect the page rendering in the project server. (You can also change the sequence of the pages in @filepath{index.ptree}, but in that case, you'll need to restart the project server to see the change.)
This page isn't a miracle of web design, but it shows you in one example:
@itemlist[
@item{Pollen markup being decoded — paragraph breaks, linebreaks, smart quotes, smart dashes — with a @racket[decode] function attached to the @code{root} node by @filepath{directory-require.rkt};}
@item{Pollen markup being decoded — paragraph breaks, linebreaks, smart quotes, smart dashes — with a @racket[decode] function attached to the @code{root} node by @filepath{pollen.rkt};}
@item{A dynamically-generated CSS file that computes positions for CSS elements using numerical values set up with @racket[define], and mathematical conversions thereof;}
@ -26,19 +26,14 @@ A parameter that holds the root directory of the current project (e.g., the dire
A parameter that reports the path to the directory of support files for the project server. Initialized to @racket[#f], but set to a proper value when the server runs.}
A parameter that determines whether the @racket[world:directory-require] file is checked for changes on every pass through @racket[render]. (Can be faster to turn this off if you don't need it.) Initialized to @racket[#t].}
These values can be changed by overriding them in your @racket["directory-require.rkt"] source file. Within this file, @seclink["submodules" #:doc '(lib "scribblings/guide/guide.scrbl")]{create a submodule} called @racket[config]. Then within this submodule, use @racket[define] to make a variable with the same name as the one in @racket[pollen/world], but without the @racket[world:] prefix. Assign it whatever value you like. Repeat as needed. When Pollen runs, these definitions will supersede those in @racket[pollen/world].
These values can be changed by overriding them in your @racket["pollen.rkt"] source file. Within this file, @seclink["submodules" #:doc '(lib "scribblings/guide/guide.scrbl")]{create a submodule} called @racket[config]. Then within this submodule, use @racket[define] to make a variable with the same name as the one in @racket[pollen/world], but without the @racket[world:] prefix. Assign it whatever value you like. Repeat as needed. When Pollen runs, these definitions will supersede those in @racket[pollen/world].
For instance, suppose you wanted the main export of every Pollen source file to be called @racket[van-halen] rather than @racket[doc], the extension of Pollen markup files to be @racket[.rock] rather than @racket[.pm], and the command character to be @litchar{🎸} instead of @litchar{◊}. Your @racket["directory-require.rkt"] would look like this:
For instance, suppose you wanted the main export of every Pollen source file to be called @racket[van-halen] rather than @racket[doc], the extension of Pollen markup files to be @racket[.rock] rather than @racket[.pm], and the command character to be @litchar{🎸} instead of @litchar{◊}. Your @racket["pollen.rkt"] would look like this:
@fileblock["directory-require.rkt"
@fileblock["pollen.rkt"
@codeblock{
#lang racket/base
@ -53,7 +48,7 @@ For instance, suppose you wanted the main export of every Pollen source file to
Though any of the values below can be overridden, it may not always be wise to do so. For instance, if you redefined @racket[world:fallback-template-prefix], you would simply break the fallback-template mechanism, because it would look for files that don't exist. But we don't live in a nanny state, so you are entrusted to say what you mean and accept the consequences.
Of course, you can restore the defaults simply by deleting these defined values from @racket["directory-require.rkt"].
Of course, you can restore the defaults simply by deleting these defined values from @racket["pollen.rkt"].
These settable values are each equipped with a corresponding @racket[world:current-]@racket[_settable-value] function that will return the value loaded from the @racket[config] submodule (if @racket[_settable-value] was defined there), otherwise the default given by @racket[world:]@racket[_settable-value]. For instance, @racket[world:command-char] will always be @litchar{◊}, but in the example above, @racket[world:current-command-char] would return @litchar{🎸}.
