Local Yarn Code

Design and Layout

The design and implementation of The Local Yarn are guided by a few basic requirements.

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. So the first requirement is that addenda to older articles, even articles from several years ago, should be extremely visible. These addenda should also be able to mark major shifts in the author’s own perspective on what they originally wrote.

The writing will live in two places: on a web server, and on bookshelves. 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 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.

Finally: everything produced here, both in print and on the web, should look good.

“Yet modest ornament with use combined
Attracts the eye to exercise the mind.”
Samuel Rogers

Names for things and how they fit together

Because of its dual print/web nature, and because it is somewhat more complicated than your typical blog, I’ve come up with a set of common terms to describe everything.

The Local Yarn is mostly comprised of Articles (individual writings) which may contain Notes (addenda by the author or others) and may also be grouped into Series. These are similar to a typical blog’s posts, comments and categories, but there are important differences (see Differences from blogs).

Articles

An article can start out very small — just a date and a few sentences — and later grow in any of several directions. 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.

Articles have the following properties:

  • A publish date and an optional last updated date.
  • An optional title
  • An author (optional)
  • A series (optional) to which the article belongs, which also indirectly determines the article’s singular noun.
  • A document body. The structure and features of the body text follow from Pollen Markup.
  • A conceal directive (optional) that can be used to prevent display of the article in various contexts: series listings, in print editions, or in the RSS feed. The template used for new/draft articles will include a directive to conceal from all of these by default. (Such an article, if included in a sync to the live web server, will still be accessible on the web via its direct URI.)
  • Optionally, one or more follow-up Notes — any of which may also indirectly determine the article’s disposition verb (e.g. “disavowed”) and disposition date (which is the date of the Note). If more than one note in an article specifies a disposition verb, the most recent one takes precedence.

Series

A Series is like an article in that it has its own body, but it has the additional effect of grouping individual articles together into a particular order. It has the following properties:

  • A name
  • A creation date
  • An order for its member articles, which can be one of:
    1. Reverse chronological, or Blog order
    2. Ascending chronological, or Journal order
    3. Arranged by subject matter (as with chapters in a book), or Pagetree order
  • A plural noun which applies to all its member articles as a group (e.g. “Speculations”)
  • A singular noun with an indefinite article “a” or ”an”, which applies to each of its member articles individually (e.g. “a speculation”).
  • A document body which appears on the series’s main page, and whose markup also dictates whether/how the listing of its member articles will be presented.