◊(Local Yarn Code "Changes On Branch cf83a366e1367b25")

*compiled/*
*.woff*
x-*/*
*.*~
web-extra/martin.css
web/martin.css
scribbled/*
code-docs/*.css
code-docs/*.js
yarn-doc/*.css
yarn-doc/*.js
*/images/*
*.db
*.sqlite
*.pdf
*.ltx
*.html
*.out
*.ltx
*.aux
*.log
*.xml
*.toc
*.mark

#lang pollen

◊; Copyright 2019 by Joel Dueck. All Rights Reserved.

◊(define-meta published "2019-04-11")

◊title{What Should People Do With Old Journals?}

When I die, I’ll leave behind a lot of ◊index{journals} and notebooks. These may be of
When I die, I’ll leave behind a lot of ◊pin{journals} and notebooks. These may be of
interest to my immediate family, but they won’t exactly be great leisure reading. The only obvious
choices are to keep them in a box in the attic, or eventually throw them out.

A ◊def{journal} is a collection of personal observations.

There ought to be a third choice. Even the most mundane journal has great value simply because it
contains lots of historical information about current thinking, lifestyle habits, values, and events,
things which change wildly over long time periods.

On the receiving end, suppose you inherit your great-grandfather’s journal; he has been dead for
◊blockquote[#:caption "hi"]{On the receiving end, suppose you inherit your great-grandfather’s journal; he has been dead for
decades and you never knew him personally. If you can find the time, you pore over it for an hour or
two, deciphering the handwriting. You learn some facts about him and how he looked at things. What
happens after that?
happens after that?}

I have an idea that there should be an ◊index[#:key "archives"]{archive}, a public repository for
I have an idea that there should be an ◊pin[#:key "archives"]{archive}, a public repository for
things like this. You could send in your great-grandfather’s journal for use by future historians.
They would digitize or transcribe it, analyze it, and tag it with metadata about who wrote it, when
they wrote it, and generally what topics they wrote about. They could allow you to specify that it
must remain private until a specified date, and provide you with a digital copy, or even a nice hard
copy if you wanted to pay a little extra.

This would give researchers a huge resource to draw upon, and allow the full value of old journals
(the sentimental ◊em{and} the historic value) to be realized, without compromising anyone’s
privacy.

#lang racket/base

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

(require deta
         db/base
         db/sqlite3
         threading
         pollen/setup
         racket/match
         "dust.rkt"
         (except-in pollen/core select))

(provide init-cache-db!
         cache-conn                     ; The most eligible bachelor in Neo Yokyo
         (schema-out cache:article)
         (schema-out cache:note)
         (schema-out cache:index-entry)
         (schema-out listing)
         delete-article!
         delete-notes!
         delete-index-entries!
         save-cache-things!
         articles
         articles+notes
         listing-htmls
         fenced-listing
         unfence)

;; Cache DB and Schemas

(define DBFILE (build-path (current-project-root) "vitreous.sqlite"))
(define cache-conn (make-parameter (sqlite3-connect #:database DBFILE #:mode 'create)))

(define-schema cache:article #:table "articles"
  ([id                   id/f #:primary-key #:auto-increment]
   [page                 symbol/f]
   [title-plain          string/f  #:nullable]
   [title-html-flow      string/f  #:nullable]
   [title-specified?     boolean/f #:nullable]
   [published            string/f  #:nullable]
   [updated              string/f  #:nullable]
   [author               string/f  #:nullable]
   [conceal              string/f]
   [series-page          symbol/f  #:nullable]
   [noun-singular        string/f  #:nullable]
   [note-count           integer/f #:nullable]
   [content-html         string/f  #:nullable]
   [disposition          string/f  #:nullable]
   [disp-html-anchor     string/f  #:nullable]
   [listing-full-html    string/f  #:nullable]   ; full content but without notes
   [listing-excerpt-html string/f  #:nullable]   ; Not used for now
   [listing-short-html   string/f  #:nullable])) ; Date and title only

(define-schema cache:note #:table "notes"
  ([id                   id/f #:primary-key #:auto-increment]
   [page                 symbol/f]
   [html-anchor          string/f]
   [title-html-flow      string/f] ; No block-level HTML elements
   [title-plain          string/f]
   [author               string/f]
   [author-url           string/f]
   [published            string/f]
   [disposition          string/f]
   [content-html         string/f]
   [series-page          symbol/f]
   [conceal              string/f]
   [listing-full-html    string/f]
   [listing-excerpt-html string/f]   ; Not used for now
   [listing-short-html   string/f])) ; Date and title only

(define-schema cache:index-entry #:table "index_entries"
  ([id          id/f #:primary-key #:auto-increment]
   [entry       string/f]
   [subentry    string/f]
   [page        symbol/f]
   [html-anchor string/f]))

(define-schema listing
  #:virtual
  ([path        string/f]
   [title       string/f]
   [author      string/f]
   [published   string/f]
   [updated     string/f]
   [html        string/f]))

(define (init-cache-db!)
  (create-table! (cache-conn) 'cache:article)
  (create-table! (cache-conn) 'cache:note)
  (create-table! (cache-conn) 'cache:index-entry))

(define (delete-article! page)
  (query-exec (cache-conn)
              (~> (from cache:article #:as a)
                  (where (= a.page ,(format "~a" page)))
                  delete)))

(define (delete-notes! page)
  (query-exec (cache-conn)
              (~> (from cache:note #:as n)
                  (where (= n.page ,(format "~a" page)))
                  delete)))

(define (delete-index-entries! page)
  (query-exec (cache-conn)
              (~> (from cache:index-entry #:as e)
                  (where (= e.page ,(format "~a" page)))
                  delete)))

(define (save-cache-things! es)
  (void (apply insert! (cache-conn) es)))

;;
;;  ~~~ Fetching articles and notes ~~~
;;

;; (Private use) Conveniece function for the WHERE `series-page` clause
(define (where-series q s)
  (define (s->p x) (format "~a/~a.html" series-folder x))
  (match s
    [(list series ...)
     (where q (in a.series-page ,(map s->p series)))] ; WHERE series-page IN (item1 ...)
    [(or (? string? series) (? symbol? series))
     (where q (= a.series-page ,(s->p series)))]      ; WHERE series-page = "item"
    [#t
     (where q (like a.series-page ,(format "%~a" (here-output-path))))]
    [_ q]))

;; (Private use) Convenience for the WHERE `conceal` NOT LIKE clause
(define (where-not-concealed q)
  (define base-clause (where q (not (like a.conceal "%all%"))))
  (match (listing-context)
    ["" base-clause]
    [(var context) (where base-clause (not (like a.conceal ,(format "%~a%" context))))]))

;; Needed to "parameterize" column names
;; see https://github.com/Bogdanp/deta/issues/14#issuecomment-573344928
(require (prefix-in ast: deta/private/ast))

;; Builds a query to fetch articles
(define (articles type #:series [s #t] #:limit [lim -1] #:order [ord 'desc])
  (define html-field
    (match type
      ['content "content_html"]
      [_ (format "listing_~a_html" type)]))
  (~> (from cache:article #:as a)
      (select (as a.page path)
              (as a.title-plain title)
              a.author
              a.published
              a.updated
              (fragment (ast:as (ast:qualified "a" html-field) "html")))
      (where-series s)
      (where-not-concealed)
      (limit ,lim)
      (order-by ([a.published ,ord]))
      (project-onto listing-schema)))

;; Builds a query that returns articles and notes intermingled chronologically
(define (articles+notes type #:series [s #t] #:limit [lim -1] #:order [ord 'desc])
  (define html-field
    (match type
      ['content "content_html"]
      [_ (format "listing_~a_html" type)]))
  (~> (from (subquery
             (~> (from cache:article #:as A)
                 (select 
                  (as A.page path)
                  (as A.title-plain title)
                  A.author
                  A.published
                  A.updated
                  (fragment (ast:as (ast:qualified "A" html-field) "html"))
                  A.series-page
                  A.conceal)
                 (union
                  (~> (from cache:note #:as N)
                      (select 
                       (as (array-concat N.page "#" N.html-anchor) path)
                       (as N.title-plain title)
                       N.author
                       N.published
                       (as "" updated) 
                       (fragment (ast:as (ast:qualified "N" html-field) "html"))
                       N.series-page
                       N.conceal)))))
            #:as a)
      (where-series s)
      (where-not-concealed)
      (limit ,lim)
      (order-by ([a.published ,ord]))
      (project-onto listing-schema)))

;; Get all the a list of the HTML all the results in a query
(define (listing-htmls list-query)
  (for/list ([l (in-entities (cache-conn) list-query)])
    (listing-html l)))

;; Return cached HTML of articles and/or notes, fenced within a style txexpr to prevent it being
;; escaped by ->html. See also: definition of `unfence`
(define (fenced-listing q)
  `(style ,@(listing-htmls q)))

;; Remove "<style>" and "</style>" introduced by using ->html on docs containing output from
;; listing functions
(define (unfence html-str)
  (regexp-replace* #px"<[\\/]{0,1}style>" html-str ""))

#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" scribble/example)

@(require (for-label deta
                     db
                     racket/base
                     racket/contract
                     sugar/coerce
                     pollen/template
                     "../dust.rkt"
                     "../crystalize.rkt"
                     "../cache.rkt"))

@(define example-eval (make-base-eval))
@(example-eval '(require "cache.rkt" txexpr))

@title[#:tag "cache-rkt"]{Cache}

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

In this project there are several places – the blog, the footer on each page, the RSS feed, series
pages — where data from an amorphous group of Pollen documents is needed. This is what the cache is
for.

This module defines and provides the schema and database connection to the SQLite cache, and some
functions for retrieving records from the cache. Use these when you need quick access to pre-cooked
HTML.

@section{Cache database}

@defparam[cache-conn conn connection?]{
The database connection.
}

@defproc[(init-cache-db!) void?]{

Creates and initializes the SQLite database cache file (named @filepath{vitreous.sqlite} and located
in the project root folder) by running queries to create tables in the database if they do not
exist.

}

@section{Retrieving cached data}

Some of this looks a little wacky, but it’s a case of putting a little extra complextity into the
back end to make things simple on the front end. These functions are most commonly used inside the
@emph{body} of a Pollen document (i.e., series pages). 

@filebox["series/my-series.poly.pm"
@codeblock|{
#lang pollen

◊title{My New Series}

...some other content

◊fenced-listing[(articles+notes 'excerpt #:order 'asc)]
}|
]

@defproc[(fenced-listing [query query?]) txexpr?]{

Fetches a the HTML strings from the SQLite cache and returns a @racket['style] tagged X-expression
with these strings as its elements. The @racket[_query] will usually be the result of a call to
@racket[articles] or @racket[articles+notes], but can be any custom query that projects onto the
@racket[listing] schema (see @racket[project-onto]).

The reason for enclosing the results in a @racket['style] txexpr is to prevent the HTML from being
escaped by @racket[->html] in the template. This tag was picked for the job because there will
generally never be a need to include any actual CSS information inside a @tt{<style>} tag in any
page, so it can be safely filtered out later. To remove the enclosing @tt{<style>} tag, see
@racket[unfence].

}

@defproc[(listing-htmls [listing-query query?]) (listof string?)]{

Returns the HTML bodies for the articles and/or notes returned by @racket[_listing-query] as a list
of strings. The @racket[_query] will usually be the result of a call to @racket[articles] or
@racket[articles+notes], but can be any custom query that projects onto the @racket[listing] schema
(see @racket[project-onto]).

}

@deftogether[(@defproc[(articles [type (or/c 'full 'excerpt 'short 'content)]
                                 [#:series series (or/c string? (listof string?) boolean?) #t]
                                 [#:limit limit integer? -1]
                                 [order stringish? 'desc]) query?]
              @defproc[(articles+notes [type (or/c 'full 'excerpt 'short 'content)]
                                       [#:series series (or/c string? (listof string?) boolean?) #t]
                                       [#:limit limit integer? -1]
                                       [order stringish? 'desc]) query?])]{

Create a query that fetches either articles only, or articles and notes intermingled, respectively.
The results will be sorted by publish date according to @racket[_order] and optionally limited to
a particular series. Use the resulting query with the @racket[listing-htmls] or
@racket[fenced-listing] functions provided by this module, or with deta’s @racket[in-entities] if
you want to work with the @racket[listing] schema structs.

The @racket[_type] parameter specifies what version of the articles’ and notes’ HTML markup you
want. For HTML suitable for listing several articles and/or notes together on the same page, use
@racket['full] (the full content but not including @tech{notes}), @racket['excerpt] (like full but
abbreviated to only the excerpt if one was specified) or @racket['short] (date and title only). Use
@racket['content] to get the entire HTML content, including any notes but not including any header
or footer. (This is the option used in the RSS feed.)

If @racket[_series] expression evaluates to @racket[#f], articles will not be filtered by series. If
it evaluates to @racket[#t] (the default), articles will be filtered by those that specify the
current output of @racket[here-output-path] in their @tt{series_pagenode} column in the SQLite
cache. If a string or a symbol is supplied, articles will be filtered by those containing the result
of @racket[(format "series/~a.html" _series)] in their @tt{series_pagenode} column in the SQLite
cache. If a list of strings or symbols is provided, this @racket[format] operation will be applied
to each of its members and articles whose @tt{series_pagenode} column matches any of the resulting
values will be included.

The @racket[_order] expression must evaluate to either @racket["ASC"] or @racket["DESC"] (or
equivalent symbols) and the @racket[_limit] expressions must evaluate to a value suitable for use in
the @tt{LIMIT} clause of @ext-link["https://sqlite.org/lang_select.html"]{a SQLite @tt{SELECT}
statement}. An expression that evaluates to a negative integer (the default) is the same as having
no limit.

Typically you will pass these functions by name to listing functions like @racket[fenced-listing]
rather than calling them directly.

@examples[#:eval example-eval
(articles 'full)]
}

@defproc[(unfence [html string?]) string?]{

Returns @racket[_html] with all occurrences of @racket["<style>"] and @racket["</style>"] removed.
The contents of the style tags are left intact.

Use this in templates with strings returned from @racket[->html] when called on docs that use the
@racket[fenced-listing] tag function.

}

@section{Modifying the cache}

@defproc[(save-cache-things! 
          [things (listof (or/c cache:article? cache:note? cache:index-entry?))]) void?]{

Saves all the @racket[_thing]s to the cache database.

}

@deftogether[(@defproc[(delete-article! [page stringish?]) void?]
              @defproc[(delete-notes!   [page stringish?]) void?])]{
              
Delete a particular article, or all notes for a particular article, respectively.

}

@section{Schema}

The cache database has four tables: @tt{articles}, @tt{notes}, @tt{index_entries} and @tt{series}.
Each of these has a corresponding schema, shown below. In addition, there is a “virtual” schema,
@tt{listing}, for use with queries which may or may not combine articles and notes intermingled.

The work of picking apart an article’s exported @tt{doc} and @tt{metas} into rows in these tables is
done by @racket[parse-and-cache-article!].

The below are shown as @code{struct} forms but are actually defined with deta’s
@racket[define-schema]. Each schema has an associated struct with the same name and a smart
constructor called @tt{make-@emph{id}}. The struct’s “dumb” constructor is hidden so that invalid
entities cannot be created. For every defined field there is an associated functional setter and
updater named @tt{set-@emph{id}-field} and @tt{update-@emph{id}-field}, respectively.

@defstruct*[cache:article ([id                   id/f]
                           [page                 symbol/f]
                           [title-plain          string/f]
                           [title-html-flow      string/f]
                           [title-specified      boolean/f]
                           [published            string/f]
                           [updated              string/f]
                           [author               string/f]
                           [conceal              string/f]
                           [series-page          string/f]
                           [noun-singular        string/f]
                           [note-count           integer/f]
                           [content-html         string/f]
                           [disposition          string/f]
                           [disp-html-anchor     string/f]
                           [listing-full-html    string/f]
                           [listing-excerpt-html string/f]
                           [listing-short-html   string/f])
            #:constructor-name make-cache:article]{

Table holding cached @tech{article} information.

When creating a @racket[cache:article] (should you ever need to do so directly, which is unlikely),
the only required fields are @racket[_page], @racket[_title], and @racket[_conceal].

}

@defstruct*[cache:note ([id              id/f]
                        [page            symbol/f]
                        [html-anchor     string/f]
                        [title-html-flow string/f]
                        [title-plain     string/f]
                        [author          string/f]
                        [author-url      string/f]
                        [published       string/f]
                        [disposition     string/f]
                        [content-html    string/f]
                        [series-page     symbol/f]
                        [conceal         string/f]
                        [listing-full-html    string/f]
                        [listing-excerpt-html string/f]
                        [listing-short-html   string/f])
                       #:constructor-name make-cache:note]{

Table holding cached information on @tech{notes}.

}

@defstruct*[cache:index-entry ([id id/f]
                               [entry       string/f]
                               [subentry    string/f]
                               [page        symbol/f]
                               [html-anchor string/f])
                              #:constructor-name make-cache:index-entry]{
                              
Table holding cached information about index entries found in @tech{articles}.

}

@defstruct*[listing ([path        string/f]
                     [title       string/f]
                     [author      string/f]
                     [published   string/f]
                     [updated     string/f]
                     [html        string/f])
                    #:constructor-name make-listing]{

This is a “virtual” schema targeted by @racket[articles] and @racket[articles+notes] using deta’s
@racket[project-onto]. It supplies the minimum set of fields needed to build the RSS feed, and which
are common to both articles and notes; most times (e.g., on @tech{series} pages) only the @tt{html}
field is used, via @racket[fenced-listing] or @racket[listing-htmls].

}

#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"
                     "../crystalize.rkt"
                     "../cache.rkt"
                     racket/base
                     racket/contract
                     racket/string
                     txexpr
                     pollen/core
                     pollen/pagetree))

@title[#:tag "crystalize-rkt"]{Crystalize}

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

“Crystalizing” is an extra layer in between docs and templates that destructures the @tt{doc} and
stores it in various pieces in a SQLite cache. Individual articles save chunks of rendered HTML to
the cache when their individual pages are rendered. When pulling together listings of articles in
different contexts that need to be filtered and sorted, a SQL query is much faster than trolling
through the Pollen cache for matching docs and regenerating the HTML.

@margin-note{These functions are designed to be used within templates, so that the rows in the cache
database for a page are updated right when that web page is rendered.}

@defproc[(parse-and-cache-article! [pagenode pagenode?] [doc txexpr?]) 
         (values non-empty-string? non-empty-string?)]{

Returns two values: the “plain” title of the article, and a string containing the full HTML of
@racket[_doc], in that order.

The title is returned separately for use in the HTML @tt{<title>} tag. If the @racket[_doc] doesn’t
specify a title, a provisional title is constructed using @racket[default-title].

Privately, it does a lot of other work. The article is analyzed, additional metadata is constructed
and saved to the SQLite cache and saved using @racket[make-cache:article]. If the article specifies
a @racket['series] meta, information about that series is fetched and used in the rendering of the
article. If there are @racket[note]s or @racket[index] tags in the doc, they are parsed and saved
individually to the SQLite cache (using @racket[make-cache:note] and
@racket[make-cache:index-entry]). If any of the notes use the @code{#:disposition} attribute,
information about the disposition is parsed out and used in the rendering of the article. 

}

@defproc[(cache-index-entries-only! [title string?] [page pagenode?] [doc txexpr?]) void?]{

Saves only the @racket[index] entres in @racket[_doc] to the cache database, so that they appear in
the keyword index.

This function allows pages that are not @tech{articles} to have their own keyword index entries, and
should be used in the templates for such pages.

As a side effect of calling this function, a minimal @racket[cache:article] is created for the page
with its @racket['conceal] meta set to @racket{all}, to exclude it from any listings.

}

.fileblock .SCodeFlow {
    padding-top: 0.7em;
    margin-top: 0;
}

.fileblock {
    width: 90%;
}

.fileblock_filetitle{
    background: #eee;
    text-align:right;
    padding: 0.15em;
    border: 1px dotted black;
    border-bottom: none;
}

.terminal, .browser {
    margin-bottom: 1em;
    padding: 0.5em;
    width: 88%;
    background: #fcfcfc;
    color: rgb(150, 35, 105);
}

.terminal .SIntrapara, .browser .SIntrapara, .fileblock .SIntrapara {
    margin: 0 0 0 0;
}

#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"
          racket/runtime-path
          (for-label "../pollen.rkt"))

@(require (for-label racket/base))

@title{Basic Notions}

@section[#:tag "design-goals"]{Design Goals}

The design of @italic{The Local Yarn} is guided by requirements that have evolved since I started
the site in 1999. I enumerate them here because they explain why the code is necessarily more
complicated than a typical blog:

@itemlist[
 @item{@bold{The writing will publish to two places from the same source: the web server, and the
 bookshelf.} The web server, because it’s a fun, fast way to publish writing and code to the whole
 world (you knew that already); but also on bookshelves, because
 @ext-link["https://thelocalyarn.com/excursus/secretary/posts/web-books.html"]{a web server is like
 a projector}, and I want to be able to turn it off someday and still have something to show for all
 my work. Plus, I just like printed books.}

 @item{@bold{Changes are part of the content.} I like to revisit, resurface and amend things I’ve
 written before. Views change, new ideas come along. In a typical blog the focus is always at
 whatever’s happening at the head of the time stream; an addendum to an older post is, for all
 practical purposes, invisible and nearly useless. I want every published edit to an article to be
 findable and linkable. I want addenda to be extremely visible. These addenda should also be able to
 mark major shifts in the author’s own perspective on what they originally wrote.}

 @item{@bold{The system will gracefully accomodate experimentation.} I should be able to write
 fiction, poetry, opinion pieces, minor observations or collections, or anything else, and have or
 create a good home for it here.}
 
 @item{@bold{Everything produced here should look good.}}

 @item{@bold{Reward exploration without disorienting the reader.} Draw connections between related
 thoughts using typographic conventions and organizational devices that would be familiar to
 a reader of books. Where dissimilar writings appear together, place signals that help the reader
 understand what they are looking at, switch contexts, and find more if they wish.}
 
 @item{@bold{Everything is produced, and reproducible, by an automatable process.} No clicking or
 tapping around in GUI apps to publish web pages and books.}
 
 ]

@section{Names for things and how they fit together}

The Local Yarn is mostly comprised of @tech{articles} (individual writings) which may contain
@tech{notes} (addenda by the author or others) and may also be grouped into @tech{series}. These are
similar to a typical blog’s @italic{posts}, @italic{comments} and @italic{categories}, but there are
important differences.

@subsection{Articles}

The @deftech{article} is the basic unit of content, like a typical blog post. In the web edition,
each article has its own @tt{.html} file; in print editions, an article may comprise either
a chapter or a part of a chapter, depending on the content.

An article can start out very small — just a date and a few sentences. @bold{Supplying a title is
optional.} Later, it may grow in any of several directions: @tech{notes} can be added, or a title, or
cross-references to later articles; or it may be added to a series. Or it may just remain the way it
started.

@subsection{Notes}

A @deftech{note} is a comment or addendum to an @tech{article} using the @racket[note] tag. It may
be written by the same person who wrote the article, or submitted by a reader.

@(define-runtime-path diagram-notes "diagram-notes.png")
@centered{@responsive-retina-image[diagram-notes]}

As shown above, a note appears at the bottom of the article to which it is attached, but it also
appears in the blog and in the RSS feed as a separate piece of content, and is given the same visual
weight as actual articles.

A note may optionally have a @deftech{disposition} which reflects a change in attitude towards its
parent article. A disposition consists of a @italic{disposition mark} such as an asterisk or dagger,
and a past-tense verb. For example, an author may revisit an opinion piece written years earlier and
add a note describing how their opinion has changed; the tag for this note might include
@racket[#:disposition "* recanted"] as an attribute. This would cause the @tt{*} to be added to the
article’s title, and the phrase “Now considered recanted” to be added to the margin, with a link to
the note.

@subsubsection{Notes vs. blog “comments”}

Typical blog comments serve as kind of a temporary discussion spot for a few days or weeks after
a post is published. Commenting on an old post feels useless because the comment is only visible at
the bottom of its parent post, and older posts are never “bumped” back into visibility.

By contrast, notes on @italic{The Local Yarn} appear as self-contained writings at the top of the
blog and RSS feed as soon as they are published. This “resurfaces” the original article
to which they are attached. This extra visibility also makes them a good tool for the original
author to fill out or update the article. In effect, with notes, each article potentially becomes
its own miniature blog.

The flip side of this change is that what used to be the “comment section” is no longer allowed to
function as a kind of per-article chat.

@tabular[#:sep @hspace[1]
         #:style 'boxed
         #:row-properties '((bottom-border top))
         (list
          (list @bold{Typical Blog Comments} @bold{Local Yarn @emph{Notes}})
          (list "Rarely used after a post has aged"
                "Commonly used on posts many years old")
          (list "Visible only at the bottom of the parent post"
                "Included in the main stream of posts and in the RSS feed alongside actual posts")
          (list "Invites any and all feedback, from small compliments to lengthy rebuttals"
                "Readers invited to treat their responses as submissions to a publication.")
          (list "Usually used by readers"
                "Usually used by the original author")
          (list "Don’t affect the original post"
                "May have properties (e.g. disposition) that change the status and
presentation of the original post")
          (list "Moderation (if done) is typically binary: approved or not"
                "Moderation may take the form of edits and inline responses."))]

@subsection{Series}

A @deftech{series} is a grouping of @tech{articles} into a particular order under a descriptive
title. A series may present its own written content alongside the listing of its articles.

The page for a series can choose how to display its articles: chronologically, or in an arbitrary
order. It can display articles only, or a mixed listing of articles and @tech{notes}, like the blog.
And it can choose to display articles in list form, or as excerpts, or in their entirety.

A series can specify @italic{nouns} (noun phrases, really) to be applied to its articles. So, for
example, a series of forceful opinion pieces might designate its articles as @emph{naked
aspirations}; the phrase “This is a naked aspiration, part of the series @italic{My Uncensored
Thoughts}” would appear prominently in the margins. Likewise, a time-ordered series of observations
might call its articles “journal entries”.

It will be easy for any series to become a printed @emph{book}, using the techniques I
demonstrated in
@ext-link["https://thelocalyarn.com/excursus/secretary/posts/web-books.html"]{@italic{The Unbearable
Lightness of Web Pages}}, and in @other-doc['(lib "bookcover/scribblings/bookcover.scrbl")].

@subsubsection{Series vs. blog “categories”}

Typical blogs are not very good at presenting content that may vary a lot in subject, length and
style. The kind of writing I want to experiment with may change a lot from day to day, season to
season, decade to decade. I wanted a single system that could organize extremely varied kinds of
writings and present them in a thoughtful, coherent way, rather than starting a new blog every time
I wanted to try writing a different kind of thing.

My solution to this was to enrich the idea of “categories”. Rather than being simply labels that you
slap on blog posts, they would be titled collections with their own unique content and way of
presenting articles and notes. In addition, they could pass down certain properties to the posts
they contain, that can be used to give signals to the reader about what they are looking at.

@tabular[#:sep @hspace[1]
         #:style 'boxed
         #:row-properties '((bottom-border top))
         (list
          (list @bold{Typical Blog Categories/Tags} @bold{Local Yarn @emph{Series}})
          (list "Every article needs to have one"
                "Many or most articles won’t have one")
          (list "Named with a single word" 
                "Named with a descriptive title")
          (list "Has no content or properties of its own"
                "Has its own written content, and properties such as nouns, ordering, etc.")
          (list "Broad in scope, few in number"	
                "Narrow in scope, many in number")
          (list "Selected to be relevant for use across the entire lifetime of the site"
                "Selected without reference to future creative direction; may be closed after only
                 a few articles"))]

#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"
          scribble/example)

@(require (for-label "../pollen.rkt"
                     "../dust.rkt"
                     "../cache.rkt"
                     "../series-list.rkt"
                     racket/base
                     racket/contract
                     txexpr
                     sugar/coerce
                     pollen/tag
                     pollen/setup
                     pollen/pagetree
                     pollen/core))

@(define dust-eval (make-base-eval))
@(dust-eval '(require "dust.rkt" txexpr))

@title{Dust}

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

This is where I put constants and helper functions that are needed pretty much everywhere in the
project. In a simpler project these would go in @seclink["pollen-rkt"]{@filepath{pollen.rkt}} but
here I have other modules sitting “behind” that one in the @tt{require} chain.

@section{Constants}

@defthing[default-authorname string? #:value "Joel Dueck"]

Used as the default author name for @code{note}s, and (possibly in the future) for articles
generally.

@defthing[web-root path-string? #:value "/"]

Specifies the path between the domain name and the root folder of the website generated by this
project.

@deftogether[(@defthing[articles-folder path-string? #:value "articles"]
              @defthing[series-folder   path-string? #:value "series"])]

The names of the folders that contain the Pollen source documents for Articles and Series
respectively, relative to the project’s document root.

@defthing[images-folder path-string? #:value "images"]

The name of the subfolders within @racket[articles-folder] and @racket[series-folder] used for
holding image files.

@deftogether[(@defproc[(articles-pagetree) pagetree?]
              @defproc[(series-pagetree) pagetree?])]

These are project-wide pagetrees: @racket[articles-pagetree] contains a pagenode for every Pollen
document contained in @racket[articles-folder], and @racket[series-pagetree] contains a pagenode for
every Pollen document in @racket[series-folder]. The pagenodes themselves point to the rendered
@tt{.html} targets of the source documents.

@deftogether[(@defproc[(here-output-path) path?]
              @defproc[(here-source-path) path?])]{

Returns the path to the current output or source file, relative to @racket[current-project-root]. If
no metas are available, returns @racket[(string->path ".")]. 

For the output path, this is similar to the @tt{here} variable that Pollen provides, except it is
available outside templates. As to the source path, Pollen provides it via the @racket['here-path]
key in the current metas, but it is a full absolute path, rather then relative to
@racket[current-project-root].

}

@defproc[(checked-in?) boolean?]{

Returns @racket[#t] if the current article is checked into the Fossil repo, @racket[#f] otherwise.

}

@defproc[(here-id [suffix (or/c (listof string?) string? #f) #f]) string?]

Returns the 8-character prefix of the SHA1 hash of the current document’s output path. If no metas
are available, the hash of @racket[(string->path ".")] is used. If @racket[_suffix] evaluates to
a string or a list of strings, they are appended verbatim to the end of the hash.

This ID is used when creating URL fragment links within an article, such as for footnotes and index
entries. As long as the web version of the article is not moved to a new URL, the ID will remain the
same, which ensures deep links using the ID don’t break. The ID also ensures each article’s internal
links will be unique, so that links do not collide when multiple articles are being shown on
a single HTML page.

@section{Metas and @code{txexpr}s}

@defproc[(maybe-attr [key symbol?] [attrs txexpr-attrs?] [missing-expr any/c ""]) any/c]

Find the value of @racket[_key] in the supplied list of attributes, returning the value of
@racket[_missing-expr] if it’s not there.

I had to write this because @racket[attr-ref] wants a whole tagged X-expression (not just the
attributes); also, by default it raises an exception when @racket[_key] is missing, rather than
returning an empty string.

@defproc[(maybe-meta [key symbolish?] [missing-expr any/c ""]) any/c]

Look up a value in @code{(current-metas)} that may or may not be present, returning the value of
@racket[_missing-expr] if it’s not there.

@defproc[(tx-strs [tx txexpr?]) string?]

Finds all the strings from the @emph{elements} of @racket[_tx] (ignoring attributes) and
concatenates them together.

@examples[#:eval dust-eval
(tx-strs '(p [[class "intro"]] 
             (em "I’m not opening the safe") ", Wilson remembers thinking."))]

@defproc[(make-tag-predicate [sym symbol?] ...) (-> any/c boolean?)]

Returns a function (or @italic{predicate}) that returns @racket[#t] if its argument is
a @racket[_txexpr] whose tag matches any @racket[_sym]. This predicate is useful for passing as the
@racket[_pred] expression in functions @racket[splitf-txexpr] and @racket[findf-txexpr].

@examples[#:eval dust-eval 
(define is-aside? (make-tag-predicate 'aside 'sidebar))

(is-aside? '(q "I am not mad, Sir Topas. I say to you this house is dark."))
(is-aside? '(aside "How smart a lash that speech doth give my Conscience?"))
(is-aside? '(sidebar "Many copies that we use today are conflated texts."))]

@defproc[(first-words [txprs (listof txexpr?)] [n exact-nonnegative-integer?]) string?]

Given a list of tagged X-expressions, returns a string containing the first @racket[_n] words found
in the string elements of @racket[_txprs], or all of the words if there are less than @racket[_n]
words available. Used by @racket[default-title].

This function aims to be smart about punctuation, and equally fast no matter how large the list of
elements that you send it.

@examples[#:eval dust-eval
(define txs-decimals
  '((p "Four score and 7.8 years ago — our fathers etc etc")))
(define txs-punc-and-split-elems
  '((p "“Stop!” she called.") (p "(She was never one to be silent.)")))
(define txs-dashes
  '((p [[class "newthought"]] (span [[class "smallcaps"]] "One - and") " only one.")
    (p "That was all she would allow.")))
(define txs-parens-commas
    '((p "She counted (" (em "one, two") "— silently, eyes unblinking")))
(define txs-short
  '((span "Not much here!")))

(first-words txs-decimals 5)
(first-words txs-punc-and-split-elems 5)
(first-words txs-dashes 5)
(first-words txs-parens-commas 5)
(first-words txs-short 5)
]

@defproc[(normalize [str string?]) string?]{

Removes all non-space/non-alphanumeric characters from @racket[_str], converts it to lowercase, and
replaces all spaces with hyphens.

@examples[#:eval dust-eval
(normalize "Why, Hello World!")
(normalize "My first-ever 99-argument function, haha")
]

}

@section{Article parsers and helpers}

@defparam[listing-context ctxt (or/c 'blog 'feed 'print "") #:value ""]

A parameter specifying the current context where any listings of articles would appear. Its purpose
is to allow articles to exclude themselves from certain special collections (e.g., the blog, the RSS
feed, print editions). Any article whose @code{conceal} meta matches the current context will not be
included in any listings returned by the listing functions in
@seclink["cache-rkt"]{@filepath{cache.rkt}}.

@defproc[(default-title [body-txprs (listof txexpr?)]) string?]

Given a list of tagged X-expressions (the elements of an article’s doc, e.g.), returns a string
containing a suitable title for the document. (Uses @racket[first-words].)

Titles are not required for articles, but there are contexts where you need something that serves as
a title if one is not present, and that’s what this function supplies.

@examples[#:eval dust-eval
(define doc 
  '(root (p "If I had been astonished at first catching a glimpse of so outlandish an "
            "individual as Queequeg circulating among the polite society of a civilized "
            "town, that astonishment soon departed upon taking my first daylight "
            "stroll through the streets of New Bedford…")))
(default-title (get-elements doc))]

@defproc[(current-series-pagenode) pagenode?]

If @code{(current-metas)} has the key @racket['series], converts its value to the pagenode pointing to
that series, otherwise returns @racket['||].

@examples[#:eval dust-eval
(require pollen/core)
(parameterize ([current-metas (hash 'series "marquee-fiction")])
  (current-series-pagenode))]

@defproc[(current-series-noun) string?]

If @code{(current-metas)} has the key @racket['series] and if there is a corresponding
@racket[series] in the @racket[series-list], return its @racket[series-noun-singular] value;
otherwise return @racket[""].

@defproc[(current-series-title) string?]

If @code{(current-metas)} has the key @racket['series] and if there is a corresponding
@racket[series] in the @racket[series-list], return its @racket[series-title] value;
otherwise return @racket[""].

@defproc[(invalidate-series) (or/c void? boolean?)]

If the current article specifies a @racket['series] meta, and if a corresponding @filepath{.poly.pm}
file exists in @racket[series-folder], attempts to “touch” the last-modified timestamp on that file,
returning @racket[#t] on success or @racket[#f] on failure. If either precondition is not true,
returns @|void-const|.

When an article is being rendered, that means the article has changed, and if the article has
changed, its series page (if any) should be updated as well. Touching the @filepath{.poly.pm} file
for a series page triggers a re-render of that page when running @tt{make web} to rebuild the web
content (see @repo-file{makefile}).

Only used in one place, @repo-file{tags-html.rkt}.

@defproc[(disposition-values [str string?]) any]

Given a string @racket[_str], returns two values: the portion of the string coming before the first
space, and the rest of the string.

@examples[#:eval dust-eval
(disposition-values "* thoroughly recanted")]

@defproc[(build-note-id [tx txexpr?]) non-empty-string?]

Given a @code{note} tagged X-expression, returns an identifier string to uniquely identify that note
within an article. This identifier is used as an anchor link in the note’s HTML, and as part of the
note’s primary key in the SQLite cache database.

@examples[#:eval dust-eval
(build-note-id '(note [[date "2018-02-19"]] "This is an example note"))
(build-note-id '(note [[date "2018-03-19"] [author "Dean"]] "Different author!"))
]

@defproc[(notes->last-disposition-values [txprs (listof txexpr?)]) any]

Given a list of tagged X-expressions (ideally a list of @code{note}s), returns two values: the value
of the @racket['disposition] attribute for the last note that contains one, and the ID of that note.

@examples[#:eval dust-eval
(define notelist 
  (list 
    '(note [[date "2018-02-19"] [disposition "* problematic"]] "First note")
    '(note [[date "2018-03-19"]] "Second note")
    '(note [[date "2018-04-19"] [disposition "† recanted"]] "Third note")))

(notes->last-disposition-values notelist)]

@section{Date formatters}

@defproc[(ymd->english [ymd-string string?]) string?]

Converts a date-string of the form @code{"YYYY-MM-DD"} to a string of the form @code{"Monthname D,
YYYY"}. 

If the day number is missing from @racket[_ymd-string], the first day of the month is assumed. If
the month number is also missing, January is asssumed. If the string cannot otherwise be parsed as
a date, an exception is raised.

If any spaces are present in @racket[_ymd-string], everything after the first space is ignored.

@defproc[(ymd->dateformat [ymd_string string?] [dateformat string?]) string?]

Converts a date-string of the form @code{"YYYY-MM-DD"} to another string with the same date
formatted according to @racket[_dateformat]. The
@ext-link["http://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table"]{pattern syntax
of the date format} comes from the Unicode CLDR.

#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"
          racket/runtime-path
          (for-label racket/base
                     "../crystalize.rkt"))

@title{Local Yarn: Source Code Notes}

@author{Joel Dueck}

These are my notes about the internals of the Local Yarn source code. In other words, a personal
reference, rather than a tutorial. 

You’ll get the most out of these notes if you have read @other-doc['(lib
"pollen/scribblings/pollen.scrbl")], and worked through the tutorials there by hand.

@margin-note{Note that these pages are heavily interlinked with the central Racket documentation at
@tt{docs.racket-lang.org}, which are written and maintained by others. 

Some links from those pages will not work unless you @ext-link["#"]{open this page in its own tab}.
}

Here’s a rough diagram showing how the @tt{.rkt} modules in this project relate to each other, and
to the Pollen source documents. This is the least complex system I could devise that would @tt{A)}
implement everything I want in my @secref["design-goals"], @tt{B)} cleanly separate dependencies for
print and web output, and @tt{C)} organize an ever-growing collection of hundreds of individual
notes and articles without noticable loss of speed. 

@(define-runtime-path source-diagram "source-diagram.png")
@centered{@responsive-retina-image[source-diagram]}

The modules are arranged vertically: those on the upper rows provide bindings which are used by
those on the lower rows. The bottom row are the @tt{.poly.pm} files that make up @tech{articles} and
@tech{series}.

Individual articles, while they are being rendered to HTML pages, save copies of their metadata and
HTML to the SQLite cache. This is done by calling @racket[parse-and-cache-article!] from within
their template. 

Any pages that gather content from multiple articles, such as Series pages and the RSS feed, pull
this content directly from the SQLite cache. This is much faster than trawling through Pollen’s
cached metas of every article looking for matching articles.

@local-table-of-contents[]

@include-section["tour.scrbl"]
@include-section["design.scrbl"]
@include-section["pollen.scrbl"]  @; pollen.rkt
@include-section["series.scrbl"]
@include-section["dust.scrbl"]    @; dust.rkt
@include-section["snippets-html.scrbl"] @; you get the idea
@include-section["cache.scrbl"]
@include-section["crystalize.scrbl"]
@include-section["other-files.scrbl"]

#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 racket/base "../cache.rkt"))

@title[#:tag "other-files"]{Other files}

@section{Home page (@filepath{index.html.pp})}

Simple Pollen preprocessor file that generates the home page.

@section{Keyword Index (@filepath{keyword-index.rkt})}

Through its provided @tt{main} function, builds the keyword index page by pulling all the index
entries directly from the SQLite cache and sorting them by first letter.

@section{Blog (@filepath{blog.rkt})}

Through its provided @tt{main} function, creates a paginated listing of all @tech{articles} and
@tech{notes}.

@section{RSS Feed (@filepath{rss-feed.rkt})}

Through its provided @tt{main} function, creates the RSS feed in the file @filepath{feed.xml}. Both
articles and notes are included. Any article or note with either @racket["all"] or @racket["feed"]
in its @racket['conceal] meta is excluded.

@section{Cache initialization (@filepath{util/init.rkt})}

Creates and initializes the cache database with @racket[init-cache-db!] and
@racket[preheat-series!].

@section{New article template (@filepath{util/newpost.rkt})}

Prompts for a title, creates an article with a normalized version of the filename and today’s date,
and opens the article in an editor.

#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
@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?]{

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

@deftogether[(@defproc[(excerpt [elements xexpr?] ...) txexpr?]
              @defproc[(excerpt* [elements xexpr?] ...) txexpr?])]{

Specify an excerpt to be used when the article or note included in an excerpt-style listing (such as
the blog). The contents of @racket[excerpt] will be extracted out of the article and note and only
appear in listings; if @racket[excerpt*] is used, its contents will be left in place in the
article/note and @emph{reused} as the excerpt in listings.

}

@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?]{

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 @racket[caps].
}

@deftogether[(@defproc[(section    [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?]{

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 @racket[(fenced-listing (articles 'short))] to appear inside a @racket[block], but when
using @racket['excerpt] or @racket['full] in place of @racket['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.

}

@deftogether[(@defproc[(link [link-id stringish?] [link-text xexpr?]) txexpr?]
              @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.

}

@defproc*[([(xref [title string?]) txexpr?]
           [(xref [article-base string?] [element xexpr?] ...) txexpr?])]{

Hyperlink to another article within @italic{The Local Yarn} using an @racket[_article-base], which
is the base filename only of an @tech{article} within @racket[articles-folder] (without the
@filepath{.poly.pm} extension).

If a single argument is supplied (@racket[_title]) it is typeset italicized as the link text, and
its @racket[normalize]d 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.

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

}

@deftogether[(@defproc[(figure     [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?]{

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?])]{

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?])]{

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?]{

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. 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 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!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?]{

Add a @tech{note} to the “Further Notes” section of the article. 

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.

The @code{#:disposition} attribute is used for notes that update or alter the whole disposition of
the article. It must be a string of the form @racket[_mark _past-tense-verb], where @racket[_mark]
is a symbol suitable for use as a marker, such as * or †, and @racket[_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”.

@codeblock|{
#lang pollen

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


If more than one note contains a @code{disposition} attribute, the one from the most recent note is
the one 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?]{

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.

To cite a source, use @racket[attrib] immediately afterward.

}

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

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

}

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

Surrounds a block quotation. To cite a source, use @racket[attrib] immediately afterward.

}

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

An attribution line, for citing a source for a block quotation, epigraph or poem.

}

@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[(mono   [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?])]{

Work pretty much how you’d expect.

}

@section{Convenience macros}

@defform[(for/s thing-id listofthings result-exprs ...)
         #: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.

}

#lang racket/base

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

;; Convenience/helper functions for this project’s Scribble documentation

(require scribble/core
         scribble/manual/lang
         scribble/html-properties
         scribble/private/manual-sprop
         scribble/decode
         racket/runtime-path
         (only-in net/uri-codec uri-encode))
(provide (all-defined-out))

(define-runtime-path custom-css "custom.css")

(define repo-url/ "https://thelocalyarn.com/code/")

;; Link to a ticket on the Fossil repository by specifying the ticket ID.
;; The "_parent" target breaks out of the iframe used by the Fossil repo web UI.
(define (ticket id-str)
  (hyperlink (string-append repo-url/ "tktview?name=" id-str)
             "ticket "
             (tt id-str)
             #:style (style #f (list (attributes '((target . "_parent")))))))

;; Link to a wiki page on the Fossil repository by specifying the title
(define (wiki title)
  (hyperlink (string-append repo-url/ "wiki?name=" (uri-encode title))
             title
             #:style (style #f (list (attributes '((target . "_parent")))))))

;; Link somewhere outside these docs or Racket docs. The `_blank` target opens in a new tab.
(define (ext-link url-str . elems)
  (keyword-apply hyperlink '(#:style) (list (style #f (list (attributes '((target . "_blank")))))) 
                 url-str
                 elems))

;; Link to show contents of the latest checked-in version of a file
;; (or a file listing if a directory was specified)
(define (repo-file filename)
  (hyperlink (string-append repo-url/ "file/" filename)
             (tt filename)
             #:style (style #f (list (attributes '((target . "_parent")))))))

(define (responsive-retina-image img-path)
  (image img-path 
         #:scale 0.5
         #:style (style #f (list (attributes '((style . "max-width:100%;height:auto;")))))))

;;
;; From https://github.com/mbutterick/pollen/blob/master/pollen/scribblings/mb-tools.rkt
;;

(define (terminal . args)
  (compound-paragraph (style "terminal" (list (css-style-addition custom-css) (alt-tag "div")))
                      (list (apply verbatim args))))

(define (cmd . args)
  (elem #:style (style #f (list (color-property "black"))) (tt args)))

(define (fileblock filename . inside)
  (compound-paragraph 
   (style "fileblock" (list* (alt-tag "div") 'multicommand
                             (box-mode "RfileboxBoxT" "RfileboxBoxC" "RfileboxBoxB") 
                             scheme-properties))
   (list
    (paragraph (style "fileblock_filetitle" (list* (alt-tag "div") (box-mode* "RfiletitleBox") scheme-properties))
               (list (make-element
                      (style "fileblock_filename" (list (css-style-addition custom-css)))
                      (if (string? filename)
                          (filepath filename)
                          filename))))
    (compound-paragraph 
     (style "fileblock_filecontent" (list* (alt-tag "div") (box-mode* "RfilecontentBox") scheme-properties))
     (decode-flow inside)))))

<div class='fossil-doc' data-title='Code Documentation' >
<!-- SPDX-License-Identifier: BlueOak-1.0.0
     This file is licensed under the Blue Oak Model License 1.0.0.
-->
    <div class='iframe-surround'>
        <iframe id='scribble' src="index.html" class="embedded-docs">
        </iframe>
    </div>
</div>

    <script>
        document.getElementById('scribble').src = "index.html?n=" + new Date()/1;
    </script>

#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"
          scribble/example)

@(require (for-label "../pollen.rkt"
                     "../series-list.rkt"
                     "../dust.rkt"
                     "../cache.rkt"
                     pollen/core
                     racket/base
                     racket/contract))

@title{Defining Series}

To create a new series:

@itemlist[#:style 'ordered

  @item{Create a file @filepath{my-key.poly.pm} inside @racket[series-folder] and include a call
  to @racket[fenced-listing] to list all the articles and notes that will be included in the series:
  @codeblock|{
#lang pollen

◊(define-meta title "My New Series")

◊block{Here’s what we call a bunch of similar articles:

◊(fenced-listing (articles 'short))

}
  }|
  }
  
  @item{Add an entry for @racket[_my-key] to @racket[series-list] in @filepath{series-list.rkt}}

  @item{Use @racket[(define-meta series "my-key")] in articles to add them to the series.}

  @item{If @racket[series-ptree-ordered?] is @racket[#t], create a @seclink["Pagetree" #:doc '(lib
  "pollen/scribblings/pollen.scrbl")]{pagetree} file in @racket[series-folder] named
  @filepath{my-key.ptree}.}

  ]

@section{Series list}

@defmodule["series-list.rkt" #:packages ()]

This module contains the most commonly used bits of meta-info about @tech{series}. Storing these
bits in a hash table of structs makes them faster to retrieve than when they are stored inside the
metas of the Pollen documents for the series themselves.

@defthing[series-list hash?]{

An immutable hash containing all the title and noun info for each @tech{series}. Each key is
a string and each value is a @racket[series] struct.

}

@defstruct[series ([key            string?]
                   [title          string?]
                   [noun-plural    string?]
                   [noun-singular  string?]
                   [ptree-ordered? boolean?])]{

Struct for holding metadata for a @tech{series}. The @racket[_ptree-ordered?] value should be
@racket[#t] if there is a @filepath{@italic{key}.ptree} file in @racket[series-folder] that provides
information on how articles in the series are ordered.

}

#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"
                     "../snippets-html.rkt"
                     racket/base
                     racket/contract
                     racket/string
                     pollen/template
                     pollen/pagetree
                     txexpr
                     sugar/coerce))

@title{HTML snippets}

@defmodule["snippets-html.rkt" #:packages ()]

Each “snippet” module provides all (well @emph{most of}) the document- and article-level blocks of
structural markup necessary for a particular target output format; this one is for HTML. The idea is
that any block of markup that might be reused across more than one template should be a function.

The functions in the snippets modules follow two conventions in this project:

@itemlist[
  @item{Functions that return strings of HTML have the prefix @tt{html$-}.}
  @item{Such functions do not do any parsing or destructuring of complex objects; every separate
  piece that will be inserted into the template is passed in as a separate argument. This makes it
  harder to change the scope of what a snippet does, but makes things faster since all the parsing
  can happen in one place, before the snippet functions are called.} ]

@section{Using @tt{pollen/mode}}

It’s worth looking at the source for this file to see how @racketmodname[pollen/mode] can be used to
make it easy to write “mini-template” functions:

@codeblock{
#lang pollen/mode racket/base

(define (html$-my-article title body-tx)
  ◊string-append{
    <p><b>◊|title|</b><p>
    ◊(->html body-tx)
  })
}

@section{HTML Snippet functions}

@defproc[(html$-page-head [title (or/c string? #f) #f] [close-head? boolean? #t])
non-empty-string?]{

Returns the @tt{<head>} section of an HTML document.

If @racket[_title] is a string it will be used inside the @tt{<title>} tag.

If you want to include additional stuff inside the @tt{<head>}, you can set @racket[_close-head?] to
@racket[#f] to prevent it from including the closing @tt{</head>} tag (you’ll have to add it
yourself).
}

@defproc[(html$-page-body-open [body-class string? ""]) non-empty-string?]{

Returns the opening @tt{<body>} and @tt{<main>} tags and elements that immediately follow, such as
site header, logo and navigation.

If @racket[_body-class] is a non-empty string, its contents will be included in the @tt{class}
attribute of the @tt{<body>} tag.
}

@defproc[(html$-series-list) non-empty-string?]{

Returns an HTML @tt{<section>} containing a list of all series, grouped by their “plural nouns”. The
grouped list will flow into columns on wider displays.
}

@defproc[(html$-article-open [pagenode pagenode?] 
                             [title-specified-in-doc? boolean?] 
                             [title txexpr?] 
                             [pubdate string?])
          non-empty-string?]{

Returns the opening @tt{<article>} tag and elements that immediately follow: permlink, publish date,
and opening @tt{<section>} tag.

The @racket[_title-specified-in-doc?] form changes the HTML markup structure used.
}

@defproc[(html$-article-close [footertext string?]) non-empty-string?]{

Returns a string containing a closing @tt{<section>} tag, a @tt{<footer>} element containing
@racket[_footertext], and a closing @tt{<article>} tag. If @racket[_footertext] is empty, the
@tt{<footer>} element will be omitted.
}

@defproc[(html$-article-listing-short [pagenode pagenode?] [pubdate string?] [title string?])
non-empty-string?]{

Returns a string of HTML for an article as it would appear in a listing context in “short” form
(date and title only, with link).
}

@defproc[(html$-page-footer) non-empty-string?]{
Returns an HTML @tt{<footer>} tag for use at the bottom of each page.
}

@defproc[(html$-page-body-close) non-empty-string?]{

Returns a string containing the page’s @tt{<footer>} and closing tags.
}

@defproc[(html$-note-contents [disposition-mark string?] [elems (listof xexpr?)])
non-empty-string?]{

Returns a string containing the body-elements of a note converted to HTML. If
@racket[_disposition-mark] is not empty, a @tt{<span>} containing it will be inserted as the first
element of the first block-level element.
}

@defproc[(html$-note-listing-full [pagenode pagenode?]
                                  [note-id string?] 
                                  [title-html-flow string?]
                                  [date string?]
                                  [contents string?] 
                                  [author string? (default-authorname)] 
                                  [author-url string? ""])
          non-empty-string?]{

Returns a string containing the complete HTML markup for a @racket[note], including title, permlink,
date, contents and author, suitable for display outside the context of its parent article.
}

@defproc[(html$-note-in-article [id string?] 
                                [date string?] 
                                [contents string?] 
                                [author string?]
                                [author-url string?]) non-empty-string?]{

Like @racket[html$-note-listing-full], but returns HTML for a @racket[note] suitable for display
inside its parent article.
}

@defproc[(html$-notes-section [note-htmls string?]) non-empty-string?]{

Returns the complete HTML for the @italic{Further Notes} section of an article.
}

@defproc[(html$-paginate-navlinks [current-page exact-positive-integer?] 
                                  [pagecount exact-positive-integer?]
                                  [basename string?]) string?]{

On the “blog”, the articles are split across multiple files: @filepath{blog-pg1.html},
@filepath{blog-pg2.html}, etc. This function provides a string containing HTML for a group of links
that can be given within each file, to link to the pages that come before/after it. 

The links are enclosed within @tt{<li>} tags. It’s up to the calling site to provide the enclosing
@tt{<ul>} tag (in case any custom styling or IDs need to be applied).
}

#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 racket/base pollen/core "../pollen.rkt"))

@title{How I Publish: A Quick Tour}

This isn’t a tutorial, since these steps probably won’t all work on your computer. Think of these
narrations like me talking while I drive.

@section{Creating an article}

Open a terminal window.

@terminal{@cmd{> cd /path/to/thelocalyarn}}

The @tt{make} command provides a high-level control panel for common tasks. Typing just make from
a terminal window shows a list of options:

@terminal{
@cmd{> make}
article     Start a new article from a template
help        Displays this help screen
publish     Sync all HTML and PDF stuff to the public web server
scribble    Rebuild code documentation and update Fossil repo
web         Rebuild all web content (not PDFs)
zap         Clear Pollen and Scribble cache, and remove all HTML output
}

Following the first option in this list, I type @tt{make article}, and enter a post title when
prompted:

@terminal{
@cmd{> make article}
racket -tm util/newpost.rkt
Enter title: @cmd{My New Post}
}

The script creates a new @filepath{.poly.pm} file using a normalized version of the title for the
filename, and opens it in my editor (this is currently hardcoded to use MacVim). When the file pops
up we see a basic template ready to edit:

@filebox["articles/my-new-post.poly.pm"
@codeblock|{
#lang pollen
 
◊; Copyright 2020 by Joel Dueck. All Rights Reserved.
◊(define-meta conceal "blog,rss")
◊(define-meta published "2020-01-18")
 
◊title{My New Post}
 
Write here!
}|]

At this point I might delete the @tt{◊title} line, since specifying a formal title is optional
(other than the one needed to generate the filename). I might also add a @racket[define-meta] for
@tt{series} or @tt{topics}. 

As long as the @racket[define-meta] for @tt{conceal} contains @racket{rss}, the new article will not
appear in the RSS feed; as long as it contains @racket{blog} it will not appear in the blog. This is
useful for when an article is in a draft state, or simply when you want to keep it semi-hidden.

When satisfied with the post I’ll remove the @racket[define-meta] for @tt{conceal}, save it one last
time, then go back to the terminal:

@terminal{
@cmd{> make web}
[lots of output: rebuilds blog pages, keyword index, RSS feed]
@cmd{> make publish}
[lots of output: uploads all web content to the server]
}

The article also needs to be added to the Fossil repository, so revisions to it will be tracked:

@terminal|{
|@cmd{> fossil add article/my-new-post.poly.pm}
ADDED  article/my-new-post.poly.pm

|@cmd{> fossil commit -m "Publish ‘My New Post’"}
Autosync:  https://joel@thelocalyarn.com/code
Round-trips: 2   Artifacts sent: 0  received: 1
Pull done, sent: 892  received: 8720  ip: 162.243.186.132
New_Version: 15507b62416716a3f0be3c444b0fc09aa4364b989140c5788cf679eb0b2463a6
Autosync:  https://joel@thelocalyarn.com/code
Round-trips: 2   Artifacts sent: 2  received: 1
Sync done, sent: 10153  received: 4680  ip: 162.243.186.132
}|

As you can see, Fossil does an automatic pull before the commit, and another automatic push
afterwards. This commit is now visible on the public timeline, and the source code for the article
can now be seen on the public repo at @tt{thelocalyarn.com/code/}.

@section{Adding notes to an article}

A few days (or years) after doing the above, I receive an email from Marjorie with commenting on
@italic{My New Post} and I decide to publish her comments.

I open the article in my editor and add some lines to the end:

@filebox["articles/my-new-post.poly.pm"
@codeblock|{
#lang pollen
 
◊; Copyright 2020 by Joel Dueck. All Rights Reserved.
◊(define-meta published "2020-01-18")
 
◊title{My New Post}
 
It’s a 4⨉4 treated. I got twenty, actually, for the backyard fence.

◊note[#:date "2020-01-23" #:author "Marjorie"]{
 Hope you sank that thing below the frost line.
}
}|]

This looks like a blog-style comment, but the @racket[note] tag function has some special powers
that typical comments don’t have, as we’ll see in a moment.

I save this, go back to the terminal and do @tt{make web} and @tt{make publish} as before.

Now if you open the article’s permlink, you’ll see the note appears in a “Further Notes” section at
the bottom — again, just like a normal blog post comment.

But if you go to the Blog section, you’ll see the note appearing in its own space right alongside
the other articles, as if it were a separate post. It will also appear in a separate entry in the
RSS feed.

@section{What’s not here yet}

Eventually there will be facilities for creating PDF files of individual articles, and print-ready
PDFs of books containing collections of articles. 

#lang racket/base

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

(require deta
         db/base
         threading
         racket/match
         racket/string
         txexpr
         pollen/template
         pollen/decode
         (except-in pollen/core select) ; avoid conflict with deta
         )

(require "dust.rkt" "cache.rkt" "snippets-html.rkt")

(provide parse-and-cache-article!
         cache-index-entries-only!)

(define current-title       (make-parameter #f))
(define current-excerpt     (make-parameter #f))
(define current-notes       (make-parameter '()))
(define current-disposition (make-parameter ""))
(define current-disp-id     (make-parameter ""))

(define (filter-special-tags tx)
  (match (get-tag tx)
    ['title (current-title tx) ""]
    ['excerpt (current-excerpt tx) ""]
    ['excerpt* (current-excerpt tx) `(@ ,@(get-elements tx))] ; splice contents back in
    ['note
     (define note-id (build-note-id tx))
     (cond [(attrs-have-key? tx 'disposition)
            (current-disp-id note-id)
            (current-disposition (attr-ref tx 'disposition))])
     (current-notes (cons (attr-set tx 'note-id note-id) (current-notes))) ""]
    [_ tx]))

;; Save an article and its notes (if any) to the database, and return 
;; (values plain-title [rendered HTML of the complete article])
(define (parse-and-cache-article! pagenode doc)
  (define body-txpr (decode doc #:txexpr-proc filter-special-tags))
  (current-notes (reverse (current-notes)))
  (let* ([pubdate (select-from-metas 'published (current-metas))]
         [doc-html    (->html body-txpr #:splice? #t)]
         [title-specified? (if (current-title) #t #f)]
         [title-val   (or (current-title) (check-for-poem-title doc))]
         [title-tx    (make-article-title pagenode
                                          title-val
                                          body-txpr
                                          (current-disposition)
                                          (current-disp-id))]
         [title-html  (->html title-tx #:splice? #t)]
         [title-plain (tx-strs title-tx)]
         [header      (html$-article-open pagenode title-specified? title-tx pubdate)]
         [series-node (current-series-pagenode)]
         [footertext  (make-article-footertext pagenode
                                               series-node
                                               (current-disposition)
                                               (current-disp-id)
                                               (length (current-notes)))]
         [footer (html$-article-close footertext)]
         [listing-short (html$-article-listing-short pagenode pubdate title-html)]
         [listing-full (string-append header doc-html footer)]
         [listing-excerpt (match (current-excerpt)
                            [#f listing-full]
                            [(var e) (string-append header (html$-article-excerpt pagenode e) footer)])]
         [notes (extract-notes pagenode title-plain (current-notes))]
         [notes-section-html (html$-notes-section (map cadr notes))])
    (thread
     (lambda ()
       (call-with-transaction
        (cache-conn)
        (lambda ()
          (cache-index-entries! pagenode doc) ; note original doc is used here
          (query-exec (cache-conn)
                      (delete (~> (from cache:note #:as n)
                                  (where (= n.page ,(symbol->string pagenode))))))
          (apply insert! (cache-conn) (map car notes))
          (delete-article! pagenode)
          (insert-one! (cache-conn)
                       (make-cache:article
                        #:page pagenode
                        #:title-plain title-plain
                        #:title-html-flow title-html
                        #:title-specified? title-specified?
                        #:published pubdate
                        #:updated (maybe-meta 'updated)
                        #:author (maybe-meta 'author default-authorname)
                        #:conceal (maybe-meta 'conceal)
                        #:series-page series-node
                        #:noun-singular (maybe-meta 'noun (current-series-noun))
                        #:note-count (length (current-notes))
                        #:content-html doc-html
                        #:disposition (current-disposition)
                        #:disp-html-anchor (current-disp-id)
                        #:listing-full-html listing-full
                        #:listing-excerpt-html listing-excerpt
                        #:listing-short-html listing-short))))))
    (values title-plain (string-append header doc-html notes-section-html footer))))

(define (check-for-poem-title doc-txpr)
  (match (car (get-elements doc-txpr))
    [(txexpr 'div
             (list (list 'class "poem"))
             (list* (txexpr 'p
                            (list (list 'class "verse-heading"))
                            heading-elems)
                    _))
     `(title (span [[class "smallcaps"]] "‘" ,@heading-elems "’"))]
    [_ '()]))

;; Return a title txexpr for the current article, constructing a default if no title text was specified.
(define (make-article-title pagenode supplied-title body-tx disposition disp-note-id)
  (define title-elems
    (cond [(null? supplied-title) (list (default-title (get-elements body-tx)))]
          [else (get-elements supplied-title)]))
  
  (define disposition-part
    (cond [(non-empty-string? disposition)
           (define-values (mark _) (disposition-values disposition))
           `(a [[class "disposition-mark"] 
                [href ,(format "~a~a#~a" web-root pagenode disp-note-id)]] 
               ,mark)]
          [else ""]))
  ;; Returns a txexpr, the tag will be discarded by the template/snippets
  `(title ,@title-elems ,disposition-part))

;; Convert a bunch of information about an article into some nice English and links.
(define (make-article-footertext pagenode series disposition disp-note-id note-count)
  (define series-part
    (match (current-series-title)
      [(? non-empty-string? s-title)
       (format "<span class=\"series-part\">This is ~a, part of <a href=\"/~a\">‘~a’</a>.</span>"
               (current-series-noun)
               series
               s-title)]
      [_ ""]))
  (define disp-part
    (cond [(non-empty-string? disposition)
           (define-values (mark verb) (disposition-values disposition))
           (format "Now considered <a href=\"/~a#~a\">~a</a>."
                   pagenode
                   disp-note-id
                   verb)]
          [else ""]))
  (define notes-part
    (cond [(note-count . > . 1)
           (format "There are <a href=\"/~a#furthernotes\">~a notes</a> appended."
                   pagenode
                   note-count)]
          [(and (note-count . > . 0) (string=? disposition ""))
           (format "There is <a href=\"/~a#furthernotes\">a note</a> appended."
                   pagenode)]
          [else ""]))
  
  (cond [(ormap non-empty-string? (list series-part disp-part notes-part))
         (string-join (list series-part disp-part notes-part))]
        [else ""]))

;; ~~~ Notes ~~~

(define (extract-notes pagenode parent-title note-txprs)
  (for/list ([n (in-list note-txprs)])
    (make-note n pagenode parent-title)))

;; Save an individual note to the DB and return the HTML of the complete note as
;; it should appear on an individual article page
(define (make-note note-tx pagenode parent-title-plain)
  (define-values (_ attrs elems) (txexpr->values note-tx))
  (define disposition-attr (maybe-attr 'disposition attrs))
  (define note-date (maybe-attr 'date attrs))
  
  ;; Check required attributes
  (unless (non-empty-string? note-date)
    (raise-arguments-error 'note "required attr missing: date" "attrs" attrs))
  (unless (or (string=? "" disposition-attr)
              (>= (length (string-split disposition-attr)) 2))
    (raise-arguments-error 'note
                           "must be in format \"[symbol] [past-tense-verb]\""
                           "disposition attr"
                           disposition-attr))
  (define-values (disp-mark disp-verb) (disposition-values disposition-attr))
  (let* ([note-id (build-note-id note-tx)]
         [title-tx (make-note-title pagenode parent-title-plain)]
         [title-html (->html title-tx #:splice? #t)]
         [author (maybe-attr 'author attrs default-authorname)]
         [author-url (maybe-attr 'author-url attrs)]
         [note-srcline (maybe-attr 'srcline attrs)]
         [content-html (html$-note-contents disp-mark disp-verb elems)]
         [listing-full (html$-note-listing-full pagenode
                                                note-id
                                                title-html
                                                note-date
                                                note-srcline
                                                content-html
                                                author
                                                author-url)])
    (list
     (make-cache:note
      #:page pagenode
      #:html-anchor note-id
      #:title-html-flow title-html
      #:title-plain (tx-strs title-tx)
      #:published note-date
      #:author author
      #:author-url author-url
      #:disposition disposition-attr
      #:series-page (current-series-pagenode)
      #:conceal (or (maybe-attr 'conceal attrs #f) (maybe-meta 'conceal))
      #:content-html content-html
      #:listing-full-html listing-full
      #:listing-excerpt-html listing-full
      #:listing-short-html "")
     (html$-note-in-article note-id note-date content-html author author-url))))

(define (make-note-title pagenode parent-title-plain)
  `(note-title "Re: " (a [[class "cross-reference"]
                          [href ,(format "~a~a" web-root pagenode)]]
                         ,parent-title-plain)))

;; ~~~ Keyword Index Entries ~~~

;; (private) Convert an entry key into a list of at most two elements,
;; a main entry and a sub-entry.
;;   "entry" → '("entry" "")
;;   "entry!sub" → '("entry" "sub")
;;   "entry!sub!why?!? '("entry" "sub")
(define (split-entry str)
  (define splits (string-split str "!"))
  (list (car splits)
        (cadr (append splits (list "")))))

(define (index-entry-txpr? tx)
  (and (txexpr? tx)
       (string=? "index-link" (attr-ref tx 'class "")) ; see definition of html-index
       (attr-ref tx 'data-index-entry #f)))

(define (txexpr->index-entry tx pagenode)
  (match (split-entry (attr-ref tx 'data-index-entry))
    [(list main sub)
     (make-cache:index-entry
      #:entry main
      #:subentry sub
      #:page pagenode
      #:html-anchor (attr-ref tx 'id))]))

;; Get index entries out of metas
(define (current-metas-keyword-entries pagenode)
  (for/list ([kw (in-list (string-split (maybe-meta 'keywords "") #px";\\s*"))])
    (match (split-entry kw)
      [(list main sub)
       (make-cache:index-entry
        #:entry main
        #:subentry sub
        #:page pagenode
        #:html-anchor "")])))

;; Save any index entries in doc to the SQLite cache.
;; Sub-entries are specified by "!" in the index key
(define (cache-index-entries! pagenode doc)
  (define-values (_ entry-txs) (splitf-txexpr doc index-entry-txpr?))
  (define all-entries
    (append (for/list ([etx (in-list entry-txs)]) (txexpr->index-entry etx pagenode))
            (current-metas-keyword-entries pagenode)))
  
  (delete-index-entries! pagenode)
  (save-cache-things! all-entries))

(define (cache-index-entries-only! title pagenode doc)
  (void
   (thread
    (lambda ()
      (call-with-transaction
       (cache-conn)
       (lambda ()
         (cache-index-entries! pagenode doc)
         (delete-article! pagenode)
         (insert-one! (cache-conn)
                       (make-cache:article
                        #:title-plain title
                        #:conceal "blog,feed"
                        #:page pagenode))))))))

#lang racket/base

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

;; Functions for tags and template content used in all Pollen source files and templates.

(require (for-syntax "targets.rkt"
                     racket/base
                     racket/syntax
                     syntax/parse))

(require pollen/tag
         pollen/setup
         "cache.rkt"
         "tags-html.rkt"
         "snippets-html.rkt"
         "crystalize.rkt")

(provide (all-defined-out)
         (all-from-out "crystalize.rkt" "snippets-html.rkt" "cache.rkt"))

(module setup racket/base
  (require "targets.rkt"
           syntax/modresolve
           racket/runtime-path
           pollen/setup)
  (provide (all-defined-out))
  (define poly-targets targets)
  (define allow-unbound-ids? #f)
  
  (define block-tags (append '(title style dt note) default-block-tags))

  (define-runtime-path tags-html.rkt     "tags-html.rkt")
  (define-runtime-path snippets-html.rkt "snippets-html.rkt")
  (define-runtime-path dust.rkt          "dust.rkt")
  (define-runtime-path crystalize.rkt    "crystalize.rkt")
  (define-runtime-path cache.rkt         "cache.rkt")
  (define-runtime-path series-list.rkt   "series-list.rkt")
  (define cache-watchlist
    (map resolve-module-path
         (list tags-html.rkt
               snippets-html.rkt
               dust.rkt
               cache.rkt
               series-list.rkt
               crystalize.rkt))))

;; Macro for defining tag functions that automatically branch based on the 
;; current output format and the list of poly-targets in the setup module.
;; Use this macro when you know you will need keyword arguments.
;;
(define-syntax (poly-branch-kwargs-tag stx)
  (syntax-parse stx
    [(_ TAG:id)
     (with-syntax ([((POLY-TARGET POLY-FUNC) ...) 
                    (for/list ([target (in-list targets)])
                              (list target (format-id stx "~a-~a" target #'TAG)))]
                   [DEFAULT-FUNC (format-id stx "html-~a" #'TAG)])
       #'(define-tag-function (TAG attributes elems)
           (case (current-poly-target)
             [(POLY-TARGET) (POLY-FUNC attributes elems)] ... 
             [else (DEFAULT-FUNC attributes elems)])))]))

;; Like above, but uses `define` instead of `define-tag-function`.
;; Use this when you know you will not need keyword arguments.
;;
(define-syntax (poly-branch-tag stx)
  (syntax-parse stx
    [(_ TAG:id)
     (with-syntax ([((POLY-TARGET POLY-FUNC) ...) 
                    (for/list ([target (in-list targets)])
                              (list target (format-id stx "~a-~a" target #'TAG)))]
                   [DEFAULT-FUNC (format-id stx "html-~a" #'TAG)])
       #'(define (TAG . args)
           (case (current-poly-target)
             [(POLY-TARGET) (apply POLY-FUNC args)] ...
             [else (apply DEFAULT-FUNC args)])))]))

;; Define all the tag functions
(poly-branch-tag root)
(poly-branch-tag title)
(poly-branch-tag excerpt)
(poly-branch-tag excerpt*)
    
(poly-branch-tag p)
(poly-branch-tag i)
(poly-branch-tag em)
(poly-branch-tag b)
(poly-branch-tag mono)
(poly-branch-tag strong)
(poly-branch-tag strike)
;(poly-branch-tag color)
(poly-branch-tag ol)
(poly-branch-tag ul)
(poly-branch-tag item)
(define li item) ; useful alias :-P
(poly-branch-tag sup)
(poly-branch-tag blockquote)
(poly-branch-tag newthought)
(poly-branch-tag sep)
(poly-branch-tag caps)
(poly-branch-tag center)
(poly-branch-tag section)
(poly-branch-tag subsection)
(poly-branch-tag code)
(poly-branch-tag dialogue)
(poly-branch-tag say)
(poly-branch-tag saylines)
(poly-branch-tag magick)  ; Extra-fancy ligatures, “long s”
(poly-branch-kwargs-tag index)
(poly-branch-tag figure)
(poly-branch-tag figure-@2x)
(poly-branch-tag image-link)
(poly-branch-kwargs-tag blockcode)
(poly-branch-kwargs-tag verse)          ; [#:title ""] [#:italic "no"]
(poly-branch-tag attrib)

(poly-branch-tag link)
(poly-branch-tag url)
(poly-branch-tag xref)
(poly-branch-tag fn)
(poly-branch-tag fndef)

(poly-branch-kwargs-tag note-with-srcline)
(poly-branch-tag block)

;; Not yet implemented
; (poly-branch-tag table)         ; #:columns ""
; (poly-branch-tag inline-math)
; (poly-branch-tag margin-note)
; (poly-branch-tag noun)
; (poly-branch-func index-entry entry)
; (poly-branch-tag spot-illustration) ; #:src "img--sans-path.png" [#:has-print-version? "yes"]

(define-syntax (note stx)
  (syntax-parse stx
    [(_ args ...)
     (with-syntax ([srcline (number->string (syntax-line stx))])
       #'(note-with-srcline #:srcline srcline args ...))]))

;; My pet shortcut for for/splice. Greatly cuts down on parentheses for the
;; most common use case (looping through a single list).
(define-syntax (for/s stx)
  (syntax-case stx ()
    [(_ thing listofthings result-expr ...)
     #'(for/splice ([thing (in-list listofthings)]) result-expr ...)]))

#lang racket/base

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

;; Functions for tags and template content used in all Pollen source files and templates.

(require (for-syntax "targets.rkt"
                     racket/base
                     racket/syntax
                     syntax/parse))

(require pollen/tag
(require yarn/markup)
         pollen/setup
         "cache.rkt"
         "tags-html.rkt"
         "snippets-html.rkt"
         "crystalize.rkt")

(provide (all-defined-out)
(provide
         (all-from-out "crystalize.rkt" "snippets-html.rkt" "cache.rkt"))

(module setup racket/base
  (require "targets.rkt"
           syntax/modresolve
           racket/runtime-path
           pollen/setup)
  (provide (all-defined-out))
 (all-defined-out)
  (define poly-targets targets)
  (define allow-unbound-ids? #f)
  
 (all-from-out yarn/markup))
  (define block-tags (append '(title style dt note) default-block-tags))

  (define-runtime-path tags-html.rkt     "tags-html.rkt")
  (define-runtime-path snippets-html.rkt "snippets-html.rkt")
  (define-runtime-path dust.rkt          "dust.rkt")
  (define-runtime-path crystalize.rkt    "crystalize.rkt")
  (define-runtime-path cache.rkt         "cache.rkt")
  (define-runtime-path series-list.rkt   "series-list.rkt")
  (define cache-watchlist
    (map resolve-module-path
         (list tags-html.rkt
               snippets-html.rkt
               dust.rkt
               cache.rkt
               series-list.rkt
               crystalize.rkt))))

;; Macro for defining tag functions that automatically branch based on the 
;; current output format and the list of poly-targets in the setup module.
;; Use this macro when you know you will need keyword arguments.
;;
(define-syntax (poly-branch-kwargs-tag stx)
  (syntax-parse stx
    [(_ TAG:id)
     (with-syntax ([((POLY-TARGET POLY-FUNC) ...) 
                    (for/list ([target (in-list targets)])
                              (list target (format-id stx "~a-~a" target #'TAG)))]
                   [DEFAULT-FUNC (format-id stx "html-~a" #'TAG)])
       #'(define-tag-function (TAG attributes elems)
           (case (current-poly-target)
             [(POLY-TARGET) (POLY-FUNC attributes elems)] ... 
             [else (DEFAULT-FUNC attributes elems)])))]))

;; Like above, but uses `define` instead of `define-tag-function`.
;; Use this when you know you will not need keyword arguments.
;;
(define-syntax (poly-branch-tag stx)
  (syntax-parse stx
    [(_ TAG:id)
     (with-syntax ([((POLY-TARGET POLY-FUNC) ...) 
                    (for/list ([target (in-list targets)])
                              (list target (format-id stx "~a-~a" target #'TAG)))]
                   [DEFAULT-FUNC (format-id stx "html-~a" #'TAG)])
       #'(define (TAG . args)
           (case (current-poly-target)
             [(POLY-TARGET) (apply POLY-FUNC args)] ...
             [else (apply DEFAULT-FUNC args)])))]))

;; Define all the tag functions
(poly-branch-tag root)
(poly-branch-tag title)
(poly-branch-tag excerpt)
(poly-branch-tag excerpt*)
    
(module+ setup
(poly-branch-tag p)
(poly-branch-tag i)
(poly-branch-tag em)
(poly-branch-tag b)
(poly-branch-tag mono)
(poly-branch-tag strong)
(poly-branch-tag strike)
;(poly-branch-tag color)
(poly-branch-tag ol)
(poly-branch-tag ul)
(poly-branch-tag item)
(define li item) ; useful alias :-P
(poly-branch-tag sup)
(poly-branch-tag blockquote)
(poly-branch-tag newthought)
(poly-branch-tag sep)
(poly-branch-tag caps)
(poly-branch-tag center)
(poly-branch-tag section)
(poly-branch-tag subsection)
(poly-branch-tag code)
(poly-branch-tag dialogue)
(poly-branch-tag say)
(poly-branch-tag saylines)
(poly-branch-tag magick)  ; Extra-fancy ligatures, “long s”
(poly-branch-kwargs-tag index)
(poly-branch-tag figure)
(poly-branch-tag figure-@2x)
(poly-branch-tag image-link)
(poly-branch-kwargs-tag blockcode)
(poly-branch-kwargs-tag verse)          ; [#:title ""] [#:italic "no"]
(poly-branch-tag attrib)

  (provide block-tags)
(poly-branch-tag link)
(poly-branch-tag url)
(poly-branch-tag xref)
(poly-branch-tag fn)
(poly-branch-tag fndef)

  (define block-tags blocks-elements))
(poly-branch-kwargs-tag note-with-srcline)
(poly-branch-tag block)

;; Not yet implemented
; (poly-branch-tag table)         ; #:columns ""
; (poly-branch-tag inline-math)
; (poly-branch-tag margin-note)
; (poly-branch-tag noun)
; (poly-branch-func index-entry entry)
; (poly-branch-tag spot-illustration) ; #:src "img--sans-path.png" [#:has-print-version? "yes"]

(define-syntax (note stx)
  (syntax-parse stx
    [(_ args ...)
     (with-syntax ([srcline (number->string (syntax-line stx))])
       #'(note-with-srcline #:srcline srcline args ...))]))

;; My pet shortcut for for/splice. Greatly cuts down on parentheses for the
;; most common use case (looping through a single list).
(define-syntax (for/s stx)
  (syntax-case stx ()
    [(_ thing listofthings result-expr ...)
     #'(for/splice ([thing (in-list listofthings)]) result-expr ...)]))

#lang racket/base

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

;; Generates an Atom feed from the SQLite cache

(require txexpr
         deta
         racket/match
         racket/file
         racket/date
         racket/string
         racket/sequence
         "dust.rkt"
         "cache.rkt")

(provide main)

(define feed-author default-authorname)
(define feed-author-email "joel@jdueck.net")
(define feed-title "The Local Yarn (Beta)")
(define feed-site-url "https://thelocalyarn.com")
(define feed-item-limit 50)

(define (as-cdata string)
  (cdata #f #f (format "<![CDATA[~a]]>" string))) ; cdata from xml package via txexpr

(define (email-encode str)
  (map char->integer (string->list str)))

;; Atom feeds require dates to be in RFC 3339 format
;; Our published/updated dates only give year-month-day. No need to bother about time zones or DST.
;; So, arbitrarily, everything happens at a quarter of noon UTC.
(define (ymd->rfc3339 datestr)
  (format "~aT11:45:00Z" datestr))

;; For the feed "updated" value, we do want a complete timestamp.
(define (current-rfc3339)
  ;; #f argument to seconds->date forces a UTC timestamp
  (define now (seconds->date (* 0.001 (current-inexact-milliseconds)) #f))
  (define timestamp
    (parameterize [(date-display-format 'iso-8601)]
      (date->string now #t)))
  (string-append timestamp "Z"))

;; Get the data out of the SQLite cache as vectors
(define (fetch-rows)
  (sequence->list
   (in-entities (cache-conn)
                (articles+notes 'content #:series #f #:limit feed-item-limit))))

(define (listing->rss-item lst)
  (match-define (listing _ path title author published updated html) lst)
  (define entry-url (string-append feed-site-url web-root path))
  (define updated-ts (if (non-empty-string? updated) updated published))
  
  `(entry (author (name ,author))
          (published    ,(ymd->rfc3339 published))
          (updated      ,(ymd->rfc3339 updated-ts))
          (title        ,title)
          (link [[rel "alternate"] [href ,entry-url]])
          (id           ,entry-url)
          (summary [[type "html"]]
                   ,(as-cdata html))))

(define (rss-feed)
  (define feed-xpr
    `(feed [[xml:lang "en-us"] [xmlns "http://www.w3.org/2005/Atom"]]
           (title ,feed-title)
           (link [[rel "self"] [href ,(string-append feed-site-url web-root "feed.xml")]])
           (generator [[uri "http://pollenpub.com/"]] "Pollen")
           (id ,(string-append feed-site-url web-root))
           (updated ,(current-rfc3339))
           (author
            (name ,feed-author)
            (email ,@(email-encode feed-author-email)))
           ,@(map listing->rss-item (fetch-rows))))
  (string-append "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n"
                 (xexpr->string feed-xpr)))

(define (main)
  (display-to-file (rss-feed) "feed.xml" #:mode 'text #:exists 'replace))

#lang racket/base

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

;; Provides fast metadata for series.
;; TO MAKE A NEW SERIES:
;;   1. Create series/my-key.poly.pm
;;   2. Add an entry for my-key to series-list below
;;   3. Use ◊define-meta[series "my-key"] in articles to add them to the series.
;;   4. If ptree-ordered is #t, also create series/my-key.ptree

(require racket/list)
(struct series (key title noun-plural noun-singular ptree-ordered?))

(define series-list
  (make-immutable-hash
   (list
   ;; ------- DEFINE SERIES HERE -----------
            ; Key               Title              plural noun    singular noun phrase
   (+series "marquee-fiction"   "Marquee Fiction" "Inventions"    "an invention"         #f)
   (+series "local-yarn"        "Local Yarn Site Notes" "Project notes" "a project note" #f)
   )))

(define (series-grouped-list)
  (group-by series-noun-plural (hash-values series-list)))

;; Quick macro to save a little typing
(define-syntax-rule (+series key title plural singular ptree)
  (cons key (series key title plural singular ptree)))

(provide (struct-out series)
         series-list
         series-grouped-list)

#lang racket/base

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

;; Tag functions used by pollen.rkt when HTML is the output format.

(require (for-syntax racket/base racket/syntax))
(require racket/list
         racket/function
         racket/draw
         racket/class
         pollen/decode
         pollen/tag
         pollen/setup
         pollen/core
         net/uri-codec
         txexpr
         "dust.rkt")

(provide html-fn
         html-fndef)

;; Customized paragraph decoder replaces single newlines within paragraphs
;; with single spaces instead of <br> tags. Allows for “semantic line wrapping”.
(define (decode-hardwrapped-paragraphs xs)
  (define (no-linebreaks xs)
    (decode-linebreaks xs " "))
  (decode-paragraphs xs #:linebreak-proc no-linebreaks))

;; A shortcut macro: lets me define a whole lot of tag functions of the form:
;;  (define html-p (default-tag-function 'p)
(define-syntax (provide/define-html-default-tags stx)
  (syntax-case stx ()
    [(_ TAG ...)
     (let ([tags (syntax->list #'(TAG ...))])
       (with-syntax ([((HTML-TAG-FUNC HTML-TAG) ...)
                      (for/list ([htag (in-list tags)])
                        (list (format-id stx "html-~a" (syntax-e htag)) (syntax-e htag)))])
         #'(begin
             (provide HTML-TAG-FUNC ...)
             (define HTML-TAG-FUNC (default-tag-function 'HTML-TAG)) ...)))]))

;; Here we go:
(provide/define-html-default-tags p
                                  b
                                  strong
                                  i
                                  em
                                  ol
                                  ul
                                  sup
                                  blockquote
                                  code)

(provide html-root
         html-title
         html-excerpt
         html-excerpt*
         html-item
         html-section
         html-subsection
         html-newthought
         html-sep
         html-caps
         html-mono
         html-center
         html-strike
         html-block
         html-blockcode
         html-index
         html-figure
         html-figure-@2x
         html-image-link
         html-dialogue
         html-say
         html-saylines
         html-magick
         html-verse
         html-attrib
         html-link
         html-xref
         html-url
         html-fn
         html-fndef
         html-note-with-srcline)

(define html-item (default-tag-function 'li))
(define html-section (default-tag-function 'h2))
(define html-subsection (default-tag-function 'h3))
(define html-newthought (default-tag-function 'span #:class "newthought"))
(define (html-sep) '(hr [[class "sep"]]))
(define html-caps (default-tag-function 'span #:class "caps"))
(define html-center (default-tag-function 'div #:style "text-align: center"))
(define html-strike (default-tag-function 'span #:style "text-decoration: line-through"))
(define html-dialogue (default-tag-function 'dl #:class "dialogue"))
(define html-mono (default-tag-function 'samp))

(define (html-block . elements)
  `(section [[class "content-block"]] (div [[class "content-block-main"]] ,@elements)))

(define (html-root . elements)
  (invalidate-series)
  (define first-pass
    (decode-elements (append elements (list (html-footnote-block)))
                     #:txexpr-elements-proc decode-hardwrapped-paragraphs
                     #:exclude-tags '(script style figure table pre)))
  (define second-pass
    (decode-elements first-pass
                     #:block-txexpr-proc detect-newthoughts
                     #:inline-txexpr-proc decode-link-urls
                     #:exclude-tags '(script style pre code)))
  `(body ,@second-pass))

(define (html-title . elements) `(title ,@elements))
(define (html-excerpt . elements) `(excerpt ,@elements))
(define (html-excerpt* . elements) `(excerpt* ,@elements))

(define (html-blockcode attrs elems)
  (define file (or (assoc 'filename attrs) ""))
  (define codeblock `(pre [[class "code"]] (code ,@elems)))
  (cond [(string>? file "") `(@ (div [[class "listing-filename"]] 128196 " " ,file) ,codeblock)]
        [else codeblock]))

(define (html-index attrs elems)
  (define index-key (maybe-attr 'key attrs (tx-strs `(span ,@elems))))
  `(a [[id ,(here-id (list "_idx-" (uri-encode index-key)))]
       [href ,(string-append "/keyword-index.html#" (uri-encode (string-downcase index-key)))]
       [data-index-entry ,index-key]
       [class "index-link"]]
      ,@elems))

;; To be used within ◊dialogue
(define (html-say . elems)
  `(@ (dt ,(car elems) (span [[class "x"]] ": ")) (dd ,@(cdr elems))))

;; Same as ◊say, but preserve linebreaks
(define (html-saylines . elems)
  (apply html-say (decode-linebreaks elems)))

(define (html-verse attrs elems)
  (let* ([title  (maybe-attr 'title attrs "")]
         [italic? (assoc 'italic? attrs)]
         [pre-attrs (cond [italic? '([class "verse"] [style "font-style: italic"])]
                          [else '([class "verse"])])]
         [pre-title (cond [(string>? title "") `(p [[class "verse-heading"]] ,title)]
                          [else ""])])
    `(div [[class "poem"]] ,pre-title (pre ,pre-attrs ,@elems))))

(define (html-magick . elems)
  (txexpr
   'div '([class "antique"])
   (decode-elements
    elems
    #:string-proc
    (λ (s) (regexp-replace* #px"(?<!f)s(?![fkb\\s”,;.’:\\!\\?]|$)" s "ſ")))))

(module+ test
  (require rackunit)
  ; always round s at the end of a word
  (check-equal? (html-magick "mirrors? yes, it is") '(div [[class "antique"]] "mirrors? yes, it is"))
  ; always round s before/after f
  (check-equal? (html-magick "offset, satisfaction") '(div [[class "antique"]] "offset, ſatisfaction"))
  ; always LONG s before hyphen
  (check-equal? (html-magick "Shafts-bury") '(div [[class "antique"]] "Shaftſ-bury"))
  ; always round s before k or b (17th-century rules)
  (check-equal? (html-magick "ask, husband") '(div [[class "antique"]] "ask, husband"))
  ; always LONG s everywhere else
  (check-equal? (html-magick "song, substitutes") '(div [[class "antique"]] "ſong, ſubſtitutes")) 

  ;; Nested elements
  (check-equal?
   (html-magick '(root "This is " (a [[href "class"]] (b "song, substitutes"))))
   '(div [[class "antique"]] (root "This is " (a [[href "class"]] (b "ſong, ſubſtitutes"))))))

(define html-attrib (default-tag-function 'div #:class "attrib"))

;; (Private) Get the dimensions of an image file
(define (get-image-size filepath)
  (define bmp (make-object bitmap% filepath))
  (list (send bmp get-width) (send bmp get-height)))

;; (Private) Builds a path to an image in the [image-dir] subfolder of the current document's 
;; folder, relative to the current document’s folder
(define (image-source basename)
  (define here-path (string->path (maybe-meta 'here-path)))
  (define-values (_ here-rel-path-parts)
    (drop-common-prefix (explode-path (current-project-root))
                        (explode-path here-path)))
  (let* ([folder-parts (drop-right here-rel-path-parts 1)]
         [img-path-parts (append folder-parts (list images-folder basename))]
         [img-path (apply build-path/convention-type 'unix img-path-parts)])
    (path->string img-path)))

(define (html-figure-@2x . elems)
  (define src (image-source (car elems)))
  (define alt-text (tx-strs `(span ,@(cdr elems))))
  (define img-width (car (get-image-size (build-path (current-project-root) src))))
  (define style-str (format "width: ~apx" (/ img-width 2.0)))
  `(figure (img [[alt ,alt-text] [style ,style-str] [src ,(string-append web-root src)]])
           (figcaption ,@(cdr elems))))

(define (html-figure . elems)
  (define src (string-append web-root (image-source (car elems))))
  (define alt-text (tx-strs `(span ,@(cdr elems))))
  `(figure [[class "fullwidth"]]
           (img [[alt ,alt-text] [src ,src]])
           (figcaption ,@(cdr elems))))

;; Simple link to an image
(define (html-image-link . elems)
  (define src (image-source (car elems)))
  (define title (tx-strs `(span ,@(cdr elems))))
  `(a [[href ,(string-append web-root src)] [title ,title]] ,@(cdr elems)))

;; There is no way in vanilla CSS to create a selector for “p tags that contain
;; a span of class ‘newthought’”. So we can handle it at the Pollen processing level.
(define (detect-newthoughts block-xpr)
  (define (is-newthought? tx) ; Helper function
    (and (txexpr? tx)
         (eq? 'span (get-tag tx))
         (attrs-have-key? tx 'class)
         (string=? "newthought" (attr-ref tx 'class))))
  (if (and (eq? (get-tag block-xpr) 'p)
           (is-newthought? (first (get-elements block-xpr))))
      (attr-set block-xpr 'class "pause-before")
      block-xpr))

;; Links
;;
;; Private use:
(define all-link-urls (make-hash))

;; Provided tag functions:
(define (html-link . args)
  `(link& [[ref ,(format "~a" (first args))]] ,@(rest args)))

(define (html-url ref url)
  (define page-path (hash-ref (current-metas) 'here-path))
  (define page-link-urls (hash-ref! all-link-urls page-path make-hash))
  (hash-set! page-link-urls (format "~a" ref) url) "")

;; Private use (by html-root):
(define (decode-link-urls tx)
  (define page-path (hash-ref (current-metas) 'here-path))
  (define page-link-urls (hash-ref! all-link-urls page-path make-hash))
  (cond [(eq? (get-tag tx) 'link&)
         (let* ([url-ref (attr-ref tx 'ref)]
                [url (or (hash-ref page-link-urls url-ref #f)
                         (format "Missing reference: ~a" url-ref))])
           `(a [[href ,url]] ,@(get-elements tx)))]
        [else tx]))

;; Fast link to another article
(define html-xref
  (case-lambda
    [(title) `(a [[href ,(format "~aarticles/~a.html" web-root (normalize title))]
                  [class "xref"]]
                 (i ,title))]
    [elems `(a [[href ,(format "~aarticles/~a.html" web-root (first elems))]
                [class "xref"]]
               ,@(rest elems))]))

;; Footnotes
;;
;; Private use:
(define all-fn-names (make-hash))
(define all-fn-definitions (make-hash))
(define (fn-id x) (here-id (string-append x "_fn")))
(define (fndef-id x) (here-id (string-append x "_fndef")))

;; Provided footnote tag functions:
(define (html-fn . args)
  (define name (format "~a" (first args)))
  (define page-path (hash-ref (current-metas) 'here-path))
  (define page-fn-names (cons name (hash-ref! all-fn-names page-path '())))
  (hash-set! all-fn-names page-path page-fn-names)
  
  (let* ([def-anchorlink (string-append "#" (fndef-id name))]
         [nth-ref        (number->string (count (curry string=? name) page-fn-names))]
         [ref-id         (string-append (fn-id name) nth-ref)]
         [fn-number      (+ 1 (index-of (remove-duplicates (reverse page-fn-names)) name))]
         [ref-text       (format "(~a)" fn-number)])
    (cond [(empty? (rest args)) `(sup (a [[href ,def-anchorlink] [id ,ref-id]] ,ref-text))]
          [else `(span [[class "links-footnote"] [id ,ref-id]]
                       ,@(rest args)
                       (sup (a [[href ,def-anchorlink]] ,ref-text)))])))

(define (html-fndef . elems)
  (define page-path (hash-ref (current-metas) 'here-path))
  (define page-fn-defs (hash-ref! all-fn-definitions page-path make-hash))
  (hash-set! page-fn-defs (format "~a" (first elems)) (rest elems)))

;; Private use (by html-root)
(define (html-footnote-block)
  (define page-path (hash-ref (current-metas) 'here-path))
  (define page-fn-names (hash-ref! all-fn-names page-path '()))
  (define page-fn-defs (hash-ref! all-fn-definitions page-path (make-hash)))
  (define note-items
    (for/list ([fn-name (in-list (remove-duplicates (reverse page-fn-names)))])
      (let* ([definition-text (or (hash-ref page-fn-defs fn-name #f)
                                  '((i "Missing footnote definition!")))]
             [backref-count (count (curry string=? fn-name) page-fn-names)]
             [backrefs (for/list ([fnref-num (in-range backref-count)])
                         `(a [[href ,(string-append "#"
                                                    (fn-id fn-name)
                                                    (format "~a" (+ 1 fnref-num)))]] "↩"))])
        `(li [[id ,(fndef-id fn-name)]] ,@definition-text ,@backrefs))))
  (cond [(null? note-items) ""]
        [else `(section ((class "footnotes")) (hr) (ol ,@note-items))]))

(define (html-note-with-srcline attrs elems)
  (txexpr 'note attrs (decode-hardwrapped-paragraphs elems)))

#lang racket/base

(provide targets)

(define targets '(html))

#lang racket/base

(require racket/file
         pollen/setup
         "../cache.rkt"
         "../snippets-html.rkt")

(provide main)

(define (main)
  (init-cache-db!)
  
  (display-to-file (html$-page-footer)
                   (build-path (current-project-root) "scribbled" "site-footer.html")
                   #:exists 'replace))

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

@font-face {
  font-family: 'Fabiol';
  src: url('LDFabiolPro-Regular.woff2') format('woff2'),
       url('LDFabiolPro-Regular.woff') format('woff');
  font-style:   normal;
  font-weight:  400;
}

@font-face {
  font-family: 'Fabiol';
  src: url('LDFabiolPro-Italic.woff2') format('woff2'),
       url('LDFabiolPro-Italic.woff') format('woff');
  font-style:   italic;
  font-weight:  400;
}

@font-face {
  font-family: 'Fabiol';
  src: url('LDFabiolPro-Bold.woff2') format('woff2'),
       url('LDFabiolPro-Bold.woff') format('woff');
  font-style:   normal;
  font-weight:  700;
}

@font-face {
  font-family: 'Triplicate T4c';
  src: url('Triplicate-T4c.woff') format('woff');
  font-style: normal;
  font-weight: 400;
  }

@font-face {
  font-family: 'Triplicate T4c';
  src: url('Triplicate-T4c-italic.woff') format('woff');
  font-style: italic;
  font-weight: 400;
  }

@font-face {
  font-family: 'Triplicate T4c';
  src: url('Triplicate-T4c-bold.woff') format('woff');
  font-style: normal;
  font-weight: bold;
  }

#lang pollen/pre

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

/* Welcome to my CSS File!  
** I have named it `martin.css`, after Martin Pale. */

