On this page:
3.1 Markup reference
title
excerpt
excerpt*
p
newthought
section
subsection
block
link
url
xref
figure
figure-@2x
image-link
fn
fndef
dialogue
say
saylines
index
note
verse
magick
blockquote
attrib
blockcode
i
em
b
mono
strong
strike
ol
ul
item
sup
caps
code
3.2 Convenience macros
for/  s
3.3 Defining new tags
poly-branch-tag
poly-branch-kwargs-tag
7.7

3 Pollen

 (require "pollen.rkt")

The file "pollen.rkt" is implicitly required in every template and every #lang pollen file in the project. It defines the markup for all Pollen documents, and also re-provides everything provided by "cache.rkt" and "crystalize.rkt".

The setup module towards the top of the file is used as described in pollen/setup.

3.1 Markup reference

These are the tags that can be used in any of The Local Yarn’s Pollen documents (articles, etc).

procedure

(title element ...)  txexpr?

  element : xexpr?
Supplies a title for the document. You can use any otherwise-valid markup within the title tag.

Titles are optional; if you don’t specify a title, the article will appear without one. This is a feature!

procedure

(excerpt elements ...)  txexpr?

  elements : xexpr?

procedure

(excerpt* elements ...)  txexpr?

  elements : xexpr?
Specify an excerpt to be used when the article or note included in an excerpt-style listing (such as the blog). The contents of excerpt will be extracted out of the article and note and only appear in listings; if excerpt* is used, its contents will be left in place in the article/note and reused as the excerpt in listings.

procedure

(p element ...)  txexpr?

  element : xexpr?
Wrap text in a paragraph. You almost never need to use this tag explicitly; just separate paragraphs by an empty line.

Single newlines within a paragraph will be replaced by spaces, allowing you to use semantic line wrapping.

procedure

(newthought element ...)  txexpr?

  element : xexpr?
An inline style intended for the first few words of the first paragraph in a new section. Applies a “small caps” style to the text. Any paragraph containing a newthought tag is given extra vertical leading.

Rule of thumb: within an article, use either section/subsection or newthought to separate sections of text, but not both. Even better, keep it consistent across articles within a series.

If you just need small caps without affecting the paragraph, use caps.

procedure

(section element ...)  txexpr?

  element : xexpr?

procedure

(subsection element ...)  txexpr?

  element : xexpr?
Create second- and third-level headings, respectively. This is counting the article’s title as the first-level header (even if the current article has no title).

procedure

(block element ...)  txexpr?

  element : xexpr?
