Vnanoの公式サイトがオープン、チュートリアルやAPI仕様書等も掲載

このコーナーで以前よりお伝えしてきた通り、RINEARNでは現在、 アプリケーション組み込み用途のコンパクトなスクリプトエンジン「 Vnano 」を、オープンソースで開発しています。その公式サイトが8月7日オープンしました。 今回は、その概要をお知らせします。

VCSSL公式サイト内のサブディレクトリ階層に、日本語版と英語版で同時開設

Vnano は、言語仕様上は、同様にRINEARNが開発している簡易計算・可視化用のスクリプト言語「 VCSSL 」のサブセットです。 従って Vnano の公式サイトも、VCSSLの公式サイト内のサブディレクトリ階層に開設しました。

また、RINEARNでは2017-2018年サイト再編以降、段階的に運営サイトの英語対応を進めています。 そこで今回のVnanoの公式サイトも、日本語版と英語版を同時開設しました。

日本語/英語それぞれにおける、Vnano 公式サイトのトップページは以下の通りです：

Vnano公式サイト 日本語版トップページ

https://www.vcssl.org/ja-jp/vnano/

Vnano公式サイト 英語版トップページ

https://www.vcssl.org/en-us/vnano/

後に述べるチュートリアルやAPI仕様書は、既に日本語と英語の両方で参照可能になっています。

ただ、API仕様書についてはまだソースコード内のドキュメンテーションコメントの英語対応が追い付いていない箇所もあり、 クラスによってはところどころ日本語が混じっているものがあります。 チュートリアルについては、既に日本語/英語でほぼ同等の内容を用意できています。

3 ステップですぐに試せるビルド済み版の提供も

これまでは、使い方を記載したドキュメントがリポジトリのREADMEしか無かった事もあり、 Vnano を試しに少し動かしてみるだけでも、スクリプトエンジンをソースコードからビルドする必要がありました。

一方、今回の上記 Vnano 公式サイトのトップページでは、 ビルド済みのスクリプトエンジンをすぐにダウンロードできるボタンも設置しています。

それに併せて、以下の3ステップで Vnano を実際に手元で動かせる簡易トライアルも掲載しています：

これにより、従来よりもずっと手短にVnanoを試しに動作させてみる事ができます。

なお、本格的な利用には、やはりアプリケーション開発に用いるのと同じバージョンのJDKでスクリプトエンジンをビルドした方が、バージョン依存性やパフォーマンスなどの観点では優位性が見込めます。

ソースコードリポジトリのREADMEを土台に再編集したチュートリアル

Vnano では、ソースコードリポジトリのREADME※において、以前からチュートリアル的な内容を掲載していました。 （※ 2019年8月7日現在。内容が増大してきているため、今後、別名ファイルに移してREADMEは単純化する可能性もあります。）

ただ、現在のRINEARNでのリポジトリの運営方針は、あくまでも情報の「 公開 」よりも「 管理 」に重点を置いて色々と割り切っている面が強く、READMEもあまり初見での見やすさなどを重視した形にはなっていない状態です。 例えば、日本語と英語の文章が段落ごとに交互に混ざりつつ、内容も全てが1ファイル内に（やや長大に）列挙的に記述されています。 これは、その方が書き手にとっての編集が楽であったり、各言語ごとの内容が徐々に乖離していくのを防ぐためといった、管理効率を重視した意図によるものです。 その反面、ドキュメントとして必ずしも参照しやすい形にはなっていません。

そこでVnano公式サイトでは、リポジトリのREADMEをベースとして各言語ごとに分割し、さらにほどほどの量で複数ページに分割した上で、少し内容に再編集を加えたものを 「 チュートリアル 」として提供しています：

Vnano チュートリアル 日本語版

https://www.vcssl.org/ja-jp/doc/vnano/

Vnano チュートリアル 英語版

https://www.vcssl.org/en-us/doc/vnano/

Webサイトはそもそもが情報の「 公開 」を目的としたものであるため、再編集や構成の際もその点を意識しており、リポジトリのREADMEよりも情報を参照しやすい形になっています。

チュートリアルページの例: https://www.vcssl.org/ja-jp/vnano/doc/tutorial/use

ただ、完全にWebベースに移行してしまうと、やはり各言語ごと内容の乖離や、旧バージョン用を含む情報管理、および編集の手間などの点で、いくらかデメリットが生じてしまいます。 そこで、少なくとも上記チュートリアルについては、今後もリポジトリのREADME（または今後名称変更した別ファイル）を原稿のようなものとして第一に更新し、 そこからWebページに（ある程度の離散的な間隔で）反映するといった形で運営していく予定です。

スクリプトエンジンの構成クラス群のAPI仕様書も公開

加えて、Vnano 公式サイトの開設にあわせて、Vnanoのスクリプトエンジンを構成するクラス群のAPI仕様書も、以下の通りWeb上での掲載を開始しました：

Vnano スクリプトエンジン APIリファレンス（仕様書） 日本語版

https://www.vcssl.org/ja-jp/dev/code/main-jimpl/api/org/vcssl/nano/

Vnano スクリプトエンジン APIリファレンス（仕様書） 英語版

https://www.vcssl.org/en-us/dev/code/main-jimpl/api/org/vcssl/nano/

このAPI仕様書は、スクリプトエンジンのソースコード内に記載されたドキュメンテーションコメントから、Javadoc を用いて生成したものです。 Vnano のリポジトリ内には、その生成めのスクリプトとして generatedocs(.sh/.bat) が同梱されています。 ただ、この生成スクリプトで生成したAPI仕様書では、デフォルトでは日本語/英語の両方が表示されます。 日本語や英語のみを表示するには、CSS ファイルを編集して .lang-ja{ display: none; } などと追記し、目的外の言語を非表示指定する必要があります。

これは、Javadocの仕様内で日本語/英語のコンテンツを切り分けるのは意外と容易ではなく、 現状ではとりあえずの暫定的な方法として、 ドキュメンテーションコメント内の記述を span/div タグで囲みつつ、 class 指定で lang-ja (日本語用) と lang-en (英語用) のように言語情報をマークアップし、 その後にCSSで目的言語外の記述を非表示にする事で対応しているためです。 スクリプト側で言語選択のステップを入れて自動的にCSSに追記するようにしてもよいのですが、 ソース編集時には同時表示したい事もあったり、その他いくつかの理由などから、現状ではデフォルトは行わないようになっています。

一方、上記の公式サイト内のAPI仕様書では、日本語/英語のみを表示するように設定済みのものを掲載しています。 そのため、master ブランチにも反映されていないような最新または暫定的のコードの仕様書を生成したい場合を除いては、 手動生成するよりも、公式サイト内のAPI仕様書の方が手軽に参照できます。

API仕様書ページの例:
https://www.vcssl.org/ja-jp/dev/code/main-jimpl/api/org/vcssl/nano/compiler/AstNode.html

なお、ドキュメンテーションコメントを多言語対応した事の結果、ソースコード内でのコメントから目視でAPI仕様を読むのは、それなりにうっとうしい形になってしまっています。 ただ、そもそもドキュメンテーションコメントは必ずしもコード内コメントとしての可読性がベストな形ではなく、 どちらを優先するかによって、どうしてもある程度は他方にトレードオフのようなものが生じてしまうため、 Vnano ではAPIレベルの仕様はWebブラウザで閲覧する方針に割り切っています。 今回の公式サイト内でのAPI仕様書公開にあわせて、各クラスのソースコードの冒頭にも、そのクラスのAPI仕様書のURLを記載するよう追記しています（未対応のものも残っています）。

◇

以上の通りです。RINEARNでは今後もVnanoの正式リリースに向けた準備を進め、順次このコーナーにてお知らせしていく予定です。