テンプレートページ：ラベル付きの図

このページでは、テンプレートページや本文の図のうち、画像の上に文字を置くものを扱います。テンプレートページの書き方はテンプレートページに、ラベルスタイルとアンカーのラベル用フィールドは設定 › テンプレートページにあります。

#ラベル付きの図

:::figure{resource="mapa-europa" slot="mapa"}
::label[OCÉANO ATLÁNTICO]{at="atlantico" style="mar"}
::label[**Madrid**]{at="madrid"}
::label[Mar Negro]{at="62% 48%"}
:::

:::figure{resource="…"}は、::resourceと同じく1つのリソースをキャプションと番号付きで置き、画像の上に置くラベルを並べます。ラベル1つにつき::label[テキスト]{…}を1行書き、間に空行をはさんでもかまいません。

• atは、リソースのアンカー（画像の上に一度だけ定義し、すべての言語で共有する点）を指定します。アンカーのないラベルには、画像に対するパーセントで点をat="x% y%"と指定します。
• styleはラベルスタイルを指定し、アンカーのスタイルより優先します。
• leaderはラベルからアンカーの点まで線を引き、leader="none"はその線を外します（引き出し線、凡例、記号を参照）。
• 角括弧の中のテキストはインラインのMarkdownで、太字、イタリック、チップ、:iconで書く記号が使えます。

図は、枠の中だけでなく本文の流れの中でも使えます。図のラベルは文字として画像の上に描かれ、図がどこに置かれてもいっしょに移ります。段、フロート、再配置の手順（内容を収めるための処理）で回転や縮小をした枠、見開きのどれでも同じです。図を閉じる:::が欠けていると、ラベルでも空行でもない最初の行で図は終わり、閉じていないコンテナーとして報告されます。

#図に固有の文言

リソースに入っているのは1枚の画像、そのアンカー、1組の文言だけですが、本の版ごとに文言は違います。そこで図はalt、caption、noteを自分で指定できます。開始行の属性としても、専用の行としても書け、そのファイルのページではリソースの文言に代わって使われます。

:::figure{resource="relieve" alt="Mapa de relieve de Varenia"}
::caption[Relieve de **Varenia**, con sus tres cordilleras]
::note[Fuente: levantamiento de 1932]
::label[Mar de Sal]{at="mar"}
:::

• 開始行の属性としては、alt、caption、noteに引用符で短い文字列を渡します。::alt[…]、::caption[…]、::note[…]の行は角括弧の中の文字列を取り、リソースのキャプションや注記と同じくインラインのMarkdownと、改行の\\が使えます。同じ名前の属性より行が優先されます。行はラベルの間に置け、空行をはさんでもかまいません。
• 図が指定しない項目は、リソースのままです。空文字列は「何も書かない」の意味で、caption=""はキャプションを外し、alt=""は画像を装飾として扱います。
• 文言は、それを書いた章の中でリソースのものに代わります。レイアウトも、各出力の代替テキストも、タグ付きPDFも、この文言を使います。リソース自体は変わりません。1つの章の中では、リソースの文言は1組だけで、最初の図のものが使われます。同じリソースを使う後の図が別の文言を書いても表示されず、figureWordsSharedで知らされます。専用のキャプションが必要な縮小版には、同じ画像ファイルを指す2つ目のリソースを使ってください。ラベルと違い、キャプションはMarkdownと1文字ずつ対応づけられてはいません。sourceAtは、リソースのキャプションと同じように、クリックした位置のソースを返します。

#ラベルの組み方

