◊(Local Yarn Code "Diff")

Differences From Artifact [c9accf05]:

To Artifact [3b0baad7]:


1
2
3
4
5
6
7
8

9
10
11
12
13
14
15
16
17
18
19

20
21
22
23
24
25


26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

78
79
80
81
82
83
84
85
86
87
88
89



90
91
92
93
94
95
96
97



98
99
100
101
102
103
104
105
106
107
108



109
110

111
112
113
114


115

116
117
118
119
120



121
122


123
124

125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141


142
143

144
145
146
147
148
149
150
151


152

153
154
155
156
157


158
159

160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179


180
181
182
183

184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199


200

201
202
203
204

205
206
207

208
209
210
211
212
213
214
215
216


217


218
219
220
221
222

223
224

225
226
227
228
229
230
231
232
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

20
21
22
23
24
25

26
27
28
29
30
31










































32
33
34
35
36

37
38
39
40
41
42
43
44
45
46
47


48
49
50
51
52
53
54
55
56


57
58
59
60
61
62
63
64
65
66
67
68


69
70
71
72

73
74
75
76
77
78
79

80
81
82



83
84
85
86
87
88
89
90

91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

112
113
114
115
116
117
118
119
120
121
122

123
124
125
126
127
128
129
130
131

132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176

177
178
179
180

181
182
183

184
185
186
187
188
189
190
191


192
193
194
195
196
197
198
199
200

201
202

203

204
205
206
207
208
209
210








+










-
+





-
+
+




-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-





-
+










-
-
+
+
+






-
-
+
+
+









-
-
+
+
+

-
+




+
+
-
+


-
-
-
+
+
+


+
+

-
+

















+
+

-
+








+
+
-
+





+
+

-
+




















+
+



-
+
















+
+
-
+



-
+


-
+







-
-
+
+

+
+




-
+

-
+
-







#lang scribble/manual

@; SPDX-License-Identifier: BlueOak-1.0.0
@; This file is licensed under the Blue Oak Model License 1.0.0.

@(require "scribble-helpers.rkt")
@(require (for-label "../pollen.rkt"
                     "../dust.rkt"
                     "../cache.rkt"
                     "../crystalize.rkt"
                     racket/base
                     racket/contract
                     racket/string
                     txexpr
                     pollen/tag
                     pollen/setup
                     pollen/core
                     sugar/coerce))

