◊(Local Yarn Code "Diff")

#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"]{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 @seclink["cache-rkt"]{@filepath{cache.rkt}} and
everything provided by @filepath{cache.rkt} and @filepath{crystalize.rkt}.
@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{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.

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.
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?)]
 (-> 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?)]
         (-> 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.

}