README

This post is even less likely to be interesting than the “how” post. I realized that I’ve now implemented a bunch of syntactic shortcuts and failed to properly document them anywhere. I was going to write a README to myself, but then decided I might as well post it.

Biliographic metadata

These fields are recognized in the bibliographic metadata paragraph. Any unrecognized field is simply copied through with the @error flag set. (So “:foo: bar” becomes “<foo error="true">bar</foo>”.)

:uri: · The URI of the post. Must begin with a slash, must not end with a slash, must consist only of reasonable URI characters.

:volnum: · The volume number. Optional. On initial posting, defaults to the current volume. Preserved automatically for subsequent repostings.

:issuenum: · The issue number. Optional. On initial posting, defaults to the next issue. Preserved automatically for subsequent repostings.

:pubdate: · The published date. Must be an xs:dateTime. On initial posting, defaults to fn:current-dateTime(). Preserved automatically for subsequent repostings.

:author: · The author. Optional. Defaults to me.

:copy: · The copyright. Optional. Defaults to the current year.

:where: · The identifier for a location. Location identifiers are uploaded separately. The @error flag is set if the location is unknown. May be repeated.

:subject: · The identifier for a subject. Subject identifiers must be part of the subject taxonomy, uploaded separately. The @error flag is set if the subject is unknown. May be repeated.

Confusingly, the :subject: identifiers are described as “topics” in the weblog and the Wikipedia, people, and other arbitrary URIs are described as “subjects”. I should probably fix that by changing this keyword to :topic:.

:wikipedia: · A Wikipedia topic (the part of the Wikipedia URI after /wiki/). This tag makes the specified Wikipedia topic a subject for the post, even if the article is not explicitly mentioned inline.

:rdfsubj: · Tags a URI as a “subject”. The format of this tag is:

:rdfsubj: http://example.com/ SubjectId Subject Label

It has the effect of making http://example.com/ a subject (meaning that it will appear in the list of subjects) with the short identifier “SubjectId” and the label “Subject Label”. The parts are delimited by spaces, so no spaces in the subject identifier!

If more complicated semantics are needed (a preferred label, for example, or a separate sort label), that can be done in extra.rdf, a separate upload.

Inline markup

Inline markup consists of strings of the form

{:keyword:token “string”}

These are parsed within the text of the raw HTML output that comes from the CommonMark parser.

:wiki: (or just :) · Inserts a link to the specified Wikipedia topic. If a string is not provided, the topic token is used as the link text.

:person: · Inserts a personal name as a subject. For ease and consistency of presentation, use the form {:person:Last,First “Name”}. If a preferred label is needed (because “Name” is sometimes “Norman Walsh” and sometimes “Norm”, for example), put it in extra.rdf, uploaded separately.

:t: · Inserts a reference to a twitter handle. Generates semantic data and a link. {:t:ndw} generates @ndw.

:tweet: · Inserts a reference to a specific tweet. For example, {:t:ndw} {:tweet:ndw/859606489325064192 “announced”} his new weblog: @ndw announced his new weblog.

:block: and :inline: · These forms leave markers in the HTML that can be processed later. A :block:tag leaves <x-block target="tag"></x-block> in the HTML. An :inline:tag leaves <x-inline target="tag"></x-inline> in the HTML. The only distinction between block and inline is that a block will be hoisted out of the paragraph that contains it. So:

This is some text with a {:block:foo} marker
and an {:inline:bar} marker.

will produce

<p>This is some text with a </p>
<x-block target="foo"></x-block>
<p> marker
and an <x-inline target="bar"></x-inline> marker.</p>

I’ve got a handful of places where I use this to inject markup computed by queries at the point of rendering rather than the point of POSTing.

:trip: · I generate XML itinerary markup from a variety of sources. The :trip: marker takes a trip id and inserts the markup so that it can be rendered.

:img: · The :img: marker inserts references to images on photos.nwalsh.com into a posting. The link and image source can be generated from a single tag. The “string”, if specified, becomes a caption. If no caption is provided, the image title (from the photo itself) is used as the caption.

Other markup

In epigraphs, a leading :attr: identifies the attribution of the quotation.

I think that’s it. I’ll try to remember to update this as things evolve.