@title[#:tag "pollen-rkt"]{@filepath{pollen.rkt}}
@title[#:tag "pollen-rkt"]{Pollen}

@defmodule["pollen.rkt" #:packages ()]

The file @filepath{pollen.rkt} is implicitly @code{require}d in every template and every @code{#lang
pollen} file in the project. It defines the markup for all Pollen documents, and also re-provides
everything provided by @code{crystalize.rkt}.
everything provided by @seclink["cache-rkt"]{@filepath{cache.rkt}} and
@seclink["crystalize-rkt"]{@filepath{crystalize.rkt}}.

The @code{setup} module towards the top of the file is used as described in
@racketmodname[pollen/setup].

@section{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.

@defproc[#:kind "syntax"
 (poly-branch-tag (tag-id symbol?))
 (-> txexpr?)]

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

You @emph{must} define these branch functions separately, and you must define one for @emph{every}
output format included in the definition of @racket[poly-targets] in this file’s @racket[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., @filepath{tags-html.rkt}.

Functions defined with this macro @emph{do not} accept keyword arguments. If you need keyword
arguments, see @racket[poly-branch-kwargs-tag].

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

@defproc[#:kind "syntax"
         (poly-branch-kwargs-tag (tag-id symbol?))
         (-> txexpr?)]

Works just like @racket[poly-branch-tag], but uses Pollen’s @racket[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.

@section{Markup reference}

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

@defproc[(title [element xexpr?] ...) txexpr?]
@defproc[(title [element xexpr?] ...) txexpr?]{

@margin-note{The @code{title} function is not actually defined in @filepath{pollen.rkt} or anywhere
else. In Pollen, any undefined function @tt{title} defaults to @racket[(default-tag-function
title)], which is what I want. It is documented here because its presence or absence has
side-effects on the display of the article.}

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!

@defproc[(p [element xexpr?] ...) txexpr?]
}

@defproc[(p [element xexpr?] ...) txexpr?]{

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
@ext-link["https://scott.mn/2014/02/21/semantic_linewrapping/"]{semantic line wrapping}.

@defproc[(newthought [element xexpr?] ...) txexpr?]
}

@defproc[(newthought [element xexpr?] ...) txexpr?]{

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 @code{newthought} tag is given extra
vertical leading.

Rule of thumb: within an article, use either @code{section}/@code{subsection} or @code{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 @code{smallcaps}.

If you just need small caps without affecting the paragraph, use @racket[caps].
}

@deftogether[(@defproc[(section    [element xexpr?] ...) txexpr?]
              @defproc[(subsection [element xexpr?] ...) txexpr?])]
              @defproc[(subsection [element xexpr?] ...) txexpr?])]{

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

}

@defproc[(block [element xexpr?] ...) txexpr?]
@defproc[(block [element xexpr?] ...) txexpr?]{

A container for content that should appear grouped together on larger displays. Intended for use in
Series pages, where the template is very minimal. You would want output from
@racket[listing<>-short/articles] to appear inside a @racket[block], but you would want output from
@racket[listing<>-full/articles] to appear outside it (since each article effectively supplies its own
Series pages, where the template is very minimal to allow for more customization. You would want
output from @racket[<listing-short>] to appear inside a @racket[block], but you would want output
from @racket[<listing-full>] to appear outside it (since each article effectively supplies its own
block). Only relevant to HTML output.

}

@deftogether[(@defproc[(link [link-id stringish?] [link-text xexpr?]) txexpr?]
              @defproc[(url  [link-id stringish?] [url string?]) void?])]
              @defproc[(url  [link-id stringish?] [url string?]) void?])]{

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

@codeblock|{
  #lang pollen
  If you need help, ◊link[1]{Google it}.

  ◊url[1]{https://google.com}
}|

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

}

@deftogether[(@defproc[(figure     [image-file string?] [caption xexpr?] ...) txexpr?]
              @defproc[(figure-@2x [image-file string?] [caption xexpr?] ...) txexpr?])]
              @defproc[(figure-@2x [image-file string?] [caption xexpr?] ...) txexpr?])]{

Insert a block-level image. The @racket[_image-file] should be supplied as a filename only, with no
folder names. It is assumed that the image is located inside an @racket[images-folder] within the
same folder as the source document.

For web output, using @racket[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.

}

@defproc[(image-link [image-file string?] [link-text xexpr?] ...) txexpr?]
@defproc[(image-link [image-file string?] [link-text xexpr?] ...) txexpr?]{

Adds a hyperlink to @racket[_image-file], supplied as a filename only with no folder names. It is
assumed that the image is located inside an @racket[images-folder] within the same folder as the
source document.

}

@deftogether[(@defproc[(fn    [fn-id stringish?]) txexpr?]
              @defproc[(fndef [fn-id stringish?] [elements xexpr?] ...) txexpr?])]
              @defproc[(fndef [fn-id stringish?] [elements xexpr?] ...) txexpr?])]{

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:

@codeblock|{
  #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 @code{fndef} for a given id may be placed anywhere in the source document, even before it is
referenced. If you create a @code{fn} reference without a corresponding @code{fndef},
a @code{"Missing footnote definition!"} message will be substituted for the footnote text.
Conversely, creating a @code{fndef} that is never referenced will produce no output, warning or
error.

}

@deftogether[(@defproc[(dialogue [elements xexpr?] ...) txexpr?]
              @defproc[(say [interlocutor string?] [elements xexpr?] ...) txexpr?]
              @defproc[(saylines [interlocutor string?] [elements xexpr?] ...) txexpr?])]
              @defproc[(saylines [interlocutor string?] [elements xexpr?] ...) txexpr?])]{

Use these tags together for transcripts of dialogue, chats, screenplays, interviews and so
forth. The @racket[saylines] tag is the same as @racket[say] except that within @racket[saylines],
linebreaks within paragraphs are preserved.

Example usage:

@codeblock|{
  #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.}
  }
}|

}

