The Aozora Bunko Notation Specification

Status: Draft v0.1.0 · Date: 2026 · License: Apache-2.0 OR MIT

This document specifies 青空文庫記法 (Aozora Bunko notation): the inline and block annotation language used to mark up plain-text works in the Aozora Bunko digital library — ruby, emphasis dots and side lines, gaiji (out-of-repertoire glyph) references, kunten / return marks, layout containers, page and section breaks, and editor annotations.

It is written to be implementable from the text alone: it uses RFC 2119 keywords, an ABNF grammar, an explicit processing model, a diagnostics catalogue, and a machine-readable conformance suite.

This specification is an independent formalisation. It is not affiliated with or endorsed by Aozora Bunko. The authoritative human-facing source is the official 注記一覧 (https://www.aozora.gr.jp/annotation/); where that source is silent or ambiguous, this document makes an explicit normative decision and records the rationale.

See §1 Introduction to begin.

1. Introduction

青空文庫記法 (Aozora Bunko notation) is the annotation language used to mark up the plain-text works of Aozora Bunko, Japan's volunteer digital library. It encodes the typographic features of printed Japanese books — ruby (furigana), emphasis dots and side lines, out-of- repertoire glyphs (gaiji), classical-Chinese reading marks (kunten), indentation and alignment, page and section breaks — as inline directives inside otherwise ordinary text, e.g.

　明治の頃｜青梅《おうめ》街道沿いに、可哀想［＃「可哀想」に傍点］な話。

This document specifies that language normatively: precisely enough that two independent implementations, reading only this text, produce the same result for the same input.

1.1 Scope

This specification defines:

• the character-level input a conforming processor accepts, and the normalization applied before parsing (§3, §4);
• the lexical grammar of notation constructs (§5, Annex D);
• the notation catalogue — every directive and inline construct, its parameters, and its meaning (§6);
• the structural processing model — pairing, nesting, and forward-reference resolution (§7);
• a reference rendering to HTML and a byte-exact serialization round-trip (§8);
• the diagnostics a processor reports for malformed input (§9); and
• conformance, anchored by a machine-readable test-vector suite (§10).

It does not define a file format, a transport, a stylesheet, or the visual appearance of any construct beyond a reference mapping.

1.2 Relationship to the official 注記一覧

The authoritative human-facing description of the notation is Aozora Bunko's official 注記一覧 (annotation guide), https://www.aozora.gr.jp/annotation/. That guide is the source of record for intent: which constructs exist and what they mean. It is, however, prose-and-example only — it has no formal grammar, no precise processing model, and no conformance suite, and in several places it is silent or ambiguous about edge cases.

This specification follows the official guide wherever it is determinate. Where the guide is silent or admits more than one reading, this document makes an explicit normative decision, grounded additionally in the forms and frequencies actually observed in the Aozora Bunko corpus. Each such decision is recorded as a decision record (referenced from the relevant section) so that the choice — and its rationale — is auditable rather than folkloric.

This specification is independent and is not endorsed by or affiliated with Aozora Bunko.

1.3 Document status

Status: draft v0.1.0

The framework (§§1–5, 7–12) and the notation families in §6 are normative. A few families that the official guide itself treats as provisional — 太字 / 斜体 (§6.12), 表 / 段組 (§6.13), saidoku-moji (§6.5), and some layout directives (§6.6) — are documented with their notation, but their full normative semantics are deferred to a later revision and not yet required for conformance; each is flagged where it appears (see §10.5).

1.4 Conformance levels (overview)

Normative requirements use the keywords of §2. Conformance is verified against the test vectors of §10, each tagged must, should, or may. A conforming processor matches every must-level expectation; the lower levels scale the obligation down. The full contract is in §10 and in conformance/RUNNER.md at the repository root.

1.5 Document conventions

Japanese notation strings, keywords, and examples are given verbatim in Japanese; surrounding explanation is in English. Full-width punctuation that is significant to the grammar (［ ＃ ］ 《 》 ｜ ※ 「 」 （ ） 〔 〕) is shown as-is and identified by Unicode scalar value in Annex D. Byte offsets in examples and vectors are UTF-8 byte offsets into the sanitized source (§4).

2. Conventions and Terminology

2.1 Requirement keywords

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals, as shown here.

2.2 Grammar notation

Grammar is given in ABNF (RFC 5234), with terminals expressed as Unicode scalar values (%xNNNN). The collected grammar is Annex D; fragments are inlined where relevant. Because notation is embedded in free Japanese text, the grammar's text production is disambiguated from constructs by the leftmost-longest rule of §5, not by ABNF negation.

2.3 Definitions

• Source — the input byte sequence (§3), decoded to Unicode scalar values.
• Sanitized source — the source after the §4 normalization pass. Unless stated otherwise, all byte offsets in this document and in conformance vectors are UTF-8 byte offsets into the sanitized source. For input with no BOM, no CR, and no 〔…〕 accent span, the sanitized bytes equal the source bytes.
• Directive — a bracketed annotation ［＃ … ］ (§5, §6). The text between ＃ and ］ is the directive's body.
• Inline construct — a notation that attaches within a line: ruby, bouten/bousen, tate-chu-yoko, gaiji, kaeriten, warichu, and the generic annotation.
• Container — a construct delimited by a paired opener and closer that governs the enclosed content (§7): block layout (字下げ etc.), 罫囲み, and the inline 傍点/傍線 range and 割り注.
• Ruby — a reading (furigana) attached to a base run, ｜base《reading》 or its implicit form (§6.1).
• Gaiji (外字) — a character outside the assumed repertoire, written as a ※［＃…］ reference resolved to a Unicode scalar where possible (§6.4).
• Men-ku-ten (面区点) — a JIS X 0213 plane-row-cell address, e.g. 第3水準1-85-54, used to identify a gaiji (§6.4, Annex B).
• Kunten / kaeriten (訓点・返り点) — classical-Chinese reading marks (§6.5).
• Processor — any implementation that consumes the notation. A conforming processor satisfies §10.
• Diagnostic — a structured, non-fatal observation a processor reports about the input (§9). Processing always continues and produces a best-effort result.

2.4 Error-handling philosophy

The notation has no concept of a fatal parse error. A conforming processor MUST always produce a result for any input, however malformed, and MUST NOT abort. Malformed or suspect input is surfaced through the diagnostics of §9 while the affected construct degrades to a defined best-effort form (typically the literal text, or a generic annotation that preserves the bytes). This recoverability requirement is what lets the same processor handle a century of hand-entered files.

2.5 Character repertoire and code points

Significant full-width delimiters are referred to by their Japanese glyph and Unicode scalar value; the canonical list is in Annex D. The most important are ［=U+FF3B, ＃=U+FF03, ］=U+FF3D, 《=U+300A, 》=U+300B, ｜=U+FF5C, ※=U+203B, 「=U+300C, 」=U+300D, 〔=U+3014, 〕=U+3015.

3. Document Model and Character Encoding

3.1 Input

A notation document is a sequence of bytes representing Japanese text with embedded notation. Historically Aozora Bunko files are encoded in Shift_JIS (specifically the Microsoft / JIS X 0208 variant); modern tooling also uses UTF-8.

• A conforming processor MUST accept UTF-8 input.
• A conforming processor SHOULD accept Shift_JIS input and decode it to Unicode before processing. A byte that does not decode under the declared or detected encoding is replaced by U+FFFD; a processor MAY additionally report this.

Once decoded, the input is a sequence of Unicode scalar values; all subsequent sections operate on that sequence (after §4 normalization). This specification does not define encoding detection; the encoding is either declared out of band or detected by the processor.

3.2 Byte-order mark

A leading U+FEFF (BOM), in any number, is removed during normalization (§4) and carries no meaning.

3.3 Line structure

Lines are separated by LF (U+000A). CR (U+000D) and CRLF are normalized to LF (§4). A line is a maximal run with no LF. Several constructs are line-scoped — single-line layout directives (§6.6), accent spans (§5.5, §4), and the break interaction of §6.6/§6.9 — and refer to this definition.

3.4 Reserved private-use code points

Some processors use private-use scalar values internally as placeholder markers while rewriting the text. A processor that does so MUST ensure such code points cannot be confused with source content: if the source itself contains one of its reserved scalars, the processor neutralizes the occurrence during §4 and reports source-contains-pua. Which code points are reserved is an implementation detail; that source occurrences are made harmless is normative. Real Aozora Bunko text does not contain such code points.

3.5 Coordinates

After §4, the text is the sanitized source. Every span in this document and in the conformance vectors is a half-open UTF-8 byte range into the sanitized source (§2.3). For input with no BOM, no CR, and no 〔…〕 accent span, the sanitized bytes equal the decoded source bytes, so offsets coincide.

4. Pre-processing (Normalization)

Before lexing (§5), a processor applies a normalization pass producing the sanitized source (§2.3). Normalization is defined to be loss-free: the serializer (§7/§8) reconstructs the original notation, so normalization never discards information a round-trip needs.

The steps apply in order.

4.1 BOM removal

Leading U+FEFF code points are removed (§3.2). Removal is a prefix operation; it shifts subsequent offsets but introduces no other change.

4.2 Line-ending normalization

Every CRLF (U+000D U+000A) and every lone CR (U+000D) is replaced by a single LF (U+000A). After this step the text contains no CR.

4.3 Accent decomposition (〔…〕)

An accent span 〔…〕 (§5.5) encloses Latin letters written with a following ASCII combining indicator; the span is rewritten to the combined Unicode form. For example 〔e'〕 → é, 〔u"〕 → ü, 〔n~〕 → ñ. The exact indicator-to-combining-mark mapping is normative and given in Annex A.

Rules:

• An accent span MUST begin and end on the same line; an unterminated 〔 on a line is not an accent span (it is literal text).
• The whole accented word or phrase is enclosed, not each letter individually, matching the official guidance.
• A processor that performs decomposition MUST report accent-decomposition-applied (severity note) for each span that actually contained a digraph, and the reported span is in post-decomposition coordinates (the rewrite is not length-preserving).
• The transform is loss-free: the serializer reconstructs the 〔…〕 source form (§7).

A 〔…〕 whose body contains no recognized digraph is left unchanged and emits no diagnostic.

4.4 Reserved-code-point neutralization

If the source contains a code point the processor reserves internally (§3.4), the processor neutralizes it here and reports source-contains-pua. The neutralized form is implementation-defined but MUST NOT be mistakable for a notation construct.

4.5 Presentational normalization (optional)

A processor MAY apply additional presentational normalizations that do not change which constructs are recognized — for example, isolating a long horizontal rule line (a run of ─, -, = …) onto its own block so it renders as a separator. Such steps are OPTIONAL, MUST be loss-free, and MUST NOT alter the element stream of §5. They are not part of the conformance contract.

4.6 Result

The output of §4 is the sanitized source. All later phases, all spans in this document, and all conformance vectors are defined over it.

5. Lexical Syntax

This section defines how the sanitized source (§4) is decomposed into elements: directives, ruby spans, gaiji references, double-angle quotations, accent spans, and runs of plain text. The complete grammar is Annex D; the key productions are inlined below.

5.1 Element stream

document = *element
element  = gaiji-ref / ruby / angle-quote / accent-span / directive / text

A processor scans the source left to right, at each position recognizing the longest construct that begins there; if none begins there, the position contributes to a text run. This leftmost-longest rule is normative and resolves the alternatives of element (ABNF cannot express the negative lookahead that "is not the start of a construct" requires). One consequence:

• A ※ immediately followed by ［＃ is a gaiji reference (gaiji-ref), not a bare reference mark plus a directive.

5.2 Directives

directive = LBRACK HASH body RBRACK        ; ［＃ body ］
body      = *body-char                     ; any scalar except ］

A directive is the universal annotation form: a full-width ［, a full-width ＃, an opaque body, and a full-width ］. Directives do not nest a ］; the body runs to the first ］. The body MAY itself contain corner-quoted targets (「…」) and parenthesised parameters (（…）), which are significant to body classification but not to this lexical layer.

What a directive means is determined by classifying its body — this is the notation catalogue of §6. Classification is a function of the body string (and, for forward-reference directives, of the surrounding text per §7). A body that matches no known form is retained as a generic annotation (§6.14); a processor MUST NOT discard it, preserving the guarantee that no bare ［＃ ever reaches output.

5.3 Ruby and double-angle quotation

ruby        = [ BAR base ] RUBY-OPEN reading RUBY-CLOSE   ; ［｜］base《reading》
angle-quote = ANGLE-OPEN angle-content ANGLE-CLOSE        ; ≪…≫ (input) → 《…》 (display)

A ruby span is an optional explicit base introduced by ｜, then a reading inside 《 … 》. Without the ｜, the base is determined by the look-back rule of §6.1. The detailed semantics are §6.1.

A double-angle quotation is the input encoding ≪…≫ (U+226A/U+226B) for a 底本's twin angle brackets 《…》, kept distinct from the ruby markers 《 … 》 (U+300A/U+300B) they would otherwise collide with; §6.15. Because the delimiters are distinct scalars, no leftmost-longest tie-break arises.

5.4 Gaiji references

gaiji-ref = REFMARK directive              ; ※［＃ … ］

A gaiji reference is a reference mark ※ immediately followed by a directive. The directive body carries the glyph description and, optionally, a JIS X 0213 men-ku-ten or a U+XXXX code point; resolution is §6.4.

5.5 Accent spans

accent-span = TORT-OPEN accent-body TORT-CLOSE   ; 〔 … 〕

An accent span 〔…〕 encloses Latin letters written with a following combining indicator (e' → é). It is recognized lexically here but resolved during normalization (§4); by the time §6 classification runs, an accent span has already been folded to combined Unicode. An accent span does not cross a line boundary (§4).

5.6 Text

All other source is text. Text is opaque to this layer except that its boundaries are set by the leftmost-longest rule of §5.1.

5.7 Coordinates

Every element carries a span: the half-open [start, end) byte range it occupies in the sanitized source (§2.3). Spans of the top-level element stream tile the source contiguously, without gaps or overlap. All offsets reported in §6, §9, and the conformance vectors are these sanitized-source byte offsets.

6. Notation Catalogue

This section defines every notation family: the directives and inline constructs a processor recognizes, their parameters, and their meaning. Each family is a subsection (§6.1–§6.20).

6.0.1 Per-family template

Every family subsection follows the same shape:

1. Synopsis — what the construct does, in one or two sentences.
2. Notation — the source forms, with an ABNF fragment and verbatim examples.
3. Parameters — any variable parts (counts, variant keywords, targets).
4. Semantics — normative behaviour (RFC 2119 keywords), including how the construct relates to the node model (§8) and serialization (§7).
5. Error conditions — the §9 diagnostics this family can raise.
6. Conformance vectors — the conformance/vectors/ cases that pin it.

Where the official 注記一覧 is silent or ambiguous, the Semantics make an explicit decision and cite a decision record under docs/adr/. A family the official guide treats as provisional (§6.13) is documented here with its notation; its full normative semantics are deferred (§10.5).

6.0.2 Family index

6.1 Ruby (ルビ)

Synopsis

Ruby attaches a small reading (furigana) to a base run of text. It is the most common construct in the corpus.

Notation

ruby = [ BAR base ] RUBY-OPEN reading RUBY-CLOSE   ; ［｜］ base 《 reading 》

The reading is written in double angle brackets 《 … 》 immediately after the base. The base is identified in one of two ways:

• Explicit base — a ｜ (U+FF5C) marks where the base begins; the base is the run from ｜ up to 《:

  ｜青梅《おうめ》
  ｜後手々々《ごてごて》
  

• Implicit base — with no ｜, the base is the maximal run of same-class characters immediately preceding 《 (see Parameters):

  青空《あおぞら》
  

Parameters

• base — the run the reading applies to.
  • For the explicit form, the base is exactly the text between ｜ and 《.
  • For the implicit form, the base is the maximal preceding run of one character class — a processor MUST take a trailing run of kanji (CJK ideographs); it MAY extend the implicit base over other single classes (kana, Latin) as the official guide allows, but MUST stop at a class boundary or at any preceding notation construct. When the intended base spans classes, the author uses the explicit ｜ form; this is why ｜ exists.
• reading — the furigana text inside 《 … 》; it is plain text and MUST NOT itself contain a ruby (see Error conditions).

Semantics

• A ruby span yields a ruby node whose span covers the whole construct (from ｜ or the implicit base start, through the closing 》), carrying the base and the reading.

• Reference rendering (§8) is HTML5 <ruby> with <rp> fallback parentheses:

  <ruby>青梅<rp>(</rp><rt>おうめ</rt><rp>)</rp></ruby>
  

• Serialization (§7) reconstructs the source form, including the ｜ when the base was explicit, so the round-trip is byte-exact.

• An adjacent 《《…》》 is two ruby openers — a nested ruby error, not a single construct. The double-angle quotation notation (§6.15) is the distinct ≪…≫.

Error conditions

• Empty reading with explicit base — ｜青梅《》 raises empty-ruby-reading (error) and degrades to plain text. A bare 《》 with no ｜ is literal text and is not flagged.
• Nested ruby — a reading body that opens another ruby (｜漢《か《ん》じ》) raises nested-ruby (error); the outer ruby is parsed best-effort and the label points at the inner 《.
• Unclosed 《 — a reading with no closing 》 raises unclosed-bracket; the region degrades to plain text.

Conformance vectors

ruby_explicit, ruby_implicit, empty-ruby-reading, nested-ruby, mixed_ruby_bouten (under conformance/vectors/).

6.2 Bouten and Bousen (傍点・傍線)

Synopsis

Bouten (傍点) are emphasis dots set beside characters in vertical text — the Japanese equivalent of italic/bold for emphasis. Bousen (傍線) are the same idea with a line. The two form one family with a 点/線 split.

Notation

Three forms produce emphasis.

• Forward reference — quote the target; the emphasis applies to the most recent preceding occurrence (§7.5):

  ［＃「平和」に傍点］
  平和［＃「平和」に傍点］      ← redundant explicit copy (also accepted)
  

• Range — a bare opener and matching closer wrap the run directly. Note there is no ここから/ここで; those prefixes are for block layout and bold/italic, not bouten:

  bouten-range = directive 1*element directive   ; ［＃<kw>］ … ［＃<kw>終わり］
  

  彼は［＃傍点］必ず［＃傍点終わり］来る
  ［＃二重傍線］乙［＃二重傍線終わり］
  ［＃左に傍線］丙［＃左に傍線終わり］
  

• Left side — an optional 左に prefix places the marks on the left of the vertical base text (［＃左に傍線］…, ［＃「X」の左に傍点］).

Parameters

• variant — one of the fourteen keywords of Annex C.4; nine 点 and five 線. The rare 鎖線 / 破線 (線) and 黒三角傍点 (点) are official but corpus-sparse; a processor renders them like any other variant where it has a glyph, otherwise degrading them (§6.14).
• family — 点 (dots) or 線 (line). The family is what pairing checks for the range form (§7.2).
• position — right (default) or left (左に).
• target — for the forward-reference form, the quoted run to emphasise.

Semantics

• The forward-reference form resolves its target by the look-back rule of §7.5 and yields a bouten node over that run.
• The range form pairs opener and closer by family (§7.1) and yields a container node (family-tagged bouten-range) over the enclosed content. It is an inline construct (§7.3): in the corpus it never spans a line, and rendering does not introduce block structure.
• Reference rendering (§8) is <em class="aozora-bouten aozora-bouten-<slug> aozora-bouten-<side>">…</em>, the same markup for both forms so a stylesheet treats them identically.
• Serialization (§7.6) reconstructs the source form, including a redundant forward-reference target copy and a 左に prefix, byte-exact.

Error conditions

• Family mismatch (range) — a 点 opener closed by a 線 closer, or vice-versa, raises mismatched-bouten-container (error); the run is keyed to the opener's variant (recovery). A same-family variant difference (e.g. 白丸傍点 closed by 丸傍点終わり) is tolerated.
• Ambiguous target (forward reference) — a quoted target occurring more than once in the look-back raises bouten-target-ambiguous (warning).
• Target with no referent (forward reference) — a single-target に<kw> / の左に<kw> directive whose quoted target does not occur in the look-back is a self-contained forward bouten: the quoted run is itself the marked text, rendered <em class="aozora-bouten …">, and serialization reconstructs the directive byte-exact (§7.6). A no-referent target has zero look-back occurrences, so it never raises bouten-target-ambiguous. A multi-target bracket (「A」「B」) with any missing target is not promoted and degrades to a generic annotation (§6.14): non-contiguous targets cannot be spliced into one leaf.
• Unclosed range — an opener with no closer is handled per unclosed-bracket.

Conformance vectors

bouten-target-ambiguous, bouten_range, bouten_range_chain_line, bouten_chain_line, bouten_black_triangle, mismatched-bouten-container, mixed_ruby_bouten, bouten_forward_no_referent.

6.3 Tate-chu-yoko (縦中横)

Synopsis

Tate-chu-yoko ("horizontal-within-vertical") sets a short run — typically multi-digit numbers or Latin initialisms — upright and horizontal inside vertical text, so e.g. 24 reads as a unit rather than two stacked digits.

Notation

A forward-reference directive names the run:

昭和二十四年は西暦19［＃「19」は縦中横］24［＃「24」は縦中横］年。

tcy = LBRACK HASH LQUOTE target RQUOTE %s"は縦中横" RBRACK

Parameters

• target — the quoted run to rotate. It is resolved against the preceding text by the look-back rule (§7.5).

Semantics

• The directive resolves its target (§7.5) and yields a tate-chu-yoko node over the matched run.
• Reference rendering (§8) is <span class="aozora-tcy">…</span>.
• Serialization reconstructs the directive (and the literal target it follows) byte-exact (§7.6).

Error conditions

• Target not found — a target absent from the look-back raises tcy-target-not-found (warning); the directive degrades to a generic annotation (§6.14).

Conformance vectors

tate_chu_yoko.

6.4 Gaiji (外字)

Synopsis

A gaiji (外字, "external character") is a glyph outside the assumed character repertoire — a rare kanji, a special kana, a symbol. It is written as a ※［＃…］ reference carrying a human description and, where possible, a machine address (a JIS X 0213 men-ku-ten or a Unicode code point) that resolves it to an actual character.

Notation

gaiji-ref = REFMARK directive          ; ※［＃ description 〔、address〕 ］

※［＃「てへん＋劣」、第3水準1-84-77］     ← JIS X 0213 men-ku-ten
※［＃「口＋世」、U+546D、123-4］          ← Unicode reference (+ provenance)
※［＃「土へん＋竒」、123-4］              ← description only (provenance locator)
※［＃二の字点、1-2-22］                  ← named, with men-ku-ten
※［＃二重かっこ開く］                    ← named, dictionary-resolved (no address)

A description in 「…」 quotes is recognised on its own; a bare (unquoted) description with no address is recognised only when it names a known dictionary glyph (※［＃二重かっこ開く］ → ｟, the same glyph as the upstream 始め二重括弧 entry), so an ordinary ［＃…］ directive is not mistaken for a gaiji. The canonical serialization quotes the description (※［＃「二重かっこ開く」］). Vector: gaiji_double_paren.

A bare ローマ数字N description (※［＃ローマ数字17］) is recognised the same way, with the glyph composed rather than looked up: the numeral N is spelled from the U+2160 (uppercase) / U+2170 (lowercase, ローマ数字N小文字) single-letter Roman-numeral blocks — 17 → ⅩⅤⅠⅠ (Ⅹ+Ⅴ+Ⅰ+Ⅰ) — because values ≥ 13 have no single JIS X 0213 cell (the corpus pairs those with a page-line locator, not an address). It resolves like any other gaiji and serialises to the canonical quoted form (※［＃「ローマ数字17」］). Vector: roman_numeral.

The accent form 〔…〕 (§4.3, Annex A) and the iteration marks ／＼ / ／″＼ are related glyph-encoding notations covered in Annex B.

Standalone form (tolerant)

Some 凡例 write the same ［＃description〔、address〕］ reference without the leading ※ — a standalone descriptive note rather than an inline insertion. A conforming processor SHOULD recognise it as a gaiji node when the body carries a resolvable description or a mencode / page-line address (so an ordinary ［＃…］ note is not mistaken for one), and serialise it back without a ※. This is a corpus-attested tolerant extension, not part of the core external_character.html notation; the reference-mark form above is canonical. Vector: standalone_gaiji.

Parameters

• description — the text before the first 、: a radical composition (木＋世), a name (二の字点), or a directly-typed character.
• address — an optional 、-separated trailer: a JIS X 0213 men-ku-ten (第N水準P-R-C / 面-区-点), a U+XXXX code point, and/or a page-line provenance locator.

Semantics

• The reference yields a gaiji node whose span covers the whole ※［＃…］. Resolution order is normative (Annex B): explicit U+XXXX, then men-ku-ten, then a named description (including the composed ローマ数字N numerals), then a single-character description.
• On success the node carries the resolved scalar (or combining sequence); reference rendering (§8) emits that character (optionally wrapped for styling).
• Serialization reconstructs the ※［＃…］ reference byte-exact (§7.6); a resolved gaiji round-trips to its source form, never to the bare glyph.

Error conditions

• Unresolved — a reference that resolves to neither Unicode nor JIS X 0213 raises unresolved-gaiji (warning) and falls back to the description text.

Conformance vectors

gaiji, gaiji_double_paren, roman_numeral, unresolved-gaiji, accent-decomposition-applied.

6.5 Kunten (訓点・返り点)

Synopsis

Kunten are the marginal marks that let classical Chinese (漢文) be read in Japanese word order. This section specifies kaeriten (返り点), the reading-order return marks, their okurigana, and the left-side ruby that — composed with these — expresses a saidoku-moji (再読文字, a character read twice). See the final subsection.

Notation

Kaeriten are recognized only in bracketed form — a mark inside a directive:

有［＃二］朋自遠方来［＃一］
未［＃レ］嘗［＃（ハ）］

kaeriten = LBRACK HASH ( ladder-mark / okurigana ) RBRACK

• ladder-mark — one of the single marks 一 二 三 四 上 中 下 甲 乙 丙 丁 レ or the Xレ compounds 一レ 二レ 三レ 上レ 中レ 下レ (Annex C.5).
• okurigana — parenthesised kana （…）, a reading aid.

A bare reading-mark glyph written inline in running text (有レ朋) is not recognized — a processor cannot tell a genuine 返り点 from an ordinary 一/上/レ in prose, which is exactly why the bracketed form exists.

Parameters

• mark — the literal mark text; classified into a family and rank for the pairing check (below). The ladder families and bases are: numeric 一<二<三<四 (base 一), jouge 上<中<下 (base 上), kō-otsu 甲<乙<丙<丁 (base 甲). レ is standalone; okurigana never ladders.

Semantics

• Each recognized mark yields a kaeriten node carrying the mark text.
• Reference rendering (§8) is <sup class="aozora-kaeriten">mark</sup>.
• Serialization reconstructs ［＃mark］ byte-exact (§7.6).

Pairing (document-wide base presence)

A return mark of rank ≥ 2 implies the existence of its family base. A processor checks this document-wide and base-only: if a mark of rank ≥ 2 (二/三/四, 中/下, 乙/丙/丁) appears but its family base (一/上/甲) is absent from the entire document, it raises bracketed-kaeriten-no-pair (error).

The scope is deliberately the whole document and the test deliberately base-only — not per-clause and not a strict contiguous ladder. This is forced by the corpus: real kanbun writes 二 before 一 (reading order), return-mark groups routinely span 、/。 and line boundaries, and 上下点 legitimately uses just 上…下 (skipping 中). A narrower scope or stricter ladder flags valid kanbun. This decision is recorded in docs/adr/0001-kaeriten-pairing-rule.md.

Error conditions

• bracketed-kaeriten-no-pair — see Pairing above.
• kaeriten-outside-kanbun (warning) — a conservative heuristic: when a document contains exactly one kaeriten and its surroundings read as ordinary kana prose, the lone mark is likely a stray annotation, not a return mark. A document with a cluster of kaeriten (real 漢文) is never flagged.

Left-side ruby and saidoku-moji (再読文字)

Saidoku-moji (再読文字) — a kanbun character read twice with different glosses (e.g. 未, 将, 当) — has no dedicated notation. It is written as a composition of constructs already defined: a left-side ruby for the second reading, plus okurigana and a return mark. For example, 未 read 「いまだ…ず」 is 未［＃「未」の左に「ザル」のルビ］［＃（ダ）］［＃レ］.

The left-side ruby is the one piece §6 does not otherwise cover. A forward-reference directive attaches a reading to the left of the preceding run (vs §6.1 ruby, which is on the right):

未［＃「未」の左に「ザル」のルビ］

left-ruby = LBRACK HASH LQUOTE target RQUOTE %s"の左に" LQUOTE reading RQUOTE %s"のルビ" RBRACK

• target — the preceding run the reading attaches to (resolved by §7.5).
• reading — the left-side reading text.

A left-side ruby yields a ruby node with a left side. Reference rendering (§8): <ruby>X<rp>(</rp><rt class="aozora-ruby-left">Y</rt><rp>)</rp></ruby>. Serialization reconstructs X［＃「X」の左に「Y」のルビ］ byte-exact (§7.6). The right-side variant (の右に…のルビ) is deferred (§10.5); the left-side annotation form (の左に…の注記) is covered next.

Side annotation (注記)

A side annotation (注記) attaches an editorial note — not a phonetic reading — to the left of the preceding run. It shares the forward-reference shape of the left-side ruby but ends in の注記, so a processor keeps it distinct: a side-note node, never ruby.

未来［＃「未来」の左に「みらい」の注記］

side-note = LBRACK HASH LQUOTE target RQUOTE %s"の左に" LQUOTE note RQUOTE %s"の注記" RBRACK

• target — the preceding run the note attaches to (resolved by §7.5).
• note — the left-side annotation text.

A side annotation yields a side-note node. Reference rendering (§8) places the note like a left-side ruby but marks it a note: <ruby>X<rp>(</rp><rt class="aozora-sidenote">Y</rt><rp>)</rp></ruby>. Serialization reconstructs X［＃「X」の左に「Y」の注記］ byte-exact (§7.6). The right-side annotation form (の右に…の注記) is deferred (§10.5).

Marginal annotation (傍記)

A marginal annotation (傍記) attaches a redaction marker — 典型的に × — beside the preceding run. It records a 底本's 伏字 (a masked word) in proletarian-literature restoration: the original word is set as X and the marker Y notes that the source censored it. It shares the side-note node with the 注記 form, but uses a bare に connector and ends in の傍記, so a processor keeps it distinct and round-trips it to its own keyword.

革命［＃「革命」に「×」の傍記］

marginal-note = LBRACK HASH LQUOTE target RQUOTE %s"に" LQUOTE note RQUOTE %s"の傍記" RBRACK

• target — the preceding run the marker attaches to (resolved by §7.5).
• note — the marker text (典型的に ×).

A marginal annotation yields a side-note node, rendered like the 注記 form: <ruby>X<rp>(</rp><rt class="aozora-sidenote">Y</rt><rp>)</rp></ruby>. Serialization reconstructs X［＃「X」に「Y」の傍記］ byte-exact (§7.6) — the bare に, not の左に. This is a corpus-attested tolerant extension (102 occurrences, one shape); 注記 is the canonical side annotation. Vector: boki.

Conformance vectors

bracketed-kaeriten-no-pair, kaeriten-outside-kanbun, left_ruby, side_note_left, boki, and the kaeriten recognition cases under conformance/vectors/.

6.6 Layout containers (字下げ・地付き ほか)

Synopsis

Layout directives control horizontal placement of lines: indentation (字下げ), end-alignment (地付き / 地上げ, i.e. flush to the foot of the vertical line), line length (字詰め), centring (中央揃え), and margined right-alignment (地寄せ). Each has a block form (a paired container governing many lines) and, for indent, end-align, and centring, a single-line form; line length (字詰め) has a block form only. This section pins indentation (including the hanging-indent 折り返し字下げ form), end-alignment, line length, the single-line centring marker (ページの左右中央 / 中央揃え), and the compound indent opener — an indent whose ここからN字下げ carries a trailing, 、-separated stack of clauses (page-centre, line layout, and the decorative styles ゴシック体 / 横書き / 罫囲み / 小さい活字). The block centring form (which has no closer in practice) and margined right-alignment (地寄せ) remain deferred (§10.5); they are catalogued in Annex C.2.

Notation

［＃ここから2字下げ］          ← block indent opener
　本文…
［＃ここで字下げ終わり］        ← closer

［＃ここから5字下げ、ページの左右中央に］  ← indent + page-centre
　献辞…
［＃ここで字下げ終わり］

［＃ここから2字下げ、折り返して4字下げ］  ← hanging indent (first line 2, wrap 4)
　長い本文が折り返して4字下げされる…
［＃ここで字下げ終わり］

［＃ここから天付き、折り返して1字下げ］      ← top-flush hanging indent (amount 0, wrap 1)
　長い本文が折り返して1字下げされる…
［＃ここで字下げ終わり］

［＃ここから2字下げ、小さい活字］          ← compound indent + decorative style
　一段小さい活字で組まれた2字下げの本文…
［＃ここで字下げ終わり］

［＃ここから4字下げ、横書き、中央揃え、罫囲み］  ← compound indent + style stack
　横書き・中央揃え・罫囲みの4字下げブロック…
［＃ここで字下げ終わり］

［＃2字下げ］この行だけ        ← single-line indent
［＃地付き］平和への誓い        ← single-line end-align (foot)
［＃地から2字上げ］…           ← single-line end-align, 2 from the foot
［＃ページの左右中央］          ← single-line centring marker (page centre)
［＃この行はゴシック体］本文行   ← single-line gothic (a typeface, not 太字)
見出し行［＃大文字、太字］       ← single-line absolute size (+ optional 、太字)

［＃ここから地付き］…［＃ここで地付き終わり］          ← block end-align
［＃ここから地から2字上げ］…［＃ここで字上げ終わり］   ← block end-align (margin)

［＃ここから26字詰め］…［＃ここで字詰め終わり］        ← block line-width (26 chars/line)

indent-block-open = LBRACK HASH %s"ここから" 1*DIGIT %s"字下げ" RBRACK
indent-wrap-open  = LBRACK HASH %s"ここから" 1*DIGIT %s"字下げ、折り返して" 1*DIGIT %s"字下げ" RBRACK
indent-center-open = LBRACK HASH %s"ここから" 1*DIGIT %s"字下げ、" ( %s"ページの左右中央" [ %s"に" ] / %s"左右中央" ) RBRACK

; compound opener: amount字下げ followed by an open-ended `、`-separated
; stack of clauses (one new modifier = one new `indent-clause` alternative).
; `天付き` is the amount-0 spelling for the top-flush hanging form.
indent-compound-open = LBRACK HASH %s"ここから" ( 1*DIGIT %s"字下げ" / %s"天付き" ) 1*( "、" indent-clause ) RBRACK
indent-clause = %s"折り返して" 1*DIGIT %s"字下げ"                                  ; wrap
              / ( %s"ページの左右中央" [ %s"に" ] / %s"左右中央" / %s"中央揃え" )    ; center
              / 1*DIGIT %s"字詰め" / 1*DIGIT %s"行" 1*DIGIT %s"字組み" [ %s"で" ]    ; line layout
              / %s"ゴシック体" / %s"横書き" / %s"横組み" / %s"罫囲み" / %s"小さい活字" ; decorative style

indent-single     = LBRACK HASH 1*DIGIT %s"字下げ" RBRACK
line-width-open   = LBRACK HASH %s"ここから" 1*DIGIT %s"字詰め" RBRACK
align-end-single  = LBRACK HASH %s"地付き" RBRACK
                  / LBRACK HASH %s"地から" 1*DIGIT %s"字上げ" RBRACK
center-single     = LBRACK HASH ( %s"ページの左右中央" / %s"中央揃え" ) RBRACK
line-gothic-single = LBRACK HASH %s"この行はゴシック体" RBRACK
line-font-single  = LBRACK HASH abs-size-keyword [ %s"、太字" ] RBRACK
abs-size-keyword  = %s"特大文字" / %s"大文字" / %s"中文字" / %s"小文字"

(1*DIGIT admits ASCII or full-width digits.)

Parameters

• amount — for indent, the number of full-width characters to indent.
• wrap — for the hanging-indent form (折り返し字下げ), the indent applied to wrapped continuation lines after the first; absent for a plain indent.
• center — true for a compound indent carrying a page-centre clause (ページの左右中央 / 左右中央 / 中央揃え); the indented block is also page-centred. false otherwise.
• offset — for end-align, the distance from the foot: 0 (地付き) or N (地からN字上げ).
• width — for line-width (字詰め), the number of full-width characters per line the enclosed run is set to.
• styles — for a compound indent, the co-applied decoration set carried by the opener's clause stack: any of gothic (ゴシック体), horizontal (横書き / 横組み), framed (罫囲み), and font (小さい活字, a one-stage-smaller font). The set is order-independent on input and open-ended: a future decorative modifier is one new clause without changing the model (it rides the same projections, below). Empty for a plain or center-only indent.

Semantics

• A block opener/closer pair (§7.1) yields a container node (family indent, align-end, or line-width) governing the enclosed lines; containers nest (§7.3). Pairing is by family, so a 2字下げ opener pairs with a plain 字下げ終わり (§7.2). The hanging-indent opener (ここからN字下げ、折り返してM字下げ) is the same indent family carrying a wrap parameter, so it too closes with the shared 字下げ終わり. The compound opener ここからN字下げ followed by a 、-separated clause stack is likewise the indent family — carrying a center flag and a styles set drawn from the stack — and all compound indents close with the single generic 字下げ終わり (pairing is by family; the open payload is authoritative). The redundant explicit compound closer 字下げ終わり、〈X〉も終わり folds to the canonical ここで字下げ終わり.
• Compound clause canonicalisation. The clause stack is order-independent on input. The serializer re-emits the recognised clauses in a fixed canonical order: amount字下げ → 折り返してM字下げ → ページの左右中央に → {W字詰め | L行W字組みで} → ゴシック体 → 横書き → 罫囲み → 小さい活字. Canonical spellings are normalised on serialize: 中央揃え / 左右中央 → ページの左右中央に; ゴチック → ゴシック体; 横組み → 横書き. The line-layout clauses 字詰め (LineWidth) and 字組み (Kumi) are distinct and are never merged. The top-flush hanging form ここから天付き、折り返してM字下げ models as amount 0 plus wrap M and canonicalises to ここから0字下げ、折り返してM字下げ. These canonical picks are fixed by ADR-0004 (extending ADR-0003).
• Decline-whole on any unknown clause (losslessness). A compound opener governs a container only when every clause is recognised. If any clause is unrecognised (e.g. 横組み右揃えで, 数式, 本文よりひとまわり大きい太ゴシック体, or an embedded forward reference such as 「」は返り点), the whole ［＃…］ is retained as a generic annotation (§6.14), reports unrecognised-container-directive, and round-trips byte-exact. A partially-recognised set never opens a container.
• The line-width opener (ここからN字詰め) is the line-width family carrying a width parameter; it is block-only (no single-line form) and closes with 字詰め終わり (§7.2).
• The end-align block opener (ここから地付き / ここから地からN字上げ) is the align-end family carrying an offset parameter, closed by either 字上げ終わり or 地付き終わり (pairing is by family, §7.2). The opener's offset is authoritative; the closer carries none. Round-tripping (§7.6) preserves that offset and canonicalises the closer to 地付き終わり.
• A single-line directive (no ここから, no closer) governs only the rest of its line and is a zero-width marker node (indent / align-end / center / line-gothic), not a wrapping container (§7.4). It does not capture following lines. The centring marker (ページの左右中央 / 中央揃え) flags its line as page-centred; この行はゴシック体 sets its line in gothic (the single-line counterpart of the ゴシック体 compound clause, a typeface distinct from 太字, #435); the actual styling is a presentation concern (§8). A 大文字 / 中文字 / 小文字 / 特大文字 marker (optionally 、太字) flags its line with an absolute font size (§6.17) — the postfix headline form; the bold flag canonicalises to 、太字 (only that spelling is admitted, so the round-trip is exact, mirroring the single この行はゴシック体 spelling).
• Breaks persist across a block container (not flagged); a break sharing a line with a single-line directive drops it (§6.9, §7.4).
• Reference rendering (§8): block → <div class="aozora-container aozora-container-<family>">…</div> (indent adds aozora-container-indent-N and data-amount="N"; the hanging form adds aozora-container-wrap-indent and data-wrap="M"; line-width adds data-width="N"); single-line → a marker <span class="aozora-indent aozora-indent-N"> / <span class="aozora-align-end" data-offset="N"> / <span class="aozora-center"> / <span class="aozora-line-futoji"> / <span class="aozora-line-font-<slug>"> (the absolute-size marker; 、太字 adds aozora-line-futoji).
• A compound indent renders to a single <div> (one </div>) carrying flat classes: the indent's own classes plus, in the same canonical clause order, each decorative style's standalone container class — ゴシック体 → aozora-container-futoji, 横書き → aozora-container-yokogumi, 罫囲み → aozora-container-keigakomi, 小さい活字 → aozora-container-font-smaller (with data-steps="1"). data-amount is emitted as today; the page-centre flag adds the centre class as for the existing combined form. The JSON wire is unchanged: the container-pair kind stays "indent" and SCHEMA_VERSION is unchanged. Like amount and center, the decorative styles are not projected as JSON node/pair fields — they ride the HTML classes and the Pandoc key-values (a space-joined modifiers kv). Conformance therefore pins the styles via the serialize and html projections, not via a new nodes field.
• The official guidance is to prefer an annotation over inserted whitespace, so the same visual layout round-trips through the directive, not spaces.

Error conditions

• mismatched-container-close — a closer of a different family than its opener (e.g. indent opened, end-align closed).
• unrecognised-container-directive — a ここから… opener naming no known container kind, or a compound opener carrying any unrecognised clause (the decline-whole rule, above): the whole ［＃…］ is kept as a generic annotation (§6.14) and round-trips byte-exact, opening no container.
• break-in-single-line-container — a break sharing a single-line directive's line (§7.4).

Further layout directives

This revision pins normative semantics for 字下げ (including the 折り返し字下げ hanging form and the top-flush 天付き form), 地付き / 地上げ, 字詰め (ここからN字詰め), the single-line centring marker (ページの左右中央 / 中央揃え), and the compound indent opener whose ここからN字下げ carries a 、-separated clause stack — a page-centre clause, a line-layout clause (字詰め / 字組み), and the decorative styles ゴシック体, 横書き (= 横組み), 罫囲み, and 小さい活字 (canonical order, spellings, and the decline-whole-on-unknown rule are fixed in ADR-0004).

Deferred to a later revision (§10.5): the block centring form (ここから中央揃え / ここからページの左右中央, which has no closer in the corpus and so does not fit the paired-container model — page-centring within an indent is supported, above), and margined right-alignment (地寄せ). Also deferred (and declining losslessly) are embedded-directive compounds, in which a clause is itself another notation construct rather than a layout modifier (e.g. ここから2字下げ、「」は返り点, ここから字下げ、ここから数式). Their notation is catalogued in Annex C.2. A processor encountering an unrecognised ここから… opener — or a compound opener with any unrecognised clause — retains it as a generic annotation (§6.14) and reports unrecognised-container-directive.

Conformance vectors

indent_container, wrap_indent, align_end_container, line_width_container, center_page, line_gothic_single, line_font_size_single, line_font_size_bold_single, indent_compound_styled, nested_containers, mismatched-container-close, unrecognised-container-directive, break-in-single-line-container.

6.7 Keigakomi (罫囲み)

Synopsis

Keigakomi draws a ruled frame (a box) around a block of text — used for notices, inset boxes, and the like.

Notation

A paired block container:

［＃罫囲み］
枠の中の文章。
［＃罫囲み終わり］

keigakomi-open  = LBRACK HASH %s"罫囲み" RBRACK
keigakomi-close = LBRACK HASH %s"罫囲み終わり" RBRACK

The official guide also writes this block as ［＃ここから罫囲み］ … ［＃ここで罫囲み終わり］. The bare opener/closer above is the canonical pair in this specification; the ここから/ここで variant is an accepted equivalent and pairs by the same keigakomi family.

There is also an inline forward-reference form that boxes a single run, the span-level counterpart of the block container (parallel to how 太字 has both a block range and a は-form leaf, §6.12):

注意［＃「注意」は罫囲み］事項。
新興河上［＃「新興河上」に枠囲み］      ← に particle + 枠囲み spelling

keigakomi-inline = target "［＃「" target "」" (%s"は" / %s"に") %s"罫囲み" "］"

Unlike 太字/斜体 (は-only, §6.12), the frame decoration accepts either particle — は ("is framed") or に ("frame applied to"). The core recognises only the canonical keyword 罫囲み. The corpus-rare, non-canonical spellings 枠囲み / 枠囲い (and the rule-style names 表罫囲み / ミシン罫囲み) are not folded onto 罫囲み — that would erase their spelling; they degrade to a lossless Unknown directive (§6.14) with a lint suggesting は罫囲み (#435).

Box-character enclosure (「□」囲み)

A second inline form names the enclosing glyph explicitly, in a quoted token after the particle:

一［＃「一」は「□」囲み］

box-enclosure = target "［＃「" target "」" %s"は「" box-glyph %s"」囲み" "］"
box-glyph     = %x25A1   ; □ (U+25A1) — the only attested glyph

This is the same enclosure family as 罫囲み — it boxes the target run — but a distinct style: a box glyph rather than a ruled frame. The □ names an enclosure kind, not free data; a future non-□ glyph would be a further named kind (compare 二重罫囲み / 点線丸囲み), never an arbitrary character. The look-back rule of §7.5 consumes the preceding literal exactly as the other は-form leaves.

Parameters

None for the block form. The inline form names a single target (the quoted run to box), resolved by the look-back rule of §7.5.

Semantics

• The opener/closer pair (§7.1) yields a container node (family keigakomi) governing the enclosed block; it nests with other block containers (§7.3).
• The inline forward-reference form yields an emphasis node over its target run and is an inline construct. The box-character form (「X」は「□」囲み) likewise yields an emphasis node over its target.
• Reference rendering (§8) is <div class="aozora-container aozora-container-keigakomi">…</div> for the block form, <span class="aozora-keigakomi-inline">…</span> for the inline rule form, and <span class="aozora-keigakomi-box">…</span> for the box-character form (the box is drawn by the stylesheet, so the □ glyph is not emitted into the body).
• Serialization reconstructs the block opener/closer byte-exact (§7.6); the canonical inline rule form (は罫囲み / に罫囲み) reconstructs its particle and keyword byte-exact, and the box form reconstructs 「X」は「□」囲み byte-exact — all idempotent. The non-canonical 枠囲み / 枠囲い are not recognised (they degrade, §6.14, and round-trip verbatim as an Unknown).

Error conditions

• mismatched-container-close — closed by a different container family.
• unclosed-bracket — opener with no closer.

Conformance vectors

keigakomi_container, keigakomi_inline_forward, keigakomi_inline_framed, box_enclosure, box_enclosure_no_referent.

6.8 Warichu (割り注)

Synopsis

Warichu (割り注, "split note") is an inset two-line annotation set at half size within the run of the main text — a traditional interlinear note.

Notation

A paired inline range:

本文［＃割り注］注の内容［＃割り注終わり］に続く本文。

warichu-open  = LBRACK HASH %s"割り注" RBRACK
warichu-close = LBRACK HASH %s"割り注終わり" RBRACK

Parameters

None; the enclosed content is the note body.

Semantics

• The opener and closer are recognized as inline annotation markers; the content between them is the warichu body. The pair is an inline construct (§7.3) — it does not introduce block structure and, in the corpus, does not span a line.
• Reference rendering (§8) wraps the body as inline: <span class="aozora-warichu">…</span>.
• Serialization reconstructs the opener/closer byte-exact (§7.6).

Error conditions

• break-in-single-line-container (warning) — a page or section break inside an open warichu range drops it (§7.4, §6.9): a break is block-level and a warichu is inline.
• unclosed-bracket — an opener with no closer.

Conformance vectors

warichu_inline.

6.9 Breaks (改ページ・改丁・改段・改見開き)

Synopsis

Break directives mark page-level structure inherited from print: a new page, a new recto/leaf, a new column section, or a new two-page spread.

Notation

Each is a self-contained directive on its own line — no opener/closer, no inner content:

［＃改ページ］      ← new page
［＃改丁］          ← new recto / leaf (丁)
［＃改段］          ← new column section
［＃改見開き］      ← new two-page spread

break = LBRACK HASH ( %s"改ページ" / %s"改丁" / %s"改段" / %s"改見開き" ) RBRACK

Parameters

None.

Semantics

• ［＃改ページ］ yields a page-break node; 改丁 / 改段 / 改見開き yield a section-break node tagged recto / column / spread respectively. Both are block leaves (§8.1) standing on their own line.
• Reference rendering (§8): <div class="aozora-page-break"></div> for 改ページ; <div class="aozora-section-break aozora-section-break-<kaicho|kaidan|kaimihiraki>"></div> for the section flavours.
• Interaction with annotations and containers (§7.3, §7.4):
  • a break does not close a block layout container (字下げ, 地付き, 罫囲み); those persist across page boundaries, matching print typography, and a break inside one is not flagged;
  • a break that shares a line with a single-line layout directive, or that falls inside an inline 割り注 range (§6.8), drops that scope and raises break-in-single-line-container (§7.4).
• Serialization reconstructs the directive byte-exact (§7.6).

Error conditions

• break-in-single-line-container (warning) — see Semantics.

Conformance vectors

page_break, section_break, break-in-single-line-container.

6.10 Headings (見出し)

Synopsis

A heading marks a run of text as a structural title. Aozora distinguishes three levels (大 / 中 / 小 見出し) and, orthogonally, three styles — standard, same-line (同行, the title shares its line with the body that follows) and window (窓, an inset title). Style and level combine freely: 同行中見出し, 窓小見出し, and so on. Headings are most often expressed as a forward-reference hint that promotes or marks a quoted run.

Notation

A heading is written in one of three forms — a forward-reference hint, a paired delimiter, or a block (ここから…) delimiter:

　　　　序［＃「序」は大見出し］                           ← hint (forward-reference)
萩原朔太郎［＃「萩原朔太郎」は同行中見出し］　二十年の友。…  ← hint (same-line)
［＃窓小見出し］チベット探検の動機［＃窓小見出し終わり］     ← paired
［＃ここから中見出し］本文…［＃ここで中見出し終わり］       ← block

heading-hint         = LBRACK HASH LQUOTE target RQUOTE %s"は" [ style ] level %s"見出し" RBRACK
heading-paired-open  = LBRACK HASH [ style ] level %s"見出し" RBRACK
heading-paired-close = LBRACK HASH [ style ] level %s"見出し終わり" RBRACK
heading-block-open   = LBRACK HASH %s"ここから" [ style ] level %s"見出し" RBRACK
heading-block-close  = LBRACK HASH %s"ここで" [ style ] level %s"見出し終わり" RBRACK
level                = %s"大" / %s"中" / %s"小"
style                = %s"同行" / %s"窓"

The optional style prefix selects 同行 (same-line) or 窓 (window); its absence is the standard style. Style and level pair freely (…は同行中見出し, ［＃窓小見出し］, ［＃ここから大見出し］). The 窓 style appears almost exclusively in the paired form.

Parameters

• target — (hint form) the quoted run promoted or marked as a heading (resolved by §7.5). The paired and block forms have no quoted target: the content delimited between the opener and closer is the heading text.
• level — 大 / 中 / 小.
• style — standard (no prefix), 同行 (same-line), or 窓 (window).

Semantics

• A heading hint resolves its target (§7.5) and carries the level and style. It promotes that run to a heading node when the target is the bare line immediately preceding the directive — the run is pulled out of the flow and becomes the heading. When the referent is not such a clean preceding line, the hint is retained inline (a heading-hint marker) rather than promoted, so no run is mis-titled and no input is lost. The quoted target is matched ruby-stripped (§7.5), so a title carrying ruby — 両頭《りやうとう》の蛇《へび》 — is still recognised by its base text 両頭の蛇 (retained as a hint, since a ruby-bearing run is not a clean bare line). The 同行 (same-line) and 窓 styles in practice run into the body on their own line, so they are typically retained as hints; the standard style with a bare title line is the usual promotion case.
• A paired (［＃<style?><level>見出し］ … ［＃<style?><level>見出し終わり］) or block (［＃ここから…見出し］ … ［＃ここで…見出し終わり］) opener/closer pair (§7.1) delimits its content explicitly and yields a heading node wrapping that content — no forward reference or promotion is involved. Pairing is by the heading family at a matching level and style; a closer of a different level or style than its opener is a mismatch (§7.2). The 窓 style uses the paired form almost exclusively; the standard and 同行 styles occur in all three forms.
• Reference rendering (§8): a promoted standard 大 / 中 / 小 heading is <h1>–<h3> (class="aozora-heading aozora-heading-<large|medium|small>"); the 同行 / 窓 styles add an aozora-heading-<same-line|window> modifier (and 窓 renders as a styled <div> rather than an outline <hN>); a referent-present unpromoted hint is a hidden inline marker (<span class="aozora-heading-hint" data-level=… data-style=… data-target=… hidden>), with data-style present only for a non-standard style, while a self-contained hint (see Error conditions) renders its target visibly (<span class="aozora-heading-hint" data-level=…>X</span>, no hidden, no data-target) — the inline analogue of a heading, valid where the directive sits mid-line. The precise tag is part of the reference mapping (§8.2), not mandated. The paired and block forms render the same heading element (<hN> / <div> with the level and style classes) wrapping their delimited content directly (phrasing content, not a nested paragraph).
• Serialization reconstructs the directive (the hint's literal target, or the paired / block opener and closer around the content) byte-exact (§7.6).

Error conditions

• A single-target heading hint whose target is absent from the look-back is not an error: it is a self-contained forward heading — the quoted run is itself the heading text, retained as a visible heading-hint marker (never promoted, since there is no preceding line to reclaim). §6.14 degradation does not apply, as with the other forward references (§6.2, §6.12, §7.5).
• A multi-quote heading hint with any missing referent still degrades to a generic annotation (§6.14): a non-contiguous referent cannot be spliced into a single heading run.

Conformance vectors

heading, heading_hint, heading_forward_no_referent, heading_ruby_hint, heading_promoted, heading_same_line, heading_window, heading_paired_window, heading_block.

6.11 Illustrations (挿絵)

Synopsis

An illustration directive records an inserted image and, optionally, a caption — a reference to a figure file rather than image data itself.

Notation

［＃挿絵（fig01.png）入る］
［＃挿絵（fig01.png）「図一」入る］

sashie  = LBRACK HASH %s"挿絵（" path %s"）" [caption] %s"入る" RBRACK
path    = 1*body-char-not-rparen
caption = %s"「" 1*body-char-not-rquote %s"」"

The path is the figure file name between the full-width parentheses （ … ）. An OPTIONAL 「caption」 between ） and 入る carries the figure's caption ([AOZORA-ANNOTATION], graphics.html).

Parameters

• path — the figure file reference.
• caption — OPTIONAL associated caption text, where the source provides one.

Semantics

• The directive yields a sashie node carrying the file reference (and caption if present).
• Reference rendering (§8) is an image reference; because this specification does not fetch or embed image data, the reference mapping emits a figure placeholder/reference rather than pixels. A caption, when present, renders into the figure's <figcaption>.
• Serialization reconstructs the directive — including the optional 「caption」 — byte-exact (§7.6).

Error conditions

A malformed 挿絵（…） that does not close as ）入る is retained as a generic annotation (§6.14); no dedicated diagnostic is defined.

Conformance vectors

sashie, sashie_caption.

6.12 Bold and Italic (太字・斜体)

Synopsis

太字 (bold / ゴシック) and 斜体 (italic) mark a run for emphasis as a change of weight or slant, rather than the dots or lines of bouten (§6.2). The two form one family with a 太字/斜体 split, parallel to the 点/線 split of bouten.

Notation

Three forms produce emphasis. Unlike bouten the particle is は (not に), and the family has both a bare inline range and a ここから/ここで block range.

• Forward reference — quote the target; the emphasis applies to the most recent preceding occurrence (§7.5):

  作者附記［＃「作者附記」は太字］
  序文［＃「序文」は斜体］
  

• Inline range — a bare opener and matching closer wrap the run directly, within a line. This is the most common form in the corpus:

  emphasis-range = directive 1*element directive   ; ［＃太字］ … ［＃太字終わり］
  

  本文［＃太字］註［＃太字終わり］。
  値は［＃斜体］ｅ［＃斜体終わり］である。
  

• Block range — the ここから/ここで…終わり form wraps one or more whole paragraphs; the opener sits on its own line:

  ［＃ここから太字］
  強調する段落。
  ［＃ここで太字終わり］
  

Parameters

• weight — 太字 (bold) or 斜体 (italic). The weight is what pairing checks for the range forms (§7.2): a 太字 opener pairs with a 太字 closer.
• target — for the forward-reference form, the single quoted run to emphasise. The form names exactly one target; a multi-quote body (「A」「B」は太字) is not a recognised emphasis shape and degrades (§6.14).

Semantics

• The forward-reference form resolves its target by the look-back rule of §7.5 and yields an emphasis node over that run. It is an inline construct.
• The inline range form pairs opener and closer by weight (§7.1) and is an inline construct (§7.3): in the corpus it never spans a line, and rendering does not introduce block structure. It yields a container node (weight-tagged bold / italic) over the enclosed content.
• The block range form pairs the same way but is a block construct: it wraps the enclosed paragraphs in a weight-tagged container node.
• Reference rendering (§8): the inline forms are <b class="aozora-futoji">…</b> (太字) and <i class="aozora-shatai">…</i> (斜体) — presentational elements distinct from the <em> of bouten, so the two families never collide on one tag. The block form is a block container, <div class="aozora-container aozora-container-futoji">…</div> (resp. aozora-container-shatai), so the wrapped paragraphs nest validly.
• Serialization (§7.6) reconstructs the source form — the は forward reference (including a redundant preceding target copy), the bare inline range, or the ここから/ここで block range — byte-exact.

Error conditions

• Weight mismatch (range) — a 太字 opener closed by a 斜体 closer, or vice-versa, raises mismatched-container-close (error); the run is keyed to the opener's weight (recovery).
• Unclosed range — an opener with no closer is handled per unclosed-bracket.
• Target with no referent (forward reference) — a は太字 / は斜体 directive whose quoted target does not occur in the preceding text has no earlier run to emphasise, so the quoted target is itself the styled run: a self-contained forward reference, rendered <b> / <i>. ゴシック体 is a first-class gothic construct (§6.6), distinct from 太字 — the corpus uses them in disjoint works and gothic is a typeface family, not a bold weight — so the parser preserves its spelling and never folds it to 太字; serialization reconstructs ［＃「X」はゴシック体／太字／斜体］ byte-exact (§7.6). The vanishing ゴチック variant degrades (§6.14) with a lint suggesting ゴシック体. (Contrast the multi-quote body above, which is still unrecognised and degrades, §6.14.)

Conformance vectors

bold_inline, italic_inline, bold_block, italic_block, bold_forward, italic_forward, emphasis_mixed, bold_forward_no_referent, italic_forward_no_referent, bold_forward_gothic_no_referent (under conformance/vectors/).

6.13 Tables and columns (表・段組)

Synopsis

Two block containers mark table (表) and multi-column (段組) regions. Both are layout containers: they delimit a region but carry no cell, row, or column markup — the enclosed content is plain text whose alignment is set by spacing in the source. A processor marks the region; the internal structure is not machine-readable.

Notation

［＃ここから表］…［＃ここで表終わり］              ← table region
［＃ここから2段組み］…［＃ここで段組み終わり］     ← 2-column region

table-block-open   = LBRACK HASH %s"ここから表" RBRACK
table-block-close  = LBRACK HASH %s"ここで表終わり" RBRACK
columns-block-open = LBRACK HASH %s"ここから" 1*DIGIT %s"段組" [ %s"み" ] RBRACK
columns-block-close = LBRACK HASH %s"ここで段組" [ %s"み" ] %s"終わり" RBRACK

(The み okurigana is optional — 段組 and 段組み both occur.)

Parameters

• count — for columns (段組), the number of columns (2段組, 3段組, …).

Semantics

• A block opener/closer pair (§7.1) yields a container node — family table or columns — governing the enclosed lines; containers nest (§7.3), and pairing is by family (§7.2). The columns opener carries a count; the table opener has no parameter.
• The enclosed content is ordinary flow content (§5); there is no notation for table cells, rows, or column boundaries. Visual structure depends on the source's spacing and the rendering medium.
• Reference rendering (§8): <div class="aozora-container aozora-container-table">…</div> and <div class="aozora-container aozora-container-columns" data-columns="N">…</div>. The precise structure is part of the reference mapping (§8.2), not mandated.
• Serialization reconstructs the opener and closer around the content (§7.6); the み okurigana is normalised to 段組み.

Error conditions

• mismatched-container-close — a closer of a different family than its opener.
• unrecognised-container-directive — a ここから… opener naming no known container kind (kept as a generic annotation, §6.14).

The official guide's column sub-directives — 上段 / 下段 (explicit upper/lower column), 段間に罫 (rule between columns), 段組み適用外 (exemption) — and compound forms (ここから2字下げ、4段組み) are deferred to a later revision (§10.5); a processor retains them as generic annotations.

Conformance vectors

table_container, columns_container.

6.14 Input-editor annotations (入力者注)

Synopsis

Volunteer transcribers add editorial notes — flagging a surprising spelling as faithful to the source (ママ), recording a divergence from the base text, and so on. These are the input-editor annotations. This family also includes the generic annotation: the defined fate of any ［＃…］ whose body matches no other construct.

Notation

怪体な［＃「怪体」に「ママ」の注記］          ← "as-is from the source"
峰﹅［＃「峰」は底本では「峯」］              ← textual divergence note
本文［＃入力者注(5)］                        ← numbered input-typist note (→ 注5)
起上り［＃「起上り」にルビ］                 ← ruby-presence note (X carries ruby)
本文［＃ルビは「材木置場」にかかる］         ← ruby-binding note (ruby applies to X)
親［＃左にルビ付き］子［＃左に「よみ」のルビ付き終わり］  ← left-ruby span pair (reading on closer)
［＃なにかしらの注記］                       ← generic (unrecognised) annotation

mama-note     = LBRACK HASH LQUOTE target RQUOTE %s"に「ママ」の注記" RBRACK
textual-note  = LBRACK HASH LQUOTE target RQUOTE %s"は底本では" LQUOTE alt RQUOTE RBRACK
editor-note   = LBRACK HASH %s"入力者注(" 1*DIGIT %s")" RBRACK   ; ASCII parens + digits
ruby-attached = LBRACK HASH LQUOTE target RQUOTE %s"にルビ" RBRACK
ruby-retarget = LBRACK HASH %s"ルビは" LQUOTE target RQUOTE %s"にかかる" RBRACK
ruby-pair-open  = LBRACK HASH %s"左にルビ付き" RBRACK
ruby-pair-close = LBRACK HASH %s"左に" LQUOTE reading RQUOTE %s"のルビ付き終わり" RBRACK
annotation    = directive          ; any body not classified by §6.1–§6.13

Parameters

• target — for ママ and textual-note forms, the quoted run the note concerns (resolved per §7.5).
• alt — for a textual note, the base-text form the run diverges from.
• index — for the numbered input-typist note (入力者注(N)), the note number N (ASCII digits) referenced in the file's 凡例.

Semantics

• A ママ note marks its target as intentionally reproduced from the source; a textual note records the base-text reading. Both yield an annotation node carrying the editorial kind and resolve their target by §7.5.
• A numbered 入力者注(N) note yields an annotation node of editorial kind editor-note, rendered (§8) as a visible 注N superscript rather than a hidden span. The whole body must match exactly; a compound note that merely cites a number (e.g. 底本では…。入力者注(6)) stays a textual note.
• The ruby-placement notes — 「X」にルビ (the run X carries a ruby gloss) and ルビは「X」にかかる (a nearby ruby applies to X) — are proofreading markers, not renderable ruby (the gloss text is not in the directive). Each yields an annotation node of editorial kind ruby-attached / ruby-retarget, rendered (§8) as a compact visible marker (<sup class="aozora-ruby-note">ルビ</sup>) rather than the run X — X is usually the adjacent text and re-emitting it would double-render. The raw bracket round-trips byte-exact (§7.6).
• The left-side-ruby span pair — 左にルビ付き (opener) … 左に「Y」の ルビ付き終わり (closer) — brackets a run carrying a left-side ruby whose reading Y is named on the closer. Both markers yield an annotation node (editorial kinds ruby-pair-open / ruby-pair-close); like the inline warichu pair they are independent raw-preserving directives, not coupled at the tree level. Reference rendering (§8) is a compact marker on each — 左ルビ on the opener and 左ルビ「Y」 on the closer (the reading Y is a gloss, not surrounding text, so it does not double-render). Both round-trip byte-exact (§7.6).
• Generic annotation (the catch-all). Any directive whose body is not classified by §6.1–§6.13 yields a generic annotation node that retains the directive's literal bytes. A processor MUST NOT drop it: this is the guarantee that no bare ［＃ ever reaches output — every ［＃…］ is claimed, recognized or not. A ここから… body that looks like a container opener but names none additionally raises unrecognised-container-directive (§6.6).
• Reference rendering (§8) preserves the annotation (e.g. a hidden or side-channel span); serialization reconstructs the original ［＃…］ byte-exact (§7.6).

Error conditions

• unrecognised-container-directive — a ここから… opener naming no known container.
• Forward-reference notes (ママ, textual) whose target is absent degrade per §7.5.

Conformance vectors

annotation, editor_note, ruby_attached, ruby_retarget, left_ruby_pair, unrecognised-container-directive.

6.15 Double-angle quotation (二重山括弧)

Synopsis

A source text (底本) may set a phrase inside twin angle brackets 《…》. Those glyphs (U+300A / U+300B) are exactly the ruby reading markers (§6.1), so an Aozora Bunko transcription cannot write them literally without colliding with ruby. The transcription therefore encodes the quotation as ≪…≫ (U+226A / U+226B) and a processor restores the display form 《…》.

底本 《重要》 → transcription ≪重要≫ → display 《重要》.

Notation

A run delimited by ≪ (U+226A) and ≫ (U+226B):

≪重要≫

angle-quote   = ANGLE-OPEN angle-content ANGLE-CLOSE   ; ≪ … ≫
ANGLE-OPEN    = %x226A                                 ; ≪
ANGLE-CLOSE   = %x226B                                 ; ≫

The delimiters are distinct Unicode scalars from the ruby markers 《/》 (U+300A / U+300B), so this construct never competes with ruby under the leftmost-longest rule (§5.1).

Parameters

• content — the quoted run between the delimiters. It MAY contain the same nested inline constructs a ruby reading may (e.g. a gaiji reference), folded the same way (§7).

Semantics

• A well-formed ≪content≫ yields an angle-quote node over the run.
• Reference rendering (§8) is <span class="aozora-angle-quote">《…》</span>: the processor restores the display brackets 《…》 (U+300A / U+300B) inside the span. The input scalars ≪/≫ are not emitted.
• Serialization (§7.6) reconstructs the input form ≪content≫ (U+226A / U+226B), byte-exact; parse ∘ serialize is a fixed point.
• An adjacent 《《…》》 in source is not this construct: those are two ruby openers and raise nested-ruby (§9). The double-angle quotation is only ever the distinct ≪…≫ encoding.

Error conditions

• Unclosed ≪ — a ≪ with no matching ≫ is handled per unclosed-bracket (error); the region degrades to plain text.
• Empty ≪≫ — an empty body produces no node; the bytes degrade to plain text and are not flagged (mirroring a bare 《》).
• A stray ≫ with no opener is literal text and is not flagged.

Conformance vectors

angle_quote (under conformance/vectors/).

6.16 Superscript, subscript, and side glyphs (上付き・下付き・小書き)

Synopsis

Four forward-reference families set a short run as a small glyph offset from the baseline rather than changing its weight or slant (§6.12):

• 上付き小文字 (superscript) and 下付き小文字 (subscript) — the 横組み (horizontal-writing) raised/lowered small characters of mathematics (exponents) and chemistry (formula indices).
• 行右小書き and 行左小書き — the 縦組み (vertical-writing) small glyphs set to the right or left of the line.

All four are documented on the official 注記一覧 "その他" page ([AOZORA-ANNOTATION], etc.html). They share the forward-reference shape and the は particle with 太字/斜体 (§6.12) and yield the same emphasis node, so the spec groups them as one inline family distinct from bouten (§6.2).

Notation

Each family is forward reference only — quote the target; the treatment applies to the most recent preceding occurrence (§7.5). The particle is は.

script-glyph = target "［＃「" target "」は" keyword "］"
keyword      = "上付き小文字" / "下付き小文字" / "行右小書き" / "行左小書き"

ｅ２［＃「２」は上付き小文字］
Ｈ２［＃「２」は下付き小文字］
あい［＃「い」は行右小書き］
あい［＃「い」は行左小書き］

Unlike 太字/斜体 there is no bare inline range and no ここから/ここで block range for these families: the official guide gives only the forward-reference form, and the corpus attests only it.

Parameters

• kind — one of 上付き小文字 / 下付き小文字 / 行右小書き / 行左小書き.
• target — the single quoted run to treat. As with §6.12, the form names exactly one target; a multi-quote body is not a recognised shape and degrades (§6.14).

Semantics

• Each form resolves its target by the look-back rule of §7.5 and yields an emphasis node over that run. It is an inline construct.

• The node carries the kind so serialization (§7.6) can reconstruct the source directive, including the redundant preceding target copy, byte-exact.

• Reference rendering (§8):

  • 上付き小文字 → <sup class="aozora-uwatsuki">…</sup>
  • 下付き小文字 → <sub class="aozora-shitatsuki">…</sub>
  • 行右小書き → <span class="aozora-kogaki-right">…</span>
  • 行左小書き → <span class="aozora-kogaki-left">…</span>

  The <sup> / <sub> elements give super- and sub-script their conventional horizontal rendering; the 小書き families, which are positional in vertical writing, render as side <span>s a stylesheet can place. None collides with the <b> / <i> of §6.12, the <em> of bouten (§6.2), or the <ruby> of §6.1.

Error conditions

• Target with no referent — a は… directive whose quoted target does not occur in the preceding text has no earlier run to treat, so the quoted target is itself the treated run: a self-contained forward reference, rendered <sup> / <sub> / side <span>. Serialization reconstructs the directive byte-exact (§7.6); no input is lost (parallel to the 太字/斜体 rule, §6.12).

Conformance vectors

superscript_forward, subscript_forward, side_glyph_right, side_glyph_left, superscript_forward_no_referent, subscript_forward_no_referent, side_glyph_right_no_referent, side_glyph_left_no_referent (under conformance/vectors/).

6.17 Character size (文字サイズ)

Synopsis

A character-size directive shifts a run's type size by a relative number of stages, larger or smaller, without changing its weight (§6.12) or position (§6.16). It is the typographic device the official guide records for editor's notes, mathematics, and emphasis where weight is unsuitable ([AOZORA-ANNOTATION], etc.html).

Notation

Two forms occur. The forward-reference form (particle は) resizes a single run:

font-size  = target "［＃「" target "」は" size-spec "］"
size-spec  = magnitude %s"段階" direction %s"文字"
magnitude  = 1*DIGIT          ; ASCII or full-width, 1..127
direction  = %s"大きな" / %s"小さな"

見出し［＃「見出し」は2段階大きな文字］
注記［＃「注記」は1段階小さな文字］

The block form resizes the enclosed paragraphs:

font-size-open  = LBRACK HASH %s"ここから" size-spec RBRACK
font-size-close = LBRACK HASH %s"ここで" direction %s"文字終わり" RBRACK

［＃ここから2段階大きな文字］
大きく組まれた段落。
［＃ここで大きな文字終わり］

The block closer drops the magnitude — it names only the direction (大きな / 小さな); the opener's stage count is authoritative.

Absolute sizes (特大 / 大 / 中 / 小文字)

A second, absolute scale names a fixed size rather than a relative stage — 特大文字 > 大文字 > 中文字 > (body) > 小文字. The forward-reference form is corpus-attested (「X」は小文字); unlike the relative scale it takes no magnitude.

abs-size    = target "［＃「" target "」は" abs-keyword "］"
abs-keyword = %s"特大文字" / %s"大文字" / %s"中文字" / %s"小文字"

ヱ［＃「ヱ」は小文字］

The absolute 小文字 is a size, distinct from the script-glyph 上付き小文字 / 下付き小文字 (§6.16) whose keyword it is a substring of: the recogniser matches the whole は… body, so the two never collide. (The single-work postfix headline forms ［＃大文字］ / ［＃大文字、太字］ apply the same scale at the line scope; they are documented under the line directives.)

Parameters

• magnitude — the number of stages, 1‥127. A leading run of ASCII or full-width digits; a missing or zero magnitude, or one that overflows the stage range, is not a recognised size change and degrades (§6.14).
• direction — 大きな (larger, a positive stage count) or 小さな (smaller, negative).
• target — the single quoted run to resize (as §6.12 / §6.16).

Semantics

• The forward-reference form resolves its target by the look-back rule of §7.5 and yields an emphasis node carrying the signed stage count. It is an inline construct.
• The block form pairs opener and closer by the font-size family (§7.1) and yields a block container node carrying the opener's signed stage count. Because the closer names only a direction, a 大きな opener closed by a 小さな closer is not flagged as a family mismatch; the corpus never mixes them.
• Reference rendering (§8): the inline form is <span class="aozora-font-larger" data-steps="N">…</span> (大きな) / <span class="aozora-font-smaller" …> (小さな); the block form is <div class="aozora-container aozora-container-font-larger" data-steps="N">…</div> (resp. aozora-container-font-smaller), where N is the (positive) magnitude. A stylesheet maps the stage count to a size.
• Serialization (§7.6) reconstructs ［＃「X」はN段階大きな/小さな文字］. A full-width magnitude canonicalises to ASCII; the mapping is idempotent, so the parse∘serialize fixed point holds after the first pass.
• The absolute forward form yields an emphasis node carrying the absolute size; reference rendering (§8) is <span class="aozora-font-{slug}">…</span> with slug font-extra-large / font-large / font-medium / font-small. Serialization reconstructs ［＃「X」は…文字］ byte-exact.

Error conditions

• Target with no referent — a は…文字 directive whose quoted target does not occur in the preceding text has no earlier run to resize, so the quoted target is itself the resized run: a self-contained forward reference, rendered <span data-steps>. Serialization reconstructs the directive byte-exact (§7.6).
• Malformed magnitude — a zero, missing, or out-of-range stage count degrades (§6.14); no dedicated diagnostic is defined.

Conformance vectors

font_size_larger_forward, font_size_smaller_forward, font_size_block, font_size_larger_no_referent, font_size_absolute_small_forward (under conformance/vectors/).

6.18 Horizontal writing (横組み)

Synopsis

A 横組み directive sets a run or a block of text horizontally inside an otherwise vertical document — used for Western dates, formulae, and tabular fragments ([AOZORA-ANNOTATION], etc.html). Two forms occur: an inline forward reference for a single run and a ここから/ここで block region.

Notation

horizontal-inline = target "［＃「" target "」は横組み］"
horizontal-open   = LBRACK HASH %s"ここから横組み" RBRACK
horizontal-close  = LBRACK HASH %s"ここで横組み終わり" RBRACK

西暦［＃「西暦」は横組み］

［＃ここから横組み］
2024年1月
［＃ここで横組み終わり］

Parameters

• target — for the inline form, the single quoted run to set horizontally (resolved by the look-back rule, §7.5).

Semantics

• The inline forward-reference form yields an emphasis node over its target and is an inline construct.
• The block form pairs opener and closer by the horizontal family (§7.1) and yields a block container node governing the enclosed paragraphs; it nests with other block containers (§7.3).
• Reference rendering (§8) is <span class="aozora-yokogumi">…</span> for the inline form and <div class="aozora-container aozora-container-yokogumi">…</div> for the block form. Whether a processor reorients glyphs or merely tags the region is a presentation choice; the node model only records that the run is 横組み.
• Serialization reconstructs the inline directive or the block opener/closer byte-exact (§7.6).

Error conditions

• Target with no referent (inline) — the quoted target has no earlier run to reorient, so it is itself the 横組み run: a self-contained forward reference, rendered <span class="aozora-yokogumi">. Serialization reconstructs the directive byte-exact (§7.6).
• Mismatched / unclosed block — handled per mismatched-container-close and unclosed-bracket.

Conformance vectors

horizontal_inline_forward, horizontal_container, horizontal_inline_forward_no_referent (under conformance/vectors/).

6.19 Structural markers (本文終わり・改行)

Synopsis

Two self-contained marker directives carry document structure rather than inline styling. 本文終わり marks the end of the main body — a colophon or afterword follows — and is a block-level structural leaf. 改行 is a forced in-paragraph line break — an inline leaf.

Notation

Each is a self-contained directive with no opener/closer and no inner content:

［＃本文終わり］    ← end of the main body (a colophon/afterword follows)
［＃改行］          ← forced in-paragraph line break

body-end     = LBRACK HASH %s"本文終わり" RBRACK
forced-break = LBRACK HASH %s"改行" RBRACK

Parameters

None.

Semantics

• ［＃本文終わり］ yields a zero-width bodyEnd node — a block leaf (§8.1, like a break) standing on its own line. It marks the boundary after which a colophon or afterword follows; it does not capture or govern the following lines.
• ［＃改行］ yields a forcedBreak node — an inline leaf forcing a line break inside the current paragraph without ending it.
• Reference rendering (§8): bodyEnd → <div class="aozora-body-end"></div>; forcedBreak → <br />.
• 改行 is longest-match disambiguated from 改行天付き (the §6.6 top-flush hanging-indent form): only a bare ［＃改行］ is a forced break; ［＃ここから改行］天付き… opens an indent region (§6.6) instead.
• Serialization reconstructs each directive byte-exact (§7.6).

Error conditions

• None specific. A malformed marker body (an unrecognised directive between ［＃ and ］) falls to the generic annotation handling of §6.14 and round-trips byte-exact.

Conformance vectors

body_end, forced_break (under conformance/vectors/).

6.20 Fractions (分数)

Synopsis

The 分数 (fraction) forward reference typesets a short run as a fraction — a numerator over a denominator — rather than as inline text. It is the mathematical-typography sibling of the script glyphs (§6.16): a forward reference with the は particle and a single target, yielding an emphasis node. The official 注記一覧 lists it among the emphasis-page treatments ([AOZORA-ANNOTATION], etc.html); the corpus attests only the forward-reference form.

Notation

Forward reference only — quote the target; the treatment applies to the most recent preceding occurrence (§7.5). The particle is は. The target is a fraction expression separated by a slash, either ASCII / (U+002F) or fullwidth ／ (U+FF0F); both widths occur in the corpus.

fraction = target "［＃「" target "」は分数］"
target   = numerator slash denominator
slash    = "/" / "／"

1/4［＃「1/4」は分数］
１／４［＃「１／４」は分数］

Unlike 太字/斜体 (§6.12) there is no bare inline range and no ここから/ここで block range for 分数: the official guide gives only the forward-reference form, and the corpus attests only it. A comma-joined compound that pairs 分数 with another treatment in one bracket (［＃「3」は上付き小文字、「1/143」は分数］) is not this single-target shape; it degrades to an unrecognised directive (§6.14) pending the multi-directive grammar.

Parameters

• target — the single quoted run to typeset. As with §6.16, the form names exactly one target; a multi-quote body is not a recognised shape and degrades (§6.14). The renderer splits the target on the first slash: text before the slash is the numerator, text after it the denominator.

Semantics

• The form resolves its target by the look-back rule of §7.5 and yields an emphasis node over that run. It is an inline construct.

• The node carries the 分数 attribute so serialization (§7.6) can reconstruct the source directive, including the redundant preceding target copy, byte-exact.

• Reference rendering (§8): the target is split on the first slash into a numerator and a denominator, joined by the fraction slash ⁄ (U+2044) —

  分数 → <span class="aozora-bunsu"><sup>NUM</sup>⁄<sub>DEN</sub></span>
  

  The aozora-bunsu wrapper distinguishes a fraction from the lone <sup> of §6.16 (aozora-uwatsuki); neither collides with the <b>/<i> of §6.12, the <em> of bouten (§6.2), or the <ruby> of §6.1. A target with no slash (not attested) renders verbatim inside the wrapper.

Error conditions

• Target with no referent — a は分数 directive whose quoted target does not occur in the preceding text has no earlier run to treat, so the quoted target is itself the treated run: a self-contained forward reference, rendered as the fraction wrapper above. Serialization reconstructs the directive byte-exact (§7.6); no input is lost (parallel to the §6.16 rule).

Conformance vectors

fraction_forward, fraction_forward_no_referent (under conformance/vectors/).

6.21 Dotted letters (ドット付き)

Synopsis

The ドット付き (dotted-letter) directive composes a combining dot above or below a base Latin letter in the immediately-preceding run — m → ṁ, s → ṣ. It records the diacritics of transliterated Sanskrit / Pāli that Aozora Bunko's plain-text encoding cannot spell directly. It is a forward reference with the は particle, yielding an emphasis node.

This is a distinct mechanism from the §6.19 accent decomposition of Annex A: that scheme rewrites ASCII digraphs (a + ` → à) inside a 〔…〕 span at the character level; this directive instead names a letter of the preceding run and asks for a dot. The two compose — a dotted letter frequently sits inside an already-decomposed 〔…〕 span (see the vectors).

The official 注記一覧 ([AOZORA-ANNOTATION]) lists it among the emphasis-page treatments; the corpus attests only the forward-reference form.

Notation

The directive has no 「X」 quoted target. Its body is a selector that names a letter (and, optionally, which occurrence) of the preceding run, the は particle, a position (上 above / 下 below), and the keyword ドット付き.

dotted     = run "［＃" clause *( ( "。" / "、" ) clause ) "］"
clause     = selector "は" [ set-adv ] position "ドット付き"
selector   = [ ordinal ] letters
ordinal    = number "つめの" / "最後の" / "前の" / "後の"
set-adv    = "ともに" / "それぞれ"
position   = "上" / "下"
letters    = 1*ALPHA            ; ASCII letters, case-significant for the glyph
number     = 1*DIGIT            ; ASCII or fullwidth digits

A body may carry several 。- or 、-joined clauses; every clause addresses the same preceding run, and their substitutions are applied together.

Sam［＃mは上ドット付き］
Sisa［＃２つめのsは下ドット付き］
Visnu［＃snはともに下ドット付き］
〔Mīhr〕［＃hは下ドット付き］
Samsa［＃mは上ドット付き。２つめのsは下ドット付き］
Konkana［＃前のnは上ドット付き、後のnは下ドット付き］

run is the source text immediately preceding the bracket: a bare Latin word, or a whole 〔…〕 accent span (whose tortoiseshell brackets are retained).

Parameters

• selector — names the base letter(s):
  • a bare letter (m) selects the first composable occurrence in the run (a word-initial capital with no dotted glyph, e.g. the N of Nara-sinha, is skipped in favour of the intended lowercase letter);
  • an ordinal Nつめの / 最後の / 前の / 後の selects the N-th / last / first / last occurrence, counting case-insensitively (an uppercase S is occurrence 1 for a ２つめのs over Sīsa); 前の / 後の name the earlier / later of a letter's two occurrences across a 、-joined pair; the selected position must itself be composable;
  • a cluster of several letters with ともに / それぞれ dots each listed letter's first occurrence independently (sn → the first s and first n).
• position — 上 (dot above) or 下 (dot below).

The ともに / それぞれ adverb is spelling-only: it is preserved verbatim on serialization but does not change which occurrences are dotted.

Semantics

• The directive resolves against the reclaimed preceding run (§7.5) and yields an emphasis node over it, with Reclaimed provenance: the run is pulled back so the composed span is its sole rendered copy, and serialization (§7.6) re-emits the literal run followed by the raw directive body, byte-exact. It is an inline construct.

• Composition is NFC: each (letter, position) pair maps to a single precomposed scalar (ṁ U+1E41, ṅ U+1E45, ṃ U+1E43, ṇ U+1E47, ṣ U+1E63, ṭ U+1E6D, ḥ U+1E25, ṛ U+1E5B, ḍ U+1E0D, and capitals Ṭ U+1E6C, Ṛ U+1E5A). Composition is case-preserving (t → ṭ, T → Ṭ).

• Reference rendering (§8) emits the composed run inside a wrapper —

  ドット付き → <span class="aozora-accent-dot">…composed run…</span>
  

  aozora-accent-dot does not collide with any other treatment's class.

• A multi-clause body applies every clause's substitutions to the one reclaimed run (resolve-all-then-substitute, so an earlier dot never shifts a later clause's index) and still yields a single node.

Error conditions

• No reclaimable run — when a 》 ruby close or Japanese text butts the bracket there is no preceding Latin run (dot-over-ruby-base is not representable in a text-only forward leaf, the bouten-over-ruby limitation of §6.2). The directive degrades to an unrecognised directive (§6.14), rendered as a hidden raw span and serialized verbatim.
• Absent or un-composable occurrence — a selector naming a letter absent from the run, an ordinal out of range, or a (letter, position) pair with no precomposed glyph (e.g. an uppercase S below) degrades likewise, losing no input.
• Word-qualified and 段目 forms — a word-qualified selector (simhaのm…) and a 段目 table-row reference (４段目、Sinhaのn…) address a named word or a table row rather than the adjacent run; their 、-split pieces are not pure ASCII-letter selectors, so they degrade to an unrecognised directive. A body in which any clause fails to parse degrades as a whole.

Conformance vectors

accent_dot_above, accent_dot_below, accent_dot_tortoise, accent_dot_ordinal, accent_dot_uppercase, accent_dot_cluster, accent_dot_multi_clause, accent_dot_former_latter, accent_dot_ruby_base_unknown, accent_dot_dangyou_unknown (under conformance/vectors/).

7. Structural Processing Model

§5 yields a flat element stream; §6 classifies each directive. This section defines the structure built on top: how openers pair with closers, how containers nest, how forward references resolve, and how the result serializes back to source byte-for-byte.

7.1 Pairing

Some constructs are paired: an opener and a matching closer with content between them. The paired families are:

• block layout containers — ［＃ここから…］ / ［＃ここで…終わり］ (§6.6);
• 罫囲み — ［＃罫囲み］ / ［＃罫囲み終わり］ (§6.7);
• 割り注 — ［＃割り注］ / ［＃割り注終わり］ (§6.8); and
• the 傍点/傍線 range form — ［＃傍点］ / ［＃傍点終わり］ (§6.2).

Pairing uses a stack: each opener is pushed; each closer pops the nearest open of a compatible family and forms a pair governing the content between them. A processor MUST pair by family, not by exact variant, so that e.g. a 2字下げ opener pairs with a plain 字下げ終わり closer.

7.2 Mismatch and recovery

• A closer whose family differs from the popped opener raises mismatched-container-close; the opener is auto-closed at the closer and the pair is keyed by the opener's family (recovery).
• Within the 傍点/傍線 range family, a 点-vs-線 family disagreement raises mismatched-bouten-container (§6.2); the run is keyed to the opener's variant.
• A closer with no open on the stack, or an opener never closed, is handled per unmatched-close / unclosed-bracket; the affected marker degrades but its bytes are preserved.

7.3 Block vs inline; nesting

A paired construct is block or inline:

• Block containers (block layout, 罫囲み) govern whole lines and may nest; rendering wraps them as block elements. Breaks (§6.9) persist across a block container (print typography), so a break inside one is not flagged.
• Inline ranges (傍点/傍線 range, 割り注) attach within a line and do not introduce block structure. The corpus shows these never span a line in practice.

Containers nest by the stack discipline of §7.1; an inner pair closes before its outer pair.

7.4 Single-line containers

A single-line layout directive (［＃地付き］, ［＃2字下げ］, §6.6) has no closer: it governs the remainder of its line only and is modelled as a zero-width marker, not a wrapping container. Consequently a page or section break sharing that line, or a break inside a 割り注 range, drops the governed scope and raises break-in-single-line-container (§6.9).

7.5 Forward-reference resolution

Some directives name a target by quoting it and look backwards in the already-seen text to find the run they apply to:

• ［＃「X」に傍点］ and its variants (§6.2),
• ［＃「X」は縦中横］ (§6.3),
• heading hints ［＃「X」は…見出し］ (§6.10), and
• 「ママ」/textual-note annotations (§6.14).

Resolution rule: a processor scans the text preceding the directive (back to the start of the current line, or the document per the construct) for the most recent occurrence of the quoted target X, and applies the construct to that run. The matched run may be adjacent to the directive (the redundant explicit form 平和［＃「平和」に傍点］) or lie earlier in the same base run (太字の［＃「太字」は太字］ — の intervenes); in both cases the construct is applied in place to that occurrence, and the directive round-trips unchanged (§7.6).

• The look-back is over the base text: ruby readings (《…》) and the explicit-base ｜ marker are not part of what X matches against. A heading whose title carries ruby — ○　両頭《りやうとう》の蛇《へび》［＃「○　両頭の蛇」は中見出し］ — quotes the ruby-stripped target ○　両頭の蛇, which a processor resolves against the ruby-stripped run ○　両頭の蛇.

• If X does not occur in the look-back, the directive degrades to a generic annotation and raises the family's "target not found" diagnostic (e.g. tcy-target-not-found).

• If X occurs more than once, the chosen run may be unintended; a processor raises the family's "ambiguous" diagnostic where defined (e.g. bouten-target-ambiguous) and applies the construct to the match its look-back selects.

• If X resolves but the matched run cannot be styled in place — it is a ruby base (bouten-over-ruby is not representable as a text-only leaf), lies on an earlier line, sits inside another construct, or is one of several quoted targets — a processor keeps the directive, leaves the run unstyled, and raises forward-referent-not-stylable. The directive still round-trips unchanged (§7.6).

• The redundant explicit form 平和［＃「平和」に傍点］ (the target literal immediately precedes the directive) is common and MUST round-trip unchanged (§7.6).

7.6 Serialization round-trip

A processor that serializes MUST be a fixed point: re-parsing a serialized result yields the same structure, and serializing again yields the same bytes. Normalization (§4) is loss-free for this reason — the serializer reconstructs 〔…〕 accent spans, the ｜ of an explicit ruby base, the literal target of a redundant forward reference, and the original directive strings. The serialize projection of each conformance vector pins this.

8. Reference Rendering

This specification defines notation in terms of an abstract node model; a processor's primary output is that structure (the nodes / pairs projections of §10). This section gives a reference rendering to semantic HTML5. The node model is normative; the specific HTML is a reference mapping — informative, so that the conformance suite can pin a concrete output, but a processor MAY target a different presentation.

8.1 Node model (normative)

Parsing yields a tree of nodes. Each node has a kind and a sanitized-source span; container nodes have children. The kinds, with the family that produces them, are:

The nodes conformance projection lists recognized nodes in source order, each with its span; container open/close appear as containerOpen / containerClose entries (in source coordinates).

8.2 Reference HTML mapping (informative)

Text is grouped into paragraphs (<p>); a blank line ends a paragraph; a single newline within a paragraph is a <br />. The five HTML-significant ASCII characters (< > & " ') are escaped. The reference renderer ships no stylesheet; the aozora-* class hooks are presentation contracts a consumer styles.

8.3 Why a reference mapping, not a mandated one

The notation describes Japanese typography (vertical writing, ruby, emphasis dots); the faithful visual result depends on the rendering medium. Pinning a reference HTML lets the suite check a concrete output and lets tools interoperate, without forcing every processor — a paginator, an EPUB builder, a search indexer — to emit identical markup. A processor claims conformance against the projections it produces (§10.1).

9. Diagnostics and Error Handling

A processor reports diagnostics: structured, non-fatal observations about the input. Per §2.4 a processor MUST always produce a result and MUST NOT abort; diagnostics annotate what it noticed and how the affected construct degraded.

9.1 Diagnostic structure

Each diagnostic carries:

• a stable code — a kebab-case identifier such as empty-ruby-reading. Codes are stable across minor revisions; new diagnostics add new codes.
• a severity — error, warning, or note.
• a span — a byte range in the sanitized source (§2.3) locating the construct.

A conforming processor MUST detect and report every error-severity diagnostic in §9.2–§9.5 whose triggering condition the input meets (these are the must-level diagnostics of §10), with the specified code and severity. warning and note diagnostics are RECOMMENDED. A processor MAY report additional diagnostics under codes not defined here.

9.2 Encoding and lexical

Source contains PUA

source-contains-pua · warning

The source contains a code point that a processor reserves internally as a placeholder (§3.4). This diagnostic applies only to a processor that uses such a strategy; it neutralizes the occurrence during §4 and reports this. Real Aozora Bunko text does not contain such code points.

Unclosed bracket

unclosed-bracket · error

An opener (ruby 《, a directive ［＃, a quote, …) reached end of input with no matching closer. Recovery: the region degrades to plain text; no pair is emitted. The label points at the opener.

Unmatched close

unmatched-close · error

A closer appeared with no matching opener, or against a different kind of opener. Recovery: the stray closer is treated as plain text. The label points at the closer.

9.3 Normalization and gaiji

Accent decomposition applied

accent-decomposition-applied · note

A 〔…〕 accent digraph was rewritten to its combined Unicode form during §4 (〔e'〕 → é). Intended behaviour, surfaced as a note so an editor can show what changed; the transform is loss-free and the serializer (§7) reconstructs the 〔…〕 form. The span is in post-decomposition coordinates.

Unresolved gaiji

unresolved-gaiji · warning

A ※［＃…］ reference resolved to neither a Unicode scalar nor a JIS X 0213 cell (§6.4). Recovery: rendering falls back to the description text. The label points at the reference.

9.4 Ruby

Empty ruby reading

empty-ruby-reading · error

An explicit-base ruby supplied a base (｜ precedes 《) but an empty 《》 reading. A bare 《》 with no ｜ is not flagged (it is literal text). Recovery: degrades to plain text. The label spans the whole ｜base《》.

Nested ruby

nested-ruby · error

A ruby reading body itself opened another ruby (｜漢《か《ん》じ》). Ruby does not nest; an adjacent 《《…》》 is likewise two openers, not a single construct (the double-angle quotation notation is the distinct ≪…≫, §6.15). Recovery: the outer ruby is parsed best-effort; the label points at the inner 《.

9.5 Containers, forward references, and kunten

Mismatched container close

mismatched-container-close · error

A paired container opened with one family (indent / align-end / keigakomi / warichu) was closed by a closer of a different family. Comparison is by family, so 2字下げ closed by a plain 字下げ終わり is not flagged. Recovery: the opener is auto-closed at the closer, keyed by the open family. The label points at the closer.

Unrecognised container directive

unrecognised-container-directive · warning

A ［＃ここから…］ opener named no known container kind. Recovery: kept as a generic annotation (the "no bare ［＃" guarantee, §6.14, holds); no container is opened. The label spans the directive.

Mismatched bouten container

mismatched-bouten-container · error

A 傍点/傍線 range (§6.2) opened with one family (点 dots / 線 line) and was closed by the other (［＃傍点］…［＃傍線終わり］). Recovery: the run is keyed to the opener's variant. The label points at the closer.

Break in single-line container

break-in-single-line-container · warning

A page or section break shares a source line with a single-line layout directive (§6.6), or falls inside a 割り注 range (§6.8). A single-line container governs only the rest of its line, so the break drops it. Block containers persist across breaks and are not flagged. The label points at the break.

TCY target not found

tcy-target-not-found · warning

A ［＃「X」は縦中横］ forward reference (§6.3) named a target absent from the preceding text. Recovery: degrades to a generic annotation. The label spans the directive.

Bouten target ambiguous

bouten-target-ambiguous · warning

A ［＃「X」に傍点］ forward reference (§6.2) named a target that occurs more than once in the preceding look-back. Recovery: applied to the match the look-back rule selects, which may not be intended. The label spans the directive.

Forward referent not stylable

forward-referent-not-stylable · warning

An inline-style forward reference (［＃「X」は太字／斜体］, ［＃「X」に傍点］, は縦中横, は「□」囲み, …, §6.2 / §6.3 / §6.12) named a target X that is present in the look-back (§7.5) but cannot be styled in place: it is a ruby base (bouten-over-ruby is not representable), lies on an earlier line, sits inside another construct, or is one of several quoted targets. Recovery: the directive is kept and round-trips unchanged, but the run is left unstyled. The label spans the directive.

Bracketed kaeriten no pair

bracketed-kaeriten-no-pair · error

A bracketed kaeriten of rank ≥ 2 (［＃二］ / ［＃下］ / ［＃乙］) appeared in a document whose family base (一 / 上 / 甲) is absent entirely (§6.5). The check is document-wide and base-only. Recovery: the mark is kept. The label points at the unpaired mark.

Kaeriten outside kanbun

kaeriten-outside-kanbun · warning

A kaeriten is the only one in the document and its surroundings read as ordinary kana prose, i.e. it is likely a stray annotation rather than a return mark (§6.5). A conservative lookahead heuristic; a cluster of kaeriten is never flagged. The label points at the lone mark.

9.6 Diagnostic ordering

When a processor exposes diagnostics as an ordered sequence, that sequence SHOULD be non-decreasing by processing phase — normalization (§4) before lexical/pairing before classification (§5, §6) before the post-pass that resolves containers (§7). This keeps editor surfaces and golden tests stable. Ordering within a phase is not constrained.

10. Conformance

10.1 Conforming processor

A conforming processor is an implementation that, for every input:

1. produces a result without aborting (§2.4);
2. applies the §4 normalization and the §5–§7 model; and
3. satisfies every must-level expectation of the conformance suite (§10.3).

A processor need not implement every projection (some have no HTML renderer, some no serializer); it conforms with respect to the projections it produces. A processor MUST NOT emit, for a must-level vector, a projection that contradicts that vector.

10.2 The role of this specification (master)

This specification is designed to be the single source of truth a processor conforms to. The normative prose, the examples, and the machine-readable suite are kept in one repository so they cannot drift: every normative example in §6 corresponds to a vector, and a consuming processor SHOULD pin a tagged release (vX.Y.Z) of this repository — a git revision also works — and run the suite in its own CI, failing on any must mismatch.

10.3 Conformance suite

The suite lives at conformance/vectors/. Each case is a vector.json validating against conformance/schema/vector.schema.json and carrying a source plus the expected projections (nodes, pairs, serialize, diagnostics, and optionally html). The runner contract — how a processor consumes a vector, which projections are compared, and how matches are scored by level — is conformance/RUNNER.md.

Levels

For a must vector, the nodes, pairs, and diagnostics projections are mandatory comparisons; serialize is compared when the processor has a serializer; html is compared when the processor has the reference renderer (§8) and the vector's level pins it.

10.4 Claiming conformance

An implementation claiming conformance SHOULD state:

• the specification version it targets (a vX.Y.Z release tag; or the git revision);
• which projections it produces;
• its results against the suite, including any justified should/may divergences.

10.5 Coverage and growth

The §6 catalogue covers the core notation families. The boundary below is grounded in a full sweep of every work in P4suta/aozorabunko_text (17,889 files, re-measured 2026-06-25) — parsed and bucketed by the reference implementation, not estimated. Counts are occurrences across that sweep. An earlier draft of this section misreported several of them (noted inline); they are corrected here from the measured data. The most recent #78 burn-down promoted the compound-indent modifier set (§6.6) and the structural-marker leaves (§6.19), dropping the residual Unknown (generic-annotation) total from 3418 to 2848.

Recognised, pending full §6 promotion

These corpus-attested forms are recognised by the reference implementation (typed distinctly, not the generic-annotation fallback). They are listed here because their full normative §6 text and vectors are still being written; until then a conforming processor MAY treat them as generic annotations (§6.14), but the recommended behaviour is the typed form below.

• File-header 凡例 symbols — the de-facto-standard legend that prefixes nearly every work: ［＃］ (入力者注, ~14k occurrences), ［＃…］ (返り点), ［＃（…）］ (訓点送り仮名). Empty / placeholder directives — not unrecognised notation. Typed distinctly so they leave the generic-annotation bucket.
• Bare-range forms of families whose ここから…/ここで…終わり block form is already in §6: ［＃{N}段階…文字］…［＃…文字終わり］ (font-size, ~15k), ［＃横組み］…終わり (~3k), ［＃行右/左小書き］…終わり (~8k), ［＃キャプション］…終わり (~2.5k).
• Block 罫囲み / 割り注 (the ここから… region forms; the bare ［＃罫囲み］/［＃割り注］ remain inline), 天から{N}字下げ (top-origin indent), and the bare 改行天付き、折り返して{N}字下げ hanging indent.
• Range bouten 「X」～「Y」に<kind> (also 〜) — marks the whole preceding run from X to Y.
• Input-editor notes: 「X」はママ (sic), 「X」は底本では「Y」 (source divergence), 「X」に「Y」の注記 (side annotation — see the correction below), numbered illustrations ［＃挿絵{N}（…）入る］, and caption-before figures 「caption」のキャプション付きの(図|挿絵|写真)（file）入る.

Promoted in the #78 burn-down

Two families that this section previously listed as outside the model are now normative, each with a must vector:

• Structural-marker leaves (§6.19) — ［＃本文終わり］ (body end, 242 occurrences, the #1 unrecognised body before this change) is a block leaf; ［＃改行］ (forced break, 165) is an inline leaf. See body_end and forced_break.
• Compound-indent modifier set (§6.6) — the decorative clauses an indent opener may stack after ここからN字下げ、 (ゴシック体, 横書き/横組み, 罫囲み, 小さい活字), order-independent on input and re-emitted in a fixed canonical order, are now §6.6-normative (no longer deferred). Page-centring within an indent (ページの左右中央に) is part of the same compound form and is likewise supported. See indent_compound_styled. The canonical order, spellings, and the modifier set are fixed by ADR-0004 (extending ADR-0003).

Closed as a boundary (kept lossless-generic)

These forms were reviewed in the #78 burn-down and closed for want of corpus demand: a conforming processor retains the whole ［＃…］ as a generic annotation (§6.14), round-tripping byte-exact. The measured occurrence is recorded so the boundary is auditable.

• Rare bouten in bare-range form — ［＃鎖線］…［＃鎖線終わり］ and the 破線 / 黒三角傍点 variants: 0 occurrences. The forward-reference form (「X」に鎖線の傍点 etc.) stays normative; the bare-range deferral is recorded in ADR-0004.
• Right-side ruby / annotation — the right side is already the default ｜《》 ruby, so an explicit の右に…のルビ bracket is redundant. The の右に…のルビ and の右に…の注記 forms have 0 occurrences (an earlier "≈8" was wrong); the attested side-annotation form 「X」に「Y」の注記 is recognised (above).
• Table cell / row structure — ［＃ここから表］ marks a region; there is no sanctioned cell or row delimiter (the full-width ／ is an editor convention). 段間に罫 appears just once across the sweep and 上段/下段 never appear as directives (0) — far too sparse to pin a sub-region model.
• Column sub-regions — 上段/下段/段組み適用外 as in-region directives: 0 occurrences. The 段組み region itself is recognised; it carries no sanctioned sub-region split.

Still deferred

• Block centring with no closer — ここから中央揃え (0) and the attested ここからページの左右中央 (11) appear in the corpus without a matching closer, so they do not fit the paired-container model and remain generic annotations. (Page-centring within an indent is supported — §6.6, above.)
• 地寄せ (margined right-align) and embedded-directive compounds — ［＃ここからN字下げ、「」は返り点］, ［＃ここから字下げ、ここから数式］ and the like: any unrecognised clause triggers the decline-whole rule, so the whole directive is retained losslessly and reports unrecognised-container-directive.
• Left-ruby block form (［＃左にルビ付き］…［＃左に「X」のルビ付き終わり］) — the paired-block counterpart of the forward-reference left-side ruby (which is normative). ~2 occurrences, and the reading sits in the closer, so it does not fit the streaming per-run container machinery. Pinned only on demand.
• ローマ数字、面-区-点 gaiji form — needs a node the model does not yet carry; left as a generic annotation until promoted.

The full sweep leaves a residue of generic-annotation occurrences (down from ~194k before successive rounds of corpus grounding). The remainder is overwhelmingly correct as a generic annotation: open-ended 入力者注 free-text prose (not a fixed notation) and forward references whose target is genuinely absent — legend examples like （例）［＃「第一章」は中見出し］, where the quoted target never occurs as a preceding run. (A heading whose title merely carries ruby is not such a case: its target is present, only ruby-split, and is resolved ruby-stripped per §7.5 — see heading_ruby_hint.)

As a family in the first group gains full normative text it gains a vector, recorded in Annex E. Coverage is tracked openly with full-corpus evidence rather than implied — a processor is never asked to match a behaviour this document has not pinned with a vector.

11. Security Considerations

The notation is a markup language for archival text; processing untrusted input nonetheless warrants care.

11.1 Resource exhaustion

Constructs nest (containers, §7.3) and forward references scan preceding text (§7.5). A naive look-back that rescans from the document start for every reference is quadratic in the number of references; a deeply nested or highly pathological document can drive memory and time up. A processor SHOULD bound look-back cost (e.g. an index of candidate targets) and SHOULD bound nesting depth, degrading gracefully (a generic annotation) rather than consuming unbounded resources.

11.2 Reserved-code-point confusion

A processor that uses private-use code points as internal markers (§3.4) MUST neutralize any such code point appearing in the source (§4.4) and report source-contains-pua; otherwise crafted input could forge internal markers and corrupt the placeholder mapping, mis-attributing or mis-rendering spans.

11.3 Encoding confusion

Input may be Shift_JIS or UTF-8 (§3.1). Mis-detecting the encoding can change which bytes form a delimiter and therefore which constructs are recognized. A processor SHOULD obtain the encoding out of band where possible, and MUST replace undecodable bytes with U+FFFD rather than guessing a delimiter.

11.4 Output-context injection

The reference HTML (§8) escapes the five HTML-significant ASCII characters. A processor emitting HTML (or any other structured output) MUST escape for its output context; gaiji descriptions, annotation bodies, and resolved targets are author-controlled text and MUST NOT be emitted into markup unescaped.

11.5 Gaiji table trust

Gaiji resolution (§6.4, Annex B) maps men-ku-ten and descriptions to Unicode via data tables. A processor SHOULD treat those tables as a trusted, versioned input; a wrong mapping silently substitutes a different glyph. Unresolved references degrade visibly (unresolved-gaiji) rather than guessing.

12. References

12.1 Normative references

• [BCP 14] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, RFC 2119, March 1997; and B. Leiba, Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words, RFC 8174, May 2017.
• [RFC 5234] D. Crocker, Ed., P. Overell, Augmented BNF for Syntax Specifications: ABNF, RFC 5234, January 2008.
• [RFC 7405] P. Kyzivat, Case-Sensitive String Support in ABNF, RFC 7405, December 2014.
• [UNICODE] The Unicode Consortium, The Unicode Standard. https://www.unicode.org/versions/latest/.
• [JISX0213] JIS X 0213, 7-bit and 8-bit double byte coded extended Kanji sets for information interchange. Used for gaiji men-ku-ten addressing (§6.4, Annex B).

12.2 Informative references

• [AOZORA-ANNOTATION] Aozora Bunko, 注記一覧 (annotation guide). https://www.aozora.gr.jp/annotation/. The authoritative human-facing description this specification formalises (§1.2). Snapshot date is recorded per citing section / decision record.
• [AOZORA-MANUAL] Aozora Bunko, 工作員手引き / 入力規約 (volunteer input conventions). https://www.aozora.gr.jp/aozora_text/.
• [CORPUS] The Aozora Bunko text corpus, used to ground notation forms and frequencies (§1.2). Cited per section where a frequency claim is made.

Annex A. Accent decomposition table

This annex is normative. It defines the indicator-to-character mapping for the 〔…〕 accent decomposition of §4.3. Within an accent span, a Latin base letter immediately followed by an ASCII indicator is rewritten to the corresponding precomposed Unicode character.

A.1 Indicators

The & indicator also forms ligatures, which are checked before the ring-above reading (longest match wins, §A.3):

A.2 Coverage

Not every (letter, indicator) pair has a precomposed form; only the pairs that map to a Unicode character are decomposed. The closed set is enumerated below (lower- and upper-case share the same indicators):

A 〔…〕 span whose body contains no sequence in this table is left unchanged and emits no diagnostic (§4.3).

A.3 Rules

• Longest match. A multi-character ligature (ae&, s&, …) is matched in preference to a shorter reading of its prefix. s& is ß, never s + ring.
• Line-bounded. An accent span begins and ends on one line (§4.3, §5.5).
• Loss-free. The serializer reconstructs the original 〔…〕 source form (§7.6); decomposition is reversible by construction.
• Diagnostic. Each span that actually contained a digraph raises accent-decomposition-applied (note), in post-decomposition coordinates.

The enumeration above follows the official 外字 accent guidance (§12 [AOZORA-ANNOTATION]). Additions are a MINOR revision: a new (letter, indicator) row never changes an existing mapping.

Annex B. Gaiji resolution

This annex defines how a ※［＃…］ gaiji reference (§6.4) resolves to a character. It is normative as to the order of resolution and the forms recognized; the underlying JIS X 0213 and description tables are versioned data (§11.5).

B.1 Reference forms

A gaiji reference is ※ followed by a directive whose body is a glyph description optionally followed by an address. The forms, by the address they carry:

The body before the first 、 is the human description (radical-composition like 木＋世, or a name like 二の字点). The 、-separated trailer carries the address(es). A bare page-line locator (123-4) is a provenance note, not a resolvable address.

B.2 Resolution order

A processor resolves the reference by trying, in order, and stopping at the first hit:

1. an explicit U+XXXX in the body — validated with char::from_u32 semantics (a value that is not a Unicode scalar does not resolve here);
2. a JIS X 0213 men-ku-ten (第N水準P-R-C or 面-区-点) → the scalar (or combining sequence) for that cell;
3. a description that names a known glyph (the 外字注記辞書 / description table) → its scalar;
4. a single-character description — if the description is itself exactly one character, that character.

If none resolves, the reference is unresolved: the processor reports unresolved-gaiji (warning) and the reference falls back to its description text (§6.4, §8).

B.3 Special forms

• くの字点 (kunojiten, the vertical iteration mark) is written ／＼, and its voiced form ／″＼. These are notation, not a ※［＃…］ reference.
• A men-ku-ten cell MAY map to a combining sequence (more than one scalar), e.g. a base kana plus a combining mark; resolution yields the full sequence.

B.4 Round-trip

Resolution is for rendering; the serializer (§7.6) reconstructs the original ※［＃…］ reference verbatim, so a resolved or unresolved reference round-trips losslessly.

The men-ku-ten and description tables derive from JIS X 0213 (§12 [JISX0213]) and Aozora Bunko's 外字注記辞書. A processor SHOULD treat them as trusted, versioned inputs (§11.5).

Annex C. Directive vocabulary (slugs)

This annex enumerates the controlled vocabulary of directive keywords — the fixed strings a directive body (§5.2) is classified against. It is the companion data to §6. Keywords are matched against the body verbatim; parameter slots are shown as N (a decimal count, ASCII or full-width) or … (a quoted target / path).

C.1 Breaks (§6.9)

C.2 Layout containers (§6.6)

Further layout keywords (§6.6, deferred): the block centring form ここから…中央…, margined right-align …地寄せ, and compound directives (ここから2字下げ、中央揃え).

C.2a Tables and columns (§6.13)

Deferred (§6.13, §10.5): column sub-directives 上段 / 下段, 段間に罫, 段組み適用外.

C.3 Keigakomi (§6.7) and warichu (§6.8)

C.4 Bouten / bousen variants (§6.2)

The 点 (dot) family and 線 (line) family. Each appears in the inline forward-reference form (［＃「X」に <kw>］) and the range form (［＃<kw>］ … ［＃<kw>終わり］), optionally prefixed by 左に for the left side.

(鎖線 / 破線 / 黒三角傍点 are official but corpus-sparse; a processor renders them like any other variant where it has a glyph, otherwise degrading per §6.14.)

C.5 Kaeriten marks (§6.5)

Single (12): 一 二 三 四 上 中 下 甲 乙 丙 丁 レ. Compound (6, Xレ): 一レ 二レ 三レ 上レ 中レ 下レ. Okurigana: （…） (parenthesised kana).

Ladder families and bases (§6.5): numeric 一<二<三<四 (base 一), jouge 上<中<下 (base 上), kō-otsu 甲<乙<丙<丁 (base 甲). レ is standalone.

C.6 Other directives

Any body matching no keyword here is a generic annotation (§6.14); a ここから… opener matching no container raises unrecognised-container-directive.

Annex D. Collected ABNF grammar

This annex collects the normative lexical grammar (§5). Terminals are Unicode scalar values; the grammar applies to the §4 sanitized source. Body classification (§6), structural pairing, and forward-reference resolution (§7) are defined in prose, not in this grammar.

; The Aozora Bunko Notation Specification — collected lexical grammar.
; ABNF per RFC 5234 / RFC 7405. Terminals are Unicode scalar values given by
; %x (codepoint), so this grammar applies to the §4 sanitized source decoded
; to a sequence of Unicode scalar values (UTF-8 on the wire).
;
; SCOPE: this grammar fixes the LEXICAL surface — how a directive, a ruby
; span, a gaiji reference, and an accent span are delimited. It deliberately
; treats a directive body as an opaque run; *which* directive a body denotes
; is classified by the normative prose of §6, and structural pairing /
; forward-reference resolution is defined by §7. Alternatives of `element`
; are applied by LEFTMOST-LONGEST match (§5); `text` is whatever remains.

; ===== Delimiter terminals (full-width) =====
LBRACK      = %xFF3B          ; ［  FULLWIDTH LEFT SQUARE BRACKET
RBRACK      = %xFF3D          ; ］  FULLWIDTH RIGHT SQUARE BRACKET
HASH        = %xFF03          ; ＃  FULLWIDTH NUMBER SIGN
RUBY-OPEN   = %x300A          ; 《  LEFT DOUBLE ANGLE BRACKET
RUBY-CLOSE  = %x300B          ; 》  RIGHT DOUBLE ANGLE BRACKET
ANGLE-OPEN  = %x226A          ; ≪  MUCH LESS-THAN (double-angle quotation, input)
ANGLE-CLOSE = %x226B          ; ≫  MUCH GREATER-THAN (double-angle quotation, input)
BAR         = %xFF5C          ; ｜  FULLWIDTH VERTICAL LINE (ruby base mark)
REFMARK     = %x203B          ; ※  REFERENCE MARK (gaiji)
LQUOTE      = %x300C          ; 「  LEFT CORNER BRACKET
RQUOTE      = %x300D          ; 」  RIGHT CORNER BRACKET
LPAREN      = %xFF08          ; （  FULLWIDTH LEFT PARENTHESIS
RPAREN      = %xFF09          ; ）  FULLWIDTH RIGHT PARENTHESIS
TORT-OPEN   = %x3014          ; 〔  LEFT TORTOISE SHELL BRACKET (accent span)
TORT-CLOSE  = %x3015          ; 〕  RIGHT TORTOISE SHELL BRACKET

; ===== Top level =====
; A document is a sequence of elements; `text` carries everything that does
; not begin a construct, per the leftmost-longest rule (§5).
document    = *element
element     = gaiji-ref / ruby / angle-quote / accent-span / directive / text

; ===== Directive:  ［＃ body ］ =====
; `body` is opaque here; §6 classifies it (page break, indent, bouten, …).
directive   = LBRACK HASH body RBRACK
body        = *body-char
body-char   = %x0-FF3C / %xFF3E-10FFFF      ; any scalar except ］ (U+FF3D)

; ===== Gaiji reference:  ※［＃ … ］ =====
; A reference mark immediately followed by a directive (§6.4).
gaiji-ref   = REFMARK directive

; ===== Ruby =====
; Explicit base is delimited by ｜; the implicit form takes its base from a
; preceding run per §6.1. Reading is the run inside 《 … 》.
ruby            = [ BAR base ] RUBY-OPEN reading RUBY-CLOSE
base            = 1*base-char
base-char       = %x0-3009 / %x300C-FF5B / %xFF5D-10FFFF
                                            ; excludes 《 》 (U+300A/B) and ｜ (U+FF5C)
reading         = 1*reading-char
reading-char    = %x0-300A / %x300C-10FFFF  ; excludes 》 (U+300B)

; ===== Double-angle quotation:  ≪ … ≫  (input) → 《 … 》 (display) =====
angle-quote     = ANGLE-OPEN angle-content ANGLE-CLOSE
angle-content   = 1*angle-char
angle-char      = %x0-226A / %x226C-10FFFF   ; excludes ≫ (U+226B, ANGLE-CLOSE)

; ===== Accent span:  〔 … 〕  (one per line; see §4) =====
accent-span     = TORT-OPEN accent-body TORT-CLOSE
accent-body     = *accent-char
accent-char     = %x0-3014 / %x3016-10FFFF  ; excludes 〕 (U+3015)

; ===== Text =====
; The maximal run that does not begin one of the constructs above. ABNF
; cannot express the negative lookahead directly; §5 defines the
; leftmost-longest disambiguation that yields it.
text        = 1*scalar
scalar      = %x0-D7FF / %xE000-10FFFF      ; any Unicode scalar value

Annex E. Change log

The authoritative change log is CHANGELOG.md at the repository root; this annex mirrors it for readers of the rendered book.

Draft v0.1.0 (unreleased)

Added — the initial framework (§§1–5, 7–12) and annexes; normative notation families (ruby including the left-side ruby (saidoku-moji building block) and the left-side annotation 注記, bouten/bousen including the range form, 左に side, and the rare 鎖線 / 破線 / 黒三角傍点 variants, tate-chu-yoko, gaiji, the layout containers including the 折り返し字下げ hanging form, the 字詰め line-width form, the single-line centring marker and the combined 字下げ＋ページ 左右中央 form, tables / columns (表・段組 block layout containers), keigakomi, warichu, breaks, headings (大/中/小 levels × standard/同行/窓 styles, in forward-reference, paired, and block forms), illustrations, bold/italic (太字・斜体), input-editor annotations, double-angle quotation (二重山括弧, ≪…≫ → 《…》), the superscript / subscript / side-glyph families (§6.16: 上付き小文字・下付き小文字・ 行右小書き・行左小書き), the character-size change (§6.17: N段階大きな/小さな文字, both the forward-reference and ここから/ここで block forms), and horizontal writing (§6.18: 横組み, inline は横組み and the ここから/ここで block)); the bundled illustration caption 挿絵（file）「caption」入る (§6.11); the families the official guide treats as provisional or that this revision has not yet pinned, documented with their notation (the block centring form, the 段組 sub-directives, the left-ruby block form, and the standalone caption directive — see §10.5); the machine-readable conformance suite (schema, vectors, runner contract); and the decision records under docs/adr/.

Changed — recharacterized the double-angle quotation (二重山括弧, §6.15): an earlier draft mis-described 《《…》》 as a "double-bracket bouten" selected over ruby by leftmost-longest. The input encoding is ≪…≫ (U+226A/U+226B), restored to the display form 《…》 (U+300A/U+300B); a literal 《《…》》 in source is two ruby openers (a nested-ruby error). The double_ruby vector is renamed angle_quote.

Versioning: the specification follows Semantic Versioning. While pre-1.0 (0.x), a normative change that can break a conforming processor bumps the minor; backward-compatible additions and fixes bump the patch. See §10.5 for how provisional families graduate to must coverage.