DOASでCSSの概要を記述する

バージョン0.91のDOASに対応しました。

CSSを書くときに、そのそれが何の役割をするのか(どこをスタイリングするのか)という概要をどう書いたらよいのか迷うことがあります。

特に大人数で作業している場合は形式を決めておきますが、他人が書いたものだとどうも区切り線[1]や改行のタイミングが気に入らなかったりします。僕はというと、3ping.orgさんの「CSSのコメントの書き方コレアレ」という記事を参考に、import.cssに各CSSの概要をまとめて書いていました。

何か自分を納得できるような形式がないか探していて、DOASを見つけました。これはかなりよいのではないかと思って早4ヶ月[2]、やっとエントリ書けました:-<

DOAS : Description of a Script/Stylesheet vocabularyとは

主として単一ファイルで完結しているJavaScript, perl, phpなどのスクリプトやXSLT, CSSなどのスタイルシートの概要を、ファイル内に記述するための語彙。(名前空間宣言を節約してシンプルに記述するための)DOAPの派生語彙。日本語によるプロパティあり。

このリンク先の冒頭にも書かれているように、これは神崎氏が作成者であるようです。[3]また、バージョンが0.73(2007年3月29日に修正されています)0.91(2008年1月7日に修正されています)であることから作成段階のものなのでしょうか。

たぶん説明するよりサンプル見た方が早いですね。

サンプル

僕のぬかみそCSSに書いているDOASの例を挙げておきます。
書き方は参照先をみれば分かると思いますし、そのCSSを開いてみてもよいかもしれません。

ちょっとしたメモ – DOASとTurtle/RDFにて、DOASの使用法のより詳細な解説とRDFとの対応についての記事が公開されています。DOASに興味がある方はぜひそちらもご覧下さい。

/**
@prefix : <http://purl.org/net/ns/doas#> .
<http://versionfive.jp/css/default.css> a :CSSstylesheet;
 :title "Default Stylesheet - VERSIONFIVE";
 :shortdesc "Default stylesheet for XHTML pages of this site.";
 :created "2007-08-14";
 :release [:revision "2.0.1"; :created "2007-12-25"];
 :author [:name "VERSIONFIVE"; :homepage <http://versionfive.jp/> ];
 :license <http://creativecommons.org/licenses/by/3.0/> .
*/

はじめに引用したところにもあるように、各プロパティには日本語名が用意されているのでそちらを使ってもよいと思います。

バージョン0.91にて、releaseの日本語名が改訂版から公開版に変更になっています。

/**
@prefix : <http://purl.org/net/ns/doas#> .
<http://versionfive.jp/css/default.css> a :CSSstylesheet;
 :タイトル "デフォルトスタイルシート - VERSIONFIVE";
 :一行説明 "このサイトのXHTMLページのデフォルトスタイルシート.";
 :作成日 "2007-08-14";
 :公開版 [:版 "2.0.1"; :作成日 "2007-12-25"];
 :作成者 [:名 "VERSIONFIVE"; :ホームページ <http://versionfive.jp/> ];
 :ライセンス <http://creativecommons.org/licenses/by/3.0/> .
*/

まとめ、関連情報

上の例のように、決まった形式が指定されているとすごく心が安らぐのはXHTMLとか書く人間だからでしょうか。
DOASのよいところは、CSSだけでなくJavaScriptやPHPなどにも同じ形式で概要を書くことができるところです。マークアップエンジニアが書く言語は大体カバーできていますね。

CSSの概要の書き方に困っている方、いかがでしょう。

関連情報

多少関連した話として、Javadocのように、CSSに書いたコメントから仕様書を生成するcssdocというプロジェクトも草案段階で動いているそうです。(via : JACK THREE FIVE)

いつもは自分(もしくはプロジェクトメンバー)のために書いているコメントを再利用できるのは便利ですね。

  1. 例 : ハイフン"-"とかイコール"="とかシャープ"#"とかアスタリスク"*"とか [back]
  2. 当時のブックマーク [back]
  3. 名前空間(namespace)に指定されているURI(http://purl.org/net/ns/doas#)をたたいてみると同ページにリダイレクトされます。 [back]

「DOASでCSSの概要を記述する」への6件のフィードバック

  1. DOASは何だかステキですね。
    :license . の記述の箇所ですが、仕事などの関係でCreative Commonsの「本作品を複製、頒布、展示、実演することができます。」にはしたくない場合、どのように記述すべきでしょうか。
    サイト名でよいのでしょうか。。

  2. >なかにしゆうすけさん
    神崎氏による定義ファイルのlicenseのプロパティの欄には以下のようにあります。

    rdfs:comment
    The URI of the license the program is distributed under
    rdfs:comment(@ja)
    プログラムのライセンスを表すURI。

    ということで、おそらくURIを記述するべきなのかな?
    作られているサイトにライセンスについて言及されているページ(の一部)があるのでしたら、そこのURIを記述しておけばよいかと思います。

  3. なるほど。ご丁寧にありがとうございます。
    DOASをつかってわかりやすいサイト構築を心がけていこうと思います。

  4. >なかにしゆうすけさん
    自分も勉強不足でした><
    決まったフォーマットが与えられるとつくりやすくなりますよね、僕ももっと勉強します。

  5. のっさん、いつもお世話になってますヽ(・ω・)ノ

    DOAS の license について、rights という項目もありますよ。
    http://www.kanzaki.com/ns/doas#rights
    内容には「プログラムの権利を記述するテキスト。」とあるので、
    Copyright © 2008 xxxxx All Rights Reserved. とか、
    この○○に関する一切の権利は■■にあります。
    などと書けばいいのではないでしょうか。

  6. >石澤 りんさん
    これはどうもです!

    DOAS の license について、rights という項目もありますよ。

    ほんとですね、これは気づかなかった・・・勉強不足です。
    今再度見るとバージョンもこのエントリを書いた0.73から0.91に上がって多少変更点もあるようですし、追記したいと思います。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

CAPTCHA