2 Writing Punct
Start your Punct source file with #lang punct. Then just write in CommonMark-flavored Markdown.
Punct allows inline Racket code that follows @ Syntax but with the • “bullet” character (U+2022) as the control character instead of @. On Mac OS, you can type this using ALT+8.
Punct source files automaticaly provide two bindings: doc (a document) and metas (a hash table).
2.1 Using require
By default, Punct programs have access to the bindings in racket/base and punct/core. You can import bindings from other modules in two ways:
By using require as you usually would, or
By adding one or more Module Paths directly on the #lang line.
#lang punct "my-module.rkt" racket/math •; All bindings in "my-module.rkt" and racket/math are now available •; You can also just use require normally •(require racket/string)
2.2 Metadata block
Sources can optionally add metadata using key: value lines, delimited by lines consisting only of consecutive hyphens:
#lang punct --- title: Prepare to be amazed date: 2020-05-07 draft?: '#t --- Regular content goes here
This is a syntactic convenience that comes with a few rules and limitations:
The metadata block must be the first non-whitespace thing that follows the #lang line.
Each value will always be parsed as a flat string —
or, if prefixed with a single quote ', as a simple datum (using read). If more than one datum appears after the ', the first will be used and the rest discarded.
Prefixing meta values with ' allows you to store booleans and numbers, as well as complex
values like lists, vectors, hash tables, or anything else that read would count as a single
datum (and which fits in one line) —
If you want to use the results of expressions in your metadata, you can use the set-meta function anywhere in the document or in code contained in other modules. Within the document body you can also use the ? macro as shorthand for set-meta.
Changed in version 1.2 of package punct-lib: Added ability to use datums quoted with ' in metadata.
2.3 Markdown and Racket
When evaluating a source file, Punct does things in this order:
The metadata block is parsed and its values added to current-metas.
Any inline Racket expressions are evaluated and replaced with their results. Tagged X-expressions are preserved in the final document structure (see Custom elements). Any non-string value other than a list, and any list beginning with something other than a symbol, is coerced into a string.
The entire document is run through the commonmark parser, producing a document which is bound to doc.