Web IDL、bikeshed、respec - 仕様書作成のための便利ツールを使いこなそう

本記事は、TechFeed Experts Night#1 〜 Web標準 / CSS / Webアクセシビリティを語ろうのセッション書き起こし記事になります。イベントページのタイムテーブルから、その他のセッションに関する記事もお読み頂けますので、一度アクセスしてみてください。

本セッションの登壇者

セッション動画（YouTubeチャンネル登録もお願いします。）

スライド資料はこちら

仕様開発者向けの便利ツールということで、いくつか最新の現状をお話ししようと思います。

MDNなど、いろいろと解説サイトもありますので、仕様本体まで見に行くということはそれほど頻繁ではないかもしれません。でも仕様書も昔に比べて最近はだいぶいろいろな情報がインテグレートされたり、周辺ツールもそろってきたりしていて、仕様以外も含んだ情報を見やすく載せているページという感じになりつつあります。

自動リンクによる相互参照が可能

サンプルとして見ていただきたいのですが、CSS Textでしたらここにあるように一番下にcaniuseなどのデータがあったり、緑のボックスとしてWebプラットフォームテストの○×状況が数字で書かれていたりします。右側のパネルで示しているのが本文の中です。各定義のところに関連するテスト一覧のパネルがあり、テストがどういうふうに通っているのか、ブラウザごとの状況が緑丸と赤丸で示されています。これらのテストを実際に自分で使っているブラウザで走らせることができるようにするためのリンクなどもあります。

今ここでは「manual」というところにポインタを当てていますが、ツールがサポートしてくれているおかげで、定義されているプロパティや、APIでしたら関数名/引数などのところにリンクが張られるようになっています。これに加えて仕様書の記述の中でもリンクが自動的に張られるようになっています。ただ、実際には少し文章で記述しているので完全自動ではありません。

Web IDLでさまざまな機能を実現

APIの側では、今のAPI仕様書はすべての部分がWeb IDLと呼ばれるインターフェース定義言語で記述されるようになっています。これはWebXR APIの仕様書ですが、関数名や引数、プロパティなどは全部extractできるような状態になっていて、さらにリンクが張られています。また、実際にそのAPIがどういう処理をするのかも基本的にマークダウンなどの形で書いておくと、自動的にこのようにIf ～ otherwiseなども含んでそれなりにきれいな形で見られるように成形してくれる機能が入っています。また、Web IDLなのでツールで引っ張り出してきてマイニングして、巨大なデータベースを作るといったことも行われるようになっています。

ここ(下図)には、MDNのパネルが表示されています。これはMDNのbrowser-compat-dataから取ってきていますが、どういうブラウザのどういうバージョンで使えるようになったかという情報も仕様書によっては取得して表示されるようになってきています。

2大ツールが併存して利用されている

最近の状況としては、仕様はbikeshedやrespecと呼ばれるツールで変換してHTMLを生成する形で書かれることが多く、その中で定義がWeb IDLで記述されるようになっています。また、リンクが自動的に生成されて、caniuseやbrowser-compat-dataなど、実装状況の取り込みも行われるようになっています。

2つのツールが並列に存在しており、使用するツールはグループによって異なりますが、bikeshedを使っているところが最近は多い印象です。また、このツールはC++など他の標準化団体でも使われています。標準化団体が共同で作成しているツールになりますので、さまざまな機能が取り込まれていっています。

ツールが整備されるのと同時に、w3.org/TR/に公開されるドラフトの更新頻度も変わってきています。昔は定期的に、たとえば数カ月に一度などある程度大きな変更が行われたときに更新されていたのですが、GitHubで開発されているPRがマージされるごとに/TRの仕様書が更新されるような状態になり始めていて、非常に頻繁に更新されるようになってきました。グループによってはもう数日に1回ぐらいの頻度で更新しているところもあります。

ユーザーの方々や開発者の方々が便利に使えるように、Web IDLで記述したり、さまざまなサポートツールを使うようになったりして、各種のデータストアや周辺の自動ツールもかなり整備が進んできています。また、仕様書のタイトルで検索できるリファレンスのサイトができていたり、Web IDLで定義されたAPIの関数名や引数を取りまとめた大きなデータが生成されたりするようになっています。

一番下に書いてあるのは実際にTypeScriptのWeb系APIの定義の方にもそのまま利用されているデータで、手元でやってみたいといった興味があればNPMでインストールできますので、こちらも参照してみてください。「これどうだったかな」とWeb IDLまで戻って見ることはあまりないかもしれませんが、ツールを使って大規模にデータを集約して、こういう傾向があるなという解析もできるようになっていますので、興味がある方は使っていただければと思います。

先ほどTypeScriptでも使われているとお話ししましたが、これは実際にブラウザ向け仕様開発で変換するときにリンクを張ったりする元データとして使われています。しかし、noneやmanualなどのキーワードは大量の仕様書で定義されているので、どれを参照するのかをちゃんと指定しないと思いがけない場所にリンクされるということもあったりして、けっこう大変な作業です。そのようにツールを利用しながら実際の仕様書が生成されています。

サマリーインデックスの活用がおすすめ

最後にひとつご紹介です。先ほどもお話ししましたように、PRごとに更新といった状況で仕様書が非常に頻繁に更新されるようになってきていますが、W3CについてはW3C/Keioで月間サマリーインデックスとして更新された仕様書の一覧などさまざまな情報をまとめたサイトも公開しておりますので、こちらもよろしければご覧ください。

以上になります。ありがとうございました。