A container for content that should appear grouped together on larger displays. Intended for use in Series pages, where the template is very minimal to allow for more customization. You would want output from (fenced-listing (articles 'short)) to appear inside a block, but when using 'excerpt or 'full in place of 'short in that code, you would want the output to appear outside it (since the “full” and “excerpt” versions of each article effectively supply their own blocks). Only relevant to HTML output.

procedure

(link link-id link-text)  txexpr?

  link-id : stringish?
  link-text : xexpr?

procedure

(url link-id url)  void?

  link-id : stringish?
  url : string?
All hyperlinks are specified reference-style. So, to link some text, use the link tag with an identifier, which can be a string, symbol or number. Elsewhere in the text, use url with the same identifier to specify the URL:

#lang pollen
If you need help, link[1]{Google it}.
 
url[1]{https://google.com}

The url tag for a given identifier may be placed anywhere in the document, even before it is referenced. If you create a link for an identifier that has no corresponding url, a "Missing reference: [link-id]" message will be substituted for the URL. Conversely, creating a url that is never referenced will produce no output and no warnings or errors.

procedure

(xref title)  txexpr?

  title : string?
(xref article-base element ...)  txexpr?
  article-base : string?
  element : xexpr?
Hyperlink to another article within The Local Yarn using an article-base, which is the base filename only of an article within articles-folder (without the ".poly.pm" extension).

If a single argument is supplied (title) it is typeset italicized as the link text, and its normalized form is used as the article base to generate the link. If more than one argument is supplied, the first is used as the article base, and the rest are used as the contents of the link.

#lang pollen
 
A link to xref{My Ultimate Article} will link to “my-ultimate-article.poly.pm”.
A link using xref["my-ultimate-article"]{this form} goes to the same place.

procedure

(figure image-file caption ...)  txexpr?

  image-file : string?
  caption : xexpr?

procedure

(figure-@2x image-file caption ...)  txexpr?

  image-file : string?
  caption : xexpr?
Insert a block-level image. The image-file should be supplied as a filename only, with no folder names. It is assumed that the image is located inside an images-folder within the same folder as the source document.

For web output, using figure-@2x will produce an image hard-coded to display at half its actual size, or the width of the text block, whichever is smaller.

procedure

(image-link image-file link-text ...)  txexpr?

  image-file : string?
  link-text : xexpr?
Adds a hyperlink to image-file, supplied as a filename only with no folder names. It is assumed that the image is located inside an images-folder within the same folder as the source document.

procedure

(fn fn-id)  txexpr?

  fn-id : stringish?

procedure

(fndef fn-id elements ...)  txexpr?

  fn-id : stringish?
  elements : xexpr?
As with hyperlinks, footnotes are specified reference-style. In the output, footnotes will be numbered according to the order in which their identifiers are referenced in the source document.

Example:

#lang pollen
Shoeless Joe Jackson was one of the best players of all timefn[1].
 
fndef[1]{But he might have lost the 1919 World Series on purpose.}

You can refer to a given footnote definition more than once.

The fndef for a given id may be placed anywhere in the source document, even before it is referenced. If you create a fn reference without a corresponding fndef, a "Missing footnote definition!" message will be substituted for the footnote text. Conversely, creating a fndef that is never referenced will produce no output, warning or error.

procedure

(dialogue elements ...)  txexpr?

  elements : xexpr?

procedure

(say interlocutor elements ...)  txexpr?

  interlocutor : string?
  elements : xexpr?

procedure

(saylines interlocutor elements ...)  txexpr?

  interlocutor : string?
  elements : xexpr?
Use these tags together for transcripts of dialogue, chats, screenplays, interviews and so forth. The saylines tag is the same as say except that within saylines, linebreaks within paragraphs are preserved.

Example usage:

#lang pollen
 
dialogue{
  say["Tavi"]{You also write fiction, or you used to. Do you still?}
  say["Lorde"]{The thing is, when I write now, it comes out as songs.}
}

procedure

(index [#:key key] elements ...)  txexpr?

  key : string? = ""
  elements : xexpr?
Creates a bidirectional link between this spot in the document and an entry in the keyword index under key. If key is not supplied, the string contents of elements are used as the key. Use ! to split key into a main entry and a subentry.

The example below will create two index entries, one under the heading “compassion” and one under the main heading "cats" and a subheading “stray”:

#lang pollen
 
“I have a theory which I suspect is rather immoral,” Smiley
went on, more lightly. “Each of us has only a quantum of
index{compassion}. That if we lavish our concern on every
stray index[#:key "cats!stray"]{cat} we never get to the
centre of things. What do you think of it?”

procedure

(note #:date date-str    
  [#:author author    
  #:author-url author-url    
  #:disposition disp-str])  txexpr?
  date-str : non-empty-string?
  author : string? = ""
  author-url : string? = ""
  disp-str : string? = ""
Add a note to the “Further Notes” section of the article.

The #:date attribute is required and must be of the form YYYY-MM-DD.

The #:author and #:author-url attributes can be used to credit notes from other people. If the #:author attribute is not supplied then the value of default-authorname is used.

The #:disposition attribute is used for notes that update or alter the whole disposition of the article. It must be a string of the form mark past-tense-verb, where mark is a symbol suitable for use as a marker, such as * or †, and past-tense-verb is the word you want used to describe the article’s current state. An article stating a metaphysical position might later be marked “recanted”; a prophecy or prediction might be marked “fulfilled”.

#lang pollen
 
note[#:date "2019-02-19" #:disposition "✓ verified"]{I wasn’t sure, but now I am.}

If more than one note contains a disposition attribute, the one from the most recent note is the one used.

Some caveats (for now):

procedure

(verse [#:title title    
  #:italic? italic]    
  element ...)  txexpr?
  title : string? = ""
  italic : boolean? = #f
  element : xexpr?
Typeset contents as poetry, with line breaks preserved and the block centered on the longest line. To set the whole block in italic, use #:italic? #t — otherwise, use i within the block.

If the first element in an article is a verse tag with the #:title attribute specified, that title is used as the article’s title if the normal title tag is absent.

To cite a source, use attrib immediately afterward.

procedure

(magick element ...)  txexpr?

  element : xexpr?
Typeset contents using historical ligatures and the “long s” conventions of 17th-century English books.

procedure

(blockquote element ...)  txexpr?

  element : xexpr?
Surrounds a block quotation. To cite a source, use attrib immediately afterward.

procedure

(attrib element ...)  txexpr?

  element : xexpr?
An attribution line, for citing a source for a block quotation, epigraph or poem.

procedure

(blockcode element ...)  txexpr?

  element : xexpr?
Typeset contents as a block of code using a monospace font. Line breaks are preserved.

procedure

(i element ...)  txexpr?

  element : xexpr?

procedure

(em element ...)  txexpr?

  element : xexpr?

procedure

(b element ...)  txexpr?

  element : xexpr?

procedure

(mono element ...)  txexpr?

  element : xexpr?

procedure

(strong element ...)  txexpr?

  element : xexpr?

procedure

(strike element ...)  txexpr?

  element : xexpr?

procedure

(ol element ...)  txexpr?

  element : xexpr?

procedure

(ul element ...)  txexpr?

  element : xexpr?

procedure

(item element ...)  txexpr?

  element : xexpr?

procedure

(sup element ...)  txexpr?

  element : xexpr?

procedure

(caps element ...)  txexpr?

  element : xexpr?

procedure

(code element ...)  txexpr?

  element : xexpr?
Work pretty much how you’d expect.

3.2 Convenience macros

syntax

(for/s thing-id listofthings result-exprs ...)

 
  listofthings : (listof any/c)
A shorthand form for Pollen’s for/splice that uses far fewer brackets when you’re only iterating through a single list.

#lang pollen
 
for/s[x '(7 8 9)]{Now once for number x}
 
◊;Above line is shorthand for this one:
for/splice[[(x (in-list '(7 8 9)))]]{Now once for number x}

3.3 Defining new tags

I use a couple of macros to define tag functions that automatically branch into other functions depending on the current output target format. This allows me to put the format-specific tag functions in separate files that have separate places in the dependency chain. So if only the HTML tag functions have changed and not those for PDF, the "makefile" can ensure only the HTML files are rebuilt.

syntax

(poly-branch-tag tag-id)  (-> txexpr?)

  tag-id : symbol?
Defines a new function tag-id which will automatically pass all of its arguments to a function whose name is the value returned by current-poly-target, followed by a hyphen, followed by tag. So whenever the current output format is 'html, the function defined by (poly-branch-tag p) will branch to a function named html-p; when the current format is 'pdf, it will branch to pdf-p, and so forth.

You must define these branch functions separately, and you must define one for every output format included in the definition of poly-targets in this file’s setup submodule. If you do not, you will get “unbound identifier” errors at expansion time.

The convention in this project is to define and provide these branch functions in separate files: see, e.g., "tags-html.rkt".

Functions defined with this macro do not accept keyword arguments. If you need keyword arguments, see poly-branch-kwargs-tag.

The thought behind having two macros so similar is that, by cutting out handling for keyword arguments, poly-branch-tag could produce simpler and faster code. I have not verified if this intuition is meaningful or correct.

syntax

(poly-branch-kwargs-tag tag-id)  (-> txexpr?)

  tag-id : symbol?
Works just like poly-branch-tag, but uses Pollen’s define-tag-function so that keyword arguments will automatically be parsed as X-expression attributes.

Additionally, the branch functions called from the new function must accept exactly two arguments: a list of attributes and a list of elements.