◊;{Here, broadly, is the approach we are taking here:

   1. The site shall look decent and readable even when CSS is unavailable.

   2. There's a vertical rhythm of ◊x-lineheight[1] that just about 
      everything follows.
      
   3. Define the mobile (smallest screen) layout first...            [Lines 026-???]
      ...then do some dynamic type sizing on screens 768px+ wide     [Lines ???-???]
   
   4. If CSS Grid support is detected, we'll do some nice-looking    [Lines ???-???]
      layout on screens 768px+ wide.
}

@import url('font.css');
@import url('normalize.css');

/* Let us first address the matter of font size in different screen sizes. */

/* Mobile portrait screens will see a minimum 18px font. */
html { 
    font-size: 22px;
    height: 100%;
    } 

/* Start increasing type size dynamically at screen widths of 768px */
@media (min-width: 768px) { 
    html { font-size: 2.8vw; } 
}

/* Top out at 23px for screens up to 800px TALL */
◊; @media only screen and (min-width: 1000px) and (max-height: 800px) {
◊;    html { font-size: 26px; } /* =  2.6% of 1000px (min-width) */
◊; }

/* Top out at 28px for screens 801px-1000px TALL */
@media (min-width: 1000px) and (max-height: 920px) { 
   html { font-size: 28px; }     /* =  2.8% of 1000px (min-width) */
}
/* For screens taller than 1000 px, top out at 32px */
@media (min-width: 1178px) and (min-height: 921px) {
    html { font-size: 33px; }    /* =  2.8% of 1178px (min-width) */
}

