diff --git a/pollen/private/ts.rktd b/pollen/private/ts.rktd index 870ce2e..b0278be 100644 --- a/pollen/private/ts.rktd +++ b/pollen/private/ts.rktd @@ -1 +1 @@ -1552843367 +1552843398 diff --git a/pollen/scribblings/setup.html b/pollen/scribblings/setup.html deleted file mode 100644 index 2da3353..0000000 --- a/pollen/scribblings/setup.html +++ /dev/null @@ -1,2 +0,0 @@ - -Setup
►Setup
Setup
1 How to override setup values
2 Values
setup:  project-server-port
default-project-server-port
setup:  main-export
default-main-export
setup:  meta-export
default-meta-export
setup:  extension-escape-char
default-extension-escape-char
setup:  preproc-source-ext
default-preproc-source-ext
setup:  markup-source-ext
default-markup-source-ext
setup:  markdown-source-ext
default-markdown-source-ext
setup:  null-source-ext
default-null-source-ext
setup:  pagetree-source-ext
default-pagetree-source-ext
setup:  template-source-ext
default-template-source-ext
setup:  scribble-source-ext
default-scribble-source-ext
setup:  main-pagetree
default-main-pagetree
setup:  main-root-node
default-main-root-node
setup:  block-tags
default-block-tags
setup:  command-char
default-command-char
setup:  template-prefix
default-template-prefix
setup:  newline
default-newline
setup:  linebreak-separator
default-linebreak-separator
setup:  paragraph-separator
default-paragraph-separator
setup:  render-cache-active
default-render-cache-active
setup:  compile-cache-active
default-compile-cache-active
setup:  compile-cache-max-size
default-compile-cache-max-size
setup:  cache-watchlist
default-cache-watchlist
setup:  publish-directory
default-publish-directory
setup:  unpublished-path?
default-unpublished-path?
setup:  omitted-path?
default-omitted-path?
setup:  extra-published-path?
default-extra-published-path?
setup:  extra-path?
default-extra-path?
setup:  splicing-tag
default-splicing-tag
setup:  poly-source-ext
default-poly-source-ext
setup:  poly-targets
default-poly-targets
setup:  index-pages
default-index-pages
setup:  trim-whitespace?
default-trim-whitespace?
setup:  allow-unbound-ids?
default-allow-unbound-ids?
3 Parameters
current-server-port
current-project-root
current-server-extras-path
current-poly-target
7.1.0.6

Setup

 (require pollen/setup) package: pollen

1 How to override setup values

The values below can be changed by overriding them in your "pollen.rkt" source file:

  1. Within this file, create a submodule called setup.

  2. Within this submodule, use define to make a variable with the same name as the one in pollen/setup, but without the setup: prefix.

  3. Assign it whatever value you like.

  4. Repeat as needed.

  5. (Don’t forget to provide the variables from within your setup submodule.)

When Pollen runs, these definitions will supersede those in pollen/setup.

For instance, suppose you wanted the main export of every Pollen source file to be called van-halen rather than doc, the extension of Pollen markup files to be .rock rather than .pm, and the command character to be 🎸 instead of ◊. Your "pollen.rkt" would look like this:

"pollen.rkt"
#lang racket/base
 
;; ... the usual definitions and tag functions ...
 
