[クロス本草稿]ドキュメント

本文章は、技術書典5にて[project daisy bell]( https://twitter.com/MNukazawa )がリリースする予定の、クロスプラットホーム・デスクトップアプリケーション・GUIフレームワーク・クロスレビュー本（仮）（以下、クロス本）の一部の草稿です。
クロス本は、筆者のGtk/Qt/electronの経験と知見について扱います。具体的な解説書というより技術エッセイです。
本文章には、校正前の文章・記憶により記述し未確認の内容・雑なmarkdown風紀法・張ってないURLリンク、などがあります。

# ドキュメント

公式ドキュメントのメンテナンスレベルは重要である。

最低限、APIマニュアルとクイックスタートマニュアルとサンプルコードが公式で欲しい。
サンプルコードは初心者状態で触るので、最低限の作業で完動するものであって欲しい。

公式ドキュメントとは別に、Stack OverflowのFAQ・有象無象のブログ記事(Qiita含む)・物理書籍等の、非公式な外部ドキュメントの充実度は気になるところである。
外部ドキュメントの充実度は、人気のバロメータでありフレームワークの将来性を測る指標として採用検討の際に気になるところである。
筆者は公式ドキュメントの他に、ブログ記事があればそちらも読む。

Gtk/Qt/Electronすべてにおいて、残念ながら物理書籍は母数が少なく、タイミングに恵まれないこともあり、筆者は今のところ縁がない。
書籍の内容は大抵、網羅性は高いがAPI解説が主で公式ドキュメントの日本語訳のような者が多く、実用に関するEffectiveな内容はまずない。

公式ドキュメントにおいて、「XXXについては書いてない」「XXXができない」と書いてあることはまずないので、そのへんは筆者の体感を書いた。
そういう時の筆者は、悪魔の証明になるが、APIマニュアルのページタイトルあたりを網羅して書いてないことを確認しつつ、Web上で同じ結論に到達した人が居なかったか確認している。

一応再度注意しておくと、以下に指摘している不備は、当時のもので現在は解決しているかもしれないし、そもそも十分探していないから見つかっていないだけかもしれない。
実際、開発と無関係に本書のために調べてみると、見たことのない新しい資料がわりと出てくる...。
(こんな同人誌出して大丈夫なのか筆者...本当に)

## Gtk

[GTK+ 3 Reference Manual]( https://developer.gnome.org/gtk3/ )
Gtk2とGtk3でドキュメントが分かれている。Gtk3はさらにversion毎にページが分けられている。
<<ここにスクリーンショット>> [GtkAlignment Widget]( https://developer.gnome.org/gtk3/3.22/GtkAlignment.html )

Gtk3バージョン内でのAPI変更(追加・削除ほか)はドキュメント中に記載され、必要に応じてURLリンクなどが追加される。

とても不思議なことに、何故か、Gtkのドキュメントを引くためだけのアプリケーションが存在する。
内容はWebから参照できるものと同じである。
<<ここにスクリーンショット>> [GTK-Doc, Devhelp]( https://wiki.gnome.org/Apps/Devhelp )

Devhelpという名前は名前空間汚染的(ex.Surface,Go言語)だと思う。

CSSについて十分なドキュメントは存在しない。(これについての文句はCSSの章で書くはず。)

配布パッケージの作り方については公式ドキュメントがない。
Gtk3自体がライブラリビルドだけでも依存関係の解決はユーザ側でできるという前提だが、実際にはライブラリ間のversion依存が複雑。
Gtk3ライブラリのビルドだけで挫折or満足してしまう可能性が高い...。
[参考:Gtk2-3野良ビルドをしている @niloufarjp 氏のtwitter]( https://twitter.com/niloufarjp )
以前からライブラリ以外に必要なものはあったが、Gtk3からはアイコンキャッシュ等、さらに複雑になった模様。
またGtk3以降もバージョンにより必要なものが微妙に異なるようで、野良の情報を集めてなんとかする必要がある。

### サンプルコード

アプリケーションサンプル集が、gtk-3-examplesというパッケージ名で、集約されたアプリケーションの形式で存在する。
Widgetの使用方法がメイン。
<<ここにスクリーンショット>>

問題点として、サンプルコードを単にコピペしただけでは動作するアプリケーションのコードにならない。
サンプルコードはmain部分が共通化されており、このmain部分が記載されていないため、探してきて補完しないと手元でサンプルコードをビルドしてみることができない。
(手元のGtkバージョンで同サンプルコードが有効か否か確認する等したい派の筆者は困る。)
また、サンプルコードはanjutaが生成するほど本格的でなくエラーチェックを真面目にしているわけでもないわりに、わかりやすく単純に書かれているわけでもなく、微妙に参考にしにくい。

### 外部ドキュメント

Qt,Electronと比べると、GtkについてはWeb上の情報は少ない。

非公式のドキュメントとして、
[GTK+/GNOMEによるGUIアプリケーションプログラミング (菅谷保之著)]( http://wiki.cis.iwate-u.ac.jp/~suzuki/Soft/GUI-Application-Programming-20070430.pdf )
がある。
なぜかWeb上で無償公開されている。
Gtk3になってAPIが多少変更されたが、これが扱っている範囲はGtk2,Gtk3の間であまり違いはないので十分参照できる。
筆者は一時期、USBメモリに開発環境と一緒に入れて持ち歩いていた。
今見ると、
[入門GTK+ (菅谷保之著)]( http://wiki.cis.iwate-u.ac.jp/~wiki/csd/docs/GTK-book-all.pdf )
というものがやはりWeb上に有り、こちらのほうが新しい？(といっても2012年だとのことだが)
CSS化前のドキュメントなのでCSS関連の内容はない。
Web上の断片情報が少ない一方で、これらのドキュメントに、主要なWidgetおよび基本的な機能が網羅されている。

物理書籍は、Gtk2時代の古い書籍しか存在しない。
物理書籍も販売されている「入門GTK+ (菅谷保之著)」を同人誌と言うのは無理がある。
同人誌でGtkを扱っているものを見た覚えがない。だから本書を書いたところもある。

### その他

救いとして、GtkにはMLがあり、疑問点は質問すれば大抵は数日中に回答がある。
[modal dialogに関するML上での質問]( https://mail.gnome.org/archives/gtk-app-devel-list/2017-June/msg00050.html )
さっき自分の質問タイトルでWeb検索したら引っかからなかったので、検索性に難があるのでは？

## Qt

[Qt Documentation]( http://doc.qt.io/qt-5/ )
Qtのversion毎にドキュメントが分かれているが番号が飛び飛びなので、どうやら長期サポート・メジャー変更あたりで区切っている模様。

QtもCSSの詳細なドキュメントは無いが、QtCreatorのフォームデザイナとCSS入力支援があるので多少マシである。

ARMボードへのクロスビルドに関する公式ガイドページとか無いの？ (仕事でわりと面倒な目に遭った)

### サンプルコード

Qtのサンプルコード集はWebサイトに存在する。
QtCreatorからもサンプルにアクセスできる。
[List of Qt Examples]( http://doc.qt.io/qt-5/all-examples.html )
サンプル毎のスクリーンショットが用意されていることもあり、GtkのようなWidgetの使用方法というより、用途ごとのアプリケーションサンプルとしての色合いが強いように見える。
これはGUIツールキットとしてのGtkとクロスプラットホームFWとしてのQtの性質を反映しているところもあると思う。
プロジェクトのファイルが一通り揃っており、これはそのままビルドして実行できるプロジェクト一式なので、Gtkのサンプルコードよりも参考にしやすい。

### 外部ドキュメント

Gtkと比較すると、調べたときに扱っているページが多い。

Qtにはインストーラ作成の仕組みが用意されているが、これについての同人誌が出ている。
今見たらAmazonで取扱があった。
「インストーラーで配ろう！ (理ろぐ) Kindle版」(URLは長くなってしまうため略)
技術書典などで見る。たぶんいつもの人が出しているのかなという気がする。

Qt4(QtC++)時代のものだが、オライリーから動物本が出ている。
また、Qt5になってからのQtQuick(QML)の物理本が出ている。

### その他

Qtには何故か専用のStack Overflowみたいなサイトがある。普通に検索に引っかかるので意識する必要はない。
筆者は幸い質問が必要になったことがないため、使ったことはない。

## Electron

[Electron Documentation]( https://electronjs.org/docs )

### サンプルコード
そんなものはない。
ドキュメント中にコード断片として存在する。
Gtk,QtよりさらにFWとしての性質が強い(テンプレートに埋め込む的な)性質が強いせい、またGUIサンプルはそのままHTMLページサンプルになってしまうからか。

### 外部ドキュメント

出たばかりなのもあり、わりと新しい情報が多い。
//ただ、良くも悪くもnodejs,npm周りのテクノロジなので、陳腐化も早いかも。

大きなアドバンテージとして、HTML/CSS/JSなのでSPAなどWebページ設計のための膨大な情報がそのままElectronで使える。
(これはよく言われていてその通り。)

物理書籍が出ている。
[Electronではじめるアプリ開発 ~JavaScript/HTML/CSSでデスクトップアプリを作ろう](URLは長くなってしまうので略)
筆者は本書を見つけた時点で、初心者向けのスタートガイドや網羅情報はすでに必要なくなっていたので購入しなかった。
自動アップデートやエラーレポートなどの踏み込んだ内容は書いてなかった。

技術書典などでちらほら見なくもない。

### その他

公式ドキュメントにプラットフォーム毎のBuild Instructionsなんてページがあるけれど、Electronはnpmでバイナリ取得できるのもあって、こういう情報はGtkの方にこそ欲しい...。