• 位置：ラベルはアンカーの点に置かれます。点は画像全体に対する割合で表すので、画像がセーフエリアに合わせてトリミングされても、小さく組まれても、ラベルは画像といっしょに動きます。アンカーのalignはラベルのどの側を点に合わせるか、verticalAlignはどの辺を点の高さに合わせるかを決めます。startとendはラベル自身の書字方向に従い、アラビア語のラベルではstartが右端です。rotateは点を中心にラベルを時計回りに任意の角度で回します。川の流れに沿った川名や、斜めに並ぶ山地名などに使います。
• 見た目：ラベル自身のstyle、なければアンカーのstyleがラベルスタイルを指定します（「設定：テンプレートページ」を参照）。スタイルがなければ本文の書体設定を使います。縁取りは文字の塗りの下に輪郭を描き、下地（background）は文字のまわりの矩形を塗ります。下地はpaddingの分だけ広がります。
• 収め方：アンカーにwidthがあると、ラベルはその幅の中で語と語の間で折り返し、語の途中では切りません。ある語が幅より広いときは、ラベル全体をスタイルのminScaleまで小さく組みます。それでも収まらないラベルは、いちばん広い語を切って描きます。widthがなければラベルは1行のままで、キャプションと同じく\\で改行した所だけ折り返します。
• テキスト：角括弧の中はインラインのMarkdownで、キャプションと同じように組まれます。太字、イタリック、チップ、ハイライト、相互参照、インライン数式が使えます。複数の語からなる名前は、言語ごとに語順が違っても1つのラベルです。::label[大西洋]と::label[ATLANTIC OCEAN]は同じアンカーに置かれます。右から左へ書く言語のラベルは右から左へ組まれ、中国語と日本語のラベルは文字の間で折り返します。
• 出力：キャンバス、PDF、HTMLビューアー、固定レイアウトのEPUB、Folioがラベルを描きます。右から左のページでも、ラベルは画像が示す位置にとどまります。
• 縦組み：アンカー（またはそのラベルスタイル）にwritingMode: 'vertical-rl'を指定すると、ラベルは縦組みのページと同じように組まれます。文字は正立のまま1文字ずつ上から下へ並び、列は右から左へ進みます。欧文の単語と長い数字は横倒しに、短い数字は1マスに収まります。このときwidthは画像の高さに対する割合、つまり1列の長さで、中国語や日本語のラベルはさらに列を増やして折り返します。alignは列に沿った向き（startが列の上端）、verticalAlignは列をまたぐ向き（topが最初の列、つまり右端の列）で、rotateはラベルをさらに回します。右から左へ綴じる本の鏡像ページでも、ラベルは同じく列を上から下へ、文字を正立のまま、画像の同じ位置で読めます（postext 1.40以降）。
• 検査：ラベルスタイルのminScaleまで縮めても幅に収まらないラベルにはlabelOverflow、行がぶつかる2つのラベルでは後のほうにlabelOverlapが出ます。どちらも版ごとに調べるので、語の長い訳文では、どこに余裕が必要かがわかります。部（:::part{palette="…"}）のパレットは、キャプションと同じようにそのページのラベルの色を置き換えます。コントラストの検査は、ラベルを下地の上で、なければ縁取りの上で測ります。画像の上に直接置いたラベルは、背景が画像なので対象外です。印刷のプリフライトは、ラベルの小さな文字が複数のインキで刷られていないか、インキの量、仕上がり線までの距離も調べます。
• 見開きで。 見開きののどをまたぐ図（crossGutter: trueの枠）は、それぞれのページに自分の側の半分を描きます。そのため、ラベルの矩形がのどの帯に入ると、折り目で切れてどちらのページでも読めなくなります。そこでラベルは、アンカーの点がある側へ、帯の端まで横にずれ、高さは変わりません。のどの真上にある点は、枠と同じく最初のページに属します。gutter: 'cross'のアンカーはその場に残ります。両ページにまたがる見出しに使います。紙面の外側の縁には手を加えません。仕上がり線を越えたラベルは、画像と同じように切れます。postext 1.43以降。

#引き出し線、凡例、記号

postext 1.48からは、ラベルを名前の指す場所から離して置けます。ラベルを地図の凡例にすることも、ラベル、キャプション、表のセルに記号を入れることもできます。

引き出し線：アンカーのlabelAtはラベルを点から離れた位置に置き（海の上の名前、図解の余白の注記）、引き出し線がラベルから点まで線を引きます。線の見た目はラベルスタイルのleaderで決まり（設定 › ラベルスタイルを参照）、Markdownでは1つのラベルごとに線を付けるか外すかだけを書きます。

:::figure{resource="relieve" slot="mapa"}
::label[Sierra Alta]{at="peaks" leader}
::label[Lago Verde]{at="lake" leader="none"}
:::

leaderにnone、false、off以外の値を指定すると線が付きます。属性がなければアンカーのleaderで決まり、どちらもなければ、点から離して置いたラベルは、スタイルにleaderがあるときに線が付きます。枠の注記から画像の一点を指すこともできます。端に画像のアンカーを指定したコネクター（anchor: 'lake'）を使います。

複数行のラベル：:::figureの中の:::label{at="…" style="…"} … :::は、ラベルを1行ずつ書きます。ソースの空でない行がそれぞれラベルの1行になるので、凡例や住所の各行の末尾に\\を書く必要はありません。最初の:::がラベルを閉じ、次の:::が図を閉じます。::label[…]はこれまでどおり1行のラベルで、\\を書いた所だけで改行します。

凡例：kind: 'legend'のスタイルのラベルは地図の凡例です。各行が1つの項目になり、項目の先頭の記号は、いちばん幅の広い記号に合わせた列に並ぶので、項目の言葉は同じ位置から始まります。各行には記号を先に書きます。

:::figure{resource="mapa-politico" slot="mapa"}
:::label{at="key" style="key"}
:icon[国]{glyph="■" color="country"} 国
:icon[首都]{glyph="⊙" font="Noto Sans Math"} 首都
:icon[町]{resource="town-mark" size="0.55"} 町
:icon[国境]{line="dashed" color="border"} 国境
:::
::label[:icon[首都]{glyph="⊙" font="Noto Sans Math"} Varena]{at="capital"}
:::

