README
A quick bit of documentation for my markup conventions.
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.