Boblet Coding Style Guide

By Oli
At 6:25 PM · Sunday, 2 November · 2003
To CSS · Coding · HTML · Weblogging

This is a self-reference on how to code for Boblet. Feel free to ignore (unless you are interested in the why’s and how’s of my code).

Inserting and deleting text; <ins> & <del>

If I edit a story after publication it’s generally to correct mistakes (usually spelling, but possibly factual errors), or to add additional information. I’m not going to mark up corrections to spelling mistakes. Here’s how I mark up the bigger stuff (the same code is applicable to del):

<ins datetime="yyyy-mm-ddThh:mm:ss+9" title="" cite="" class=""> </ins>
datetime is the year, month and day, followed by a “T” for time then hour (24 hour clock), minute and second, finally followed by the time from UTC (for Japan this is “+9”). This is described in the W3’s Date and Time Note, and 4Reference lists other time zones’ difference to UTC
title and cite are for describing the reason or providing a link to the reason for the change. I might use title occasionally.
I use class to distinguish between in-line and block inserts/deletes. Block-level ones should have the class class="insdel-block", allowing them to have a different style (presently ins has a red dotted underline for inline, and a red dotted left border for block. Presently del is not displayed).

Citing references; <cite>

Citation can be a rather general concept applicable to people, books, movies, companies and other reference sources (including websites). I distinguish between these via CSS classes:

<cite class="" title=""> </cite>

I generally don’t use the title attribute because what is cited is usually clear from context. Here are the class attribute names I use:

  • class="cite-person" (full name, usually when quoting as a reference)
  • class="cite-com" (company name, for websites the site name without “www”)
  • class="cite-book"
  • class="cite-film"

At the moment I’m wrapping any cited Japanese words in a span then a cite. This is not exactly semantic, so it’s possible I’ll use the lang & xml:lang attributes someday if my Japanese gets good enough to cite Japanese things regularly.

Representing code; <code>

I’m planning to implement Sean Voisen’s MTCodeBeautifier plugin at some stage for HTML and CSS code at some stage. This would mean converting Beautifier.org templates to MTCodeBeautifier format, which looks tough (I don’t use any of the languages Sean has converted :/ ). However I don’t want to use his system of specifying a language attribute to denote the code’s language, because this isn’t an official attribute (it used to be used for <script>, but has been depreciated in favour of type mime types). I can’t even use the lang attribute with a user-defined language code because Computer languages are explicitly excluded from language codes. So I’ve used classes like for <cite>, plus a title tag. Mixed code sources will be tagged according to what’s most relevant.

<code title="" class=""> </code>
  • <code title="HTML code" class="code-html">
  • <code title="CSS code" class="code-css">
  • <code title="PHP code" class="code-php">
  • <code title="MT code" class="code-mt"> (for MovableType)

When listing a block of code (rather than in-line), I put the code in <blockquote><p> </p></blockquote> tags. Paul Hammond has written about various ways to mark up code, and I agree with his conclusions.

Japanese language — using <span>

I use a UTF-8 charset so I can use Japanese. If I used Shift_JIS (a Japanese character set that allows Japanese and English/Romanji), users of older versions of English Windows IE get prompted for a Japanese language support download (note that I don’t know if these older browsers include Unicode support). And of course plain text doesn’t exist.

However, marking up foreign languages can be hard. For example, there is no official way to tag Japanese text written in English (romanji). What I’ve done is based on Jonathon Delacour’s article on marking up Japanese semantically, although my conclusion and his are different.

<span lang="ja" xml:lang="ja" title="Romanji; English definition">Japanese in Romanji•(Japanese)</span>
The lang & xml:lang attributes are for HTML and XHTML-compliant browsers respectively. “ja” is the Japanese language code.
I use the title attribute to give the Japanese word or phrase in Romanji, plus a translation in English. The Romanji is usually the same as the text I’m tagging, but is sometimes more detailed (eg ‘Beat’ Takeshi -> ‘Beat’ Takeshi Kitano).

This tag encloses both the word/phrase in Romanji and in Japanese (kanji/kana). The Japanese text is enclosed in brackets () (or Japanese quotes 「�? if it’s eg a movie title) and separated from the romanji by a “・”. Kanji name breaks are also indicated by this dot to make reading easier. I’ve used Japanese brackets up to now “（）” which have a big space associated with them. I’m considering to change to using an English space-bracket combination ” () “, so Japanese text blends into English prose better. I use Hepburn romanisation, and to represent long vowels I use macron character entities, which unfortunately don’t have short names. Here are the decimal codes:

Displayed entity Decimal code Definition
ā &#257; Small a with macron
ī &#299; Small i with macron
ū &#363; Small u with macron
ē &#275; Small e with macron
ō &#333; Small o with macron
Ā &#256; Capital A with macron
Ī &#298; Capital I with macron
Ū &#362; Capital U with macron
Ē &#274; Capital E with macron
Ō &#332; Capital O with macron

Jonathon also has a great tutorial on Japanese text, including how to implement Japanese language support on your computer, and how to configure MT to display Japanese

Discussion...

Comments (2) · TrackBacks (0)  to  http://www.boblet.net/cgi-bin/mttb-external.cgi/32
1. Comment by catlin gaudet  · 28 Jan, 2004 · 6:06 PM

[Comment removed; off-topic]

2. Comment by mauriz  · 31 Jan, 2004 · 2:39 AM

Why not use MIME types as class for code?