Index: .fossil-settings/ignore-glob ================================================================== --- .fossil-settings/ignore-glob +++ .fossil-settings/ignore-glob @@ -1,21 +1,20 @@ *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 Index: articles/what-should-people-do-with-old-journals.poly.pm ================================================================== --- articles/what-should-people-do-with-old-journals.poly.pm +++ articles/what-should-people-do-with-old-journals.poly.pm @@ -4,28 +4,30 @@ ◊(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. DELETED cache.rkt Index: cache.rkt ================================================================== --- cache.rkt +++ cache.rkt @@ -1,209 +0,0 @@ -#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 "" introduced by using ->html on docs containing output from -;; listing functions -(define (unfence html-str) - (regexp-replace* #px"<[\\/]{0,1}style>" html-str "")) DELETED code-docs/cache.scrbl Index: code-docs/cache.scrbl ================================================================== --- code-docs/cache.scrbl +++ code-docs/cache.scrbl @@ -1,246 +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" 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{"] 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]. - -} DELETED code-docs/crystalize.scrbl Index: code-docs/crystalize.scrbl ================================================================== --- code-docs/crystalize.scrbl +++ code-docs/crystalize.scrbl @@ -1,61 +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") - -@(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{} 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. - -} DELETED code-docs/custom.css Index: code-docs/custom.css ================================================================== --- code-docs/custom.css +++ code-docs/custom.css @@ -1,28 +0,0 @@ -.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; -} DELETED code-docs/design.scrbl Index: code-docs/design.scrbl ================================================================== --- code-docs/design.scrbl +++ code-docs/design.scrbl @@ -1,172 +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"))] - DELETED code-docs/diagram-notes.png Index: code-docs/diagram-notes.png ================================================================== --- code-docs/diagram-notes.png +++ code-docs/diagram-notes.png cannot compute difference between binary files DELETED code-docs/dust.scrbl Index: code-docs/dust.scrbl ================================================================== --- code-docs/dust.scrbl +++ code-docs/dust.scrbl @@ -1,287 +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" - 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. DELETED code-docs/main.scrbl Index: code-docs/main.scrbl ================================================================== --- code-docs/main.scrbl +++ code-docs/main.scrbl @@ -1,58 +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 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"] DELETED code-docs/other-files.scrbl Index: code-docs/other-files.scrbl ================================================================== --- code-docs/other-files.scrbl +++ code-docs/other-files.scrbl @@ -1,42 +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") - -@(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. - - DELETED code-docs/pollen.scrbl Index: code-docs/pollen.scrbl ================================================================== --- code-docs/pollen.scrbl +++ code-docs/pollen.scrbl @@ -1,382 +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") -@(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. - -} DELETED code-docs/scribble-helpers.rkt Index: code-docs/scribble-helpers.rkt ================================================================== --- code-docs/scribble-helpers.rkt +++ code-docs/scribble-helpers.rkt @@ -1,79 +0,0 @@ -#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))))) - DELETED code-docs/scribble-iframe.html Index: code-docs/scribble-iframe.html ================================================================== --- code-docs/scribble-iframe.html +++ code-docs/scribble-iframe.html @@ -1,13 +0,0 @@ -<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> DELETED code-docs/series.scrbl Index: code-docs/series.scrbl ================================================================== --- code-docs/series.scrbl +++ code-docs/series.scrbl @@ -1,74 +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" - 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. - -} - DELETED code-docs/snippets-html.scrbl Index: code-docs/snippets-html.scrbl ================================================================== --- code-docs/snippets-html.scrbl +++ code-docs/snippets-html.scrbl @@ -1,161 +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") - -@(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). -} DELETED code-docs/source-diagram.png Index: code-docs/source-diagram.png ================================================================== --- code-docs/source-diagram.png +++ code-docs/source-diagram.png cannot compute difference between binary files DELETED code-docs/tour.scrbl Index: code-docs/tour.scrbl ================================================================== --- code-docs/tour.scrbl +++ code-docs/tour.scrbl @@ -1,137 +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") - -@(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. - DELETED crystalize.rkt Index: crystalize.rkt ================================================================== --- crystalize.rkt +++ crystalize.rkt @@ -1,285 +0,0 @@ -#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)))))))) ADDED pollen-old.rkt Index: pollen-old.rkt ================================================================== --- pollen-old.rkt +++ pollen-old.rkt @@ -0,0 +1,147 @@ +#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 ...)])) Index: pollen.rkt ================================================================== --- pollen.rkt +++ pollen.rkt @@ -1,147 +1,11 @@ #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 ...)])) +(require yarn/markup) + +(provide + (all-defined-out) + (all-from-out yarn/markup)) + +(module+ setup + (provide block-tags) + (define block-tags blocks-elements)) DELETED rss-feed.rkt Index: rss-feed.rkt ================================================================== --- rss-feed.rkt +++ rss-feed.rkt @@ -1,83 +0,0 @@ -#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)) DELETED series-list.rkt Index: series-list.rkt ================================================================== --- series-list.rkt +++ series-list.rkt @@ -1,34 +0,0 @@ -#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) DELETED tags-html.rkt Index: tags-html.rkt ================================================================== --- tags-html.rkt +++ tags-html.rkt @@ -1,313 +0,0 @@ -#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))) DELETED targets.rkt Index: targets.rkt ================================================================== --- targets.rkt +++ targets.rkt @@ -1,5 +0,0 @@ -#lang racket/base - -(provide targets) - -(define targets '(html)) DELETED util/init.rkt Index: util/init.rkt ================================================================== --- util/init.rkt +++ util/init.rkt @@ -1,15 +0,0 @@ -#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)) DELETED web-extra/font.css Index: web-extra/font.css ================================================================== --- web-extra/font.css +++ web-extra/font.css @@ -1,48 +0,0 @@ -/* 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; - } DELETED web-extra/logo.png Index: web-extra/logo.png ================================================================== --- web-extra/logo.png +++ web-extra/logo.png cannot compute difference between binary files DELETED web-extra/mark.svg Index: web-extra/mark.svg ================================================================== --- web-extra/mark.svg +++ web-extra/mark.svg cannot compute difference between binary files DELETED web-extra/martin.css.pp Index: web-extra/martin.css.pp ================================================================== --- web-extra/martin.css.pp +++ web-extra/martin.css.pp @@ -1,1066 +0,0 @@ -#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; } -} DELETED web-extra/normalize.css Index: web-extra/normalize.css ================================================================== --- web-extra/normalize.css +++ web-extra/normalize.css @@ -1,341 +0,0 @@ -/*! 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; -} ADDED web/font.css Index: web/font.css ================================================================== --- web/font.css +++ web/font.css @@ -0,0 +1,48 @@ +/* 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; + } ADDED web/logo.png Index: web/logo.png ================================================================== --- web/logo.png +++ web/logo.png cannot compute difference between binary files ADDED web/mark.svg Index: web/mark.svg ================================================================== --- web/mark.svg +++ web/mark.svg cannot compute difference between binary files ADDED web/martin.css.pp Index: web/martin.css.pp ================================================================== --- web/martin.css.pp +++ web/martin.css.pp @@ -0,0 +1,1066 @@ +#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; } +} ADDED web/normalize.css Index: web/normalize.css ================================================================== --- web/normalize.css +++ web/normalize.css @@ -0,0 +1,341 @@ +/*! 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; +} ADDED yarn-doc/cache.scrbl Index: yarn-doc/cache.scrbl ================================================================== --- yarn-doc/cache.scrbl +++ yarn-doc/cache.scrbl @@ -0,0 +1,246 @@ +#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]. + +} ADDED yarn-doc/crystalize.scrbl Index: yarn-doc/crystalize.scrbl ================================================================== --- yarn-doc/crystalize.scrbl +++ yarn-doc/crystalize.scrbl @@ -0,0 +1,61 @@ +#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. + +} ADDED yarn-doc/design.scrbl Index: yarn-doc/design.scrbl ================================================================== --- yarn-doc/design.scrbl +++ yarn-doc/design.scrbl @@ -0,0 +1,172 @@ +#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"))] + ADDED yarn-doc/dust.scrbl Index: yarn-doc/dust.scrbl ================================================================== --- yarn-doc/dust.scrbl +++ yarn-doc/dust.scrbl @@ -0,0 +1,287 @@ +#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. ADDED yarn-doc/main.scrbl Index: yarn-doc/main.scrbl ================================================================== --- yarn-doc/main.scrbl +++ yarn-doc/main.scrbl @@ -0,0 +1,58 @@ +#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"] ADDED yarn-doc/other-files.scrbl Index: yarn-doc/other-files.scrbl ================================================================== --- yarn-doc/other-files.scrbl +++ yarn-doc/other-files.scrbl @@ -0,0 +1,42 @@ +#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. + + ADDED yarn-doc/pollen.scrbl Index: yarn-doc/pollen.scrbl ================================================================== --- yarn-doc/pollen.scrbl +++ yarn-doc/pollen.scrbl @@ -0,0 +1,382 @@ +#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. + +} ADDED yarn-doc/scribble-helpers.rkt Index: yarn-doc/scribble-helpers.rkt ================================================================== --- yarn-doc/scribble-helpers.rkt +++ yarn-doc/scribble-helpers.rkt @@ -0,0 +1,79 @@ +#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))))) + ADDED yarn-doc/series.scrbl Index: yarn-doc/series.scrbl ================================================================== --- yarn-doc/series.scrbl +++ yarn-doc/series.scrbl @@ -0,0 +1,74 @@ +#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. + +} + ADDED yarn-doc/snippets-html.scrbl Index: yarn-doc/snippets-html.scrbl ================================================================== --- yarn-doc/snippets-html.scrbl +++ yarn-doc/snippets-html.scrbl @@ -0,0 +1,161 @@ +#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). +} ADDED yarn-doc/tour.scrbl Index: yarn-doc/tour.scrbl ================================================================== --- yarn-doc/tour.scrbl +++ yarn-doc/tour.scrbl @@ -0,0 +1,137 @@ +#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. + ADDED yarn-lib/info.rkt Index: yarn-lib/info.rkt ================================================================== --- yarn-lib/info.rkt +++ yarn-lib/info.rkt @@ -0,0 +1,11 @@ +#lang info + +(define collection "yarn") +(define version "0.9") + +(define pkg-desc "implementation part of \"yarn\"") +(define license 'BlueOak-1.0.0) +(define deps '("base" + "pollen" + "threading-lib" + "txexpr")) ADDED yarn-lib/markup.rkt Index: yarn-lib/markup.rkt ================================================================== --- yarn-lib/markup.rkt +++ yarn-lib/markup.rkt @@ -0,0 +1,152 @@ +#lang racket/base + +; SPDX-License-Identifier: BlueOak-1.0.0 +; This file is licensed under the Blue Oak Model License 1.0.0. + +;; Pollen “tag functions” that return elements of a Yarn AST. This AST can be +;; rendered into HTML or other formats (using, e.g., the yarn/render/html module). + +(require pollen/decode + pollen/tag + racket/string + txexpr + "index.rkt" + "string.rkt" + "tools.rkt" + yarn/path) + +(provide (all-defined-out)) + +(define (root . elems) + (print (validate-txexpr `(test ,@elems))) + (check-title elems) + (serialize-article-placeholder) + `(document ,@(decode-hardwrapped-paragraphs elems))) + +;; Customized paragraph decoder replaces single newlines within paragraphs +;; with single spaces instead of <br> tags (allow hard-wrapped paragraphs) +(define (decode-hardwrapped-paragraphs xs) + (define (no-linebreaks xs) + (decode-linebreaks xs " ")) + (decode-paragraphs xs 'paragraph #:linebreak-proc no-linebreaks)) + +;; Set a title if not already set +(define (check-title elems) + (cond + [(and (not (meta-set? 'title)) + (pair? elems) + ((tx-is? 'poetry #:has-attrs 'title) (car elems))) + (set-meta 'title (format "‘~a’" (attr-ref (car elems) 'title))) + (set-meta 'title-supplied? #t)] + [(not (meta-set? 'title)) + (set-meta 'title (if (pair? elems) (first-words elems 5) ""))])) + +;; Yarn AST: +;; (document Block-Contents) +;; Footnote definitions, index entry keys are stored in the metas + +;; Block-Content := +;; (heading #:level Inline-Contents) +;; | (paragraph Inline-Contents) +;; | (thematic-break style) +;; | (codeblock info Inline-Contents) +;; | (blockquote items := (item Block-Contents)) +;; | (poetry title style Block-Contents) +;; | (itemization style start Block-Contents) +;; | (dialogue speeches := (speech interlocutor Block-Contents)) +;; | (figure source caption) +;; | (margin-note Block-Contents) + +;; Inline-Content := +;; string? +;; | (italic Inline-Contents) +;; | (bold Inline-Contents) +;; | (link destination Inline-Contents) +;; | (monospace Inline-Contents) +;; | (strikethrough Inline-Contents) +;; | (caps Inline-Contents) +;; | (image description source) +;; | (xref type dest-key Inline-Contents) +;; | (footnote-ref label) +;; | line-break + +(define blocks-elements + '(heading + paragraph + thematic-break + codeblock + blockquote + poetry + itemization + dialogue + figure + margin-note)) + +(define inline-elements + '(italic + bold + link + image + xref + footnote-ref + line-break)) + +(define (title . t) (set-meta 'title t) (set-meta 'title-supplied? #t) "") +(define (section . s) `(heading [[level "2"]] ,@s)) +(define (subsection . s) `(heading [[level "3"]] ,@s)) +(define (excerpt . e) (set-meta 'excerpt e)) +(define (excerpt* . e) (apply excerpt e) `(@ ,@e)) + +(define (pause [type 'blank]) `(thematic-break ,type)) ; type = blank | mark + +(define codeblock (default-tag-function 'codeblock #:info "")) +(define blockquote (default-tag-function 'blockquote)) ; #:caption +(define figure (default-tag-function 'figure)) + +(define (i . inline) `(italic ,@inline)) +(define em i) +(define (b . inline) `(bold ,@inline)) +(define (mono . inline) `(monospace ,@inline)) +(define (caps . inline) `(caps ,@inline)) +(define (strike . inline) `(strikethrough ,@inline)) +(define br 'line-break) + +(define (link ref . elems) `(link ,ref ,@elems)) +(define (url ref URL) (update-metas-subhash 'urls ref URL) "") + +(define (xref type elems k) + (define key (or k (normalize-key (->text elems)))) + (cons-to-metas-list 'xref-keys key) + `(xref ,type ,key ,@elems)) + +(define (pin #:key [key #f] . elems) (xref 'idx elems key)) +(define (def #:key [key #f] . elems) (xref 'def elems key)) +(define (ref #:key [key #f] . elems) (xref 'ref elems key)) + +(define (fn ref) `(footnote-ref ,ref)) +(define (fndef ref . elems) (update-metas-subhash 'footnote-defs ref elems) "") + +(define (ol . elems) `(itemization [[start "1"]] ,@elems)) ; #:style +(define (ul . elems) `(itemization ,@elems)) ; #:style +(define (item . blocks) `(item ,@blocks)) + +(define (dialogue . speeches) `(dialogue ,@speeches)) +(define (say interlocutor elems) `(speech ,interlocutor ,@elems)) +(define (saylines interlocutor elems) + `(speech ,interlocutor ,@(decode-linebreaks elems 'line-break))) + +(define verse (default-tag-function 'poetry)) ; #:title, #:style + +(define-tag-function (note attrs elems) + (let* ([note-count (update-meta 'note-count add1 0)] + [note-id (string-append (attr-ref attrs 'date) (format "_~a" note-count))] + [maybe-disp (string-split (attr-ref attrs 'disposition ""))] + [the-note (attr-set* `(note ,attrs ,@elems) 'id note-id 'parent (here-output-path))]) + (cond + [(> (length maybe-disp) 1) + (set-meta 'disposition `(,(car maybe-disp) + ,(string-join (cdr maybe-disp)) + ,note-id))]) + (cons-to-metas-list 'notes the-note) + (serialize-note the-note note-count) + "")) ADDED yarn-lib/path.rkt Index: yarn-lib/path.rkt ================================================================== --- yarn-lib/path.rkt +++ yarn-lib/path.rkt @@ -0,0 +1,28 @@ +#lang racket/base + +; SPDX-License-Identifier: BlueOak-1.0.0 +; This file is licensed under the Blue Oak Model License 1.0.0. + +(require pollen/core + pollen/file + pollen/setup + racket/path) + +(provide here-source-path + here-output-path) + +(define (identity v) v) + +;; Return the path to the current Pollen source, relative to project root +(define (here-source-path #:string? [string? #t]) + (define proc (if string? path->string identity)) + (cond + [(current-metas) + (proc (find-relative-path (current-project-root) (hash-ref (current-metas) 'here-path)))] + [else "."])) + +;; Return the path to the output filename for the current Pollen source, +;; relative to project root +(define (here-output-path #:string? [string? #t]) + (define proc (if string? path->string identity)) + (proc (->output-path (here-source-path #:string? #f)))) ADDED yarn-lib/render/html.rkt Index: yarn-lib/render/html.rkt ================================================================== --- yarn-lib/render/html.rkt +++ yarn-lib/render/html.rkt @@ -0,0 +1,163 @@ +#lang racket/base + +; SPDX-License-Identifier: BlueOak-1.0.0 +; This file is licensed under the Blue Oak Model License 1.0.0. + +;; Renders a Yarn AST and metadata into HTML + +(require "../tools.rkt" + "../string.rkt" + "../path.rkt" + koyo/haml + pollen/core + pollen/decode + racket/function + racket/list + racket/match + racket/string + txexpr) + +(provide doc->html) + +;; TODO: most of this should all go into the template code +(define (doc->html doc) + (define-values (title-type class) + (if (meta-set? 'title-supplied?) + (values 'given "with-title") + (values 'generated "no-title"))) + (haml + (:article.h-entry + [[:class class]] + ,@(heading/permlink title-type) + (:section.entry-content + ,@(decode-elements #:block-txexpr-proc render-block + #:inline-txexpr-proc render-inline + (cdr doc)))))) + +;; TODO: This should really go into the template code +(define (heading/permlink title-type) + (define m (current-metas)) + (define p (hash-ref m 'published)) + (case title-type + [(given) + (haml + (:h1.entry-title ,@(hash-ref m 'title)) + (:p.time + (:a.rel-bookmark + [[:href (string-append "/" (here-output-path))]] + (:time.published [[:datetime p]] (ymd->english p)))))] + [(generated) + (haml + (:h1 + (:a.rel-bookmark + [[:href (string-append "/" (here-output-path))]] + (:time.entry-title [[:datetime p]] (ymd->english p)))))])) + +;; Block-Content := +;; ✅ (heading level Inline-Contents) +;; | ✅ (paragraph Inline-Contents) +;; | ✅ (thematic-break style) +;; | ✅ (codeblock info Inline-Contents) +;; | ✅ (blockquote items := (item Block-Contents)) +;; | ✅ (poetry title style Block-Contents) +;; | ✅ (itemization style start Block-Contents) +;; | ✅ (dialogue speeches := (speech interlocutor Block-Contents)) +;; | ✅ (figure source caption) +;; | (margin-note Block-Contents) + +(define (render-block e) + (match e + [(list 'heading (list (list 'level lev)) elems ...) (render-heading lev elems)] + [(list 'paragraph elems ...) `(p ,@elems)] + [(list 'thematic-break style) `(hr [[class ,style]])] + [(list 'blockquote elems ...) `(blockquote ,@elems)] + [(txexpr 'poetry attrs elems) (render-poetry attrs elems)] + [(txexpr 'codeblock attrs elems) (render-codeblock attrs elems)] + [(txexpr 'itemization attrs elems) (render-itemization attrs elems)] + [(txexpr 'dialogue _ elems) `(dl ,@elems)] + [(list 'speech interlocutor elems ...) + `(@ (dt ,interlocutor (span [[class "x"]] ": ")) (dd ,@elems))] + [(txexpr 'figure attrs elems) (render-figure (car elems) (cdr elems))] + [else (raise-argument-error 'render-block "block-content" e)])) + +;; Inline-Content := +;; string? +;; | ✅ (italic Inline-Contents) +;; | ✅ (bold Inline-Contents) +;; | ✅ (link destination Inline-Contents) +;; | ✅ (monospace Inline-Contents) +;; | ✅ (strikethrough Inline-Contents) +;; | ✅ (caps Inline-Contents) +;; | (image description source) +;; | ✅ (xref type dest-key Inline-Contents) +;; | ✅ (footnote-ref label) +;; | line-break + +(define (render-inline e) + (match e + [(list 'italic elems ...) `(i ,@elems)] + [(list 'bold elems ...) `(b ,@elems)] + [(list 'monospace elems ...) `(samp ,@elems)] + [(list 'strikethrough elems ...) `(del ,@elems)] + [(list 'caps elems ...) `(span [[class "caps"]] ,@elems)] + [(list 'link dest elems ...) (render-link dest elems)] + [(list 'xref type key elems ...) (render-xref type key elems)] + [(list 'footnote-ref ref) (render-footnote-ref ref)] + [(list 'item elems ...) `(li ,@elems)] + [else e])) + +(define (render-link dest elems) + (define url + (or (get-metas-subhash 'urls dest) + (format "#Missing_Reference_~a" dest))) + `(a [[href ,url]] ,@elems)) + +(define (render-heading level elems) + (define tag (string->symbol (format "h~a" level))) + `(,tag ,@elems)) + +(define (render-poetry attrs elems) + (define title + (match (attr-ref attrs 'title attrs #f) + [(? string? t) `(p [[class "verse-heading"]] ,t)] + [_ ""])) + (define pre-attrs + (cond + [(string-contains? (attr-ref attrs 'style "") "italic") + '((style "font-style: italic"))] + [else '()])) + `(div [[class "poem"]] ,title (pre [[class "verse"] ,@pre-attrs] ,@elems))) + +(define (render-codeblock attrs elems) + (define file (or (assoc 'filename attrs) "")) + (define codeblock `(pre [[class "code"]] (code ,@elems))) + (cond [(non-empty-string? file) `(@ (div [[class "listing-filename"]] 128196 " " ,file) ,codeblock)] + [else codeblock])) + +(define (render-itemization attrs elems) + (define tag (if (attr-ref attrs 'start #f) 'ol 'ul)) + `(,tag ,attrs ,@elems)) + +(define (render-figure source elems) + `(figure [[class "fullwidth"]] + (img [[src ,source]] [[alt ,(->text elems)]]) + (figcaption ,@elems))) + +;; The AST guarantees that they key will already be URI-safe +(define (render-xref type key elems) + `(a [[id ,(here-key (format "_~a-~a" type key))] + [href ,(string-append "/keyword-index.html#" key)] ; TODO: ref type links need to resolve to the target + [data-index-entry ,key] + [class ,(symbol->string type)]] + ,@elems)) + +(define (render-footnote-ref ref) + (cons-to-metas-list 'fn-names ref) + (let* ([here (here-key)] + [fn-names (hash-ref (current-metas) 'fn-names)] + [def-anchor (format "#~a_fndef_~a" here ref)] + [nth-ref (number->string (count (curry equal? ref) fn-names))] + [ref-id (format "#~a_fn_~a_~a" here ref nth-ref)] + [fn-number (+ 1 (index-of (remove-duplicates (reverse fn-names)) ref))] + [ref-text (format "(~a)" fn-number)]) + `(sup (a [[href ,def-anchor] [id ,ref-id]] ,ref-text)))) ADDED yarn-lib/string.rkt Index: yarn-lib/string.rkt ================================================================== --- yarn-lib/string.rkt +++ yarn-lib/string.rkt @@ -0,0 +1,114 @@ +#lang racket/base + +(require gregor + racket/match + racket/string + txexpr) + +(provide ->text + first-words + ymd->english) + +(module+ test (require rackunit)) + +;; Concatenate the string elements of a txexpr or list together +(define (->text v) + (match v + [(txexpr _ _ elements) (->text elements)] + [(list elements ...) (string-append* (map ->text elements))] + [(? string? s) s] + [_ ""])) + +;; Return the first N words out of a list of txexprs. This function will unpack the strings out of +;; the elements of one txexpr at a time until it finds the requested number of words. It aims to be +;; both reliable and fast for any size of list you pass it, and smart about the punctuation it +;; allows through. + +(define punc-allowed-in-word '(#\- #\' #\% #\$ #\‘ #\’ #\# #\& #\/ #\. #\!)) + +(define (word-boundary? c) (or (char-whitespace? c) (equal? c #\null) (eof-object? c))) +(define (word-char? c) (or (char-alphabetic? c) (char-numeric? c))) + +(define (first-words txprs words-needed) + (define in (open-input-string (->text (car txprs)))) + (define out (open-output-string)) + + (define words-found + (let loop ([words-found 0] [last-c #\null] [last-c-in-word? #f]) + (define c (read-char in)) + + (cond [(equal? words-found words-needed) words-found] + [(eof-object? c) + (cond [(positive? words-found) (if last-c-in-word? (+ 1 words-found) words-found)] + [else 0])] + [else + (define-values (write-this-char? new-word-count c-in-word?) + (cond + ;; Spaces increment the word count if the previous character was part of, + ;; or adjacent to, a word + [(and (char-whitespace? c) last-c-in-word?) + (values (if (equal? words-needed (+ 1 words-found)) #f #t) (+ 1 words-found) #f)] + ;; Some punctuation survives if the previous or next char is part of a word + [(member c punc-allowed-in-word) + (cond [(or (word-char? last-c) (word-char? (peek-char in))) + (values #t words-found #t)] + [else (values #f words-found #f)])] + [(word-char? c) + (values #t words-found #t)] + ;; If c is a non-whitespace non-allowed character that immediately follows a word, + ;; do not write it out but count it as being part of the word. + [(and (not (word-char? c)) (not (char-whitespace? c)) last-c-in-word?) + (values #f words-found #t)] + [else (values #f words-found #f)])) + + (cond [(and (char-whitespace? c) write-this-char?) (write-char #\space out)] + [write-this-char? (write-char c out)]) + (loop new-word-count c c-in-word?)]))) + + (define words (get-output-string out)) + (cond [(equal? words-found words-needed) (string-append words "…")] + [(equal? '() (cdr txprs)) words] + [else (string-append words " " (first-words (cdr txprs) (- words-needed words-found)))])) + +(module+ test + (require rackunit) + (define txs-decimals + '((p "Four score and 7.8 years ago — our fathers brought forth on this continent etc etc"))) + (define txs-punc+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!"))) + + (check-equal? (first-words txs-decimals 5) "Four score and 7.8 years…") + (check-equal? (first-words txs-punc+split-elems 5) "Stop! she called. She was…") + (check-equal? (first-words txs-dashes 5) "One and only one. That…") + (check-equal? (first-words txs-dashes 4) "One and only one.…") + (check-equal? (first-words txs-parens-commas 5) "She counted one two silently…") + (check-equal? (first-words txs-short 5) "Not much here!")) + +;; ~~~ Convenience functions for YYYY-MM-DD date strings ~~~ + +;; These functions ignore everything after the first space in the input! +(define (ymd->dateformat ymd-string dateformat) + (~t (iso8601->date (car (string-split ymd-string))) dateformat)) + +(define (ymd->english ymd-string) + (ymd->dateformat ymd-string "MMMM d, yyyy")) + +(module+ test + (check-equal? (ymd->english "2018-08-12") "August 12, 2018") + (check-equal? (ymd->dateformat "2018-08-12" "d MMM YYYY") "12 Aug 2018") + + ;; How we handle weird input + (check-equal? (ymd->english "2018-08-12 everything after 1st space ignored") "August 12, 2018") + (check-equal? (ymd->english "2018-08 omitting the day") "August 1, 2018") + (check-equal? (ymd->english "2018 omitting month and day") "January 1, 2018") + (check-equal? (ymd->dateformat "2018-08-12" "123") "123") + + ;; Stuff we just don't handle + (check-exn exn:gregor:parse? (lambda () (ymd->english "2018-xyz")))) ADDED yarn-lib/tools.rkt Index: yarn-lib/tools.rkt ================================================================== --- yarn-lib/tools.rkt +++ yarn-lib/tools.rkt @@ -0,0 +1,109 @@ +#lang racket/base + +(require file/sha1 + pollen/core + racket/file + racket/list + racket/string + threading + txexpr) + +(provide (all-defined-out)) + +;; Convert a string into all lowercase, delete all non-alphanum chars, replace spaces with ‘-’ +(define (normalize-key str) + (~> (string-downcase str) + (regexp-replace #rx"ies$" _ "y") + (string-trim "s" #:left? #f) + (regexp-replace* #rx"[^A-Za-z0-9 ]" _ "") + (string-normalize-spaces #px"\\s+" "-"))) + +;; ~~ Metas reference and updating ~~~~~~~~~~~~~~~ + +;; Computes a unique string key for the current Pollen source and stashes it in the metas +(define (here-key [suffix ""]) + (define metas (current-metas)) + (define (set-here-key!) + (set-meta 'here-key + (~> (hash-ref metas 'here-path) + string->bytes/utf-8 + sha1-bytes + bytes->hex-string + (substring 0 8)))) + (string-append (hash-ref metas 'here-key set-here-key!) suffix)) + +;; +;; Meta tools ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(define (meta-set? key) + (and (hash-ref (current-metas) key #f) #t)) + +(define (set-meta key val) + (current-metas (hash-set (current-metas) key val)) + val) + +(define (update-meta key proc default) + (let ([updated (proc (hash-ref (current-metas) key default))]) + (set-meta key updated))) + +(define (cons-to-metas-list key val) + (define consed (cons val (hash-ref (current-metas) key '()))) + (current-metas (hash-set (current-metas) key consed)) + consed) + +(define (update-metas-subhash key subkey val [proc (λ (v) v)]) + (define metas (current-metas)) + (define subhash (hash-ref metas key hasheq)) + (set-meta key (hash-set subhash subkey (proc val)))) + +(define (get-metas-subhash key subkey) + (hash-ref (hash-ref (current-metas) key #hasheq()) subkey #f)) + +;; Returns a function will test if a txexpr's tag matches the given symbol and +;; (optionally) contains all given attributes. +(define (tx-is? t #:has-attrs [a '()]) + (define tags (if (list? t) t (list t))) + (define attrs (if (list? a) a (list a))) + (lambda (v) + (and (txexpr? v) + (member (get-tag v) tags) + (andmap (λ (attr) (attrs-have-key? a attr)) attrs) + #t))) + +;; “Notes”, in addition to being attached to/contained in articles, are also +;; shown alongside articles in the chronological feed. To make building this +;; mixed chronological feed faster, articles and notes create files in a +;; “serialize” subfolder at compile time: +;; * The filenames are prefixed with the thing’s YMD date. +;; * Note-files contain a datum of the entire note. +;; * Article-files contain only the path to the article’s source. +;; +;; This way building the chrono feed is simple and doesn’t require loading +;; and sorting the docs/metas of the entire article set. + +(define serialize-folder "compiled/.serialized") + +(define (current-serialize-folder-path) + (and~> (hash-ref (current-metas) 'here-path #f) + explode-path + (drop-right 1) + (append (list serialize-folder)) + (apply build-path _))) + +;; +;; TODO: Possible speed gains by spawning a thread to do this +(define (serialize-article-placeholder) + (let* ([ser-folder (current-serialize-folder-path)] + [filename (format "~a.article" (hash-ref (current-metas) 'published))] + [placeholder (build-path ser-folder filename)]) + (unless (directory-exists? ser-folder) (make-directory ser-folder)) + (unless (file-exists? placeholder) + (write-to-file (hash-ref (current-metas) 'here-path) + (build-path ser-folder filename) + #:exists 'truncate)))) + +(define (serialize-note note num) + (let ([ser-folder (current-serialize-folder-path)] + [filename (format "~a_~a.note" (attr-ref note 'date) num)]) + (unless (directory-exists? ser-folder) (make-directory ser-folder)) + (write-to-file note (build-path ser-folder filename) #:exists 'truncate)))