HTMLで脚注をお手軽に

自分が欲しいものを自分で作って充足する、そんな私の開発記録です

Footnote-JSをリリース

本日(2022/02/05),JavaScriptライブラリ「Footnote-JS」をリリースしました。
このライブラリは、タグ<foot-note>による容易な注釈の入力と、 <foot-note-list>による挿入位置の指定のみによる自動的な脚注の集約を実現しています。
シンプルな動作例(ソースサンプル付き)はGitHubPage上で公開しています

開発期間は2日間、実動1人日程度でしょうか。来歴はGithubのコミットログで残っていますが、 2/3の夜に手を付け始めて、今日の夕方に完成しています。
脚注機能は公式なHTMLには無いようなので、Wikipediaの脚注機能を理想形として思い描いて実装しました

使い方

jsファイルをGitHubのリリースから入手し、自身のサーバに格納してください。headタグ内でjsファイルを読み込ませてください

<h3>（定義）</h3>
<h4>第二条</h4>
４　この法律において「気象業務」とは、次に掲げる業務をいう。<br>
　一　<span id="weather">気象</span>、<span id="ground">地象</span>、地動及び<span id="water">水象</span>の<span id="watch">観測</span>並びにその成果の収集及び発表<br>
　二　気象、地象（地震にあつては、発生した断層運動による地震動（以下単に「地震動」という。）に限る。）及び水象の予報及び警報<br>
　三　気象、地象及び水象に関する情報の収集及び発表<br>
<foot-note for="weather">大気（電離層を除く。）の諸現象</foot-note>
<foot-note for="ground">地震及び火山現象並びに気象に密接に関連する地面及び地中の諸現象</foot-note>
<foot-note for="water">気象又は地震に密接に関連する陸水及び海洋の諸現象</foot-note>
<foot-note for="watch">自然科学的方法による現象の観察及び測定</foot-note>
　四　地球磁気及び地球電気の常時観測並びにその成果の収集及び発表<br>
　五　前各号の事項に関する統計の作成及び調査並びに統計及び調査の成果の発表
<foot-note-list></foot-note-list>

このサンプルコードは、以下のように描画されます。

（定義）

第二条

４　この法律において「気象業務」とは、次に掲げる業務をいう。
　一　気象、地象、地動及び水象の観測並びにその成果の収集及び発表
　二　気象、地象（地震にあつては、発生した断層運動による地震動（以下単に「地震動」という。）に限る。）及び水象の予報及び警報
　三　気象、地象及び水象に関する情報の収集及び発表

大気（電離層を除く。）の諸現象

地震及び火山現象並びに気象に密接に関連する地面及び地中の諸現象

気象又は地震に密接に関連する陸水及び海洋の諸現象

自然科学的方法による現象の観察及び測定　四　地球磁気及び地球電気の常時観測並びにその成果の収集及び発表
　五　前各号の事項に関する統計の作成及び調査並びに統計及び調査の成果の発表気象業務法

コーディングとしては、
1. 注釈をつけたい部分にidを付与してspanなどで括る
2. 注釈の内容をfoot-noteタグに書き込む。この時、対応するidをfor属性で指定する
3. 脚注を表示したい箇所にfoot-note-listタグを埋め込む
の3手順になります。
GitHubPageの別サンプルで例示していますが、脚注はページ全体で通し番号が振られます。また、脚注は複数個所に挿入することができます。複数個所に挿入した場合、その箇所より上にあってまだ注釈が表示されていないものだけが出力されます
（サンプルの１～３の塊では、４は対象外。４の脚注では１～３を再表示はしない）

例外処理として、span等での範囲指定をしないままfoot-noteを書かれた場合にも対応しています。この場合、タグが書かれた箇所に脚注へのリンク注釈が設定されます。
また、foot-note-listを記載しなかった場合、bodyタグ内の最後に脚注を自動生成します。なお、listより後に新たな注釈をつけた場合も同様に最後に自動生成します

開発録

カスタムHTMLタグ

今回、私が初めての試みをしたのが、カスタムHTMLタグです。
class付けしたdivタグを入れ子にしてJS/CSSで制御するようなwebアプリは開発業務経験があるのですが、今回は使いやすいように、<foot-noteタグを独自定義してみました

MDNのカスタム要素の使用のリファレンスページは何周したか分からないくらい読みました。大きく躓いたポイントは、「自立カスタム要素」と「カスタマイズされた組み込み要素」の区別です。

自律カスタム要素とカスタマイズされた組み込み要素

まずはMDNの当該記載を引用してみます

自律カスタム要素 — 標準の HTML 要素を継承しません。
HTML 要素としてページ内で記述して使います。例えば、あるいは document.createElement("popup-info") などです
カスタマイズされた組み込み要素 — これらを作成するには、どの要素を拡張するかを指定する必要があり、基本要素を記述し、カスタム要素の名前を is 属性（またはプロパティ）で指定することで使用します

実装の最中、しっかりとこれらを混同していました。label（標準要素）を拡張して<foot-note>を作ろうとしていたのです。最小限の実装をした時点で、コンストラクタやその他イベントが呼び出せていないことに気付き、原因を探求した結果がこの誤解でした。
拡張するなら、<label is="foot-note">にするしかないし、<foot-note>と書きたければ標準要素の拡張はできないという仕様でした

connectedCallbackイベント

イベントの実行タイミングと、タグ定義の追加タイミングの調整で若干手間取りました。
最終的な実行フローは

1. タグ定義をブラウザに認識させる（customElements.define()）
2. DOMの読み込みに沿って記載されている順に注釈リンクを生成する

となりましたが、この順序が逆転するとうまく注釈の生成ができない事象が発生していました。
DOMが読み込まれた時点でconnectedCallbackイベントが発火します。しかし、タグ定義が読み込まれていないと、そのイベントに対応する処理が未知のままで、最後まで脚注が生成されないままドキュメントの読み込みが完了扱いになってしまいました

jsの圧縮

今回は実行を見送った事項です。
GitHubで配付しているjsファイルのソースは圧縮していません。コメント等を込々で120行程度、4KBに収まったので、わざわざやらなくてもいいかな、と思った次第です
圧縮プラグインの使い方が分からなかったとか、そ、そんな…

空行や改行に伴うインデント分の空白の除去、そして変数名の短縮によるファイル容量の圧縮効果、このステップ数だと恩恵を受けてもKB単位に影響するのかな…みたいなお気持ち！！！
試すことすらできちゃいないんだ…

つれづれ

今回の開発中、MDNドキュメントに不自然な日本語を発見して、2つ程修正のプルリクを投げました。 GitHub管理されていると、お気軽に修正提案ができていいですね。某Micr〇s〇ftのC#,VBのドキュメント、日本語翻訳の改善ももうちょっと気軽にさせてほしい… 機械翻訳そのまま提供、のページを手動翻訳で参画するとかできるんだろうか

今回のライブラリ、言語問わず利用してもらえるように「脚注」とか「Footnote」とかそういう単語をあえて表に出力しないような実装にしました。<<脚注>>とかそんな表示をつけたかった気もしますけどね。 i18nみたいな多言語対応を組み込むほどの規模じゃないよなぁ…と思ったり。
あとは、脚注を表示する箇所の上下の枠線とかのスタイルをカスタムできるような仕様にしてもよかったのかな…

foot-note-list{
   border-top: 1px double gray !important;
   border-bottom: 2px solid gray !important;
}

一応importantつけて指定すれば任意に変えられるとは思います…

今回は開発しつつ裏ではまるっきり違うタスクも並行していたり。マルチタスク下手なはずなのに～