記号：:icon[代替テキスト]{…}は、行の中にベースラインに載せて小さな記号を置きます。

resource、glyph、lineのうち最初に書いたものが記号の種類を決めます。どれもなければ、ディレクティブはテキストのままです。角括弧の中のテキストは記号の代替テキストで、スクリーンリーダー、タグ付きPDF、画像の代替テキストは記号の代わりにこれを読みます。角括弧が空の記号は装飾として扱います。記号が読まれるのは、図のラベルと、リソースのすべての文言（キャプション、注記、表のセル）です。このリリースでは、本文、見出し、デザイン用のテキストでは読まれません。

#labelAnchorUnknown

::labelのatが、図のリソースにないアンカーを指しています。このラベルは描かれません。リフロー型EPUBでは引き続き一覧に出て、画像の代替テキストにも含まれます。警告には、リソース、アンカー、リソースにあるアンカー（known）、言語、ページ、ラベルの文字のソース範囲が入ります。アンカーのidを直すか、リソースにアンカーを追加するか、at="x% y%"で位置を指定してください。

Sandboxの検査パネルでは、この警告から本文パネルのラベルへ移動できます。ピンのボタンを押すと、画像のアンカーの画面が、この名前のアンカーを置く準備ができた状態で開き、画像を1回クリックするとアンカーが追加されます。

#anchorUnlabelled

図のリソースのアンカーにラベルスタイルが設定されているのに、この言語では図のどの::labelもそこに置かれていません。地図には語を置く場所があるのに、この版ではその語が抜けています。これは情報としての指摘で、postext checkはinfoとして出します。スタイルのないアンカー（漫画の話者のものなど）は報告されません。警告には、リソース、アンカー、そのスタイル、言語、ページ、図のソース範囲が入ります。この言語のMarkdownにラベルを書くか、アンカーのスタイルを外してください。

検査パネルでは、この警告から本文パネルの図へ移動できます。ピンのボタンを押すと、画像のアンカーの画面が、このアンカーを選んだ状態で開きます。

#labelOverflow

ラベルが、ラベルスタイルの許す最小の倍率（minScale）に縮めてもアンカーのwidthより広いままです。ラベルはその倍率で描かれ、幅からはみ出します。警告には、リソース、ラベルの文字、アンカー（パーセントで置いたラベルにはありません）、指定された幅、到達した倍率、言語、ページ、ラベルの文字のソース範囲が付きます。版ごとに調べるので、語の長い言語では、別の言語ではあふれない場所であふれます。アンカーのwidthを広げるか、この版のMarkdownでその語を短くするか、ラベルスタイルのminScaleを下げてください。中国語や日本語のラベルは文字の間で折り返すので、この形ではあふれません。postext 1.39以降。

#labelOverlap

同じ図の2つのラベルの行がぶつかっています。下地のあるラベルは、下地の範囲で判定します。警告は、書かれた順で後のほうのラベルに付き、ぶつかった前のラベルのうち最初のものの文字と、ぶつかった前のラベルの数が添えられます。判定にはラベルといっしょに回転した行ごとの矩形を使うので、短い行の横の空いた部分はぶつかりに数えません。2つの行が行の高さの8分の1までかぶっても、ぶつかりとは見なしません。版ごとに調べます。アンカーの一方を動かすか、ラベルのwidthを狭めて折り返させるか、この版のMarkdownで語を短くしてください。Sandboxの検査パネルでは、ピンのボタンで画像のアンカーの画面が開き、そのラベルのアンカーが選ばれます。postext 1.39以降。アンカーまたはそのラベルスタイルにoverlap: 'allow'を書くと、元の印刷物で隣のラベルに接して刷られているラベル（点の多い地図など）は検査から外れ、それを含む組は報告されません（postext 1.42以降）。画像のavoid領域は、地図の記号として扱われます。画像のマークの回避エリアモードで、点やアイコンの上に、画像に対する割合で矩形を描きます。ラベルがその1つにかかると同じように報告され、相手のラベルの代わりにsymbol 2と示されます（データではwithSymbol）。overlap: 'allow'にすると、そのラベルは両方の検査から外れます（postext 1.42以降）。

#figureWordsShared

ある:::figureが、同じ章の前の図がすでに文言を指定したリソースに、異なる文言（alt、caption、note）を指定しています。ページには最初の図の文言が表示され、こちらは省かれます。警告には、リソース、省かれた文言、そのうち最初のもののソース範囲が入ります。後の図が独自の文言を書いていなければ問題ありません。この図には専用のリソースを割り当ててください。同じ画像ファイルを指す2つ目のリソースを作り、専用のキャプション、番号、アンカーを付けます。Sandboxの検査パネルでは「図」に分類されます。postext 1.42以降。