From 6bcb1f717a6993b7ee95afe02f0962db906e98f0 Mon Sep 17 00:00:00 2001 From: Matthew Butterick Date: Sat, 22 Aug 2015 11:06:06 -0700 Subject: [PATCH] doc clarifications on "directory-require.rkt" --- scribblings/tutorial-third.scrbl | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/scribblings/tutorial-third.scrbl b/scribblings/tutorial-third.scrbl index 35d5c4f..e5ee562 100644 --- a/scribblings/tutorial-third.scrbl +++ b/scribblings/tutorial-third.scrbl @@ -648,15 +648,15 @@ And get this output: @(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. 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{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. 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. -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. Still, the choice is yours: the name of this file can be changed by resetting the @racket[world:directory-require] value. +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. -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 underneath. +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. -@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.} +@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.} 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: