3 Pollen

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).

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

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

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.

#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.

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.

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.

Example:

#lang pollen

Shoeless Joe Jackson was one of the best players of all time◊fn[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.

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.}

}

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?”

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):

• Avoid defining new footnotes using fndef inside a note; these footnotes will be placed into the main footnote section of the article, which is probably not what you want.

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.

3.2 Convenience macros

#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.

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.

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