怖いよ, coqdoc さん！

Coq には、コメントをドキュメントとして扱う機能があります。ソースコードからドキュメントを生成するには coqdoc というコマンドを使います。

coqdoc は LaTeX や HTML などを生成させることが出来ます。私も HTML のドキュメントを生成させたりしています。

coqdoc は CSS と HTML を一緒に生成します。しかし、この内容が見づらいと私は感じていました。理由は以下の二つです。

• 横幅が制限されているため、 PC のディスプレイだと巨大な余白が出来る。
• ソースコードの部分とドキュメントの部分で背景の色が違い、ドキュメントだけを一塊として強調する仕組みになっているが、同じ見出しの下にあるドキュメントでも塊が分割されていたり、見出しを跨いでドキュメントが一塊になっていたりしていて、私にとっては気持ち悪さを感じる。

coqdoc が生成する通常の CSS をそのまま使っているサイトは印象として少ないのですが、 Infinite Data and Proofs - Certified Programming with Dependent Types が一例になります。これを見ればデフォルトのデザインがどのようなものか分かります。

これを改善するために、私は一から独自の CSS を作成しようと考えました。もちろん、デフォルトの CSS を改変する方法もありますが、これは LGPL-2.1 であるため、私のプロジェクトには改変版を含めることが出来ませんでした。

地獄の窯が開いた

CSS を書くためには対象となる HTML の構造を知らなければなりませんでした。 coqdoc が生成する HTML がどのようなものなのか、 Google Chrome のデベロッパーモードを使って探検してみました。

(**

最初の段落。

次の段落。

*)

このようなコメントがどのような HTML になるか読者は予測できますでしょうか？ それぞれの段落が p タグで包まれるんでしょと思ったあなたは正常です。 coqdoc は p タグを使いません。

<div class="doc">
最初の段落。

<div class="paragraph"> </div>

次の段落。
</div>

このような HTML が生成されます。意味不明です。 div はブロック要素のはずです。気力を削がれながらもデフォルトの CSS を確認しました。

.paragraph {
    height: 0.75em;
}

このように高さが指定されていました。つまり、段落と段落の間のスペースを div 要素で表現しているのです。段落の間の隙間のために br 要素を使う人がいるのは知っていましたが、こんな世界があったとは驚きです。私は無知でした。

些細な他の問題

ソースコードを表現するためには pre 要素を使うのが普通だと思いますが、大量の br 要素を使っていました。

coqdoc では The dog is [foo baa]. という風にドキュメントの中にインラインでコードを埋め込むことが出来ます。これが The dog is <span class="inlinecode">foo</span> <span class="inlinecode">baa</span>. と変換されます。空白が span タグに包まれていません。 span.inlinecode という風に指定して文字サイズを大きくしようとしても、空白だけが大きくなりません。

HTML の中に余計なスペースがたくさんあります。元々のテキストの中に HTML のタグなどを差し込むという処理を基本としていると伺えます。

body 要素の直下に div id="page" 要素だけがあり、その中に他の全ての要素が入っている構造になっています。フラットにすれば良いのではと疑問に思いました。

ドキュメントの塊がドキュメントの構造と一致しないのは、コード部とドキュメント部が交互に切り替わる構造になっていたのが原因でした。これは一貫した設計であり理解できます。しかし、この条件下でのドキュメント部は一塊として見れないものだと感じます。

私が見ていた HTML の中では h1 要素が二回現れていましたが、これは Markdown の # foo と同じことであり、ユーザー側が h1 要素に変換される構文を使わないことで回避可能でした。

div id="header と div id="main" と div id="footer" 要素でページ全体を三つに区切っていました。これは今ならそのものずばり header と main と footer 要素があります。使うべきというようなものではありませんが。

ショックを乗り越えて

何とか新しい CSS を仕上げました。その成果はここで見ることが出来ます。デザインに関しては素人なので、まだまだ悪い所があるはずなのですが、私自身がきちんと見れるところまで完成させられたので、ひとまずは満足しました。

ちなみに、 GitLab Pages を初めて使ったんですが、 CI の中でファイルを吐き出せば自動的に引っ張り上げてくれるようになっていて、リポジトリの中に生成物を置く必要がある GitHub Pages と比較して設計の筋がとても良かったです。最初はリポジトリをホストするだけだった GitHub と、最初から周辺のツールまでまとめて扱うことが目標だった GitLab の違いが表れていると思うと、面白いです。

ライセンス

この記事のライセンスは CC BY 4.0 とします。