WINI ━ WIKIやMARKDOWNを超えた新しいマークアップ言語処理システム




WINI markupは、WIKI markupやmarkdownと同じく、いわゆる軽量マークアップ言語の一つである。
既存のマークアップ言語の良いところは見習いつつ、より軽く強力で使いやすいテキスト構築ツールとして、2019年に開発・公開された。
公開用webページの素材づくりだけでなく私的なメモの蓄積にも便利に使えるだろう。

**この記事で取り上げたWini.pmはVersion 1.0にアップデートされ、大きく機能拡張しています。
最新の情報についてはマニュアル記事『[ウェブサイトらくらく作成 軽量マークアップ言語markgaab/Wini](https://zenn.dev/kojidoi/books/6831494c86db9b)』をご覧ください。**

# はじめに

[軽量マークアップ言語](https://ja.wikipedia.org/wiki/%E8%BB%BD%E9%87%8F%E3%83%9E%E3%83%BC%E3%82%AF%E3%82%A2%E3%83%83%E3%83%97%E8%A8%80%E8%AA%9E)では、基本的にはプレーンテキストとして文書を書いていく。ただし、「**マークアップ文字**」やHTMLタグなどの特別な意味をもたせた文字列を挿入することで、特定の部分に「特別な意味や機能や見た目」があることを示す。

書かれたテキストを見れば、マークアップ文法を知らなくても、そこに何が書いてあるのかは容易に把握できる。マークアップ文字は、ある種の制約を受け入れつつも「簡単にわかりやすく書ける」ことを重視して策定されているので、文法を習得するのも極めて容易である。これらは各種の軽量マークアップ言語がもつ共通的な長所である。

しかし、既存の軽量マークアップ言語にはいろいろと不便な点もある。
<dl>
<dt>表現力に限界がある</dt><dd>特に、たくさんのデータを分かりやすくまとめるには「表」が欠かせないが、既存のどのシステムでも作表はややこしく、その割に制約だらけだ。
「簡易」マークアップなのだから仕方がない。不満ならHTMLを直接いじれやという声があるかもしれない。だが、ややこしいものを簡単に作りたいというのは自然な欲求だろう。その点でフラストレーションが沸き起こることは禁じ得ない。
</dd>
<dt>HTMLへの手軽な変換ツールが見当たらない</dt><dd>軽量マークアップデータからHTMLファイルを得る主たる手段はCMSや静的サイトジェネレータと呼ばれるツールの利用だろう。だがこのジャンルのソフトウェアに使いやすいものがなかなか見当たらない。機能的には優れていても設定や操作がやたら煩雑だったりPHPのセットアップとかが求められたりする。ライターは文章を書きたいのであってPC上でのややこしい設定作業を強制されたくはないはずだ。</dd>
</dl>

そこで**WINI**の開発と相成った。「できるだけ手間暇かけずに手軽にHTMLコンテンツを構築する」という目的において、既存のwikiやmarkdownを（少なくとも部分的には）上回る有用性をもつ軽量マークアップ言語の登場である。

本稿では、WINIの基本的な使い方と文法について簡潔に説明する。ぜひ興味を持っていただき、お試しいただけることを、作者としては願ってやまない。

# 環境構築

WINIで書かれた文書は、最終的にHTML5[^html5]に変換されることが想定されている。その変換を実現するツールは、今の所は筆者が作成した**wini.pm**しかない。

[^html5]: 厳密にはW3Cが推進していた「狭義のHTML5」は廃案となり、今はWHATWG規格のHTMLとかいうべきであるらしいのだが、ややこしいので本稿ではHTML5で統一する。いずれにせよ、そんな細かいことをごちゃごちゃ考えなくてもそこそこの品質の出力を得られるようにすることがWINIをはじめとする簡易マークアップ言語の務めと言えるだろう。

つまり、WINIの環境構築とは、テキストエディタおよびwini.pmのインストールである。しかし、テキストエディタは最低限のもの（「メモ帳」など）は普通すでにあるはずである。したがって、もっとも単純には、WINIの環境構築はすなわちwini.pmのインストール作業ということになる。

wini.pmは[github](https://github.com/Koji-Doi/wini)にて公開されている。MITライセンスを採用していて、誰もが無料でダウンロードでき、営利だろうと非営利だろうと自由に利用できる。

wini.pmは[perl](https://ja.wikipedia.org/wiki/Perl)というプログラミング言語で書かれている。したがってWINIを活用するにはperlインタープリタが利用できる環境が必要である。

## perlの確認: Unix-like OSの場合

linuxやFreeBSD、MacOSなどのいわゆるUNIX-like OSではたいてい初めからperlが使えるようになっている。このため、WINIのセットアップは超絶簡単である。たった一つのファイル(wini.pm)をゲットして適当なディレクトリに放り込むだけ。これだけでWINIが使えるようになる。

## perlの確認： MS Windowsの場合
windowsの場合は、それに先立ちperlの入手がまず必要である。

ややこしいことは一切考えず、最短距離でお試しだけやってみたい向きには、[Starawberry perl](http://strawberryperl.com/releases.html)のポータブル版をお勧めする。本体PCのレジストリなど環境設定を「汚す」こともないので、後顧の憂いなく試用できるはずだ。これをUSBメモリに展開して複数PCを渡り歩きながら利用することもできる。別記事で詳しく紹介している。

参照：
[自宅でも職場でもネカフェでもperl - Qiita](https://qiita.com/doikoji/items/2280ff1e29b610bd07a3)

もう少し本格的にやりたい向きにはMSYS2がよいだろう。こちらもポータブル版が存在する。

もちろん、WSLを使ってもよい。

本文書ではwindowsユーザは上記のような選択をしたものと仮定して手順を説明する。しかし、他の選択をした場合もコマンドラインを起動した後の手順に特に違いはないはずなので安心してほしい。

## wini.pmの取得

[wini.pmの公式配布元はgithubとする。](https://github.com/Koji-Doi/wini)

まずは[zipファイルをダウンロード](https://github.com/Koji-Doi/wini/archive/master.zip)して適当なディレクトリ（フォルダ）に展開する。githubの使い方に慣れている方はcloneなりなんなりよしなに。展開ディレクトリ中にwini.pm、test.wini、test.htmlが入っているのを確認してほしい。

当該ディレクトリに移動して、コマンドラインで次のように入力してみよう。

```
perl wini.pm --version
```

`wini.pm ver. 0 rel. 20200519`などと、wini.pmのバージョン番号・リリースIDが表示されただろうか。


## スタートアップ

ここからは、コマンドラインでの作業である。

まずはターミナルを起動してコンソールを使えるようにする（Windows上でWSLとubuntuをインストールした人は、メニューにubuntuという項目ができているはずなのでクリックする）。

wini.pmを展開したディレクトリに移動し、コマンドライン上に次のように入力する。

```
perl wini.pm --whole < test.wini > mytest.html
```

うまくいけばmytest.htmlというファイルが新たに作成され、その内容は既存のtest.htmlと同じであるはずだ。そう確認できたなら、環境設定は成功している。さらに貴方は既にwini.pmによるHTMLファイル作成手順をマスターしたことになる。

test.htmlをブラウザで開き、test.winiをエディタで開き、両者をざっくり眺めていただきたい。WINIがどんなことをするシステムなのか雰囲気は掴んでいただけるのではないだろうか。

# クイックスタート: 平文・改段落のみからなる作文

準備は整った。作文を始めよう。

エディタを起動し、何でもいいので文章を書いてみよう。原則的には、普通の文章を普通に書けばよい。みやすさ、編集操作の利便を考えて、適当に改行を入れよう。最終的な出力のことはまだ考えなくても良い。

ただし、段落を改めたいときには、かならず１行以上の「空行」を入れて欲しい。つまり改行を続けざまに２個以上入れるということだ。

[HTML5](https://ja.wikipedia.org/wiki/HTML5)のタグは、基本的に自由に挿入してよい。

HTML5タグの範囲外で`<>{}[]&|`)はそのまま書いてはならない。それ以外の半角記号（`#`や`!`など）は、行の途中に書くのは構わないが行頭に置いてはならない。これらは「**マークアップ文字**」となり、特別な書き方があるのだ。正しい書き方は後で解説するので、とりあえずこれらは[数値文字参照か文字実体参照](https://ja.wikipedia.org/wiki/%E6%96%87%E5%AD%97%E5%8F%82%E7%85%A7)で書くとよい。`<`を出すのに`&lt;`と書くのは多少HTMLやCGIをいじっている人なら経験しているだろう。あれが文字実体参照の例である。この説明が何のことやらちんぷんかんぷんな人は、とりあえず記号を「全角文字」で入力しておいて欲しい。

ひとしきり入力を終えたらテキストファイルとしてセーブしよう。文字コードはUTF-8である。今やwindowsのメモ帳もそれがデフォルトなので迷う余地はないと思うが、くれぐれもシフトJISなどを選択しないように。ファイル名は何でも良いが、`abc.wini`のように拡張子を`.wini`で統一しておくと後々の作業が楽だろう。

前項で実行したように

```
perl wini.pm < abc.wini > abc.html
```

とコマンドラインで実行するとHTML5のファイルabc.htmlができる。

できたファイルをさらに加工するならこれを用いればよい。しかし、このファイルは入力したマークアップに対応した部分だけが出力されたもので、HTMLとして完結したものではない。そのままブラウザで表示すると問題が起こるかもしれない。

webブラウザで問題なく表示できる自己完結したHTMLファイルを得たいならば、次のようにする。

```
perl wini.pm --whole < abc.wini > abc.html
```

これで、ヘッダ・フッタなどが正しく付加され、ブラウザで問題なく表示可能なHTML5ファイルが得られる。

# 文字の見た目を変える
## 上付き文字・下付き文字

`__{abc}`のように、アンダースコア2つに続いて波括弧で挟んだテキストを置くと、そのテキストは下付き文字として扱われる。波括弧を省略すると`__`の直後の一文字だけが下付き文字となる。

また、`^^{abc}`のようにハット2つに続いて波括弧で挟んだテキストを置くと、そのテキストは上付き文字として扱われる。波括弧を省略すると`^^`の直後の一文字だけが上付き文字となる。

```
水の化学式は、H__2Oである。

1辺10cmの正方形の面積は、100cm^^2である。

ウラン235（^^{235}U）はウランの同位体の一つである。
```

当節で言及した機能はver. 0 rel. 20200102以降でサポートされている。

## 文字の強調・修飾

「スタートアップ」の項で書いた「特別な書き方」の一つが「マクロ」である。マクロの詳細な解説は後の節に譲る。ここで取り敢えず理解してほしいのは、次の2点である。

* マクロとは「ややこしい書き方をシンプルに実現するためにWINIに与える命令文」である。
* `{{マクロ名|パラメーター}}`のような形式でWINIテキスト内に挿入される。

基本的に文字修飾はマクロで実現する。たとえば、`{{b|強調したい文字列}}`のように書くと、「強調したい文字列」がボールドになる。

```
むかしむかしあるところに、{{b|おじいさん}}と{{b|おばあさん}}が住んでいました。
```

文字の修飾に関わるマクロの一覧を以下に示す。参考までにwikiやmarkdownにおける同義のマークアップも併記しておこう。

<table id="winitable1" class="winitable" style="width:80vw; height:32rem; background:white;">
<tr><th colspan="5" style="text-align:center;border-right:solid 0px;border-left:solid 0px;">文字修飾 </th></tr>
<tr><th style="width:60em;">機能 </th><th>WINI </th><th>wiki </th><th>markdown </th><th>HTML5 </th></tr>
<tr><th rowspan="2">bold </th><th style="background-color:white;">{{b&#x7c;太字}} </th><td rowspan="2">&apos;&apos;太字&apos;&apos; </td><td rowspan="2">&#x2a;&#x2a;太字** </td><td rowspan="2">&lt;span style="font-weight:bold;">太字&lt;/span> </td></tr>
<tr><th>{{*&#x7c;太字}} </th></tr>
<tr><th rowspan="2">italic </th><th>{{i&#x7c;斜体}} </th><td rowspan="2">&apos;&apos;斜体&apos;&apos; </td><td rowspan="2">&#x2a;斜体* </td><td rowspan="2">&lt;span style="font-style:italic;">斜体&lt;/span> </td></tr>
<tr><th>{{/&#x7c;斜体}} </th></tr>
<tr><th rowspan="2">underline </th><th>{{u&#x7c;下線}} </th><td rowspan="2">&lt;u>下線&lt;/u> </td><td rowspan="2">&lt;u>下線&lt;/u> </td><td rowspan="2">&lt;span style="border-bottom: solid 1px;">下線&lt;/span> </td></tr>
<tr><th>{{_&#x7c;下線}} </th></tr>
<tr><th rowspan="2">strike </th><th>{{s&#x7c;打消線}} </th><td rowspan="2">&lt;s>打消線&lt;/s> </td><td rowspan="2">&#x7e;&#x7e;打消線~~ </td><td rowspan="2">&lt;span style="text-decoration: line-through;">打消線&lt;/span> </td></tr>
<tr><th>{{-&#x7c;打消線}} </th></tr>
<tr><th colspan="5" style="text-align:center;border-right:solid 0px;border-left:solid 0px;">意味付け </th></tr>
<tr><th>機能 </th><th>WINI </th><th>wiki </th><th>markdown </th><th>HTML5 </th></tr>
<tr><th>b </th><th>{{B&#x7c;キーワード}} </th><td>&lt;b>キーワード&lt;/b> </td><td>&lt;b>キーワード&lt;/b> </td><td>&lt;b>キーワード&lt;/b> </td></tr>
<tr><th>i </th><th>{{I&#x7c;心の声}} </th><td>&lt;i>心の声&lt;/i> </td><td>&lt;i>心の声&lt;/i> </td><td>&lt;i>心の声&lt;/i> </td></tr>
<tr><th>s </th><th>{{S&#x7c;不正確・無関係}} </th><td>&lt;s>不正確・無関係&lt;/s> </td><td>&lt;s>不正確・無関係&lt;/s> </td><td>&lt;s>不正確・無関係 &lt;/s> </td></tr>
<tr><th>strong </th><th>{{&#x2a;&#x2a;&#x7c;重要}} </th><td>&lt;strong>重要 &lt;/strong> </td><td>&lt;strong>重要 &lt;/strong> </td><td>&lt;strong>重要 &lt;/strong> </td></tr>
</table>

WINIにできてwikiやmarkdownにはできない芸として、文字修飾・意味付け系の指定を「入れ子」にできることがある。つまり、`{{b|ボールドのテキストの一部を{{i|さらに斜体に}}する}}`などということが可能である。

### 論理マークアップと物理マークアップを使い分ける

HTMLのタグは2種類に大別できる。
<dl>
<dt>物理タグ</dt><dd>対象文字列の見た目をどうするかを規定するのが物理タグである。ひたすら物理タグを使って「この部分はボールド」などと「見た目」を直接的に指定していくのが「**物理マークアップ**」である。</dd>
<dt>論理タグ</dt><dd>対象文字列の文書内での「役割」を指し示すためのが論理タグである。文書内では「この部分は重要」・「この部分は見出し」などといった指定を重ねていく。見た目の規定は、「見出しはボールド」などという抽象化された形で行う。これが「**論理マークアップ**」である。</dd>
</dl>

上述のように、WINIではb,i,s,uの各マクロで`<span style=...`を出力するようにしている。spanタグ自体は本来「文字列の一部を囲う」以上の意味をもたないが、styleオプションは明確に対象文字列の見た目を規定するためのものである。つまり、ここでは物理タグへの変換を意図している。

一方で、WINIにはこれらとは別にB,I,Sマクロが用意されている。マクロ名が大文字であることに注意してほしい。マクロ名の大文字小文字はWINIでは原則的に同一視されることになっているが、これらのマクロは例外である。B,I,Sマクロで指定されたテキストはそれぞれHTML5のb,i,sタグに変換される（なお、uタグはHTML5では廃止されている）。

つまりこういうことである：

* 名前が小文字のb,i,sマクロは、物理マークアップに対応する。
* 名前が大文字のB,I,Sマクロは、論理マークアップに対応する。

また、strongタグに対応した「**マクロ」が用意されている。HTML5においてはstrongも論理タグの一種である。これについては次の「記号マクロ」の項を参照してほしい。

#### 作者のつぶやき

HTMLというマークアップ言語では、専用の「タグ」を使って文章中の特定の文字の見た目を変更することが古来から行われていた。ボールド指定のBタグ、イタリック指定のIタグ、打ち消し線指定のSタグは、手軽な文字飾り用タグとして大昔からポピュラーであり続けてきたもので、典型的な「物理タグ」として扱われてきた。

しかし、HTMLはバージョンアップを繰り返し、HTML5になってB,I,Sなどタグの定義は従来から大きく変更された。今やこれらのタグは「物理タグ」ではない。「重要」とか「強調」とか「無関係（無効）な要素」といった「テキストの意味付け」を指定する「論理タグ」に変わったのである。

多くのブラウザでは見た目が変わらないので、よほど志の高い人でなければこのような違いを気にしてはいないだろう。しかし、少しでもウェブ世界での検索品質の向上を願うなら、物理マークアップと論理マークアップは厳密に使い分け、論理マークアップによって正しくテキストを意味付けしなければならない。万人がそのことを承知し実践することを願い、WINIのマクロを定義した。

単純に「太い字で書かれたテキスト」が欲しいなら、bタグではなく、CSSで対応すべきなのだ。だから普通の人にはspanに対応したbマクロを使ってもらう。HTML5の正しい`<b>`が欲しい人には、意識的にBマクロを使ってもらおうという算段である。

HTML5にはstrongやbと利用範囲が被るemタグというものも存在する。しかし、積極的に使用する意義が作者には感じられない。そのため、WINIは直接的にはこれをサポートしていない。どうしても使いたい方は`<em>`, `</em>`を直接書き込んでほしい。


### 「記号マクロ」を使うとシンプルに文字飾りを表現できる

上の表にあるとおり、文字修飾系のb,i,u,s各マクロには、同じ意味を持つ`*`マクロ、`/`マクロ、`_`マクロ、`-`マクロが用意されている。この書法はwikiやmarkdownからの借用である。また、これらの「**記号マクロ**」は一つにまとめて書くことができるのが特徴である。`{{*/|文字列}}`は``{{b|{{i|文字列}}}}``と同じ意味となる。

さらに`*`に関しては特別ルールが存在する。`{{**|text}}`のように`*`を二つ続けた場合、これはspan styleでもbでもなく、strongタグに変換される。さらに3つ以上続けた場合はstrongタグの入れ子となる。つまり`{{***|text}}`は`<strong><strong>text</strong></strong>`と変換される。4つ以上続けた場合はその数に応じてstrongの数が増える。HTML5ではstrongタグを重ね掛けすることで「より強い強調」が表現できることになっている。WINIはその仕様に対応しているのだ。更に`{{*** *|text}}`のようにスペースを使えば他の設定とまとめて書くことができる。

# 特殊な書式

## 縦書き

`{{v|縦書きにしたいテキスト}}`

## ルビ（ふりがな）

`{{ruby|ルビを振りたい文字列|ルビ}}`

# ハイパーリンク

他所のテキストへのハイパーリンクがたくさん含まれていてこそのHTMLである。WINIでは、wikimedia markupに似たとても簡素な形式でこれを書けるようにした。

```
[http://example.com]
```

このようにURLを角括弧でくくるだけでリンクができる。この最もシンプルな形式では、URLそのものがリンクテキストとなる。たいていはもう少し気の利いたリンクテキストを用いたいだろう。それには次のようにする。

```
[http://example.com リンクテキスト]
```
このようにURLの後にスペースを挟んで後置テキストを追加すると、その後置テキストがリンクテキストとして用いられ、次の様なHTMLテキストに翻訳される。

```
<a href="http://example.com" target="_self">リンクテキスト</a>
```

文書内リンクももちろん可能である。飛び先としたい場所にIDを設定したうえで、次のように書けばよい。

```
[#hoge リンクテキスト]
```
また、ver. 0. rel 20210316以降では、markdown形式も使える。すなわち、次のような書式である。

```
[リンクテキスト](URL)
```

## ハイパーリンクに付加できるオプション

WINIのハイパーリンク指定においては、URLの直後に`|`に続けて「オプション文字列」を追記することで、リンク先ターゲットの指定ができる。

* `@@` -- `target="_blank"`に翻訳される。このオプションをつけて生成されたリンクをクリック・タップすると、新しい窓が生成され、リンク先はその新しい窓に表示される。
* `@windowName` -- `target="WindowName"`に翻訳される。生成されたリンクをクリック・タップされると、WindowNameとして指定された名前の窓の上にリンク先コンテンツが表示される。その名前の窓が既存であれば、そこにあった内容が消されて新しく指定されたコンテンツで上書きされる。その名前の窓が存在しなければ、まずは窓が新しく生成される。WindowNameに指定できるのは、半角英数字または`_`からなる任意の文字列である。

# インラインイメージ

文書中に画像が自由に埋め込める（インラインイメージ）のもHTMLの良いところである。もちろんWINIはインラインイメージを簡便に実現する方法を提供する。

```
[!image.png]
```

前述のリンクと似た形式でインラインイメージを表現できる。最も単純には、画像URLを``[]``で囲い、左角括弧の直後に`!`を置くだけである。

画像を読み込めなかったときに代替表示するテキストもぜひ設定しておきたいところだ。ハイパーテキストと同じく、URLのあとにスペースを置いてテキストを置けばよい。

```
[!image.png 画像の説明]
```

こうしてURLの後ろに付加したテキストがimgタグのaltオプションの値として使用される。

インラインイメージには出現順に`imageN`という形式のIDがつく。ここで`N`は1以上の整数値である。ただし、後述の方法で明示的にIDを付加しておくことを強く推奨する。

また、`[!!image.png]`のように`!`を重ねて書くと、figureタグが追加され、その中にimgタグが配置される。また`[!!image.png 画像の説明]]`のようにURLの後ろにスペースを挟んで配置した説明文は、imgタグのaltオプションではなくfigcaptionタグ内のテキストとして使用され、当該画像の真下に配置されることになる。

## インラインイメージに付加できるオプション

ver 0. rel 200113版以降、URLの直後に`|`を挟んで各種の「オプション指定文字列」を追記できる。これにより、フロート属性・画像表示サイズ・ID・クラスなどの指定が可能になる。

たとえば`[!image.png|>200x100 sample image]`というコードは、対象画像がimage.pngで、それを高さx幅=200x100pxで表示、さらに右寄せフロート属性を指定し、画像の左側に本文が回り込むことを許すようになる。また、ほとんどのブラウザでは、画像にフォーカスするとバルーン表示に"sample image"と表示されることだろう。

### 画像の「流し込み」とフロート属性

* `<` -- 左フロート、すなわち当該画像がページの左側に配され、右側に本文テキストが流し込まれる。
* `>` -- 右フロート、すなわち当該画像がページの左側に配され、右側に本文テキストが流し込まれる。

本文の回り込みを解除するには、テキスト中の解除したい場所に

```
---
```
とページブレーク指定マークアップを挿入する。このマークアップは前後に改行をいれて独立した行とし、また`-`以外のスペースなどの余計な文字を挟んではならない。

### 画像表示サイズを固定できる

`100x200`のように、幅と高さをpx単位で指定できる。

当該画像の元々の幅または高さをそのまま使いたい場合は、`0`を指定する。例えば`0x100`とした場合は、imgタグには`height="100"`のみが追加され、width属性は付加されない。

### 画像にはIDを付けよう

`#hoge`のように`#`に続く文字列は当該imgタグへのIDと解釈される。ここで「文字列」の構成要素として許容される文字は半角英数文字と`_`のみである。複数のIDを指定しようとした場合は、最後のものだけが有効となる。

IDを指定しなかった場合は、`imageN`というIDが自動的に付加される。ここで`N`は文書先頭からの通し番号である。

### 画像にはクラスも付けられる

`.hoge`のように`.`に続く文字列は当該imgタグへのクラス付加と解釈される。ここで「文字列」の構成要素として許容される文字は半角英数文字と`_`のみである。`.classA.classB`などと、複数のクラスを同時に指定することもできる。

## インラインイメージ＋リンク

WINIは、サムネイルを多用したページ作成にもしっかり対応している。

本文ページには縮小サイズのアイコン的な画像(サムネイル)だけを置いておき、詳しく見たい場合はそのサムネイルをクリックするとオリジナルサイズの画像のみを示したページに遷移するという形式がある。大きなグラフなどを示したいが、本文のレイアウトを崩したくもないといった状況では有効である。WINIでは、ver.0 rel. 200113版から「ハイパーリンク付きインラインイメージ」をサポートしており、こうした要求にもシンプルなマークアップで対応できるようになった。

画像URLを``[]``で囲い、左角括弧の直後に`?`をおくと、「ハイパーリンク付きインラインイメージ」を作れる。すなわち、imgタグの外側にaタグが作られ、画像をクリックすると当該画像のURLに飛べるという構造のHTMLコードとなる。同様に、figureタグに対応した`[?? ...]`記法もサポートされている。

aタグが追加される以外は`[?..]`および`[??..]`記法は`[!..]`および`[!!..]`記法と全く同じである。オプションも共通である。加えて、`@@`あるいは`@newWindow`オプションで、飛び先ターゲットの指定も可能である([ハイパーリンク](https://qiita.com/doikoji/items/f6139b7d91b48e50dcef#%E3%83%8F%E3%82%A4%E3%83%91%E3%83%BC%E3%83%AA%E3%83%B3%E3%82%AF)の項も参照のこと)。

たとえば、image.pngという大きな画像があったとして、本文中に幅100px、高さ100pxのサムネイルを置き、クリックすることでオリジナルサイズの画像表示に飛ばしたい場合、次のようなWINIコードを書けばよい。

```
[?image.png|100x100@@ でかい画像のサムネイル]
```

これは次のようなHTMLコードに変換される。ずいぶんと複雑だ。しかし我々は簡素なWINIテキストを用意すればいいだけなので楽なものだ。

```
<a href="image.png" target="_blank">
<img src="image.png" alt="でかい画像のサムネイル" id="image1" width="100" height="100">
</a>
```

# 見出し

```
! 大見出し
!! 中見出し
!!! 小見出し
```

行頭に置かれた`!`は、当該行が「見出し」であることを示すマークアップ文字である。!の数はhタグのhの後ろに書かれる数字に対応する。つまり`!`が`<h1>`、`!!`が`<h2>`という具合である。

見出しの文字列は`!`の後ろにスペースを一つ以上置いてから書く。

`!`とスペースの**間**にスペース以外から成る文字列を書くと、その部分はこのhタグのIDと解釈される。つまり、`!intro はじめに`は`<h1 id="intro">はじめに</h1>`と変換され、`! intro はじめに`は`<h1>intro はじめに</h1>`と変換される。しかし、rel.200519以降のバージョンでは、次に述べる書法に従うことを推奨する。

## 見出しにはクラスとIDを付加できる

rel.200519以降、見出しにはIDだけでなくクラスも指定できるようになった。見出しマークアップ文字`!`の直後に`#`に続けて半角英数字の文字列を置くと、その文字列が当該見出しのIDとなる。同様に`!`直後に`.`に続けて半角英数字の文字列を置くと、その文字列が当該見出しのクラスとなる。どこにもスペースを入れてはならない。スペースを入れると、それ以降の全てが見出しとして処理される。

クラス指定はID指定と併存できる。また、IDは一つの見出しにつき一つしか指定できない（複数指定を試みた場合、最後に指定したIDのみが有効となる）が、クラスは複数個同時に指定可能である。

以上のような明示的なクラス指定の有無にかかわらず、見出しには必ず`wini`というクラス名が与えられる。

たとえば、

```
!#articletitle#mx-auto Article Title
```

は、`<h1 class="wini articletitle mx-auto">Article Title</h1>`と翻訳される。


また、

```
!#articletitle#mx-auto.id1.id2 Article Title
```

は、`<h1 class="wini articletitle mx-auto" id="id2">Article Title</h1>`と翻訳される。



# 引用

引用もマクロで実現する。

## 標準的なテキスト引用

```
{{q cite=http://example.com}}
引用テキスト
{{end}}
```
qマクロとendマクロに置かれたテキストの内容は完全に保全され、WINIによる改変を受けることはない。波括弧だろうと垂直線だろうと好きに書くことができる。引用テキストはblockquoteタグに囲まれる形で出力される。

`cite=...`はオプションで、引用元を明記する目的で使う。

ver. 0 rel. 20200715以降、qマクロの代わりに「`"""`で始まる独立した行」で挟むことで同じことが出来るようになった。citeオプションをつける場合は`"""`に続けてそのまま書けばよい。つまり上記の例は次のように書いてもよい。

```
"""cite=http://example.com
引用テキスト
"""
```

この記法を使う場合、終端側の`"""`はこれだけで独立した行とし、前後に余計な文字を入れてはならない。また始端側の`"""`行には、`"""`直後のオプション指定以外は文字を入れてはならない。被引用テキストは必ず改行を入れて新しい行として書き始めなければならない。

## 改行保全引用

改行などの体裁を保ったままテキストを置きたいときはpreマクロを使う。preマクロは、qマクロと同様endマクロと対で使用する。endマクロとの間に書かれたテキストが保全されるのは、qマクロと同じである。

```
{{pre}}
引用テキスト
{{end}}
```

ver. 0 rel. 20200715以降、preマクロの代わりに「`'''`のみからなる独立した行」で挟むことで同じことが出来るようになった。つまり上記の例は次のように書いてもよい。

<pre><code>
'''
引用テキスト
'''
</code></pre>

この`'''`記法を使う場合、両端の`'''`はこれだけで独立した行とし、前後に余計な文字を入れてはならない。被引用テキストは改行の後に新しい行として書き始めなければならない。

改行保全引用では、対象テキストが`<pre>`と`</pre>`に挟まれる形で出力される。このため文中に書いた改行がそのまま反映される。

## ソースコード

プログラムコードを示したいときにはcodeマクロを使う。使い方は基本的にpreマクロと同じである。
codeマクロでは`<pre><code>`と`</code></pre>`に挟み込まれる形で引用テキストが出力される。

```
{{code}}
# perl code
$a = $a || '';
print "Hello world\n";
{{end}}
```

ver. 0 rel. 20200715以降、markdown同様にcodeマクロの代わりに\```を利用した記法が使えるようになった。つまり、上の例は次のようにも書ける。

<pre><code> &#096;&#096;&#096;
 # perl code
 $a = $a || '';
 print "Hello world\n";
 &#096;&#096;&#096;
</code></pre>

\```はその前後に一切の文字を置かずに独立した行として書かれなければならない。


# リスト（箇条書き）

```
# n1
# n2
# n3

* u1
* u2
** u1-1
** u1-2
*** u1-2-1
*** u1-2-2
* u3
* u4

; named item 1
: named item 1 desc
; named item 2
: named item 2 desc

: simple list item 1
: simple list item 2

```

番号なしリスト・番号付きリスト・説明リスト（定義リスト）に対応しており、それぞれ簡潔なマークアップで表現できる。複数種類のリストが混在した入れ子のリストにも対応している。

`#`で始まる行は「**番号付きリスト**」である。
`*`で始まる行は「**番号なしリスト**」である。
`:`で始まる行は「説明リスト」または「**番号も接頭辞もないリスト**」である。

このうち`:`の使い方については補足説明が必要であろう。

「説明リスト（昔は定義リストと呼ばれていた）」は、HTML5ではdl, dt, ddタグの組み合わせで実現されるもので、「項目名」と「当該項目の説明」が対になった形式のリストである。WINIではwikiと共通の書式を採用し、項目名は`;`、説明は`:`で始まる行に書く。

「説明リスト」の趣旨を考えれば、当然に`;`で始まる行が`:`で始まる行に先行するはずである。しかし、ウィキペディアではwikiを採用しながらこれを逸脱した書法が事実上公認されている。議論のページ（ノートと呼ばれる）をみると、各自が発言を`:`で始めていることが分かる。`;`は一切無しで`:`で始まる行ばかりが積み重なっていくのだ。このウィキペディアの慣例は、明らかに誤用と言わざるを得ない。しかし実際問題として便利だから使われているのである。

そこでWINIではこの使い方を正式にサポートすることにした。つまり、先行する`;`行が存在しない`:`行は「説明リスト」ではなく単なる箇条書きであると解釈し、dlタグとddタグではなくulタグとliタグに変換する。liタグにはさらにインラインCSSが設定され、箇条書き先頭のマーカー文字が表示されない。

## 箇条書きは入れ子にできる

上の例で示したように、マークアップ文字を複数続けることで「入れ子」のリストを作成できる。番号付き・番号なし・定義付きと、異なるタイプのリストを入れ子にすることも問題ない。

# 脚注

ver.0 rel 200726以降のバージョンで、`^`マクロを本文テキスト中に挿入することにより、脚注を挿入できるようになった。

```
本文中の好きなところに{{^|こんな風に}}脚注を{{^|いくつでも}}挿入できる。
```

`^`マクロ内のテキストがそのまま脚注のテキストとなり、まとめて本文の末尾に箇条書きの形で挿入される。それぞれの脚注には`*1`, `*2`と連番が振られる。

脚注記号はデフォルトで`*`で、その後ろに連番の数字が付く。しかし、本文テキストの後にオプションを追加することで脚注記号をアスタリスク以外のものに変えることもできる。たとえば：

```
本文中の好きなところに{{^|こんな風に|+}}脚注を{{^|いくつでも|+}}挿入できる。
```

この場合、脚注の連番は、`+1`, `+2`のようになる。

また、数字をつける代わりに脚注記号を繰り返すスタイルをとることもできる。

```
本文中の好きなところに{{^|こんな風に|**}}脚注を{{^|いくつでも|**}}挿入できる。
```

この場合、各脚注の先頭は`*`, `**`のようになる。

脚注文字のオプションとして使える指定は次のとおりである。

| オプション | 脚注先頭の表記                                          |
|:----------|:-------------------------------------------------------|
| *         | *1 *2 *3 ...                                           |
| +         | +1 +2 +3 ...                                           |
| d         | &dagger;1 &dagger;2 &dagger;3 ...                      |
| D         | &Dagger;1 &Dagger;2 &Dagger;3 ...                      | 
| s         | &sect;1 &sect;2 &sect;3 ...                            |
| p         | &para;1 &para;2 &para;3 ...                            |
| **        | * ** *** ...                                           |
| ++        | + ++ +++ ...                                           |
| dd        | &dagger; &dagger;&dagger; &dagger;&dagger;&dagger; ... |
| DD        | &Dagger; &Dagger;&Dagger; &Dagger;&Dagger;&Dagger; ... |
| ss        | &sect; &sect;&sect; &sect;&sect;&sect; ...             |
| pp        | &para; &para;&para; &para;&para;&para; ...             |

# マクロ

ここまでなし崩し的に使ってきたマクロについて、ここで詳しく説明する。

まず、繰り返しになるが、基本的にマクロは次のような形態をとる。

```
{{xxx|abc}}
```

このように開き波括弧２つ＋何か＋閉じ波括弧２つというパターンをWINIでは多用することになる。この`{`や`|`が「マークアップ文字」というわけだ。この形式でWINIに与える各種指示のことを「マクロ」と呼ぶ。`{{`と最初の`|`に囲まれた部分が当該マクロの名称であり、それ以降はマクロのパラメータである。本文書の中で特定の種類のマクロを指し示したい場合、その名称をとって「xxxマクロ」のように呼称する。

## マクロの基本

マクロは`{{`で始まり、`}}`で終わる。マクロ名とパラメータの区切りは`|`である。`{{`・`}}`・の前後には改行を入れてもよい。またパラメータ仕切り文字としての`|`の直後でも改行できる。しかし行頭に`|`をもってきてしまうと、マクロ解釈の前に「[表のデータ](https://qiita.com/doikoji/items/f6139b7d91b48e50dcef#%E8%A1%A8)」と解釈されてしまう。そう狙ったのでない限り、`|`の直前で改行してはならない。

マクロ名の解釈では、原則的に大文字小文字は区別されない（後述の通りB,b,I,i,S,sの各マクロは例外）。

定義されていないマクロは何の変換もされず、そのまま出力される。ただし、標準エラー出力に警告メッセージが出力される。

## マークアップ文字を「普通の文字」として記入するためのマクロ

「マークアップ文字」を「普通の文字」として文中で使うには数値文字参照か文字実体参照を使うべしと書いた。しかし、マクロを構成する`{`、`}`、`|`の3文字は頻出する文字でもあり、いちいち暗号のような文字IDを打ち込むのは面倒極まりないだろう。第一覚えていられない。

そこで`{{l}}`, `{{r}}`, `{{bar}}`の3つのマクロを用意した。これらはそれぞれ`{`, `}`, `|`に置換される。

# IDとクラス

HTML5で美しい論理マークアップを実現するため知っておかなければならないのが、IDとクラスという概念だ。「見た目」の指定においても、対象文字列にIDやクラスを振っておいて、そのIDやクラスを対象に文字種や色やその他の見た目属性を指定していく。

WINIでは、任意の文字列に対して、`.`マクロでクラス名を、`#`マクロでIDを指定できる。それぞれHTMLの`<span class="...">`と`<span id="...">`に変換される。

```
{{#id1|この文字列には"id1"というIDが与えられる。}}
{{.class1|この文字列は"class1"というクラスに所属することになる。}}
```

後述するように、WINIでは一部の要素に自動的にクラスやIDが振られる。また簡便にIDやクラスを与えるオプションが使える場合がある。さらに、winiには「[標準CSS](https://qiita.com/doikoji/items/f6139b7d91b48e50dcef#%E6%A8%99%E6%BA%96css)」が設定されていて、文字色・背景色などの設定が簡便にできるようになっている。うまく使って、シンプルなマークアップと理にかなった論理マークアップと美しいレイアウトを両立させてほしい。



# 表

たいていのマークアップ言語では、表の作成がひどく面倒である。残念ながらwikiも例外ではない。この面倒さを解消し、簡単快適に表を作りたい。これこそがWINI開発の主たるきっかけである。結果として以下のような文法がまとまった。作者としては、視認性と機能性がかなりのレベルで両立できたと自負している。

## 基本的な書き方

行頭に`|`が置かれた行が1行以上続いていた場合、その部分は**WINI table**とみなされ、それぞれがHTML tableに変換される。

単純な例として、ウィキペディア日本語版の[『表の作り方』](https://ja.wikipedia.org/wiki/Help:%E8%A1%A8%E3%81%AE%E4%BD%9C%E3%82%8A%E6%96%B9)にある最初の例をWINIで書き下してみよう。

```
|- 表のタイトル | class="wikitable"            |
|  見出し0   | 列見出しA | 列見出しB | 列見出しC |
|  行見出し1 |    セル1A | セル1B   | セル1C    |
|  行見出し2 |    セル2A | セル2B   | セル2C    |
``` 

まず把握してほしいのは、次の2点である。

* 最終的に出力されるwiki tableの各行はWINIテキストの各行と（ほぼ）1:1対応である。つまり、各行がそれぞれTRタグに置換される。
* 各行は、「**区切り文字列**」と「**セル内容**」がスペースで仕切られて交互に並ぶ形をとる。

この原則ゆえに、WINI tableでは、視覚的・直感的な内容把握と共に、高度な表現も可能となった。

少しだけ複雑な表の例を示そう。

```
|- capt.           | &c border="1"                          |
|!!$$50$50         |$50.f-r 列1 |$100.f-g 列2 |$150.f-b 列3 |
|!$$50         行1 |&l      A   |        B    |-            |
|!&&r$$50      行2 |^           |&l      C    |         D   |
|!$$50         行3 |        E   |        F    |-            |
|!$$50         行4 |&t      G   |^            |-            |
|!$$200        行5 |&b      H   |-            |-            |
```
このWINIテキストは次のような表になる。
![sampletable.wini.html.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/383429/aa202116-5eb6-14c1-6362-6fe3a92d40db.png)

WINIの可能性の一端がお分かりいただけただろうか。

## キャプション・表全体の設定

行頭が`|-`で始まる行は、「**キャプション・設定行**」となる。表全体の設定とキャプション文字列を設定する部分である。書式は次のようになる。

```
|- キャプション | 設定定義 |
```

### キャプション

キャプションは`|-` の直後から ` | `の直前までの文字列である。`|`の前後にスペースを置かなければならない点に注意してほしい。キャプション用文字列の中にWINIマークアップを書くことができる。その内容はtableタグ内の`<caption></caption>`内に反映される。

### 表全体の設定

` | `以降の記述は設定定義として扱われる。以下に示すような所定のフォーマットに沿った「オプション指定文字列」を追記していくことによって、表全体に関わる各種設定が行える。

## 表全体に設定できる項目

前述のとおり、キャプション・設定行には、表全体のスタイルに関する様々なパラメータを設定できる。ここではそれらの詳細を説明する。

### 罫線

#### 罫線指定文字＋線種指定＋線幅指定 

「**罫線指定文字**」で始まるオプション指定文字列によって、表内の罫線を設定できる。罫線指定文字に続けて、線種指定・線幅指定のオプションを、この順番で追加指定できる。この設定は表内のすべてのセルの設定に反映される。

たとえば、`@:4`と書くと、表内の全セルの周囲（上下左右）に4pxの破線が描かれる。

##### 罫線指定文字

罫線指定文字には以下の種類がある。罫線指定文字の書法は、ここで述べた外枠対象のものと後述のセル・行・列対象のものとで基本的に共通である。ただし、左右罫線指定の`|`だけは後述の行・列・セル単位の罫線指定にのみ有効で、外枠罫線の設定には使えない。

<table border="1">
<tr><th>罫線指定文字</th><th>意味</th></tr>
<tr><td>[</td><td>左側罫線</td></tr>
<tr><td>]</td><td>右側罫線</td></tr>
<tr><td>|</td><td>左右罫線</td></tr>
<tr><td>~</td><td>上側罫線</td></tr>
<tr><td>_</td><td>下側罫線</td></tr>
<tr><td>=</td><td>上下罫線</td></tr>
<tr><td>@</td><td>上下左右罫線</td></tr>
</table>

##### 線種指定

線種指定としては、以下のいずれかの文字を指定できる。

* `;` : 二本線 (double)
* `:` : 破線 (dashed)
* `,` : 点線 (dotted)

この指定は省略可能で、その場合は一本線(solid)が指定されたと見なされる。

##### 線幅指定

当該罫線の太さをpx単位で設定できる。線幅指定は0以上の整数値を取る。
線幅指定は線種指定の直後に置く。線種指定が省略されている場合は罫線指定文字の直後に置く。
この指定は省略可能で、デフォルトは1pxとなる。

#### 範囲指定＋罫線指定文字＋線幅指定

ver 0. rel 20200102版より、wini tableの中でtbodyおよびtfootが扱えるようになり、それに伴って、表全体だけでなく、tbodyタグの中、tfootの中のすべてのセルの罫線スタイルを一括指定するオプションが追加された。

* `t@n`: 表全体
* `b@n`: tbody内全体
* `f@n`: tfoot内全体

ここでnは任意の整数である。先述の線幅指定同様、罫線の太さをpx単位で表したものと解釈される。

#### borderオプション🚧

前述の罫線指定文字は、tableタグのstyleオプション内のパラメータを設定するものである。ところが、styleオプションとは別にtableタグにはborderというオプションが存在する。borderを使うと、表中の全行・全列の罫線の表示・非表示をまとめて設定することになり、表の外枠にも内部のセル間にも一様のスタイルで罫線が引かれることになる。

古いHTMLに基づいた解説書では、このオプションで線幅を指定できるように説明されていることがある。しかしHTML5では通用しない。あくまでも「表全体に統一的に罫線を入れるか、全く入れないか」の二択となっている [^1]。

[^1]: …はずなのだが、Firefox 71.0ではその値を変化させることでしっかり線幅が変わるようだ。

WINIではオプション指定行に`border="1"`と追記することで、tableタグにborderオプションを指定する。パラメータは事実上`1`のみである[^2]。

[^2]: …が、上記の事情があるのでborder指定の仕様はまだ変更の可能性がある。

これは「そこそこの見栄え」の表を手早く作りたいときには非常に便利である。だが、レイアウトの複雑なコントロールには対応しにくい。

### ID・クラス

`.名前`の形式のオプション指定文字列によって、当該テーブルにクラスを設定できる。
同様に`#名前`の形式のオプション指定文字列によって、当該テーブルにIDを設定できる。

### CSS

`xxx=yyy` の形式のオプション指定文字列によって、tableタグ内のstyleオプションに設定すべきCSSプロパティを指定できる。たとえば`color=red`と書くと、最終的に`<table style="color: red;">`のようになり、表中の文字が赤色となる。


### 字配り

`&`で始まるオプション指定文字列によって、表内の全セルでの水平・垂直方向の字配りの設定ができる。`&`の後には以下に示すオプション指定文字のいずれかを指定する。`&lb`のように複数を同時に指定してもよい。

<table border="1">
<tr><th>オプション指定文字</th><th>意味</th></tr>
<tr><td>l</td><td>左寄せ</td></tr>
<tr><td>r</td><td>右寄せ</td></tr>
<tr><td>c</td><td>中央寄せ</td></tr>
<tr><td>j</td><td>ジャスティフィケーション</td></tr>
<tr><td>s</td><td>左寄せ</td></tr>
<tr><td>e</td><td>右寄せ</td></tr>
<tr><td>b</td><td>下揃え</td></tr>
<tr><td>t</td><td>上揃え</td></tr>
<tr><td>m</td><td>中央揃え</td></tr>

</table>

## 行と列とセル

キャプション・設定行を除き、WINI tableの各行はHTML tableの各行（&lt;tr>..&lt;/tr>で囲まれた部分）に原則的に1:1対応する。各行は「**区切り文字列**」で分割され、分割されたそれぞれが「セル内容」である。

「区切り文字列」とは、「行頭またはスペースに続く`|`とそれに続く0文字以上のスペース以外の文字からなる文字列」である。この`|`以降の文字列は当該のセル・行または列対象の設定定義となる。設定定義の部分には、いくつかの「**オプション指定文字列**」がスペースを置かずに書き連ねられることになる。

### 脚注行

行頭を`|---`で始めると、その行は脚注と見なされ、その内容はtfootタグ内に反映される。wini table内のどこに配置しても、また何行指定しても、それらは一つにまとめられてtbodyよりも下に配置される。セル中に`^マクロ`を使って注釈を挿入した場合はそれもtfoot内に置かれるが、それらは`|---`指定の行よりも更に下に配置される。

脚注行の機能はver 0. rel 20200102版で追加された。

### 注釈

セル内の任意の文字列に対して`^マクロ`で注釈を挿入できる。

```
| セル内容{{^|このセル内容の補足}} |
```

このような感じで注釈を入れたい箇所に注釈行を挿入する。すると、出来上がりの表では、このマクロの位置に注釈文字（デフォルトは`*`）が挿入され、テキストはtfootセル内に移されて表の一番下に配置される。

この機能はver 0. rel 20200102版で追加された。

さらに[本文への注釈](https://qiita.com/drafts/f6139b7d91b48e50dcef/edit#%E8%84%9A%E6%B3%A8)で述べたのと同じオプション指定を利用して注釈記号を変更できる（ver. 0. 20200727版以降）。

### オプション指定

#### セルの結合

表中で複数セルをくっつけて「一つのセル」のように扱うことは非常に頻繁に行われる。WINIでは次のように表現する。

* 結合されるセルのオプション指定文字に`-`を指定することで、当該セルがその左にあるセルに結合されるべきであることを示す。
* 結合されるセルのオプション指定文字に`^`を指定することで、当該セルがその上にあるセルに結合されるべきであることを示す。

ウィキペディア日本語版の『表の作り方』より[「セルの結合」](https://ja.wikipedia.org/wiki/Help:%E8%A1%A8%E3%81%AE%E4%BD%9C%E3%82%8A%E6%96%B9#%E3%82%BB%E3%83%AB%E3%81%AE%E7%B5%90%E5%90%88)の項を見てみよう。wikiによるセルの結合の例が示されている。

![wikitable2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/383429/2f4b3102-47f8-0e65-5bdf-2c3b6f7ffcd9.png)

この例と同じ内容のHTML Tableを得たいなら、以下のようなコードで実現可能である。いかがであろう。wikiより遥かに直感的で解りやすいと思われないだろうか。

```
|-      | class="wikitable" &c |
|!!       |  列1 |  列2 |  列3 |
|!!! 行 1 |  A   |  B   |-     |
|    行 2 |^     |  C   |  D   |
|    行 3 |  E   |  F   |-     |
|    行 4 |  G   |^     |-     |
|    行 5 |  H   |-     |-     |
```


##### 作者のつぶやき

こうした「セルの結合」をHTML tableではcolspanやrowspanオプションによって実現する。「このセルの右（あるいは下）のいくつのセルを当該セルに結合するか」を明示する方式だ。wikiもこれに倣っている。

この方式には致命的な弱点がある。いくつのセルを結合するのかを作者がいちいちチェックして明示的に指定しなくてはならない点だ。

単純な表ならそれでもいい。だが、以下の図のように、行・列の数がある程度以上ある表の中のセルを不規則的に結合したい状況を考えてみてほしい。

![tablesample.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/383429/3ca47f96-06f5-6881-a9ff-70a9e64bf74d.png)

「最初の黄色の項目は1,2,3...8つ、その左下の緑の項目は1,2,3...5つ」などと、いちいち面倒くさい数勘定などやっていられるものか。こんなのは人間がやるべき作業ではない。コンピュータに任せるべきであろう。

というわけで、これとは一線を画したより優れた方法をWINIでは採用した次第である。

#### 複数行融合

オプション指定文字列に`^^`を加えると、その行の内容は一つ上の行に「融合」される。つまり、当該行の各セルの内容は、一つ上のセルの内容にそれぞれ追記される形となる。

例えばこんな感じになる。

```
|   #項目1 | こんな感じで           |
|^^ #項目2 | 物理的な3行を          |
|^^ #項目3 | 論理的な1行として扱う。 |
```  
これは次のように書いたのと同じ結果をもたらす。

```
| <ol><li>項目1</li><li>項目2</li><li>項目3</li></ol> | こんな感じで物理的な3行を論理的な1行として扱う。|
```

##### 作者のつぶやき

WINI tableの一行はHTML tableのtr行に原則1:1対応であると最初に述べた。ところが、これでは問題が出ることがある。どうしてもセル内に複数行の内容を書きたいことがあるのだ。他でもない、箇条書きである。

表内にこそ箇条書きをバリバリ書くべきであろう。当然ながら、箇条書きは改行しながら書きたい。表の中であっても。しかし1行:1行対応の原則を貫いていてはこれは無理だ。

一方、既存の諸々の軽量マークアップ言語で、「表中に箇条書きをバリバリ書きたい」との要求にスマートに答えてくれているものは、作者が知る限り存在しない。WINIはそれらとは一線を画さねばならないのだ。

かくして、複数行融合機能を用意する運びとなった。

さらに複雑な表のために「[表内マクロ](https://qiita.com/doikoji/items/f6139b7d91b48e50dcef#%E8%A1%A8%E5%86%85%E3%83%9E%E3%82%AF%E3%83%AD)」という機能も用意されているのでチェックしていただきたい。

#### 見出し文字

オプション指定文字列に`!`を加えると、そのセルの文字は「見出し」として扱われ、そのセルの内容は`td`タグではなく`th`タグでマークアップされる。`!!`とすると当該セルを含む行の全てのセルが、`!!!`とすると当該セルを含む列のすべてのセルが、同様に処理される。

#### 罫線

「罫線指定文字」で始まる設定定義文字列によって、当該セルの周辺の罫線の有無とその線の太さを設定できる。

設定定義文字列は線種指定と線幅指定からなる。罫線指定文字は「表全体の設定」と共通である。ただし、`==`のように2つ続けることでそのセルを含む行全体を対象としたものとみなされる。また、`===`のように3つ続けることでそのセルを含む列全体を対象としたものと見なされる。

線種指定文字と線幅指定については「表全体の設定」で述べた通りなので、詳細については同項を参照してほしい。

#### 行サイズ・列サイズ

`$数字`でセルの横幅（列サイズ）、`$$数字`でセルの縦幅（行サイズ）を設定できる。数字はpx単位と解釈される。

#### 字配り

表全体の設定の字配りの項で示したオプション指定文字列を、セル・行・列の字配り設定にも使用できる。

すなわち`&オプション文字`形式の指定で、当該セルの字配り設定ができる。`&&オプション文字`、`&&&オプション文字`で、それぞれ当該行・当該列の字配り設定ができる。

#### クラス

オプション指定文字列に`.名前`を加えると、そのセルは「名前」をクラス名とするクラスに所属することになる。`..名前`とすると当該セルを含む行の全てのセルが、`...名前`とすると当該セルを含む列のすべてのセルが、同様に処理される。

IDの指定については重要な注意事項がある。**この指定は他の全てのオプション指定の《後》に置かなければならない。** `.`以降の文字はすべてIDの一部として解釈されるからだ。

## 表内マクロ

ここまで見てきたとおり、WINI tableの文法はかなりWYSIWYG的で理解しやすい。しかし、表内のテキスト（セル内容）が長大になってくると、それなりに編集操作（具体的にはテキストに合わせて縦線を揃える操作）が煩雑になってくる。この問題を解決するために、WINI ver 0. rel. 20200727から「表内マクロ」という機能が利用できるようになった。

「表内マクロ」の利用により、セル内容をその表内でのみ通用する短いコード（表内マクロ名）に置き換えることができる。表内マクロは表本体とは分離した形で定義される。換言すると、「表構造定義」と「セル内容定義」を分割管理できるようになる。

実例を見たほうがわかりやすいだろう。以下は「表内マクロ」を利用したコード例である。

```
|-        | border="1"
|  期     |<03c1   |!! 方式  |<03c4$100  |<03c5     |<03c6$100     |<03c7 |<03c8 |<02c9 |<02c10 |
|!!! 1    | 10時間 | -       |<1c4       | 定めず   | -            |<1c7  |<1c8  | 10名 |<1c10  |
| 2       |^       |<2c3&c   |^          |^         |<2c6          |^     |^     | 7名  |<2c10  |
|02c9 通過人数                                                                          
|02c10 出場条件
|03c1 待ち時間
|03c4 出場人数
|03c5 組順位
|03c6 シード条件
|03c7 組優勝決定方法
|03c8 残留者決定方法
|1c4  ;10名
|^^   :*A組5名
|^^   :*B組5名
|1c7  成績首位全員の{{*|トーナメント}}で決定
|^^   {{^|奇数の際のシード者に前年の成績は考慮されない}}
|1c8  残留ライン上全員の{{*|トーナメント}}で決定
|^^   {{^|奇数の際のシード者に前年の成績は考慮されない}}
|1c10 棋士全員
|2c3  {{v|紅白の優勝者で決勝}}
|2c6  ;3名
|^^   :*前期七番勝負敗者
|^^   :*前期リーグ2位
|2c10 {{*|棋士全員}}（シード者以外）
```

以上のコードをwini.pmに与えると、以下のような表が出来上がる。

![winitable3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/383429/371465f4-9263-49ed-ca9c-56d017c5d84d.png)

### 表構造を記述する ━ 表内マクロを挿入する

表内マクロをセルに挿入するには、「区切り文字列」のオプションに表内マクロ名を指定する。その書式は`<マクロ名`である。

### セル内容を記述する ━　表内マクロを定義する

行頭に`|`に続けて「数字またはアルファベットのみから成る文字列」が現れた場合、その行は表内マクロの定義行と見なされる。 この「数字またはアルファベットのみから成る文字列」がそのまま表内マクロ名となる。

表内マクロ名の後ろに一つ以上のスペースを置き、マクロの内容を記述する。この部分にはWINIの全ての記法が利用できる。マクロの内容は複数行にわたって記述することもできる。行頭に`|^^`を置いて[複数行融合](https://qiita.com/doikoji/items/f6139b7d91b48e50dcef#%E8%A4%87%E6%95%B0%E8%A1%8C%E8%9E%8D%E5%90%88)の形で書けばよい。

# CSSの適用

HTMLはテキストと文章構造を定義することに特化した言語である。一方、我々がwebブラウザを通してみるテキストの「見た目」はHTMLとは独立した言語であるCSSが規定するのが原則である。WINIはHTML5のプリプロセッサであるから、「見た目」に関しては直接的なフォローは行わない。

ただ、WINIの一部のマクロは所定のCSSの記述が存在することを前提としている。また、完成品としてのHTMLファイルにおいてはヘッダ部分に適切なCSSの指定が必要とされる。そこで、コマンドとしてのwini.pmは、CSSの取り込みを簡単に実現するためのオプションパラメータをサポートしている。


## CSSフレームワークを利用する

[CSSフレームワーク](https://qiita.com/tags/css%e3%83%95%e3%83%ac%e3%83%bc%e3%83%a0%e3%83%af%e3%83%bc%e3%82%af)とは、webページの構築に使われる要素一式（ボタンやフォーム等々）のデザイン定義をセットにして供給するものである。出来合いのCSSを利用することで、レスポンシブで格好いいwebページを至極少ない手間で構築できる。有名どころではBootstrapやSemantic UIなどが挙げられるだろう。こうしたメジャーなフレームワークをベースとして更に目的特化型の定義をトッピングした二次CSSフレームワークとでも呼ぶべきものも沢山公開されている。

2020年現在において興味深い話題の一つは、クラスレスCSSフレームワークであろう。Bootstrapなどは目的ごと・レイアウトのパラメータごとに山ほどのクラスが定義され、これをdivタグを通して使いまくるというスタイルになるが、「クラスレス」はそれとは対極的な戦術を採用しており、クラスに頼らず、HTMLのタグに対してのみデザインの定義を行う。WINIを使ってみようと考えるような人は、とにかく手間をかけずに最低限の品質のwebページを仕立てたいといった欲求を大抵もっていると思われるが、そうしたユースに非常によく合うアプローチである。

参考: [【HTMLのみでOK】class/id必要なしの超手軽で軽量なCSSを利用する - Qiita](https://qiita.com/yoshi_yast/items/8083caa4f86db4e81a50)

コマンドラインツールとしてのwini.pmは、オプションパラメータの指定によってこうしたCSSフレームワークを簡単に取り込めるように設計されている。

```
wini.pm --whole --cssflamework 'https://newcss.net/new.min.css' < input.wini > output.html
```

できた`out.html`のhead内にはnew.cssを読み込むタグが含まれているはずである。

-cssflameworkオプションは複数同時に指定することもできる。また、URLを省略することもでき、その場合は`--cssflamework 'https://unpkg.com/mvp.css'`と指定したことになる。mvp.cssは使い勝手の良いクラスレスCSSフレームワークの一つである。

参考: [MVP.css - 素のHTMLでもいい感じの表示に MOONGIFT](https://www.moongift.jp/2020/04/mvp-css-%E7%B4%A0%E3%81%AEhtml%E3%81%A7%E3%82%82%E3%81%84%E3%81%84%E6%84%9F%E3%81%98%E3%81%AE%E8%A1%A8%E7%A4%BA%E3%81%AB/)

## 標準CSS

一部の機能はWINIが想定する標準的なCSS設定を前提として実現されている。具体的には色設定系のマークアップなどがそれにあたる。`--whole`オプションをつけてwini.pmを実行すると、こうした「標準的なCSS設定」を含むstyleタグが出力先HTMLファイルのヘッダに付け加えられる。さもなくばstyle設定をユーザ側で適切に補う処理を付け加えなければならない。

また、`--cssfile 外部CSSファイル名`を指定してwini.pmを実行すると、外部CSSファイルが生成され、スタイル設定がHTMLファイル内ではなくそのCSSファイルに書き加えられる。外部CSSファイル名の指定は省略でき、デフォルトは`wini.css`である。

## バリアフリーな標準色名

HTML/CSSには色名の定義があり、例えばredならRGB値は(255,0,0)だ。しかし、新マークアップ言語WINIではredは(213,94,0)としてある。

これは
https://bit.ly/2tqaP6P
の提言に従い、色覚障害者にも判別しやすいカラーリングを簡単に実現するための仕様である。

というのは、赤緑色盲の人には標準のred,greenの判別がしづらい。そこでvermillon, bluish greenで代用し、それぞれをWINIにおけるredとgreenとして取り扱う。健常者にとってはちょっとくすんだ感じになるが、判別はしやすくなるのだ。

同様にblue, magenta, purple, yellowもそれぞれ代用色を採用している。

`wini.pm --whole`で作り出されるHTMLファイルには上記を織り込んだCSS設定が記述される。マークアップにWINIを使えば、ややこしいことを考えずに自然にバリアフリーな文書作成ができるというわけなのだ。

# コマンドラインツールとしてのwini.pm

```
wini.pm < input.wini > output.html
```

冒頭に記したように、wini.pmはperlのモジュールファイルとして機能すると同時に、PATH設定されたディレクトリに置く（あるいはシンボリックリンクを置く）ことにより、単体でスクリプトファイルとして扱えるように作られている。

このことの利便性は大きい。セットアップの手間が省けるだけなく、様々な形式でシェルスクリプトに組み込むことができるし、ワンライナーで超絶的に手早くHTMLファイルを作ることができるのだ。

## ワンライナーで勉強する

まず、wini書式の使い方をワンライナーで手軽に確認できる。マクロがどのようなhtmlコードに展開されるのか確認することも容易だ。以下は、bマクロとBマクロの違いを確認しようとしたところだ。

```
$ echo '{{b|abc}}' | wini.pm
<p>
<span style="font-weight:bold;">abc</span>
</p>

$ echo '{{B|abc}}' | wini.pm
<p>
<b>abc</b>
</p>
```

## パイプとリダイレクトで実務を手早く片付ける

以下の例は、今月のカレンダーをHTMLtableとして出力するワンライナーである。

```
$ cal -1 | awk 'BEGIN{OFS=" | "} /[^ ]/{print "",$1,$2,$3,$4,$5,$6,$7}' | wini.pm > output.html
```

# おわりに

以上のとおり、WINIはシンプルながらも充分な表現力を備えた軽量マークアップ言語である。

また、wini.pmという名称から気付いている人もいるだろうが、WINI記法をサポートしたこのスクリプトファイルは元来perlのモジュールとして機能するよう作られている。つまり、簡単に他のperlスクリプトの中に組み込んで利用できるのだ。プログラミングの腕に覚えのある人はぜひ面白いアプリケーションソフト作りに生かしてほしい。作者としては次にWINIを基盤とした静的CMSを作りたいと思っている。