◊; Since line height is used in so many places...
◊(define LINEHEIGHT 1.3)
◊(define lineheight (string-append (number->string LINEHEIGHT) "rem"))
◊(define (x-lineheight multiple) 
    (string-append (real->decimal-string (* LINEHEIGHT multiple) 2) "rem"))
◊(define (derive-lineheight lines #:per-lines per)
    (string-append (real->decimal-string (/ (* LINEHEIGHT per) lines) 3) "rem"))

◊(define color-bodytext   "#2a3d45") ◊; Japanese indigo, baby
◊(define color-pagehead   "#a81606") ◊; for Faded gold, a29555
◊(define color-link       "#ab2a23")
◊(define color-linkhover  "#c14337")
◊(define color-xrefmark   "#c14337")
◊(define color-background "#f7f7f7")
◊(define color-linkbackground "#f7f7f7")

◊(define body-font "Fabiol, serif")
◊(define mono-font "'Triplicate T4c', monospace")

◊(define normal-font-features
  "\"calt\" on, \"liga\" on, \"clig\" on, \"kern\" on, \"onum\" on, \"pnum\" on")

◊(define antique-font-features
  "\"calt\" on, \"liga\" on, \"clig\" on, \"dlig\" on, \"kern\" on, \"onum\" on, \"pnum\" on")

/*
 **** 1. Mobile-first layout ***
      1.1 All Pages
      1.2 Front page
      1.3 Individual post body markup
      1.4 Journal views (article listings)  
 */

body {
    height: 100%;           /* height and flex are to keep footer stuck to bottom of page */
    display: flex;
    flex-direction: column;
    margin: 0;
    background: ◊color-background;

    /* Typography: `line-height` is important!
       All verticle rhythm based on this value. */
    line-height: ◊lineheight;
    font-family: ◊body-font;

    font-feature-settings: ◊normal-font-features; 
    color: ◊color-bodytext; /* Japanese Indigo, baby */
}

/* This is used to hide certain punctuation and things as long as CSS is available. 
   Turn off CSS and voila: stuff appears. */
.x {
    display: none;
}

.hist p {
    font-variant-alternates: historical-forms;
}
.nonhist {
    font-variant-alternates: normal;
}

main {
    background: white;
    margin: 0;
    padding: ◊x-lineheight[0.5] ◊x-lineheight[1];
    flex: 1 0 auto;
}

main > a > header {
    text-align: center;
}

main > a > header h1 {
    display: none;
    /* font-size: ◊x-lineheight[1.5];
    line-height: ◊x-lineheight[2];
    margin: 0 0 ◊x-lineheight[0.5] 0;
    font-weight: normal;
    font-style: italic;
    text-transform: lowercase;
    color: ◊color-pagehead;
    transition: color 0.25s ease; */
}

img.logo {
    height: ◊x-lineheight[3];
    filter: none;
    transition: filter 0.5s ease;
}

header:hover img.logo {
    filter: invert(12%) sepia(87%) saturate(2559%) hue-rotate(348deg) brightness(125%) contrast(88%);
    transition: filter 0.5s ease;
}

/* I read somewhere years ago that you should specify styling for links in the
   following order: Link, Visited, Hover, Active. 
       → Remember the mnemonic: Lord Vader Has Arrived.
   
   Not sure if that's relevant advice any more but I still follow it. It can't hurt. */
   
a:link, a:visited {         /* [L]ord [V]ader… */
    color: ◊color-link;
    text-decoration: none;
}

a:hover, a:active {         /* …[H]as [A]rrived */
    color: ◊color-linkhover;
    background: ◊color-linkbackground;
}

a.index-link:link, a.index-link:visited {
    color: ◊color-bodytext;
}

a.index-link:hover, a.index-link:active {
    color: #006400;
}

a.index-link::after {
    content: '\f89b';
    color: #809102;
    position: relative;
    top: -0.3em;
    font-weight: normal;
    font-style: normal;
}

main>a {
    color: inherit;
}

span.links-footnote {
    display: inline-block; /* allows keyframe animation to work */
}

:target {
    animation: hilite 2.5s;
}
@keyframes hilite {
    0% {background: transparent;}
    10% {background: #feffc1;}
    100% {background: transparent;}
}

main > aside {
    text-align: center;
}

main nav {
    font-family: 'Triplicate T4c', monospace;
    font-feature-settings: "onum" off;
    font-size: 0.7rem;
    margin: 0;
    margin-top: 0.5rem;
    text-align: center;
}

main nav ul {
    list-style-type: none;
    margin: 0.2em auto;
    padding: 0;
}

main nav li {
    display: none; /* Numbers not displayed on mobile */
    color: gray;
}

main nav li.nav-text {
    display: inline;
    text-transform: uppercase;
    letter-spacing: 0.05rem;
    font-size: 0.6rem;
}

main nav li.inactive-link {
    color: #545454; /* Accessibility (contrast) */
}

main nav li.current-page {
    color: ◊color-bodytext;
    padding: 0.2rem 0.5rem;
    border-bottom: dotted ◊color-bodytext 2px;
}

main nav li a {
    padding: 0.2rem 0.5rem;
}

main nav li a:link, nav li a:visited {
    color: ◊color-bodytext;
}

main nav li a:hover, nav li a:active {
    color: ◊color-linkhover;
    background: #ebebeb;
}

i > em { font-style: normal; }

/* On mobile, an <ARTICLE> is just a box. Later we'll do fancy stuff if grid support is detected. */
article {
    margin: ◊x-lineheight[2] 0 ◊x-lineheight[1] 0;
    padding-top: ◊x-lineheight[1];
}
article:first-of-type {
    margin-top: ◊x-lineheight[1];
}

/* Here's my thing these days about article titles: they shouldn't be required. When you write in a
   paper journal, do you think of a title for every entry? No! You just write the date. The date is
   the heading. Makes sense. But, this means I've had to think long and hard about how to present two
   different types of articles (those with titles AND dates, and those with just a date for the title). 

    filter: invert(12%) sepia(87%) saturate(359%) hue-rotate(348deg) brightness(105%) contrast(88%);
   For now: By default, the title-less article is assumed to be the norm. On these, we use <H1> to 
   show the date in italics. */
article>h1 {
    font-size: ◊x-lineheight[1];
    line-height: ◊x-lineheight[1];
    margin: 0 0 ◊x-lineheight[1] 0;
    font-style: italic;
    font-weight: bold;
}

article.no-title>h1 {
    font-weight: normal
}

/* Titles non-bold, non-smallcaps by default. This can be overridden in document markup. */
h1.entry-title {
    margin: 0 0 0 0;
    text-transform: none;
    font-style: normal;
    line-height: 1.7rem;
}

h1.entry-title.note-full {
    font-weight: normal;
    font-feature-settings: "smcp" on, "liga" on, "clig" on, "dlig" on, "kern" on, "onum" on, "pnum" on;
}

/* This <SPAN> class is used in titles for Notes appended to earlier articles */
h1.entry-title .cross-reference {
    font-feature-settings: "smcp" off, "liga" on, "clig" on, "dlig" on, "kern" on, "onum" on, "pnum" on;
    font-style: italic;
    text-transform: none;
}

/* `a.rel-bookmark` is only used in individual article or ‘journal’ views, 
    not in listings; see the design docs.
*/
a.rel-bookmark:link,        /* Lord  */
a.rel-bookmark:visited {    /* Vader */
    text-decoration: none;
    background: none;
    color: ◊color-bodytext;
}

a.rel-bookmark:hover,       /* Has     */
a.rel-bookmark:active {     /* Arrived */
    text-decoration: none;
    background: ◊color-linkbackground;
    color: #006400;
}

/* Here's where we add the minty fresh maple leaf glyph. */
a.rel-bookmark::after {
    content: '\f894'; 
    margin-left: 4px;
    font-style: normal;
    color: #809102;
}
a.rel-bookmark.note-permlink::after {
    content: '\f897';
    margin-left: 4px;
}
div.note a.rel-bookmark.note-permlink::after {
    content: '';
}
div.note a.rel-bookmark.note-permlink::before {
   font-family: ◊body-font;
   font-size: 1rem;
   content: '\00b6';
   margin-left: -0.9rem;
   float: left;
   margin-top: -2px;
}

a.rel-bookmark:hover::after {
    color: #aaba16;
}

a.cross-reference:link,
a.cross-reference:visited {
    color: ◊color-bodytext;
}

a.cross-reference::before {
    content: '☞\00a0';      /* Non-breaking space */
    font-style: normal;
    color: ◊color-xrefmark;
}

/* Footnote links */
sup a {
    font-weight: bold;
    margin-left: 3px;
}

p.time {
    margin: 0 0 ◊x-lineheight[1] 0;
}

footer.article-info {
    margin: ◊x-lineheight[1] 0;
    text-align: center;
    font-feature-settings: "smcp" on, "liga" on, "clig" on, "dlig" on, "kern" on, "onum" on, "pnum" on;
    color: #555555; /* Accessibility (contrast) */
}

footer.article-info::before {
    content: "☞\00a0";
}

/* Within article info, don’t display series info when on a series page (redundant) */
body.series-page .series-part {
    display: none;
}

p.time::before {
    content: none;
}

p.time {
    font-size: ◊x-lineheight[0.75];
    line-height: ◊x-lineheight[1];
    font-feature-settings: "scmp" off, "liga" on, "clig" on, "dlig" on, "kern" on, "onum" on, "pnum" on;
    text-transform: none;
    font-style: italic;
}

article>:last-child::after {
    content: '\f88d';  /* Round glyph */
    color: ◊color-bodytext;
    font-size: ◊x-lineheight[1];
    line-height: ◊x-lineheight[1];
    text-align: center;
    display: block;
    margin: ◊x-lineheight[1] 0;
}

/* Fossil info links */
.scm-links { 
    color: #888;
    font-size: 0.5rem;
    white-space: nowrap;
    float: right;
    text-align: right;
    margin-top: -◊x-lineheight[2.01];
    padding-right: 1ch;
    font-family: ◊mono-font;
    font-style: italic;
}

.scm-links a {
    display: inline-block;
    text-align: center;
    width: 0.9rem;
    color: #727070;
}

p {
    margin: 0;
    text-indent: 0;
}

p + p {
    text-indent: 1em;
}

.entry-content blockquote,
.content-block-main blockquote {
    font-size: ◊x-lineheight[0.7];
    line-height: ◊derive-lineheight[7 #:per-lines 6];
    margin: ◊x-lineheight[1.0] 2em;
}

.entry-content blockquote:first-child, 
.content-block-main blockquote:first-child {
    margin-top: 0;
}

.entry-content blockquote footer,
.content-block-main blockquote footer {
    margin-top: ◊x-lineheight[0.5];
    text-align: right;
    width: calc(100% + 2em);
}

.entry-content h2, .content-block-main h2 {
    font-size: 1rem;
    font-weight: normal;
    font-feature-settings: "smcp" on;
    text-transform: lowercase;
    text-align: left;
    padding-top: 0.2rem;
    border-top: dotted #ccc 2px;
    color: #666;
    line-height: ◊x-lineheight[0.96];
}

@media(min-width: 667px) {
  .entry-content h2, .content-block-main h2 {
      float: left;
      margin-left: -8rem;
      text-align: right;
      width: 7rem;
      margin-top: -0.25rem;
  }
}

hr.sep {
    border: 0;
    background: none;
    margin: ◊x-lineheight[1] 0;
    height: ◊x-lineheight[1];
}

hr.sep:after {
    display: block;
    text-align: center;
    content: '❧';
    font-size: ◊x-lineheight[1];
}

.caps, span.smallcaps, span.newthought {
    font-feature-settings: "smcp" on, "liga" on, "clig" on, "dlig" on, "kern" on, "onum" on, "pnum" on;
    font-style: normal;
}

.caps {
    text-transform: lowercase;
    font-size: 1.1em;
}

p.pause-before {
    margin-top: ◊x-lineheight[2];
    text-indent: 0;
}

.entry-content ul,
.entry-content ol,
.content-block-main ul,
.content-block-main ol {
    margin: ◊x-lineheight[0.5] 0 ◊x-lineheight[0.5] 0.6rem;
    padding: 0;
}

.entry-content li,
.content-block-main li {
    margin: 0 0 ◊x-lineheight[0.5] 0;
    padding: 0;
    text-indent: 0; 
}

.entry-content ul,
.content-block-main ul {
    list-style: none;
}

.entry-content ul li:before,
.content-block-main ul li:before {
    content: '•';
    margin-left: -0.4rem;
    margin-right: 0.2rem;
}

code {
    font-size: 0.75rem;
    font-family: ◊mono-font;
    background: #ddd;
    border-radius: 0.2em;
}

pre {
    line-height: ◊derive-lineheight[7 #:per-lines 6];
    max-width: 100%;
    overflow-x: auto;
    tab-size: 4;
}

pre code {
    border: 0;
    background: none;
    font-size: 0.6rem;
}

pre.code {
    border: dotted #aaa 2px;
    padding-left: 0.2em;
    line-height: 0.7rem;
}

samp {
    font-family: ◊mono-font;
    font-size: 0.7rem;
}

pre.verse {
    font-family: ◊body-font;
    font-size: 1rem;
    line-height: ◊x-lineheight[1];
    width: auto;
    margin: ◊x-lineheight[1] auto;
    display: table;
    white-space: pre-wrap;
    /* Whitespace is preserved by the browser.
       Text will wrap when necessary, and on line breaks */
}

p.verse-heading {
    font-feature-settings: "smcp" on, "liga" on, "clig" on, "dlig" on, "kern" on, "onum" on, "pnum" on;
    text-align: center;
    font-size: 1.3rem;
}

div.attrib {
    text-align: right;
    font-size: .8rem;
    margin-top: -◊x-lineheight[0.5];
    margin-bottom: ◊x-lineheight[1];
}
    
.entry-content figure,
.content-block-main figure {
    margin: ◊x-lineheight[1] 0;
    padding: 0;
}

figure>a {
    margin: 0;
    padding: 0;
    font-family: arial, sans-serif;
}
figure img {
    max-width: 100%;
    margin: 0 auto;
}

figcaption {
    font-size: 0.8rem;
    line-height: ◊derive-lineheight[4 #:per-lines 3];
    margin-bottom: 0.3rem;
    text-align: left;
}

dl {
    margin: ◊x-lineheight[1] 0;
}

dl.dialogue dt {
    font-feature-settings: "smcp" on, "liga" on, "clig" on, "dlig" on, "kern" on, "onum" on, "pnum" on;
    font-style: normal;
    text-transform: lowercase;
}

section.entry-content p.signoff {
    margin-top: ◊x-lineheight[1];
    font-size: 1.2rem;
}

section.footnotes {
    margin-top: ◊x-lineheight[1];
    font-size: 0.9rem;
    line-height: ◊derive-lineheight[7 #:per-lines 6];
}

section.footnotes hr {
    border: 0;
    background: ◊color-bodytext;
    height: 1px;
    margin: 0;
    width: 75%;
    text-align: left;
}

section.footnotes ol {
    margin: ◊x-lineheight[0.5] 0 0 0;
}


p.further-reading {
   margin-top: ◊x-lineheight[1];
   text-indent: 0;
   background: #eee;
   padding-left: 0.3rem;
   border-radius: 3px;
}

p.further-reading:hover {
    background-color: #ddd;
}

p.further-reading a {
    color: ◊color-bodytext !important;
    font-style: italic;
}

p.further-reading a:hover, p.further-reading a:active {
    background-color: #ddd;
}

/* ******* “Further Notes” added to articles ********
 */

div.further-notes {
    margin-top: ◊x-lineheight[3];
}

div.further-notes>h2 {
    font-style: normal;
    font-feature-settings: "smcp" on;
    border-top: solid 2px ◊color-bodytext;
    text-transform: lowercase;
    
    color: ◊color-bodytext;
    margin-top: 0;
    float: none;
    text-align: left;
}

div.note h3 {
    margin-top: 0;
    font-size: 1rem;
    font-weight: normal;
    font-family: ◊mono-font;
    font-size: 0.7rem;
    background: #f3f3f3;
    border-top: solid #b6b6b6 1px;
    padding-left: 0.2rem;
    margin-bottom: 0.3rem;
}

div.note-meta {
    margin-top: ◊x-lineheight[1];
    color: #888;
    font-size: 1.2rem;
}

.by-proprietor .note-meta {
    display: none;
}

div.note + div.note {
    margin-top: ◊x-lineheight[2];
}

.disposition-mark {
    color: ◊color-xrefmark;
    position: relative;
    top: -0.5em;
    font-size: 0.83em;
}

.disposition-mark-in-note {
    background: ◊color-xrefmark;
    color: white;
    border-radius: 0.08em;
    padding: 0 0.1em;
    margin: 0 0.4em 0 0;
    text-decoration: none !important;
}

/* ******* (Mobile first) “Short” list styling *******
 */

section.content-block {
}

article.short-listing {
    margin: ◊x-lineheight[1] 0;
    padding: 0;
    display: block;
    border: none;
    box-shadow: none;
}

article.short-listing a {
    display: block;
}

article.short-listing time {
    color: #999;
}

article.short-listing h3 {
    font-size: 1.2rem;
    margin: 0;
    padding: 0;
    font-weight: normal;
}

/* ******* (Mobile first) Columnar series list styling *******
 */

.column-list {
    margin: 0;
    column-count: 2;
    column-width: 16ch;
    column-gap: 1ch;
}

@media (min-width: 667px) {
  .column-list {
    column-count: auto;
    margin: 0 auto;
    max-width: 70ch;
  }
}

.column-list div {
    padding-left: 0.25em; /* Keeps some italic descenders inside the box */
    text-align: left;
    break-inside: avoid;
}

.column-list h2 {
    font-feature-settings: "smcp" on;
    text-transform: lowercase;
    font-weight: normal;
    font-size: 1em;
    margin: 0;
}

.column-list ul {
    margin-top: 0;
    list-style-type: none;
    padding: 0;
    margin-bottom: 0.5rem;
}

/* ******* (Mobile first) Keyword Index styling *******
 */

#keywordindex {
    column-width: 7rem;
    margin-top: ◊x-lineheight[2];
}

#keywordindex section {
    -webkit-column-break-inside: avoid; /* Chrome, Safari, Opera */
    page-break-inside: avoid; /* Firefox */
    break-inside: avoid; /* IE 10+ */
}

#keywordindex h2 {
    margin: 0;
}

#keywordindex ul {
    margin-top: 0;
    list-style-type: none;
    padding: 0;
}

#keywordindex ul ul {
    margin-left: 0.5em;
    font-size: smaller;
}

/* Footer ***** */

footer#main {
  text-align: left;
  font-size: 0.8rem;
  line-height: 1rem;
  width: 90%;
  margin: 0 auto;
  flex-shrink: 0;
}