(module setup racket/base
  (provide (all-defined-out))
  (define main-export 'van-halen)
  (define markup-source-ext 'rock)
  (define command-char #\🎸))

Of course, you can restore the defaults simply by removing these defined values from "pollen.rkt".

Every setup:name function will resolve the current value of that variable: it will return the value from the setup submodule (if name was defined there), otherwise it will return the default value (which is directly available from default-name). For instance, default-command-char will always be ◊, but in the example above, (setup:command-char) would return 🎸.

2 Values

procedure

(setup:project-server-port) → integer?

value

default-project-server-port : integer? = 8080

Determines the default HTTP port for the project server.

procedure

(setup:main-export) → symbol?

value

default-main-export : symbol? = 'doc

The main X-expression exported from a compiled Pollen source file.

procedure

(setup:meta-export) → symbol?

value

default-meta-export : symbol? = 'metas

The meta hashtable exported from a compiled Pollen source file.

procedure

(setup:extension-escape-char) → char?

value

default-extension-escape-char : char? = #\_

Character for escaping output-file extensions within source-file names.

procedure

(setup:preproc-source-ext) → symbol?

value

default-preproc-source-ext : symbol? = 'pp

procedure

(setup:markup-source-ext) → symbol?

value

default-markup-source-ext : symbol? = 'pm

procedure

(setup:markdown-source-ext) → symbol?

value

default-markdown-source-ext : symbol? = 'pmd

procedure

(setup:null-source-ext) → symbol?

value

default-null-source-ext : symbol? = 'p

procedure

(setup:pagetree-source-ext) → symbol?

value

default-pagetree-source-ext : symbol? = 'ptree

procedure

(setup:template-source-ext) → symbol?

value

default-template-source-ext : symbol? = 'pt

procedure

(setup:scribble-source-ext) → symbol?

value

default-scribble-source-ext : symbol? = 'scrbl

File extensions for Pollen source files.

procedure

(setup:main-pagetree) → string?

value

default-main-pagetree : string? = "index.ptree"

Pagetree that Pollen dashboard loads by default in each directory.

procedure

(setup:main-root-node) → symbol?

value

default-main-root-node : symbol? = 'root

Name of the root node in a decoded doc.

procedure

(setup:block-tags) → (listof symbol?)

value

default-block-tags : (listof symbol?) = '(see below)

Tags that are treated as blocks by block-txexpr?. Initialized to the block-level elements in HTML5, namely:

address article aside blockquote body canvas dd div dl fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 header hgroup hr li main nav noscript ol output p pre section table tfoot ul video

... plus setup:main-root-node.

procedure

(setup:command-char) → char?

value

default-command-char : char? = #\◊

The magic character that indicates a Pollen command, function, or variable.

procedure

(setup:template-prefix) → string?

value

default-template-prefix : string? = "template"

Prefix of the default template.

procedure

(setup:newline) → string?

value

default-newline : string? = "\n"

procedure

(setup:linebreak-separator) → string?

value

default-linebreak-separator : string? = "\n"

procedure

(setup:paragraph-separator) → string?

value

default-paragraph-separator : string? = "\n\n"

Default separators used in decoding.

procedure

(setup:render-cache-active) → boolean?

value

default-render-cache-active : boolean? = #t

Whether the render cache, which speeds up interactive sessions by reusing rendered versions of Pollen output files, is active.

procedure

(setup:compile-cache-active) → boolean?

value

default-compile-cache-active : boolean? = #t

Whether the compile cache, which speeds up interactive sessions by saving compiled versions of Pollen source files, is active.

procedure

(setup:compile-cache-max-size) → exact-positive-integer?

value

default-compile-cache-max-size : exact-positive-integer?

 = 10485760
Maximum size of the compile cache.

procedure

(setup:cache-watchlist) → (listof (or/c path? path-string?))

value

default-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 "pollen.rkt" changed).

If the cache can’t find a certain file on the watchlist, no error will arise. The file will simply be ignored. Therefore, to avoid unexpected behavior, the best policy is to use complete paths (or path strings). One way to generate a complete path to a local file is with define-runtime-path. Another way, if you’re using a module that’s already installed as part of a package, is with resolve-module-path:

"pollen.rkt"
(module+ setup
  (provide (all-defined-out))
  (require racket/runtime-path syntax/modresolve)
  (define-runtime-path my-local-mod "my-module.rkt")
  (define my-installed-mod (resolve-module-path 'package/my-other-module))
  (define cache-watchlist (list my-local-mod my-installed-mod)))

Added in version 1.4 of package pollen.

procedure

(setup:publish-directory)

 → (or/c path-string? path-for-some-system?)

value

default-publish-directory

 : (or/c path-string? path-for-some-system?)
 = "publish"
Default target for (part "raco_pollen_publish"). A complete path is used as is; a relative path is published to the desktop..

Added in version 1.1 of package pollen.

procedure

(setup:unpublished-path?) → (path? . -> . boolean?)

value

default-unpublished-path? : (path? . -> . boolean?)

 = (λ (path) #f)

Changed in version 1.1 of package pollen: Deprecated. Please use setup:omitted-path?.

procedure

(setup:omitted-path?) → (path? . -> . boolean?)

value

default-omitted-path? : (path? . -> . boolean?) = (λ (path) #f)

Predicate that determines whether a path is omitted from (part "raco_pollen_render") and (part "raco_pollen_publish") operations. If the predicate evaluated to #t, then the path is omitted.

Added in version 1.1 of package pollen.

procedure

(setup:extra-published-path?) → (path? . -> . boolean?)

value

default-extra-published-path? : (path? . -> . boolean?)

 = (λ (path) #f)

Changed in version 1.1 of package pollen: Deprecated. Please use setup:extra-path?.

procedure

(setup:extra-path?) → (path? . -> . boolean?)

value

default-extra-path? : (path? . -> . boolean?) = (λ (path) #f)

Predicate that determines if path is rendered & published, overriding (setup:omitted-path?) above, and Pollen’s default publish settings. For instance, Pollen automatically omits files with a .rkt extension. If you wanted to force a .rkt file to be published, you could include it here.

Added in version 1.1 of package pollen.

procedure

(setup:splicing-tag) → symbol?

value

default-splicing-tag : symbol? = '@

Key used to signal that an X-expression should be spliced into its containing X-expression.

procedure

(setup:poly-source-ext) → symbol?

value

default-poly-source-ext : symbol? = 'poly

Extension that indicates a source file can target multiple output types.

procedure

(setup:poly-targets) → (listof symbol?)

value

default-poly-targets : (listof symbol?) = '(html)

List of symbols that denotes the possible targets of a 'poly source file.

procedure

(setup:index-pages) → (listof string?)

value

default-index-pages : (listof string?) = '("index.html")

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 .htaccess configuration file). But with this setting, you can simulate the behavior of your live server, so that internal index-page URLs work correctly.

procedure

(setup:trim-whitespace?) → boolean?

value

default-trim-whitespace? : boolean? = #t

Predicate that controls whether the Pollen source reader trims whitespace from the beginning of a doc export. You might set this to #false if you’re using Pollen as a preprocessor for another programming language and you want to preserve leading whitespace accurately.

Added in version 1.5 of package pollen.

procedure

(setup:allow-unbound-ids?) → boolean?

value

default-allow-unbound-ids? : boolean? = #t

Predicate that controls whether Pollen converts unbound identifiers into default tags by altering the behavior of #%top in pollen/top.

Added in version 2.0 of package pollen.

3 Parameters

I mean parameters in the Racket sense, i.e. values that can be fed to parameterize.

parameter

(current-server-port) → integer?

(current-server-port port) → void?
  port : integer?
 = default-project-server-port
A parameter that sets the HTTP port for the project server.

parameter

(current-project-root) → path?

(current-project-root path) → void?
  path : path?
A parameter that holds the root directory of the current project (e.g., the directory where you launched raco pollen start).

parameter

(current-server-extras-path) → path?

(current-server-extras-path dir) → void?
  dir : path?
 = #f
A parameter that reports the path to the directory of support files for the project server.

parameter

(current-poly-target) → symbol?

(current-poly-target target) → void?
  target : symbol?
 = 'html
A parameter that reports the current rendering target for poly source files.

 
\ No newline at end of file diff --git a/pollen/scribblings/top.html b/pollen/scribblings/top.html deleted file mode 100644 index 5a2dfd4..0000000 --- a/pollen/scribblings/top.html +++ /dev/null @@ -1,2 +0,0 @@ - -Top
•Top
Top
#%top
def/  c
7.1.0.6

Top

 (require pollen/top) package: pollen

You’ll probably never invoke this module directly. But it’s implicitly imported into every Pollen markup file. And if you don’t know what it does, you might end up surprised by some of the behavior you get.

syntax

(#%top . id)

In standard Racket, #%top is the function of last resort, called when id is not bound to any value. As such, it typically reports a syntax error.

Examples:
; Let's call em without defining it
> (em "Bonjour")

em: undefined;

 cannot reference an identifier before its definition

  in module: top-level

; (em "Bonjour") is being converted to ((#%top . em) "Bonjour")
; So calling ((#%top . em) "Bonjour") will give the same result
> ((#%top . em) "Bonjour")

em: undefined;

 cannot reference an identifier before its definition

  in module: top-level

In the Pollen markup environment, however, this behavior is annoying. Because when you’re writing X-expressions, you don’t necessarily want to define all your tags ahead of time.

So Pollen redefines #%top. For convenience, Pollen’s version of #%top assumes that an undefined tag should just refer to an X-expression beginning with that tag (and uses default-tag-function to provide this behavior):

Examples:
; Again, let's call em without defining it, but using pollen/top
> (require pollen/top)
> (em "Bonjour")

'(em "Bonjour")

; (em "Bonjour") is still being converted to ((#%top . em) "Bonjour")
; But now, ((#%top . em) "Bonjour") gives a different result
> ((#%top . em) "Bonjour")

'(em "Bonjour")

The good news is that this behavior means you use any tag you want in your markup without defining it in advance. You can still attach a function to the tag later, which will automatically supersede #%top.

Examples:
> (define (em x) `(span ((style "font-size:100px")) ,x))
> (em "Bonjour")

'(span ((style "font-size:100px")) "Bonjour")

The bad news is that you’ll never get an “unbound identifier” error. These unbound identifiers will happily sail through and be converted to tags.

Examples:
> (require pollen/top)
> (define (em . xs) `(span ((style "font-size:100px")) ,@xs))
; There's a typo in my tag
> (erm "Bonjour")

'(erm "Bonjour")

If you prefer the ordinary Racket-style behavior where unbound identifiers raise an error, define setup:allow-unbound-ids? in your project as #false.

This isn’t a bug. It’s just a natural consequence of how Pollen’s #%top works. It can, however, make debugging difficult sometimes. Let’s suppose my markup depends on very-important-function, which I don’t import correctly.

Examples:
> (require pollen/top)
> (module vif racket/base
      (define (very-important-function . xs) `(secrets-of-universe ,@xs)))
; Forgot to (require 'vif)
> (very-important-function "Bonjour")

'(very-important-function "Bonjour")

So the undefined-function bug goes unreported. Again, that’s not a bug in Pollen — there’s just no way for it to tell the difference between an identifier that’s deliberately undefined and one that’s inadvertently undefined. If you want to guarantee that you’re invoking a defined identifier, use def/c.

syntax

(def/c id)

Invoke id if it’s a defined identifier, otherwise raise an error. This form reverses the behavior of #%top (in other words, it restores default Racket behavior).

Recall this example from before. In standard Racket, you get an undefined-identifier error.

Examples:
> (module vif racket/base
      (define (very-important-function . xs) `(secrets-of-universe ,@xs)))
; Forgot to (require 'vif)
> (very-important-function "Bonjour")

very-important-function: undefined;

 cannot reference an identifier before its definition

  in module: top-level

But with pollen/top, the issue is not treated as an error.

Examples:
> (require pollen/top)
> (module vif racket/base
      (define (very-important-function . xs) `(secrets-of-universe ,@xs)))
; Forgot to (require 'vif)
> (very-important-function "Bonjour")

'(very-important-function "Bonjour")

By adding def/c, we restore the usual behavior, guaranteeing that we get the defined version of very-important-function or nothing.

Examples:
> (require pollen/top)
> (module vif racket/base
      (define (very-important-function . xs) `(secrets-of-universe ,@xs)))
; Forgot to (require 'vif)
> ((def/c very-important-function) "Bonjour")

very-important-function: undefined;

 cannot reference an identifier before its definition

  in module: top-level

 
\ No newline at end of file diff --git a/pollen/scribblings/version-history.html b/pollen/scribblings/version-history.html deleted file mode 100644 index f13972a..0000000 --- a/pollen/scribblings/version-history.html +++ /dev/null @@ -1,2 +0,0 @@ - -Version notes (2.0.2038.749)
►Version notes (2.0.2038.749)
Version notes (2.0.2038.749)
1 What the version number means
2 Source code
3 Development policy
4 Changelog
4.1 Version 2.0
4.2 Version 1.5
4.3 Version 1.4
4.4 Version 1.3
4.5 Version 1.2
4.6 Version 1.1
4.7 Version 1.0
7.1.0.6

Version notes (2.0.2038.749)

1 What the version number means

Consistent with Racket’s version-numbering system, the first digit reflects major updates to Pollen that break backward compatibility. The second digit reflects feature updates that don’t affect existing features.

Inconsistent with this system, Pollen’s version also appends a build number, which is the age of the software in days and minutes. (The official version reported in Pollen’s "info.rkt" is just the major + minor digits.)

2 Source code

Pollen’s source code is available from this Git repo. The MASTER branch of the repo will always contain the most recent stable version.

Racket’s package catalog relies on this branch, so if you get your updates with raco pkg update pollen, you’ll get the most recent updates from this branch.

I will add Git tags to commits where the major or minor version changed, so if you need to rebuild an earlier version, you can.

3 Development policy

Beyond keeping the commit history available, I make no promise to maintain the public interface in its current state. I will avoid unnecessary upheaval, of course. But my goal is to make the system more capable and stable, not to permanently burden it with my current level of ignorance.

4 Changelog

4.1 Version 2.0

Dropped support for Racket versions earlier than 6.3.

Added setup:allow-unbound-ids?.

4.2 Version 1.5

Added setup:trim-whitespace?.

4.3 Version 1.4

Added setup:cache-watchlist, for/splice, for*/splice, current-metas.

4.4 Version 1.3

Various optimizations and bugfixes.

4.5 Version 1.2

raco pollen: Added --local option to (part ("(lib pollen/scribblings/pollen.scrbl)" "raco_pollen_start")).

Various optimizations and bugfixes.

4.6 Version 1.1

New features

raco pollen: Added --recursive option to (part ("(lib pollen/scribblings/pollen.scrbl)" "raco_pollen_render")).

pollen/setup: setup:omitted-path? replaces setup:unpublished-path?, and setup:extra-path? replaces setup:extra-published-path?. These settings are used during both render and publish operations. (The old names will still work, however.)

Added setup:publish-directory, which can be used to set a default publish directory.

4.7 Version 1.0

New features

pollen/cache: cached-doc and cached-metas are the preferred way to retrieve data from a Pollen source file.

The pollen/core module has been added, the new home for functions that once lived in pollen/template. Also new splicing tag @ and when/splice macro.

pollen/setup replaces pollen/world. pollen/setup values can be overridden with a setup submodule. Parameter names are no longer prefixed.

Backward incompatibilities

pollen/cache: cached-require is deprecated. Use cached-doc or cached-metas.

pollen/template: functions like get-doc, get-metas, and the select functions have been moved to pollen/core. when/block is deprecated in favor of when/splice.

pollen/template: detect-paragraphs and detect-linebreaks have been renamed decode-paragraphs and decode-linebreaks. Typography functions like smart-quotes and smart-dashes have been moved to pollen/unstable/typography. register-block-tags is gone — override default-block-tags instead.

pollen/file: refined to a more carefully curated set of functions.

pollen/template: Pollen now supports any output formats, so this module has been broken into format-specific versions. For now, the only submodule is pollen/template/html, the home of ->html.

pollen/world: superseded by pollen/setup (see above). The config submodule in a "pollen.rkt" will no longer work.

 
\ No newline at end of file