Local Yarn Code

Design and Layout

There are two big priorities underlying the design of The Local Yarn.

The first is that it 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.

The other priority is simply that, in both media, the product should have a “functional attractiveness”, as embodied in this quote from Samuel Rogers that I’ve had on my site for twenty years:

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

Information model

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

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.

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.

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.

Visual Design

The stuff described above gets translated into web and print designs.

HTML markup

“Listing” context: complete articles/notes:

<!-- Article with a title -->
<article>
  <h1 class="entry-title hentry">ARTICLE TITLE</h1>
  <p class="time">
    <a href="#here" class="rel-bookmark">
      <time datetime="2017-11-08" class="published">November 8, 2017</time>
    </a>
  </p>
  <section class="entry-content">ARTICLE BODY
  </section> 
  <footer class="article-info">
    <span class="x">(</span>
    This is ARTICLE-NOUN, part of <a href="#">‘Series Name’</a>.
    <span class="x">)</span>
  </footer>
</article>

<!-- Article without a title -->
<article>
  <h1 class="no-title hentry">
    <a href="#here" class="rel-bookmark">
      <time datetime="2017-11-08" class="entry-title published">November 8, 2017</time>
    </a>
  </h1>
  <section class="entry-content">ARTICLE BODY
  </section>
  <footer class="article-info">
    <span class="x">(</span>
    This is ARTICLE-NOUN, part of <a href="#">‘Series Name’</a>.
    <span class="x">)</span>
  </footer>
</article>

<!-- Notes -->
<article class="with-title hentry">
  <h1 class="entry-title">A note from AUTHOR, re: <a class="cross-reference" href="#">PARENT-TITLE</a></h1>
  <p class="time"><a href="#here" class="rel-bookmark note-permlink">
    <time datetime="2004-04-24">April 24, 2004</time>
  </a></p>
  <section class="entry-content">
    NOTE CONTENTS
    <p class="signoff"><i>&mdash; <a href="AUTHOR-URL">AUTHOR</a></i></p>
  </section>
</article>

Coming at some point:

  • Typographic conventions
  • Web design notes (HTML markup structure, etc)
  • Print design notes