@media (min-width: 667px) {
  footer#main {
    text-align: center;
    width: calc(100% - 4vw);
    padding: 0 2vw 1rem 2vw;
    background: linear-gradient(◊color-background 5%, #dedede 100%);
  }
}

footer#main p.title {
  font-size: 1rem;
  font-feature-settings: "smcp" on;
  text-transform: lowercase;
  margin-top: ◊x-lineheight[2];
  margin-bottom: ◊x-lineheight[0.5];
}

footer#main nav {
  font-feature-settings: "smcp" on;
  text-transform: lowercase;
}

footer#main nav code {
  font-size: 0.6rem;
}
  

/* End of mobile-first typography and layout */


/* Here’s where we start getting funky for any viewport wider than mobile portrait.
   An iPhone 6 is 667px wide in landscape mode, so that’s our breakpoint. */

@media (min-width: 667px) {
    main {
        margin: 0 auto;
        padding-left: 1rem;
        padding-right: 1rem;
        width: 30rem;
        max-width: 90%;
    }

    main nav li { display: inline; } /* Display page numbers on larger screens */

    @supports (grid-area: auto) {
        main { 
            width: 42rem;
            background: none;
        }

        header img.logo {
            height: ◊x-lineheight[3];
            max-height: 103px;
            width: auto;
        }

        /* This header is display:none above, so the following is vestigial */
        main header h1 {
            grid-area: masthead;
            margin: 0;
            line-height: 1em;
        }
        
        article {
            display: grid;
            grid-template-columns: 8rem 7fr 1fr;
            grid-template-rows: auto auto auto;
            grid-template-areas: 
               "corner title title"
               "margin main rightmargin";
            align-items: start;     /* Puts everything at the top */
            margin-bottom: 0;
            grid-column-gap: 1rem;
            box-shadow: 0.4em 0.4em 10px #e3e3e3;
            background: white;
            border: solid 1px #dedede;
            border-radius: 2px;
        }
        
        article>h1 {
            grid-area: margin;
            font-size: 1.1rem;
            text-align: right;
        }

        article>h1.entry-title {
            grid-area: title;
            font-size: ◊x-lineheight[1];
            text-align: left;
            padding-right: 0;
            margin-bottom: 0.9rem;

        }

        p.time {
            grid-area: corner;
            text-align: right;
            font-size: 1.1rem;
            line-height: 1.7rem;
        }

        footer.article-info {
            padding-top: 0.2rem;
            grid-area: margin;
            text-align: right;
            font-size: 0.8rem;
            line-height: ◊derive-lineheight[4 #:per-lines 3];
            margin: 0;
            padding-left: 3px;
        }

        article.no-title footer.article-info {
            margin-top: 1.5rem;
            padding-top: 0;
        }

        .scm-links {
            float: none;
            grid-area: rightmargin;
            height: 100%;
        }

        article.with-title .scm-links { 
            grid-area: title;
        }

        .scm-links a:hover {
            color: #2176ff;
            background: none;
        }
        
        section.entry-content {
            grid-area: main;
            /* Prevent content from overriding grid column sizing */
            /* See https://css-tricks.com/preventing-a-grid-blowout/ */
            min-width: 0;
        }

        section.entry-content > :first-child {
            margin-top: 0 !important;
        }

        article>:last-child::after {
            content: none;
            margin 0;
            display: none;
        }

        section.entry-content::after {
            content: '\f88d';
            color: ◊color-bodytext;
            font-size: ◊x-lineheight[1];
            line-height: ◊x-lineheight[1];
            text-align: center;
            display: block;
            margin: ◊x-lineheight[1] 0;
        }

        section.entry-content figure {
            display: grid;
            width: calc(112.5% + 8rem);
            margin-left: -8rem;
            grid-template-columns: 7rem 1fr;
            grid-column-gap: 1rem;
            grid-template-areas: "margin main";
        }

        section.entry-content figure img {
            grid-area: main;
        }
        section.entry-content figure figcaption {
            grid-area: margin;
            text-align: right;
            align-self: end;
        }

        /* ******* (Grid support) “Further Notes” added to articles *******
         */

        div.further-notes>h2 {
            width: calc(100% + 8rem);
            margin-left: -8rem;
        }

        div.note h3 {
        }

        /* ******* (Grid support) Journal View styling *******
         */

        section.content-block {
            display: grid;
            grid-template-columns: 8rem 7fr 1fr;
            grid-template-rows: auto auto auto;
            grid-template-areas: "margin main .";
            align-items: start;     /* Puts everything at the top */
            margin-bottom: 0;
            grid-column-gap: 1rem;
            box-shadow: 0.4em 0.4em 10px #e3e3e3;
            background: white;
            border: solid 1px #dedede;
            border-radius: 2px;
        }
        div.content-block-main {
            padding-top: ◊x-lineheight[1];
            padding-bottom: ◊x-lineheight[1];
            grid-area: main;
        }

        div.content-block-main > :first-child {
            margin-top: 0 !important;
        }
    }
}

@media print {
    html { font-size: 13pt; }
    body { background: white; color: black; }
    main { width: 100%; }
    footer.article-info { color: black; }
    article, section.content-block {
        box-shadow: none;
        border: none;
        }
    a:link, a:visited, a:hover, a:active {
        color: black;
        border-bottom: dotted 1px black;
    }
    footer#main { display: none; }
}

/*! normalize.css v8.0.0 | MIT License | github.com/necolas/normalize.css */

/* Document
   ========================================================================== */

/**
 * 1. Correct the line height in all browsers.
 * 2. Prevent adjustments of font size after orientation changes in iOS.
 */

html {
  line-height: 1.15; /* 1 */
  -webkit-text-size-adjust: 100%; /* 2 */
}

/* Sections
   ========================================================================== */

/**
 * Remove the margin in all browsers.
 */

body {
  margin: 0;
}

/**
 * Correct the font size and margin on `h1` elements within `section` and
 * `article` contexts in Chrome, Firefox, and Safari.
 */

h1 {
  font-size: 2em;
  margin: 0.67em 0;
}

/* Grouping content
   ========================================================================== */

/**
 * 1. Add the correct box sizing in Firefox.
 * 2. Show the overflow in Edge and IE.
 */

hr {
  box-sizing: content-box; /* 1 */
  height: 0; /* 1 */
  overflow: visible; /* 2 */
}

/**
 * 1. Correct the inheritance and scaling of font size in all browsers.
 * 2. Correct the odd `em` font sizing in all browsers.
 */

pre {
  font-family: monospace, monospace; /* 1 */
  font-size: 1em; /* 2 */
}

/* Text-level semantics
   ========================================================================== */

/**
 * Remove the gray background on active links in IE 10.
 */

a {
  background-color: transparent;
}

/**
 * 1. Remove the bottom border in Chrome 57-
 * 2. Add the correct text decoration in Chrome, Edge, IE, Opera, and Safari.
 */

abbr[title] {
  border-bottom: none; /* 1 */
  text-decoration: underline; /* 2 */
  text-decoration: underline dotted; /* 2 */
}

/**
 * Add the correct font weight in Chrome, Edge, and Safari.
 */

b,
strong {
  font-weight: bolder;
}

/**
 * 1. Correct the inheritance and scaling of font size in all browsers.
 * 2. Correct the odd `em` font sizing in all browsers.
 */

code,
kbd,
samp {
  font-family: monospace, monospace; /* 1 */
  font-size: 1em; /* 2 */
}

/**
 * Add the correct font size in all browsers.
 */

small {
  font-size: 80%;
}

/**
 * Prevent `sub` and `sup` elements from affecting the line height in
 * all browsers.
 */

sub,
sup {
  font-size: 75%;
  line-height: 0;
  position: relative;
  vertical-align: baseline;
}

sub {
  bottom: -0.25em;
}

sup {
  top: -0.5em;
}

/* Embedded content
   ========================================================================== */

/**
 * Remove the border on images inside links in IE 10.
 */

img {
  border-style: none;
}

/* Forms
   ========================================================================== */

/**
 * 1. Change the font styles in all browsers.
 * 2. Remove the margin in Firefox and Safari.
 */

button,
input,
optgroup,
select,
textarea {
  font-family: inherit; /* 1 */
  font-size: 100%; /* 1 */
  line-height: 1.15; /* 1 */
  margin: 0; /* 2 */
}

/**
 * Show the overflow in IE.
 * 1. Show the overflow in Edge.
 */

button,
input { /* 1 */
  overflow: visible;
}

/**
 * Remove the inheritance of text transform in Edge, Firefox, and IE.
 * 1. Remove the inheritance of text transform in Firefox.
 */

button,
select { /* 1 */
  text-transform: none;
}

/**
 * Correct the inability to style clickable types in iOS and Safari.
 */

button,
[type="button"],
[type="reset"],
[type="submit"] {
  -webkit-appearance: button;
}

/**
 * Remove the inner border and padding in Firefox.
 */

button::-moz-focus-inner,
[type="button"]::-moz-focus-inner,
[type="reset"]::-moz-focus-inner,
[type="submit"]::-moz-focus-inner {
  border-style: none;
  padding: 0;
}

/**
 * Restore the focus styles unset by the previous rule.
 */

button:-moz-focusring,
[type="button"]:-moz-focusring,
[type="reset"]:-moz-focusring,
[type="submit"]:-moz-focusring {
  outline: 1px dotted ButtonText;
}

/**
 * Correct the padding in Firefox.
 */

fieldset {
  padding: 0.35em 0.75em 0.625em;
}

/**
 * 1. Correct the text wrapping in Edge and IE.
 * 2. Correct the color inheritance from `fieldset` elements in IE.
 * 3. Remove the padding so developers are not caught out when they zero out
 *    `fieldset` elements in all browsers.
 */

legend {
  box-sizing: border-box; /* 1 */
  color: inherit; /* 2 */
  display: table; /* 1 */
  max-width: 100%; /* 1 */
  padding: 0; /* 3 */
  white-space: normal; /* 1 */
}

/**
 * Add the correct vertical alignment in Chrome, Firefox, and Opera.
 */

progress {
  vertical-align: baseline;
}

/**
 * Remove the default vertical scrollbar in IE 10+.
 */

textarea {
  overflow: auto;
}

/**
 * 1. Add the correct box sizing in IE 10.
 * 2. Remove the padding in IE 10.
 */

[type="checkbox"],
[type="radio"] {
  box-sizing: border-box; /* 1 */
  padding: 0; /* 2 */
}

/**
 * Correct the cursor style of increment and decrement buttons in Chrome.
 */

[type="number"]::-webkit-inner-spin-button,
[type="number"]::-webkit-outer-spin-button {
  height: auto;
}

/**
 * 1. Correct the odd appearance in Chrome and Safari.
 * 2. Correct the outline style in Safari.
 */

[type="search"] {
  -webkit-appearance: textfield; /* 1 */
  outline-offset: -2px; /* 2 */
}

/**
 * Remove the inner padding in Chrome and Safari on macOS.
 */

[type="search"]::-webkit-search-decoration {
  -webkit-appearance: none;
}

/**
 * 1. Correct the inability to style clickable types in iOS and Safari.
 * 2. Change font properties to `inherit` in Safari.
 */

::-webkit-file-upload-button {
  -webkit-appearance: button; /* 1 */
  font: inherit; /* 2 */
}

/* Interactive
   ========================================================================== */

/*
 * Add the correct display in Edge, IE 10+, and Firefox.
 */

details {
  display: block;
}

/*
 * Add the correct display in all browsers.
 */

summary {
  display: list-item;
}

/* Misc
   ========================================================================== */

/**
 * Add the correct display in IE 10+.
 */

template {
  display: none;
}

/**
 * Add the correct display in IE 10.
 */

[hidden] {
  display: none;
}

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

@font-face {
  font-family: 'Fabiol';
  src: url('LDFabiolPro-Regular.woff2') format('woff2'),
       url('LDFabiolPro-Regular.woff') format('woff');
  font-style:   normal;
  font-weight:  400;
}

@font-face {
  font-family: 'Fabiol';
  src: url('LDFabiolPro-Italic.woff2') format('woff2'),
       url('LDFabiolPro-Italic.woff') format('woff');
  font-style:   italic;
  font-weight:  400;
}

@font-face {
  font-family: 'Fabiol';
  src: url('LDFabiolPro-Bold.woff2') format('woff2'),
       url('LDFabiolPro-Bold.woff') format('woff');
  font-style:   normal;
  font-weight:  700;
}

@font-face {
  font-family: 'Triplicate T4c';
  src: url('Triplicate-T4c.woff') format('woff');
  font-style: normal;
  font-weight: 400;
  }

@font-face {
  font-family: 'Triplicate T4c';
  src: url('Triplicate-T4c-italic.woff') format('woff');
  font-style: italic;
  font-weight: 400;
  }

@font-face {
  font-family: 'Triplicate T4c';
  src: url('Triplicate-T4c-bold.woff') format('woff');
  font-style: normal;
  font-weight: bold;
  }