[(list(?block-txexpr?)...)elems]; leave a series of block xexprs alone
(list(wrap-procelems)))); otherwise wrap in p tag
[_(list(wrap-procelems))])); otherwise wrap in p tag
(defineelements(prep-paragraph-flowelements-in))
(defineelements(prep-paragraph-flowelements-in))
(if(ormapexplicit-or-implicit-paragraph-break?elements); need this condition to prevent infinite recursion
(if(ormapexplicit-or-implicit-paragraph-break?elements); need this condition to prevent infinite recursion
;; use append-map on wrap-paragraph rather than map to permit return of multiple elements
;; use `append-map` on `wrap-paragraph` rather than `map` to permit return of multiple elements
(append-mapwrap-paragraph(append-map(λ(es)(filter-splitesparagraph-break?))(slicefelementsblock-txexpr?))); split into ¶¶, using both implied and explicit paragraph breaks
(append-mapwrap-paragraph
(append-map(λ(es)(filter-splitesparagraph-break?))(slicefelementsblock-txexpr?))); split into ¶¶, using both implied and explicit paragraph breaks
(ifforce-paragraph
(ifforce-paragraph
(append-mapwrap-paragraph(slicefelementsblock-txexpr?)); upconverts non-block elements to paragraphs
@ -116,11 +116,11 @@ Now here's a third: the Pollen project server. To start the project server, retu
After a moment, you'll see the startup message:
After a moment, you'll see the startup message:
@terminal{
@terminal{
Welcome to Pollen @|pollen:version| (Racket @(version))
pollen: welcome to Pollen @|pollen:version| (Racket @(version))
Project root is /path/to/your/directory
pollen: project root is /path/to/your/directory
Project server is http://localhost:8080 (Ctrl+C to exit)
pollen: project server is http://localhost:8080 (Ctrl+C to exit)
Project dashboard is http://localhost:8080/index.ptree
pollen: project dashboard is http://localhost:8080/index.ptree
Ready to rock}
pollen: ready to rock}
Open a web browser and point it at the project dashboard, which by default is @link-tt{http://localhost:8080/index.ptree}. The top line of the window will say @tt{Project root} and show the name of the starting directory. Below that will be a listing of the files in the directory.
Open a web browser and point it at the project dashboard, which by default is @link-tt{http://localhost:8080/index.ptree}. The top line of the window will say @tt{Project root} and show the name of the starting directory. Below that will be a listing of the files in the directory.
@ -16,34 +16,34 @@ The values below can be changed by overriding them in your @racket["pollen.rkt"]
@itemlist[#:style 'ordered
@itemlist[#:style 'ordered
@item{Within this file, @seclink["submodules" #:doc '(lib "scribblings/guide/guide.scrbl")]{create a submodule} called @racket[setup].}
@item{Within this file, @seclink["submodules" #:doc '(lib "scribblings/guide/guide.scrbl")]{create a submodule} called @racket[setup].}
@item{Within this submodule, use @racket[define] to make a variable with the same name as the one in @racket[pollen/setup], but without the @racket[setup:] prefix.}
@item{Within this submodule, use @racket[define] to make a variable with the same name as the one in @racket[pollen/setup], but without the @racket[setup:] prefix.}
@item{Assign it whatever value you like.}
@item{Assign it whatever value you like.}
@item{Repeat as needed.}
@item{Repeat as needed.}
@item{(Don't forget to @racket[provide] the variables from within your @racket[setup] submodule.)}
@item{(Don't forget to @racket[provide] the variables from within your @racket[setup] submodule.)}
]
]
When Pollen runs, these definitions will supersede those in @racketmodname[pollen/setup].
When Pollen runs, these definitions will supersede those in @racketmodname[pollen/setup].
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:
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["pollen.rkt"
@fileblock["pollen.rkt"
@codeblock{
@codeblock{
#lang racket/base
#lang racket/base
;; ... the usual definitions and tag functions ...
;; ... the usual definitions and tag functions ...
(module setup racket/base
(module setup racket/base
(provide (all-defined-out))
(provide (all-defined-out))
(define main-export 'van-halen)
(define main-export 'van-halen)
(define markup-source-ext 'rock)
(define markup-source-ext 'rock)
(define command-char #\🎸))
(define command-char #\🎸))
}]
}]
Of course, you can restore the defaults simply by removing these defined values from @racket["pollen.rkt"].
Of course, you can restore the defaults simply by removing these defined values from @racket["pollen.rkt"].
@ -52,7 +52,7 @@ Every @racket[setup:]@racket[_name] function will resolve the current value of t
@section{Values}
@section{Values}
@defoverridable[project-server-port integer?]{
@defoverridable[project-server-port integer?]{
Determines the default HTTP port for the project server.}
Determines the default HTTP port for the project server.}
@defoverridable[main-export symbol?]{The main X-expression exported from a compiled Pollen source file.}
@defoverridable[main-export symbol?]{The main X-expression exported from a compiled Pollen source file.}
@ -63,14 +63,14 @@ Every @racket[setup:]@racket[_name] function will resolve the current value of t
@deftogether[(
@deftogether[(
@defoverridable[preproc-source-ext symbol?]
@defoverridable[preproc-source-ext symbol?]
@defoverridable[markup-source-ext symbol?]
@defoverridable[markup-source-ext symbol?]
@defoverridable[markdown-source-ext symbol?]
@defoverridable[markdown-source-ext symbol?]
@defoverridable[null-source-ext symbol?]
@defoverridable[null-source-ext symbol?]
@defoverridable[pagetree-source-ext symbol?]
@defoverridable[pagetree-source-ext symbol?]
@defoverridable[template-source-ext symbol?]
@defoverridable[template-source-ext symbol?]
@defoverridable[scribble-source-ext symbol?]
@defoverridable[scribble-source-ext symbol?]
)]{File extensions for Pollen source files.}
)]{File extensions for Pollen source files.}
@defoverridable[main-pagetree string?]{Pagetree that Pollen dashboard loads by default in each directory.}
@defoverridable[main-pagetree string?]{Pagetree that Pollen dashboard loads by default in each directory.}
@ -81,9 +81,9 @@ Every @racket[setup:]@racket[_name] function will resolve the current value of t
@defoverridable[block-tags (listof symbol?)]{Tags that are treated as blocks by @racket[block-txexpr?]. Initialized to the @link["https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements"]{block-level elements in HTML5}, namely:
@defoverridable[block-tags (listof symbol?)]{Tags that are treated as blocks by @racket[block-txexpr?]. Initialized to the @link["https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements"]{block-level elements in HTML5}, namely:
@ -93,10 +93,10 @@ Every @racket[setup:]@racket[_name] function will resolve the current value of t
@deftogether[(
@deftogether[(
@(defoverridable newline string?)
@(defoverridable newline string?)
@(defoverridable linebreak-separator string?)
@(defoverridable linebreak-separator string?)
@(defoverridable paragraph-separator string?)
@(defoverridable paragraph-separator string?)
)]
)]
Default separators used in decoding.
Default separators used in decoding.
@ -108,17 +108,17 @@ Default separators used in decoding.
@defoverridable[cache-watchlist (listof (or/c path? path-string?))]{List of extra files that the cache (= render cache + compile cache, collectively) watches during a project-server session. If one of the files on the watchlist changes, the cache is invalidated (just as it would be if @racket["pollen.rkt"] changed).
@defoverridable[cache-watchlist (listof (or/c path? path-string?))]{List of extra files that the cache (= render cache + compile cache, collectively) watches during a project-server session. If one of the files on the watchlist changes, the cache is invalidated (just as it would be if @racket["pollen.rkt"] changed).
If the cache can't find a certain file on the watchlist, it will be ignored. Therefore, to avoid unexpected behavior, the best policy is to pass in complete paths (or path strings). An easy way to convert a module name into a complete path is with @racket[resolve-module-path]:
If the cache can't find a certain file on the watchlist, it will be ignored. Therefore, to avoid unexpected behavior, the best policy is to pass in complete paths (or path strings). An easy way to convert a module name into a complete path is with @racket[resolve-module-path]:
@ -129,13 +129,13 @@ Default separators used in decoding.
@defoverridable[omitted-path? (path? . -> . boolean?)]{Predicate that determines whether a path is omitted from @secref{raco_pollen_render} and @secref{raco_pollen_publish} operations. If the predicate evaluated to @racket[#t], then the path is omitted.
@defoverridable[omitted-path? (path? . -> . boolean?)]{Predicate that determines whether a path is omitted from @secref{raco_pollen_render} and @secref{raco_pollen_publish} operations. If the predicate evaluated to @racket[#t], then the path is omitted.
@defoverridable[extra-path? (path? . -> . boolean?)]{Predicate that determines if path is rendered & published, overriding @racket[(setup:omitted-path?)] above, and Pollen's default publish settings. For instance, Pollen automatically omits files with a @racket[.rkt] extension. If you wanted to force a @racket[.rkt] file to be published, you could include it here.
@defoverridable[extra-path? (path? . -> . boolean?)]{Predicate that determines if path is rendered & published, overriding @racket[(setup:omitted-path?)] above, and Pollen's default publish settings. For instance, Pollen automatically omits files with a @racket[.rkt] extension. If you wanted to force a @racket[.rkt] file to be published, you could include it here.
@pollen-history[#:added "1.1"]}
@pollen-history[#:added "1.1"]}
@defoverridable[splicing-tag symbol?]{Key used to signal that an X-expression should be spliced into its containing X-expression.}
@defoverridable[splicing-tag symbol?]{Key used to signal that an X-expression should be spliced into its containing X-expression.}
@ -149,9 +149,9 @@ Default separators used in decoding.
@defoverridable[index-pages (listof string?)]{List of strings that the project server will use as directory default pages, in order of priority. Has no effect on command-line rendering operations. Also has no effect on your live web server (usually that's a setting you need to make in an @tt{.htaccess} configuration file).} But with this setting, you can simulate the behavior of your live server, so that internal index-page URLs work correctly.
@defoverridable[index-pages (listof string?)]{List of strings that the project server will use as directory default pages, in order of priority. Has no effect on command-line rendering operations. Also has no effect on your live web server (usually that's a setting you need to make in an @tt{.htaccess} configuration file).} But with this setting, you can simulate the behavior of your live server, so that internal index-page URLs work correctly.
@defoverridable[trim-whitespace? boolean?]{Predicate that controls whether the Pollen source reader trims whitespace from the beginning of a @racket[doc] export. You might set this to @racket[#false] if you're using Pollen as a preprocessor for another programming language and you want to preserve leading whitespace accurately.
@defoverridable[trim-whitespace? boolean?]{Predicate that controls whether the Pollen source reader trims whitespace from the beginning of a @racket[doc] export. You might set this to @racket[#false] if you're using Pollen as a preprocessor for another programming language and you want to preserve leading whitespace accurately.
@pollen-history[#:added "1.5"]}
@pollen-history[#:added "1.5"]}
@section{Parameters}
@section{Parameters}
@ -159,16 +159,16 @@ Default separators used in decoding.
I mean @italic{parameters} in the Racket sense, i.e. values that can be fed to @racket[parameterize].
I mean @italic{parameters} in the Racket sense, i.e. values that can be fed to @racket[parameterize].
@defparam[current-server-port port integer? #:value default-project-server-port]{
@defparam[current-server-port port integer? #:value default-project-server-port]{
A parameter that sets the HTTP port for the project server.}
A parameter that sets the HTTP port for the project server.}
@defparam[current-project-root port path?]{
@defparam[current-project-root port path?]{
A parameter that holds the root directory of the current project (e.g., the directory where you launched @code{raco pollen start}).}
A parameter that holds the root directory of the current project (e.g., the directory where you launched @code{raco pollen start}).}
@defparam[current-server-extras-path dir path? #:value #f]{
@defparam[current-server-extras-path dir path? #:value #f]{
A parameter that reports the path to the directory of support files for the project server.}
A parameter that reports the path to the directory of support files for the project server.}
