From 6feda80c7d176ef26f904a69d3becf4abfdc260c Mon Sep 17 00:00:00 2001 From: Matthew Butterick Date: Fri, 18 Dec 2015 12:22:51 -0800 Subject: [PATCH] resume in how to show comments? --- .../pollen-rkt.scrbl => pollen-rkt.scrbl | 146 ++++++++++-------- 1 file changed, 83 insertions(+), 63 deletions(-) rename scribblings/pollen-rkt.scrbl => pollen-rkt.scrbl (90%) diff --git a/scribblings/pollen-rkt.scrbl b/pollen-rkt.scrbl similarity index 90% rename from scribblings/pollen-rkt.scrbl rename to pollen-rkt.scrbl index 8db137f..837a50a 100644 --- a/scribblings/pollen-rkt.scrbl +++ b/pollen-rkt.scrbl @@ -1,6 +1,6 @@ #lang scribble/lp2 @(require scribble/manual) -@(require (for-label racket txexpr sugar pollen/decode pollen/tag hyphenate rackunit) scribble/eval) +@(require (for-label racket txexpr sugar pollen/decode pollen/tag hyphenate rackunit) scribble/eval pollen/scribblings/mb-tools) @(define my-eval (make-base-eval)) @declare-exporting[pollen-tfl/pollen] @(my-eval '(require txexpr sugar racket/list)) @@ -9,21 +9,32 @@ @(define lang @racket[#, @hash-lang[]]) -We can write a @filepath{pollen.rkt} file in any @|lang|. @|lang| @racketmodname[racket] is more convenient because it loads more libraries by default. For the same reason, @|lang| @racketmodname[racket/base] — with a minimal set of libraries — is slightly faster to load. In general, the more virtuous habit is @|lang| @racketmodname[racket/base]. +We can write a @filepath{pollen.rkt} file in any @|lang|. Most commonly, that will be is @|lang| @racketmodname[racket/base]. @|lang| @racketmodname[racket] is more convenient because it loads more libraries by default, but as a result it can be slightly slower to load. So @racketmodname[racket/base] is the more virtuous habit. -@racketmodname[pollen/mode] is a metalanguage that adds support for Pollen-mode commands in a source file. -So instead of @|lang| @racketmodname[racket/base] we write @|lang| @racketmodname[pollen/mode] @racketmodname[racket/base]. @racketmodname[pollen/mode] is optional. +This particular @filepath{pollen.rkt}, however, is written in @|lang| @racketmodname[scribble/lp2], which is the literate-programming variant of Racket's Scribble documentation language (which is also the basis of Pollen). @racketmodname[scribble/lp2] is like a text-based version of @racketmodname[racket/base]. The "literate programming" angle is that we can mix documentation and source code in one file. Probably not the option you'd choose for your own project, but in this teaching project, it's the right tool for the job. -BTW this file is heavily commented so it can serve as a Pollen learning tool. Rather than just read -along, you are encouraged to run this project with the project server active, and make changes to this -file and see how they affect the output. +Chunks of source code look like this: -We could avoid the next @racket[require] if we were using @|lang| @racketmodname[racket], because these libraries would -already be available. +@chunk[ + (define (racket-source-code ...) ...)] +There's nothing special about the chunk name — it's just a label that @racketmodname[scribble/lp2] will use to snap the code together @seclink["Finally"]{at the end}. The result is that if you @racket[require] this file normally, you'll get the usual functions and values; but if you run it with Scribble, it turns into the documentation you see here. +@section{What is @filepath{pollen.rkt} for?} -@chunk[ +The @filepath{pollen.rkt} source file is the main source of functions and values for the source files in a Pollen project. Everything provided from a @filepath{pollen.rkt} is automatically available to Pollen source files in the +same directory or subdirectories (unless superseded by another @filepath{pollen.rkt} below, for instance in the @filepath{fonts} subdirectory in this project). + +For more, see @secref["Using_the__pollen_rkt__file" + #:tag-prefixes '("tutorial-3") + #:doc '(lib "pollen/scribblings/pollen.scrbl")] in the main Pollen docs. + + +@section{Imports} + +If we were using @|lang| @racketmodname[racket], these next libraries would already be imported. But because we're using @racketmodname[racket/base] (via @racketmodname[scribble/lp2]), we need to @racket[require] them explicitly. + +@chunk[ (require (for-syntax racket/base racket/syntax) ; enables macros racket/list @@ -36,48 +47,50 @@ already be available. Other libraries we'll be using. -@chunk[ +@chunk[ (require sugar txexpr pollen/decode pollen/tag hyphenate - "../pricing-table.rkt")] + "pricing-table.rkt")] -Everything provided from a @filepath{pollen.rkt} is automatically available to Pollen source files in the -same directory or subdirectories (unless superseded by another @filepath{pollen.rkt}, as in the @filepath{fonts} subdirectory). +@section{Exports} Note that @racket[all-defined-out] would only export the definitions that are created in this file. To make imported definitions available too, we need to re-export them with @racket[all-from-out]. @chunk[ - (provide (all-defined-out) (all-from-out "../pricing-table.rkt")) + (provide (all-defined-out) (all-from-out "pricing-table.rkt")) ] -Pollen recognizes the environment variable POLLEN, which can take any value. -For instance, instead of starting the project server with -raco pollen start -You could do -POLLEN=SOME-STRING raco pollen start +@section{Definitions} -And "SOME-STRING" would be loaded into the POLLEN environment variable. +@subsection{Values} -We can retrieve this value with @racket[(getenv "POLLEN")]. It can be used to create branching behavior. -Here, we'll create a @racket[dev-mode?] test and use it later to change the behavior of certain functions. -@chunk[ - (define (dev-mode?) - (equal? (getenv "POLLEN") "DEV")) +Definitions in a pollen.rkt can be functions or values. +Here are a couple values. + +@racket[no-hyphens-attr]: an attribute we'll use to signal that some X-expression should not be hyphenated. + +@CHUNK[ + (define content-rule-color "#444") ; for CSS classes + (define buy-url "http://typo.la/oc") ; link to buy the Typography for Lawyers paperback + (define no-hyphens-attr '(hyphens "none")) ] +@subsection{Tag functions} + + -@section{Making tagged X-expressions (txexprs)} +@subsubsection{Making tagged X-expressions (txexprs)} In a "pollen.rkt" file you'll be making a lot of tagged X-expressions (txexprs for short). A txexpr is just a Racket list, so you can make one with any of Racket's list-making functions @@ -136,25 +149,6 @@ Below, ; we unquote @racket[attrs] because we want them as a sublist `(,tag ,attrs ,@elements))] -@section{Definitions} - -@subsection{Values} - - -Definitions in a pollen.rkt can be functions or values. -Here are a couple values. - -@racket[no-hyphens-attr]: an attribute we'll use to signal that some X-expression should not be hyphenated. - -@CHUNK[ - (define content-rule-color "#444") ; for CSS classes - (define buy-url "http://typo.la/oc") ; link to buy the Typography for Lawyers paperback - (define no-hyphens-attr '(hyphens "none")) - ] - - -@subsection{Tag functions} - @defproc[ (link @@ -894,15 +888,6 @@ but I don't want spaces in the output, so this function removes them. [str (regexp-replace* #px"—[\u00A0\u2009\\s](?=\\w)" str "—")]) str))] -@defproc[ - (capitalize-first-letter - [str string?]) - string?] -utility function for use in HTML templates. - -@chunk[ - (define (capitalize-first-letter str) - (regexp-replace #rx"^." str string-upcase))] @subsubsection{Miscellaneous tag functions} @@ -940,17 +925,52 @@ Presented without docs or comment, as it should be obvious at this point what th `(table ((class "captioned indented")) (tr (td ((style "text-align:left")) ,@xs) (td ,(caption name)))))] -@;|{ - #| - |# - - - }| +@section{Utility functions} + +@defproc[ + (dev-mode?) + boolean?] +Check whether Pollen is running in development mode, which means that it was started from the command line with the environment variable @tt{POLLEN} set to the value @tt{DEV}: + +@terminal{ +> POLLEN=DEV raco pollen ...} + +Rather than the ordinary: + +@terminal{ +> raco pollen ...} + +This functions will be useful later when we want to change the behavior of certain functions when Pollen runs in dev mode. For instance, we might want to run certain functions in a higher speed / lower quality mode. Or output debug information about others. + +@chunk[ + (define (dev-mode?) + (equal? (getenv "POLLEN") "DEV")) + ] + +Though the environment variable name is fixed as @tt{POLLEN}, there's no special magic to @tt{DEV}. We could pick any value we wanted to denote development mode: + +@terminal{ +> POLLEN=FLUGELHORN raco pollen ...} + + +@defproc[ + (capitalize-first-letter + [str string?]) + string?] +For use in our HTML templates. We could also define this function inside a template. But since we have more than one template in this project, we'll put it here, so it can be available to all the templates. + +@chunk[ + (define (capitalize-first-letter str) + (regexp-replace #rx"^." str string-upcase))] + +@section{Finally} + +This last incantation is needed so @racketmodname[scribble/lp2] knows how to put together all the code chunks we've introduced in this file. @chunk[<*> - - + +