@defproc[(index [#:key key string? ""] [elements xexpr?] ...) txexpr?]
@defproc[(index [#:key key string? ""] [elements xexpr?] ...) txexpr?]{

Creates a bidirectional link between this spot in the document and an entry in the keyword index
under @racket[_key]. If @racket[_key] is not supplied, the string contents of @racket[_elements] are
used as the key.
used as the key. Use @tt{!} to split @racket[_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 heading “cats”:
the main heading "cats" and a subheading “stray”:

@codeblock|{
  #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"]{cat} we never get to the centre of 
  things. What do you think of it?” 
  stray ◊index[#:key "cats!stray"]{cat} we never get to the
  centre of things. What do you think of it?” 
}|

}

@defproc[(note [#:date date-str non-empty-string?]
               [#:author author string? ""]
               [#:author-url author-url string? ""]
               [#:disposition disp-str string? ""]) txexpr?]
               [#:disposition disp-str string? ""]) txexpr?]{

Add a note to the “Further Notes” section of the article. Notes are like blog comments but are
Add a @tech{note} to the “Further Notes” section of the article. 
more rare and powerful; see @wiki{Differences from blogs}.

The @code{#:date} attribute is required and must be of the form @tt{YYYY-MM-DD}.

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

248
249
250
251
252
253
254
255


256
257

258
259
260
261
262





263

264
265
266


267

268
269


270
271
272
273
274
275
276
277
278
279
280
281


282


283
284
285
286
287

288
289
290
291
292
293
294
295
296
297
298
299
















































226
227
228
229
230
231
232
233
234
235
236

237
238
239
240
241
242
243
244
245
246
247

248
249
250
251
252
253

254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269

270
271
272
273
274
275
276
277
278

279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339








+
+

-
+





+
+
+
+
+
-
+



+
+
-
+


+
+











-
+
+

+
+




-
+












+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

Some caveats (for now):

@itemlist[
  @item{Avoid defining new footnotes using @code{fndef} inside a @code{note}; these footnotes will
  be placed into the main footnote section of the article, which is probably not what you want.}
]

}

@defproc[(verse [#:title title string? ""] [#:italic? italic boolean? #f] [element xexpr?] ...)
         txexpr?]
         txexpr?]{

Typeset contents as poetry, with line breaks preserved and the block centered on the longest line.
To set the whole block in italic, use @code{#:italic? #t} — otherwise, use @code{i} within the
block.

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

}

@defproc[(blockquote [element xexpr?] ...) txexpr?]
@defproc[(blockquote [element xexpr?] ...) txexpr?]{

Surrounds a block quotation. To cite a source, include a @code{footer} tag at the bottom.

}

@defproc[(blockcode [element xexpr?] ...) txexpr?]
@defproc[(blockcode [element xexpr?] ...) txexpr?]{

Typeset contents as a block of code using a monospace font. Line breaks are preserved.

}

@deftogether[(@defproc[(i      [element xexpr?] ...) txexpr?]
              @defproc[(em     [element xexpr?] ...) txexpr?]
              @defproc[(b      [element xexpr?] ...) txexpr?]
              @defproc[(strong [element xexpr?] ...) txexpr?]
              @defproc[(strike [element xexpr?] ...) txexpr?]
              @defproc[(ol     [element xexpr?] ...) txexpr?]
              @defproc[(ul     [element xexpr?] ...) txexpr?]
              @defproc[(item   [element xexpr?] ...) txexpr?]
              @defproc[(sup    [element xexpr?] ...) txexpr?]
              @defproc[(caps   [element xexpr?] ...) txexpr?]
              @defproc[(code   [element xexpr?] ...) txexpr?])]
              @defproc[(code   [element xexpr?] ...) txexpr?])]{

Work pretty much how you’d expect.

}

@section{Convenience macros}

@defform[(for/s thing-id listofthings result-exprs ...)
         #:contracts ([listofthings (listof any/c)])]
         #:contracts ([listofthings (listof any/c)])]{

A shorthand form for Pollen’s @code{for/splice} that uses far fewer brackets when you’re only
iterating through a single list.

@codeblock|{
#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}
}|

}

@section{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 @filepath{makefile} can ensure only the HTML
files are rebuilt.

@defproc[#:kind "syntax"
 (poly-branch-tag (tag-id symbol?))
 (-> txexpr?)]{

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

You @emph{must} define these branch functions separately, and you must define one for @emph{every}
output format included in the definition of @racket[poly-targets] in this file’s @racket[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., @filepath{tags-html.rkt}.

Functions defined with this macro @emph{do not} accept keyword arguments. If you need keyword
arguments, see @racket[poly-branch-kwargs-tag].

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

}

@defproc[#:kind "syntax"
         (poly-branch-kwargs-tag (tag-id symbol?))
         (-> txexpr?)]{

Works just like @racket[poly-branch-tag], but uses Pollen’s @racket[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.

}