TLDR

groff(1.22.4など、jgroffがどこかにいった時代におけるバージョン)は日本語対応とかUTF-8対応とかどうなってるの？誰か教えてくれ。
man-dbは本当の.Sh NAMEがなければ.Dd,.Osなどの「ヘッダーやフッターのための」リクエストが無視される(使ってるマクロがgroffのmdocだからか?)
- groffも同様(英文じゃなければ話にならないことを除いて)
mandocは優秀。.Sh NAMEが.Sh "名称"であろうが、.Shがなかろうがヘッダやフッタが表示される。

この記事を書いた動機

マニュアルを書いてみたい。それも是非mdoc(7)形式で書けるのであれば。

何故man(7)ではなくmdoc(7)で書くべきなのか

見た目ではなく意味論の重視ができる。あと、後者は新しい。と書くには私の我儘がヤバい。

何をした

FreeBSD 5.2-RELEASE向けの日本語オンラインマニュアルをダウンロードした
いろんなマニュアルがEUC-JPでmdoc(7)形式で書かれていた(一部はman(7)形式だった。ar.1.gzやgrep.1.gzがそうである。GNU由来のマニュアルがそのような傾向にあると思われる。)
そのなかでintro.1.gzでレンダリングのテストをしてみた

私の環境

Arch GNU/Linux。最後のpacman -Syuによるアップグレードは2023-01-04である。端末エミュレータはrxvt-unicode 9.30-1。幅は、168文字。

$ stty size
48 168

ソフトウェアは何を使った

$ yay -Q man-db groff mandoc
man-db 2.11.1-1
groff 1.22.4-7
mandoc-noconflict 1.14.6-1

※mandocパッケージもあるが、それはman-dbと衝突するし、何よりこの記事を作成している時点では上流URLが修正されていないので、mandoc-noconflictというAURパッケージで代替。

intro.1.gzの冒頭はどんな見た目か

$ zcat ./intro.1.gz | # GNU拡張ですまない。gunzip -cで同じことができる。
> iconv -f EUC-JP -t UTF-8 | # 文字コード変換。筆者の環境はUTF-8。
> awk '$1!=".\\\""{s=1}s' | # 冒頭にコピーライト表示のコメントがあるため削除
> head # 最初の十行を取得
.Dd October 21, 2001
.Dt INTRO 1
.Os
.Sh 名称
.Nm intro
.Nd 通常コマンド (ツールとユーティリティ) の手引
.Sh 解説
マニュアルのセクション1は、
.Bx
ユーザ環境を構成するコマンドのほとんどについて書かれています。

このように、.THや.SHが登場するman(7)とは打って異なり、mdoc(7)では.Dd,.Os,.Shなどのマクロが登場する。

レンダリングさせてみた

groffで

日本語文字化け。

$ zcat ./intro.1.gz | iconv -f EUC-JP -t UTF-8 |
> nroff -mdoc | # このコマンドで端末へのレンダリングが容易
> head

åç§°
     intro — éå¸¸ã³ãã³ã (ãã¼ã«ã¨ã¦ã¼ãã£ãªãã£) ã®æå¼

è§£èª¬
     ããã¥ã¢ã«ã®ã»ã¯ã·ã§ã³1ã¯ã BSD
     ã¦ã¼ã¶ç°å¢ãæ§æããã³ãã³ãã®ã»ã¨ãã©ã«ã¤ãã¦æ¸ããã¦ãã¾ãã
     ã»ã¯ã·ã§ã³1ã«å«ã¾ããã³ãã³ããä»¥ä¸ã«ããã¤ãåæãã¾ãã

     ããã¹ãã¨ãã£ã¿

man-dbで(特に何も指定しなかったらgroffが使われる…と`man 1 man`で理解なう)

ヘッダやフッタが表示されなかった。

$ zcat ./intro.1.gz | iconv -f EUC-JP -t UTF-8 | man -l - | head

名称
     intro — 通常コマンド (ツールとユーティリティ) の手引

解説
     マニュアルのセクション1は、 BSD ユーザ環境を構成するコマンドのほとんどについて書かれています。 セクション1に含まれるコマンドを以下にいくつか列挙します。

     テキストエディタ

     コマンドシェルインタプリタ

mandocで

ヘッダ出た。

$ zcat ./intro.1.gz | iconv -f EUC-JP -t UTF-8 | mandoc | head
INTRO(1)                    General Commands Manual                   INTRO(1)

 名 称
     intro – 通常コマンド (ツールとユーティリティ) の手引

 解 説
     マニュアルのセクション1は、 BSD
     ユーザ環境を構成するコマンドのほとんどについて書かれています。
     セクション1に含まれるコマンドを以下にいくつか列挙します。

考察(？)と結論

groffの方のmdoc(7)のマニュアルでは

The ‘.Sh NAME’ macro is mandatory. If not specified, headers, footers and page layout defaults will not be set and things will be rather unpleasant.

すなわち節名が文字通り「NAME」となっている節がなければ正しいレンダリングがなされないという。一方でmandocの方のmdoc(7)は同様の記述が見受けられなかった(正しいマニュアルとして最初の節にNAME節が来るべきだという記述はあったが動作にまで影響が出るわけではない)。

~~groff側よ、可能であればそのような宗教戦争を止めてくれないかね。~~