# A Bulaq page: the text framed by its commentary

> Ibn ʿAqīl’s grammar commentary in the main column, glosses in the outer side column beside the passages they explain, all inside a double ruled frame.

- HTML version: https://postext.dev/en/cookbook/bulaq-framed-page
- Recipe Nº 114 · Page & grid · Level 2 (Intermediate) · Outputs: Canvas, PDF
- Genres: Textbooks
- Requires postext ≥ 1.15.0, postext-pdf ≥ 1.15.0 · tested with 1.15.0, postext-pdf 1.15.0 on 2026-10-04
- Pages: [١](https://postext.dev/cookbook/bulaq-framed-page/en/p01.webp?v=ea0ee764), [٢](https://postext.dev/cookbook/bulaq-framed-page/en/p02.webp?v=ea0ee764), [٣](https://postext.dev/cookbook/bulaq-framed-page/en/p03.webp?v=ea0ee764), [٤](https://postext.dev/cookbook/bulaq-framed-page/en/p04.webp?v=ea0ee764), [٥](https://postext.dev/cookbook/bulaq-framed-page/en/p05.webp?v=ea0ee764), [٦](https://postext.dev/cookbook/bulaq-framed-page/en/p06.webp?v=ea0ee764)
- PDF: https://postext.dev/cookbook/bulaq-framed-page/en/bulaq-framed-page.pdf?v=ea0ee764
- Open in Sandbox: https://postext.dev/en/sandbox#recipe=bulaq-framed-page&lang=en (.postext: https://postext.dev/cookbook/bulaq-framed-page/en/bulaq-framed-page.postext)
- Last updated: 2026-10-04
- Other languages: [es](https://postext.dev/es/cookbook/bulaq-framed-page.md), [ca](https://postext.dev/ca/cookbook/bulaq-framed-page.md), [zh](https://postext.dev/zh/cookbook/bulaq-framed-page.md), [ar](https://postext.dev/ar/cookbook/bulaq-framed-page.md)

## In short

A page made like the Arabic books printed in Cairo in the 1800s: the main text in the middle, short notes on it in a narrow column at the edge, and the whole page boxed in by printed lines.

## What you'll build

Six pages set the way the Bulaq press and its Cairo successors printed a commentary in the nineteenth century. Ibn ʿAqīl’s explanation of the first verses of the Alfiyya, Ibn Mālik’s grammar in a thousand lines, runs in the main column, the verses in red; in the outer margin stands a ḥāshiya, short glosses that each open with the words of the text they explain, beside the passage they belong to. A double rule frames the type area, with a band at its head for the chapter and the folio, and a single rule parts the text from its margin. A real Bulaq page wraps the ḥāshiya round three sides of the text; Postext sets it on one side only, and this recipe says so.

**This recipe answers:**

- How do I lay out a Bulaq page, with the commentary framed around the text?

## The short answer

The commentary's column beside the text, both inside one ruled frame.

```js
// script.js, lines 31–43
// The text runs in the main column of a column-and-a-half layout; the side column, on the
// outer side, takes only boxes with span 'side', so each gloss stands level with the
// paragraph it comments on. A column rule parts the two, as the jadwal of a Bulaq page does.
const layout = { layoutType: 'oneAndHalf', sideColumnRole: 'floats', sideColumnSide: 'outer',
  sideColumnPercent: 31, gutterWidth: mm(7),
  columnRule: { enabled: true, color: col('rule'), lineWidth: pt(0.6) } };
// A gloss is a callout with no box: the margin's own face, its lemma bold in the rubric.
const hashiya = { id: 'hashiya', span: 'side', backgroundEnabled: false, borderRadius: pt(0),
  padding: { top: pt(0), right: pt(0), bottom: pt(0), left: pt(0) },
  stripe: { enabled: false }, border: { enabled: false },
  body: { fontFamily: NASKH, fontSize: pt(10), lineHeight: pt(16), color: col('ink'),
    boldColor: col('rubric'), textAlign: 'justify', firstLineIndent: pt(0),
    paragraphSpacing: true } };
```

## Ingredients

**Teaches**

- [Margin notes](https://postext.dev/en/docs/configuration.md#callout-styles): Boxes set in the side column level with the paragraph they gloss, in a column-and-a-half layout with a float channel.
- [Text, rules and boxes in page designs](https://postext.dev/en/docs/configuration.md#headers--footers): The drawing elements shared by headers, footers, openers and part pages: text with an optional pill, horizontal and vertical rules, and filled or framed boxes painted in array order.
- [Right-to-left text](https://postext.dev/en/docs/arabic-layout.md#direction-and-the-bidirectional-algorithm): direction sets the base direction of the document: 'auto' (the default) takes it from the script of locale, so 'ar', 'fa' or 'he' run right to left; the bidirectional algorithm (UAX #9) orders the Latin words and numbers inside each line, and the book binds on the right.

**Also uses**

- [Column and a half](https://postext.dev/en/docs/configuration.md#layout-types)
- [Margin column for floats](https://postext.dev/en/docs/configuration.md#layout)
- [Column rule](https://postext.dev/en/docs/configuration.md#column-rule)
- [Books bound on the right](https://postext.dev/en/docs/configuration.md#binding)
- [Arabic fonts](https://postext.dev/en/docs/arabic-layout.md#fonts)
- [Arabic as the document language](https://postext.dev/en/docs/arabic-layout.md#starting-an-arabic-book)
- [Arabic verse (bayt in two hemistichs)](https://postext.dev/en/docs/document-format.md#verse)
- [Digits of the generated numbers](https://postext.dev/en/docs/configuration.md#document-language)
- [Covers, title pages and colophons](https://postext.dev/en/docs/configuration.md#heading-styles)
- [Heading styles](https://postext.dev/en/docs/configuration.md#heading-styles)
- [Heading attributes](https://postext.dev/en/docs/document-format.md#heading-attributes)
- [Running heads and folios](https://postext.dev/en/docs/configuration.md#headers--footers)
- [Paper colour](https://postext.dev/en/docs/configuration.md#page)
- [Paragraph styles](https://postext.dev/en/docs/configuration.md#paragraph-styles)
- [Paragraphs in the other direction](https://postext.dev/en/docs/arabic-layout.md#document-block-and-inline-direction)
- [Semantic colour palette](https://postext.dev/en/docs/configuration.md#color-palette)
- [PDF export](https://postext.dev/en/docs/configuration.md#generating-pdfs)
- [Callout boxes](https://postext.dev/en/docs/configuration.md#callout-styles)
- [Designed openers](https://postext.dev/en/docs/configuration.md#span-and-advanced-design)
- [Heads by page role](https://postext.dev/en/docs/configuration.md#text-elements)
- [Fonts embedded in the PDF](https://postext.dev/en/docs/configuration.md#why-a-font-provider)
- [Running heads per section](https://postext.dev/en/docs/configuration.md#heading-styles)

**Config at a glance**

- [`bodyText`](https://postext.dev/en/docs/configuration.md#body-text), [`calloutStyles`](https://postext.dev/en/docs/configuration.md#callout-styles), [`colorPalette`](https://postext.dev/en/docs/configuration.md#color-palette), [`footer`](https://postext.dev/en/docs/configuration.md#headers--footers), [`header`](https://postext.dev/en/docs/configuration.md#headers--footers), [`headingStyles`](https://postext.dev/en/docs/configuration.md#heading-styles), [`headings`](https://postext.dev/en/docs/configuration.md#headings), [`layout`](https://postext.dev/en/docs/configuration.md#layout), [`locale`](https://postext.dev/en/docs/configuration.md#hyphenation), [`page`](https://postext.dev/en/docs/configuration.md#page), [`paragraphStyles`](https://postext.dev/en/docs/configuration.md#paragraph-styles)

**APIs**

- [`buildDocument`](https://postext.dev/en/docs/configuration.md#building-a-document), [`clearMeasurementCache`](https://postext.dev/en/docs/configuration.md#measurement-cache), [`decompressWoff2`](https://postext.dev/en/docs/configuration.md#browser-font-provider-fontsource--woff2), [`renderPageToCanvas`](https://postext.dev/en/docs/configuration.md#rendering-a-page-to-a-bitmap), [`renderToPdf`](https://postext.dev/en/docs/configuration.md#generating-pdfs)

**Typefaces**

- Amiri (OFL-1.1), Aref Ruqaa (OFL-1.1)

## Method

### 1 · The ḥāshiya in a side column of its own

The code is [the short answer](#the-short-answer) above. A column-and-a-half layout whose side column takes only floats keeps the commentary out of the text’s flow: each gloss is a `:::callout{type="hashiya" span="side"}` written after the paragraph it explains, and it stands level with that paragraph ([Layout](/en/docs/configuration#layout)). The box has no background, border or padding, so it reads as text set in the margin, its lemma in bold, which the `boldColor` turns red. `sideColumnSide: 'outer'` puts the column at the fore-edge of both pages: on the right of the even page, which lies on the right in a book bound on the right.

![Page ٣.](https://postext.dev/cookbook/bulaq-framed-page/en/p03.webp?v=ea0ee764)

*Page 3: the gloss on «كديز» stands beside the paragraph that uses the word, at the outer edge, behind the column rule.*

### 2 · A frame drawn for each side of the spread

```js
// script.js, lines 47–73
// Page-level design elements are physical: the frame follows the margins of each side of
// the spread. In a book bound on the right the even page is the right-hand one, its spine
// on its left, so its inner margin is the left one.
const frame = (parity, withBand = true) => {
  const left = parity === 'even' ? M.inner : M.outer;
  const width = TRIM.width - M.inner - M.outer;
  const box = (id, inset, thickness) => ({ kind: 'box', id: `${id}-${parity}`, parity,
    style: { borderColor: col('rule'), borderWidth: pt(thickness) },
    placement: { anchor: { to: 'page', edge: 'top-left' },
      offset: { x: mm(left - 4 + inset), y: mm(M.top - 13 + inset) },
      size: { width: mm(width + 8 - 2 * inset),
        height: mm(TRIM.height - M.top - M.bottom + 17 - 2 * inset) } } });
  return [box('outer', 0, 1.4), box('inner', 1.3, 0.4), ...(withBand ? [
    { kind: 'rule', id: `band-${parity}`, parity, direction: 'horizontal', thickness: pt(0.4),
      color: col('rule'), placement: { anchor: { to: 'page', edge: 'top-left' },
        offset: { x: mm(left - 2.7), y: mm(M.top - 4) },
        size: { width: mm(width + 5.4) } } }] : [])];
};
// The chapter centred in the band, the folio at its outer end.
const band = (id, content, parity, edge, x, extra = {}) => ({ kind: 'text', id, content,
  parity, pages: 'body', fontFamily: NASKH, fontWeight: 700, fontSize: pt(10.5),
  color: col('ink'),
  placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(M.top - 11) } }, ...extra });
const header = { elements: [...frame('even'), ...frame('odd'),
  band('head', '{chapterTitle}', 'all', 'top', 0),
  band('folio-even', '{pageNumber}', 'even', 'top-right', -(M.outer + 1), { pages: 'all' }),
  band('folio-odd', '{pageNumber}', 'odd', 'top-left', M.outer + 1, { pages: 'all' })] };
```

The frame is three page design elements in the header: two boxes with a border and no fill, 1.3 mm apart, and a rule under the band that holds the running head. Page elements are physical, so the frame is built twice, once per parity, from the margins of that side ([Page order and right binding](/en/docs/arabic-layout#page-order-and-right-binding)). The folio sits at the outer end of the band on every page, openers included; the chapter title is centred and left off the opener, where the title itself stands under it.

### 3 · A title page inside the same frame

```js
// script.js, lines 77–94
const line = (id, content, y, style) => ({ kind: 'text', id, content, align: 'center',
  overflow: 'wrap', color: col('ink'),
  placement: { anchor: { to: 'page', edge: 'top' }, offset: { y: mm(y) },
    size: { width: mm(110) } }, ...style });
const titlePage = { id: 'title', span: 'page', runningChapter: false,
  breakBefore: { enabled: true, parity: 'any' }, header: { elements: [] },
  footer: { elements: [] },
  advancedDesign: { enabled: true, slot: { elements: [...frame('odd', false),
    line('book', '{titleText}', 64, { fontFamily: RUQAA, fontWeight: 700, fontSize: pt(40),
      lineHeight: 1.3, color: col('rubric') }),
    line('on', '{attr.on}', 88, { fontFamily: NASKH, fontWeight: 700, fontSize: pt(17) }),
    { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(0.75), color: col('rubric'),
      placement: { anchor: { to: 'page', edge: 'top' }, offset: { y: mm(104) },
        size: { width: mm(30) } } },
    line('margin', '{attr.margin}', 112, { fontFamily: NASKH, fontSize: pt(13) }),
    line('latin', '{attr.latin}', 196, { fontFamily: NASKH, fontSize: pt(9), italic: true,
      color: col('muted') }),
  ] } } };
```

The title page reuses the frame without its band. Its lines come from heading attributes, `on` and `margin`, so the whole title page is one line of Markdown, and the Latin line under them changes with the edition.

## The whole recipe

One file, composed from the recipe's folder with the sample text and the Cookbook's shared kit inlined; it builds its own page. To run it, put it in a `<script type="module">` on an empty page, or paste it into the JS panel of a new CodePen (as a module). It imports postext from esm.sh, so there is nothing to install or build.

- Source folder: https://github.com/drnachio/postext/tree/main/cookbook/bulaq-framed-page

### script.js

```js
// ═══ Postext Cookbook · Nº 114 · A Bulaq page: the text framed by its commentary ════════
// https://postext.dev/en/cookbook/bulaq-framed-page
// Code: MIT · Text: Ibn ʿAqīl, Sharḥ; Ibn Mālik, Alfiyya, ar.wikisource (PD) · Pictures: none
// Fonts: Amiri, Aref Ruqaa (SIL OFL 1.1) · Needs postext ≥ 1.15.0
import { buildDocument, renderPageToCanvas, clearMeasurementCache } from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'bulaq-framed-page';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// Black and a brown-red on a toned paper: the two inks of a Cairo press around 1900.
const palette = {
  ink: '#1d1915', // text and frame rules
  rubric: '#8e3020', // the accent: lemmas of the glosses, the matn, titles
  rule: '#3a312a', // the frame
  muted: '#6a6056', // the note on the text
  paper: '#f6efe0', // a toned paper
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  { id: 'main-color', name: 'rubric (defaults)', value: { hex: palette.rubric, model: 'hex' } },
];
const NASKH = 'Amiri'; // the text, the matn and the glosses
const RUQAA = 'Aref Ruqaa'; // the title page and the chapter title
const TRIM = { width: 170, height: 240 }; // mm
const M = { top: 34, bottom: 24, inner: 20, outer: 15 }; // mm: the type area inside the frame

// #region answer: the commentary's column beside the text, both inside one ruled frame
// The text runs in the main column of a column-and-a-half layout; the side column, on the
// outer side, takes only boxes with span 'side', so each gloss stands level with the
// paragraph it comments on. A column rule parts the two, as the jadwal of a Bulaq page does.
const layout = { layoutType: 'oneAndHalf', sideColumnRole: 'floats', sideColumnSide: 'outer',
  sideColumnPercent: 31, gutterWidth: mm(7),
  columnRule: { enabled: true, color: col('rule'), lineWidth: pt(0.6) } };
// A gloss is a callout with no box: the margin's own face, its lemma bold in the rubric.
const hashiya = { id: 'hashiya', span: 'side', backgroundEnabled: false, borderRadius: pt(0),
  padding: { top: pt(0), right: pt(0), bottom: pt(0), left: pt(0) },
  stripe: { enabled: false }, border: { enabled: false },
  body: { fontFamily: NASKH, fontSize: pt(10), lineHeight: pt(16), color: col('ink'),
    boldColor: col('rubric'), textAlign: 'justify', firstLineIndent: pt(0),
    paragraphSpacing: true } };
// #endregion

// #region frame: a double rule round the type area and a band for the running head
// Page-level design elements are physical: the frame follows the margins of each side of
// the spread. In a book bound on the right the even page is the right-hand one, its spine
// on its left, so its inner margin is the left one.
const frame = (parity, withBand = true) => {
  const left = parity === 'even' ? M.inner : M.outer;
  const width = TRIM.width - M.inner - M.outer;
  const box = (id, inset, thickness) => ({ kind: 'box', id: `${id}-${parity}`, parity,
    style: { borderColor: col('rule'), borderWidth: pt(thickness) },
    placement: { anchor: { to: 'page', edge: 'top-left' },
      offset: { x: mm(left - 4 + inset), y: mm(M.top - 13 + inset) },
      size: { width: mm(width + 8 - 2 * inset),
        height: mm(TRIM.height - M.top - M.bottom + 17 - 2 * inset) } } });
  return [box('outer', 0, 1.4), box('inner', 1.3, 0.4), ...(withBand ? [
    { kind: 'rule', id: `band-${parity}`, parity, direction: 'horizontal', thickness: pt(0.4),
      color: col('rule'), placement: { anchor: { to: 'page', edge: 'top-left' },
        offset: { x: mm(left - 2.7), y: mm(M.top - 4) },
        size: { width: mm(width + 5.4) } } }] : [])];
};
// The chapter centred in the band, the folio at its outer end.
const band = (id, content, parity, edge, x, extra = {}) => ({ kind: 'text', id, content,
  parity, pages: 'body', fontFamily: NASKH, fontWeight: 700, fontSize: pt(10.5),
  color: col('ink'),
  placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(M.top - 11) } }, ...extra });
const header = { elements: [...frame('even'), ...frame('odd'),
  band('head', '{chapterTitle}', 'all', 'top', 0),
  band('folio-even', '{pageNumber}', 'even', 'top-right', -(M.outer + 1), { pages: 'all' }),
  band('folio-odd', '{pageNumber}', 'odd', 'top-left', M.outer + 1, { pages: 'all' })] };
// #endregion

// #region title: the title page, framed like the text pages
const line = (id, content, y, style) => ({ kind: 'text', id, content, align: 'center',
  overflow: 'wrap', color: col('ink'),
  placement: { anchor: { to: 'page', edge: 'top' }, offset: { y: mm(y) },
    size: { width: mm(110) } }, ...style });
const titlePage = { id: 'title', span: 'page', runningChapter: false,
  breakBefore: { enabled: true, parity: 'any' }, header: { elements: [] },
  footer: { elements: [] },
  advancedDesign: { enabled: true, slot: { elements: [...frame('odd', false),
    line('book', '{titleText}', 64, { fontFamily: RUQAA, fontWeight: 700, fontSize: pt(40),
      lineHeight: 1.3, color: col('rubric') }),
    line('on', '{attr.on}', 88, { fontFamily: NASKH, fontWeight: 700, fontSize: pt(17) }),
    { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(0.75), color: col('rubric'),
      placement: { anchor: { to: 'page', edge: 'top' }, offset: { y: mm(104) },
        size: { width: mm(30) } } },
    line('margin', '{attr.margin}', 112, { fontFamily: NASKH, fontSize: pt(13) }),
    line('latin', '{attr.latin}', 196, { fontFamily: NASKH, fontSize: pt(9), italic: true,
      color: col('muted') }),
  ] } } };
// #endregion

const config = () => ({ // a factory: the engine caches resolved configs per object
  locale: 'ar', // right to left, bound on the right, digits ٠–٩ (gotcha: arabic-locale-tag)
  colorPalette,
  page: { width: mm(TRIM.width), height: mm(TRIM.height), dpi: 150,
    backgroundColor: col('paper'), margins: { top: mm(M.top), bottom: mm(M.bottom),
      left: mm(M.inner), right: mm(M.outer), mirror: true } },
  layout,
  bodyText: { fontFamily: NASKH, fontSize: pt(12.5), lineHeight: pt(22), color: col('ink'),
    boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
    textAlign: 'justify', firstLineIndent: em(1.2), indentAfterHeading: false,
    optimalLineBreaking: true, avoidWidows: true, avoidOrphans: true },
  // Restated: any headings object drops the H1 break (gotcha: headings-drop-h1-break).
  headings: { fontFamily: RUQAA, fontWeight: 700, color: col('rubric'), textAlign: 'center',
    levels: [{ level: 1, fontSize: pt(22), lineHeight: pt(32), marginTop: pt(0),
      marginBottom: pt(8), breakBefore: { enabled: true, parity: 'any' } }] },
  headingStyles: [titlePage],
  calloutStyles: [hashiya],
  paragraphStyles: [
    // The matn's bayts: bold and in the rubric, as Ibn ʿAqīl's printers set the Alfiyya.
    { id: 'matn', fontFamily: NASKH, fontWeight: 700, fontSize: pt(12.5),
      lineHeight: pt(23), color: col('rubric'), marginTop: pt(4), marginBottom: pt(6) },
    { id: 'note', fontFamily: NASKH, fontSize: pt(9), lineHeight: pt(13), color: col('muted'),
      boldColor: col('ink'), textAlign: 'justify', firstLineIndent: pt(0), marginTop: pt(10),
      hyphenation: { enabled: true, locale: LANG } },
    { id: 'colophon', fontFamily: NASKH, fontSize: pt(7.5), lineHeight: pt(10),
      color: col('muted'), textAlign: 'left', firstLineIndent: pt(0), marginTop: pt(6) },
  ],
  header, footer: { elements: [] },
});

// ─── 2 · Content ────────────────────────────────────────────────────────────
const markdown = String.raw`---
title: "شرح ابن عقيل"
subtitle: "الكلام وما يتألف منه"
---

# شرح ابن عقيل {style="title" on="على ألفية ابن مالك" margin="وبهامشه حواشٍ على مواضع منه" latin="Ibn ʿAqīl’s commentary on the Alfiyya of Ibn Mālik, with glosses in its margin"}

# الكلام وما يتألف منه

بسم الله الرحمن الرحيم، الحمد لله وحده، وصلاته وسلامه على من لا نبي بعده.

:::verse{style="matn"}
قال محمد هو ابن مالك || أحمد ربي الله خير مالك
مصليا على النبي المصطفى || وآله المستكملين الشرفا
وأستعين الله في ألفيه || مقاصد النحو بها محويه
تقرب الأقصى بلفظ موجز || وتبسط البذل بوعد منجز
وتقتضي رضا بغير سخط || فائقة ألفية ابن معط
وهو بسبق حائز تفضيلا || مستوجب ثنائي الجميلا
والله يقضي بهبات وافره || لي وله في درجات الآخره
:::

:::callout{type="hashiya" span="side"}
**قوله «ابن مالك»:** هو جمال الدين محمد بن عبد الله بن مالك الطائي الجيّاني، وُلد بجيّان من بلاد الأندلس، ونزل دمشق وبها توفي سنة اثنتين وسبعين وستمئة.

**قوله «ألفية ابن معط»:** هي الدرّة الألفية ليحيى بن عبد المعطي الزواوي، المتوفى بالقاهرة سنة ثمان وعشرين وستمئة، وهي أسبق من ألفية ابن مالك، ولذلك قال: «وهو بسبق حائز تفضيلا».
:::

:::verse{style="matn"}
كلامنا لفظ مفيد كاستقم || واسم وفعل ثم حرف الكلم
واحده كلمة والقول عم || وكلمة بها كلام قد يؤم
:::

الكلام المصطلح عليه عند النحاة عبارة عن اللفظ المفيد فائدة يحسن السكوت عليها. فاللفظ جنس يشمل الكلام والكلمة والكلم، ويشمل المهمل كديز والمستعمل كعمرو. ومفيد أخرج المهمل، وفائدة يحسن السكوت عليها أخرج الكلمة وبعض الكلم، وهو ما تركب من ثلاث كلمات فأكثر ولم يحسن السكوت عليه، نحو: إن قام زيد. ولا يتركب الكلام إلا من اسمين، نحو: زيد قائم، أو من فعل واسم، كقام زيد، وكقول المصنف «استقم»، فإنه كلام مركب من فعل أمر وفاعل مستتر، والتقدير: استقم أنت، فاستغنى بالمثال عن أن يقول: فائدة يحسن السكوت عليها، فكأنه قال: الكلام هو اللفظ المفيد فائدة كفائدة استقم.

وإنما قال المصنف «كلامنا» ليُعلم أن التعريف إنما هو للكلام في اصطلاح النحويين لا في اصطلاح اللغويين، وهو في اللغة اسم لكل ما يُتكلم به، مفيدا كان أو غير مفيد.

:::callout{type="hashiya" span="side"}
**قوله «كديز»:** لفظ لا معنى له في كلام العرب، يمثّل به النحاة للمهمل، كما يمثّلون بزيد وعمرو للمستعمل.
:::

والكلم اسم جنس، واحده كلمة، وهي إما اسم وإما فعل وإما حرف، لأنها إن دلت على معنى في نفسها غير مقترنة بزمان فهي الاسم، وإن اقترنت بزمان فهي الفعل، وإن لم تدل على معنى في نفسها بل في غيرها فهي الحرف. والكلم ما تركب من ثلاث كلمات فأكثر، كقولك: إن قام زيد.

والكلمة هي اللفظ الموضوع لمعنى مفرد، فقولنا «الموضوع لمعنى» أخرج المهمل كديز، وقولنا «مفرد» أخرج الكلام، فإنه موضوع لمعنى غير مفرد. ثم ذكر المصنف رحمه الله تعالى أن القول يعم الجميع، والمراد أنه يقع على الكلام أنه قول، ويقع أيضا على الكلم والكلمة أنه قول. ثم ذكر أن الكلمة قد يُقصد بها الكلام، كقولهم في «لا إله إلا الله»: كلمة الإخلاص.

:::verse{style="matn"}
بالجر والتنوين والندا وأل || ومسند للاسم تمييز حصل
:::

ذكر المصنف رحمه الله تعالى في هذا البيت علامات الاسم. فمنها الجر، وهو يشمل الجر بالحرف والإضافة والتبعية، نحو: مررت بغلام زيد الفاضل، فالغلام مجرور بالحرف، وزيد مجرور بالإضافة، والفاضل مجرور بالتبعية. وهو أشمل من قول غيره «بحرف الجر»، لأن هذا لا يتناول الجر بالإضافة ولا الجر بالتبعية.

ومنها التنوين، وهو على أربعة أقسام: تنوين التمكين، وهو اللاحق للأسماء المعربة كزيد ورجل. وتنوين التنكير، وهو اللاحق للأسماء المبنية فرقا بين معرفتها ونكرتها، نحو: مررت بسيبويه وبسيبويهٍ آخر. وتنوين المقابلة، وهو اللاحق لجمع المؤنث السالم، نحو: مسلمات، فإنه في مقابلة النون في جمع المذكر السالم كمسلمين. وتنوين العوض، وهو على ثلاثة أقسام: عوض عن جملة، وهو الذي يلحق «إذ» عوضا عن جملة تكون بعدها، كقوله تعالى: ﴿وَأَنتُمْ حِينَئِذٍ تَنظُرُونَ﴾، أي حين إذ بلغت الروح الحلقوم، فحذف «بلغت الروح الحلقوم» وأتى بالتنوين عوضا عنه.

:::callout{type="hashiya" span="side"}
**قوله ﴿وأنتم حينئذ تنظرون﴾:** من سورة الواقعة، الآية الرابعة والثمانون، وقبلها: ﴿فَلَوْلَا إِذَا بَلَغَتِ الْحُلْقُومَ﴾، فمنها قدّر الشارح الجملة المحذوفة.

**قوله «سيبويه»:** هو أبو بشر عمرو بن عثمان بن قنبر، إمام البصريين وصاحب الكتاب، توفي نحو سنة ثمانين ومئة.
:::

وقسم يكون عوضا عن اسم، وهو اللاحق لكل عوضا عما تضاف إليه، نحو: كلٌّ قائم، أي كل إنسان قائم، فحذف إنسان وأتى بالتنوين عوضا عنه. وقسم يكون عوضا عن حرف، وهو اللاحق لجوار وغواش ونحوهما رفعا وجرا، نحو: هؤلاء جوارٍ، ومررت بجوارٍ، فحذفت الياء وأتي بالتنوين عوضا عنها.

وتنوين الترنم، وهو الذي يلحق القوافي المطلقة بحرف علة، كقوله:

:::verse{style="matn"}
أقلّي اللوم عاذل والعتابن || وقولي إن أصبت لقد أصابن
:::

فجيء بالتنوين بدلا من الألف لأجل الترنم.

:::callout{type="hashiya" span="side"}
**قوله «كقوله»:** البيت لجرير من قصيدة يهجو بها الراعي النميري، والقافية فيه «والعتابا… أصابا»، فأبدل التنوين من ألف الإطلاق.
:::

وظاهر كلام المصنف أن التنوين كله من خواص الاسم، وليس كذلك، بل الذي يختص به الاسم إنما هو تنوين التمكين والتنكير والمقابلة والعوض، وأما تنوين الترنم فيكون في الاسم والفعل والحرف. ومن خواص الاسم النداء، نحو: يا زيد، والألف واللام، نحو: الرجل، والإسناد إليه، نحو: زيد قائم. فمعنى البيت: حصل للاسم تمييز عن الفعل والحرف بالجر والتنوين والنداء والألف واللام والإسناد إليه، أي الإخبار عنه.

واستعمل المصنف «أل» مكان الألف واللام، وقد وقع ذلك في عبارة بعض المتقدمين، وهو الخليل، واستعمل «مسند» مكان الإسناد له.

:::callout{type="hashiya" span="side"}
**قوله «وهو الخليل»:** الخليل بن أحمد الفراهيدي البصري، شيخ سيبويه وواضع علم العروض، توفي بالبصرة سنة سبعين ومئة، وقيل غير ذلك.
:::

:::verse{style="matn"}
بتا فعلت وأتت ويا افعلي || ونون أقبلن فعل ينجلي
:::

ثم ذكر المصنف أن الفعل يمتاز عن الاسم والحرف بتاء فعلت، والمراد بها تاء الفاعل، وهي المضمومة للمتكلم نحو: فعلتُ، والمفتوحة للمخاطب نحو: تباركتَ، والمكسورة للمخاطبة نحو: فعلتِ. ويمتاز أيضا بتاء أتت، والمراد بها تاء التأنيث الساكنة، نحو: نعمت وبئست، فاحترزنا بالساكنة عن اللاحقة للأسماء، فإنها تكون متحركة بحركة الإعراب، نحو: هذه مسلمةٌ، ورأيت مسلمةً، ومررت بمسلمةٍ.

ويمتاز أيضا بياء افعلي، والمراد بها ياء الفاعلة، وتلحق فعل الأمر نحو: اضربي، والفعل المضارع نحو: تضربين، ولا تلحق الماضي. ومما يميز الفعل نون أقبلن، والمراد بها نون التوكيد، خفيفة كانت أو ثقيلة، فالخفيفة نحو قوله تعالى: ﴿لَنَسْفَعًا بِالنَّاصِيَةِ﴾، والثقيلة نحو قوله تعالى: ﴿لَنُخْرِجَنَّكَ يَا شُعَيْبُ﴾. فمعنى البيت: ينجلي الفعل بتاء الفاعل وتاء التأنيث الساكنة وياء الفاعلة ونون التوكيد.

:::callout{type="hashiya" span="side"}
**قوله ﴿لنسفعا بالناصية﴾:** من سورة العلق، الآية الخامسة عشرة، وتُكتب النون الخفيفة فيها ألفا في المصحف.

**قوله ﴿لنخرجنك يا شعيب﴾:** من سورة الأعراف، الآية الثامنة والثمانين، من قول الملأ الذين استكبروا من قوم شعيب.
:::

:::paragraphs{style="note" dir=ltr}
**A note on the text.** Ibn ʿAqīl (d. 1367) on the opening of Ibn Mālik’s Alfiyya, from ar.wikisource, without the modern editor’s footnotes and two passages on the tanwīn of rhyme; punctuation added, a few typing slips corrected. The glosses in the margin are written for this page, each opening with the words it explains, as a Bulaq ḥāshiya does.
:::

:::paragraphs{style="colophon" dir=ltr}
Set in Amiri and Aref Ruqaa (SIL OFL) · Text: Ibn ʿAqīl and Ibn Mālik, public domain, from ar.wikisource · Glosses: Postext Cookbook
:::
`; // content.<lang>.md, inlined by the Cookbook

// ─── 3 · Fonts ──────────────────────────────────────────────────────────────
const FONTS = { // every face the pages use, loaded before the build (gotcha: fonts-first)
  Amiri: ['400', '400i', '700'], // NASKH: text, matn, glosses; the Latin lines
  'Aref Ruqaa': ['700'], // RUQAA: the title page and the chapter title
};

// ─── 4 · Build & show ───────────────────────────────────────────────────────
await loadFonts(FONTS, markdown);
// The arabic file of each face, which loadFonts leaves out (gotcha: arabic-fonts-subset).
await loadArabicFonts(FONTS, markdown);
const doc = await buildWithFonts(() => buildDocument({ markdown }, config()), markdown);
showBook(doc, { title: t({ en: 'A Bulaq page', es: 'Una página de Bulaq' }) });
offerPdf(() => renderToPdf(doc, { fontProvider: arabicPdfProvider }), `${RECIPE}.pdf`);

// ─── Kit ── helpers shared by every Cookbook recipe · postext.dev/cookbook ─────

// ─── Kit · core v1 ── the same in every recipe · postext.dev/cookbook ─────────
function mm(value) { return { value, unit: 'mm' }; }
function pt(value) { return { value, unit: 'pt' }; }
function em(value) { return { value, unit: 'em' }; }
/** The sample language's string: t({ en: 'Figure', es: 'Figura' }). */
function t(strings) { return strings[LANG] ?? Object.values(strings)[0]; }
/** A file in this recipe's assets folder, served from the Postext repo by jsDelivr. */
function asset(file) { return `https://cdn.jsdelivr.net/gh/drnachio/postext@main/cookbook/${RECIPE}/assets/${file}`; }

// ─── Kit · fonts v1 ── the same in every recipe · postext.dev/cookbook ────────
// Postext measures text with the faces the browser has loaded, and caches the
// widths, so every face must be ready before the first build. Faces come from
// Fontsource: the same static files the PDF embeds, so screen and PDF agree.

/** faces = { 'Family Name': ['400', '400i', '700'] }. `text` is the sample:
 *  letters beyond Latin-1 (č, ł, ő…) also load the latin-ext files. With
 *  `optional`, a face Fontsource does not ship is skipped instead of failing.
 *  Resolves to the number of faces added. */
async function loadFonts(faces, text = '', { optional = false } = {}) {
  kitStatus('Loading fonts…');
  const ranges = {
    latin: 'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,'
      + 'U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD',
    'latin-ext': 'U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,'
      + 'U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF',
  };
  const subsets = /[Ā-˿Ḁ-ỿ]/.test(text) ? ['latin', 'latin-ext'] : ['latin'];
  const jobs = [];
  let added = 0;
  for (const [family, specs] of Object.entries(faces)) {
    const id = fontsourceId(family);
    const meta = optional ? await fontsourceMeta(family) : null;
    for (const spec of new Set(specs)) {
      const weight = parseInt(spec, 10);
      const style = spec.endsWith('i') ? 'italic' : 'normal';
      if (hasFace(family, weight, style)) continue;
      if (optional && !(meta?.weights.includes(weight) && meta.styles.includes(style))) continue;
      for (const subset of subsets) {
        const url = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-${subset}-${weight}-${style}.woff2`;
        const face = new FontFace(family, `url(${url}) format('woff2')`,
          { weight: String(weight), style, unicodeRange: ranges[subset] });
        jobs.push(face.load().then((ready) => { document.fonts.add(ready); added++; }, () => {
          if (subset === 'latin' && !optional) throw new Error(`Fontsource has no ${family} ${weight} ${style}`);
        }));
      }
    }
  }
  await Promise.all(jobs).catch((error) => { kitFail(error); throw error; });
  return added;
}

/** Runs `build` (a buildDocument or buildBundle call) and checks the faces
 *  the pages use. A regular face missing from FONTS is loaded with a warning;
 *  bold and italic variants are loaded when the family ships them. Then the
 *  measurement caches are cleared and the build runs again. */
async function buildWithFonts(build, text = '') {
  const tried = new Set();
  for (let round = 0; round < 3; round++) {
    kitStatus('Laying out…');
    await new Promise(requestAnimationFrame);          // let the status paint first
    const result = await Promise.resolve().then(build).catch((error) => { kitFail(error); throw error; });
    const wanted = { base: {}, variants: {} };
    for (const { font, base } of [result].flat().flatMap(fontStringsOf)) {
      const { family, weight, style } = parseFont(font);
      const key = `${family}|${weight}|${style}`;
      if (tried.has(key) || hasFace(family, weight, style)) continue;
      tried.add(key);
      (wanted[base ? 'base' : 'variants'][family] ??= []).push(`${weight}${style === 'italic' ? 'i' : ''}`);
    }
    if (Object.keys(wanted.base).length) {
      console.warn(`[cookbook] FONTS does not list ${JSON.stringify(wanted.base)}: loading them.`);
    }
    const added = await loadFonts(wanted.base, text) + await loadFonts(wanted.variants, text, { optional: true });
    if (added === 0) return result;
    clearMeasurementCache();
  }
  throw new Error('The fonts did not settle after three builds.');
}

/** Every font string of the layout. `base` marks a block's own face; its
 *  bold, italic and bold-italic variants are listed whether or not used. */
function fontStringsOf(doc) {
  const found = new Map();
  const walk = (node) => {
    if (!node || typeof node !== 'object') return;
    if (Array.isArray(node)) { node.forEach(walk); return; }
    for (const [key, value] of Object.entries(node)) {
      if (typeof value === 'string' && /fontString$/i.test(key)) {
        found.set(value, found.get(value) || key === 'fontString');
      } else if (value && typeof value === 'object') walk(value);
    }
  };
  walk(doc.pages);
  walk(doc.blocks);
  return [...found].map(([font, base]) => ({ font, base }));
}

/** '700 37.5px Open Sans' / 'italic 400 13px "Source Serif 4"' → { family, weight, style }.
 *  A string with no weight ('95.8px Young Serif', from a design text) is 400. */
function parseFont(font) {
  const m = /^(?:(italic|oblique)\s+)?(?:small-caps\s+)?(?:(\d+|bold|normal)\s+)?[\d.]+px\s+(.+)$/.exec(font.trim());
  if (!m) throw new Error(`Unexpected font string: ${font}`);
  const weight = m[2] === 'bold' ? 700 : !m[2] || m[2] === 'normal' ? 400 : Number(m[2]);
  return { family: m[3].replace(/^["']|["']$/g, ''), weight, style: m[1] ? 'italic' : 'normal' };
}

/** True when a loaded FontFace covers exactly this family, weight and style
 *  (document.fonts.check() is also true for families nobody declared). */
function hasFace(family, weight, style) {
  for (const face of document.fonts) {
    if (face.status !== 'loaded' || face.style !== style) continue;
    if (face.family.replace(/^["']|["']$/g, '') !== family) continue;
    const [low, high = low] = face.weight.split(' ').map(Number);
    if (weight >= low && weight <= high) return true;
  }
  return false;
}

/** Fontsource's id for a family: 'Source Serif 4' → 'source-serif-4'. */
function fontsourceId(family) { return family.toLowerCase().replace(/\s+/g, '-'); }

/** The weights and styles a family ships ({ weights: [400, 700], styles: ['normal', 'italic'] }), or null. */
function fontsourceMeta(family) {
  fontsourceMeta.cache ??= new Map();
  const id = fontsourceId(family);
  if (!fontsourceMeta.cache.has(id)) {
    fontsourceMeta.cache.set(id, fetch(`https://api.fontsource.org/v1/fonts/${id}`)
      .then((res) => (res.ok ? res.json() : null), () => null));
  }
  return fontsourceMeta.cache.get(id);
}

// ─── Kit · viewer v1 ── the same in every recipe · postext.dev/cookbook ───────
/** Shows the pages as facing spreads on a dark desk: the first page is a
 *  recto on its own, then verso | recto pairs, as in a bound book. Pages
 *  are painted when they scroll near the screen. */
function showPages(docs, { title, width = 460 } = {}) {
  const root = viewer(title);
  const pages = [docs].flat().flatMap((doc) =>
    doc.pages.map((page) => ({ doc, page, n: (doc.pageIndexOffset ?? 0) + page.index })));
  const spreads = [];
  let verso = null;
  for (const p of pages) {
    if (p.n % 2 === 1) { if (verso) spreads.push([verso, null]); verso = p; }
    else { spreads.push([verso, p]); verso = null; }
  }
  if (verso) spreads.push([verso, null]);
  const density = Math.min(window.devicePixelRatio || 1, 2);
  showPages.painter?.disconnect();
  const painter = new IntersectionObserver((entries) => {
    for (const { isIntersecting, target } of entries) {
      if (!isIntersecting) continue;
      painter.unobserve(target);
      const { doc, page } = target.postext;
      renderPageToCanvas(page, doc, target, { scale: (width * density) / page.width });
    }
  }, { rootMargin: '800px' });
  showPages.painter = painter;
  root.replaceChildren(...spreads.map((pair) => {
    const spread = document.createElement('div');
    spread.className = 'pt-spread';
    for (const p of pair) {
      const figure = document.createElement('figure');
      if (p) {
        const label = p.page.pageLabel || String(p.n + 1);
        const canvas = document.createElement('canvas');
        canvas.postext = p;
        canvas.style.aspectRatio = `${p.page.width} / ${p.page.height}`;
        canvas.setAttribute('role', 'img');
        canvas.setAttribute('aria-label', `Page ${label}`);
        const folio = document.createElement('figcaption');
        folio.textContent = label;
        figure.append(canvas, folio);
        painter.observe(canvas);
      } else figure.className = 'pt-blank';
      spread.append(figure);
    }
    return spread;
  }));
  kitStatus(`${pages.length} ${pages.length === 1 ? 'page' : 'pages'}`);
  document.documentElement.dataset.postext = 'ready';
  return pages.length;
}

/** The desk, the bar and the error reporting, created once. */
function viewer(title) {
  if (!document.getElementById('pt-kit')) {
    document.head.insertAdjacentHTML('beforeend', `<style id="pt-kit">
      :root { color-scheme: dark; }
      body { margin: 0; background: #0e1014; color: #b9bcc4; font: 13px/1.45 system-ui, sans-serif; }
      #pt-bar { position: sticky; top: 0; z-index: 1; display: flex; flex-wrap: wrap; align-items: center;
        gap: 6px 16px; padding: 10px 16px; background: rgb(14 16 20 / .92); backdrop-filter: blur(6px);
        border-bottom: 1px solid #23262d; }
      #pt-bar strong { color: #f4f1ea; font-weight: 600; }
      #pt-actions { display: flex; gap: 12px; margin-left: auto; }
      #pt-actions a, #pt-actions button { color: #d8a21a; font: inherit; background: none; border: 0; padding: 0; cursor: pointer; }
      #pages { display: grid; justify-items: center; gap: 48px; padding: 32px 16px 72px; }
      .pt-spread { display: flex; }
      .pt-spread figure { margin: 0; width: min(460px, 44vw); }
      .pt-spread canvas { display: block; width: 100%; background: #fff;
        box-shadow: 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
      .pt-spread figure:first-child canvas { box-shadow: inset -14px 0 14px -14px rgb(0 0 0 / .18), 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
      .pt-spread figcaption { margin-top: 10px; text-align: center; font: 600 10px/1 system-ui, sans-serif;
        letter-spacing: .18em; text-transform: uppercase; color: #6c7079; }
      .pt-blank { visibility: hidden; }
      @media (max-width: 760px) {
        .pt-spread { flex-direction: column; gap: 32px; }
        .pt-spread figure { width: min(460px, 92vw); }
        .pt-blank { display: none; }
      }
    </style>`);
    document.body.insertAdjacentHTML('afterbegin',
      '<header id="pt-bar"><strong id="pt-title"></strong><span id="pt-status" role="status"></span><span id="pt-actions"></span></header>');
    document.getElementById('pt-title').textContent = document.title || 'Postext';
    addEventListener('error', (event) => kitFail(event.error ?? event.message));
    addEventListener('unhandledrejection', (event) => kitFail(event.reason));
  }
  if (title) document.getElementById('pt-title').textContent = title;
  return document.getElementById('pages')
    ?? document.body.appendChild(Object.assign(document.createElement('main'), { id: 'pages' }));
}

function kitStatus(text) {
  viewer();
  document.getElementById('pt-status').textContent = text;
}

function kitFail(error) {
  document.documentElement.dataset.postext = 'error';
  kitStatus(`Error: ${error?.message ?? error}`);
}

// ─── Kit · pdf v1 ── the same in every recipe that exports a PDF ──────────────
/** postext-pdf embeds TrueType bytes. Fetch the Fontsource file the screen
 *  used, snapping to a weight the family ships and falling back to upright
 *  when it has no italic: the PDF asks for every face a block could use. */
async function fontsourceProvider(family, weight, style) {
  const id = fontsourceId(family);
  const meta = await fontsourceMeta(family);
  const weights = meta?.weights?.length ? meta.weights : [400, 700];
  const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a));
  const s = style === 'italic' && meta && !meta.styles.includes('italic') ? 'normal' : style;
  const res = await fetch(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-${w}-${s}.woff2`);
  if (!res.ok) throw new Error(`Fontsource has no ${family} ${w} ${s} (${res.status})`);
  return decompressWoff2(new Uint8Array(await res.arrayBuffer()));
}

/** A "Build the PDF" button in the bar. Once built: "Open the PDF" (a new
 *  tab, since CodePen's preview frame cannot show PDFs) and a download link. */
function offerPdf(makePdf, filename) {
  viewer();
  const button = Object.assign(document.createElement('button'), { type: 'button', textContent: 'Build the PDF' });
  button.dataset.postextPdf = filename;
  button.addEventListener('click', async () => {
    button.disabled = true;
    button.textContent = 'Building the PDF…';
    try {
      const bytes = await makePdf();
      const url = URL.createObjectURL(new Blob([bytes], { type: 'application/pdf' }));
      const size = `${Math.max(1, Math.round(bytes.length / 1024))} KB`;
      button.replaceWith(
        Object.assign(document.createElement('a'), { href: url, target: '_blank', rel: 'noopener', textContent: 'Open the PDF ↗' }),
        Object.assign(document.createElement('a'), { href: url, download: filename, textContent: `Download ${filename} · ${size}` }));
    } catch (error) {
      button.disabled = false;
      button.textContent = 'Build the PDF';
      kitFail(error);
    }
  });
  document.getElementById('pt-actions').append(button);
}

// ─── Kit · arabic v1 ── Arabic-script faces · postext.dev/cookbook ───────────
// Fontsource ships an Arabic family as one file per subset and weight: the
// `arabic` file holds the letters, the harakat, the Arabic-Indic digits, the
// Arabic punctuation and the presentation forms; `latin` and `latin-ext`
// hold the rest. loadFonts loads the latin files; this block adds the arabic
// file of every Arabic family, for the canvas and for the PDF, which shapes
// the letters with HarfBuzz from the same bytes.

/** The code points of Fontsource's `arabic` subset, as its stylesheets
 *  declare them (the same unicode-range the browser picks the file by). A
 *  function, not a const: the kit is inlined after the recipe's top-level
 *  awaits, and a const read before its line throws, where a function
 *  declaration is hoisted. */
function arabicRange() {
  return 'U+0600-06FF,U+0750-077F,U+0870-088E,U+0890-0891,U+0897-08E1,U+08E3-08FF,'
    + 'U+200C-200E,U+2010-2011,U+204F,U+2E41,U+FB50-FDFF,U+FE70-FE74,U+FE76-FEFC,U+102E0-102FB,'
    + 'U+10E60-10E7E,U+10EC2-10EC4,U+10EFC-10EFF,U+1EE00-1EEFF';
}

/** Whether code point `cp` is in the arabic file. */
function inArabicRange(cp) {
  inArabicRange.ranges ??= arabicRange().split(',').map((part) => {
    const [lo, hi = lo] = part.slice(2).split('-');
    return [parseInt(lo, 16), parseInt(hi, 16)];
  });
  return inArabicRange.ranges.some(([lo, hi]) => cp >= lo && cp <= hi);
}

/** Whether Fontsource serves `family` with an `arabic` subset. Fails when
 *  the API does not answer: an Arabic face taken for a Latin one would set
 *  its letters in a system face. */
async function isArabicFamily(family) {
  const meta = await fontsourceMeta(family);
  if (!meta) throw new Error(`api.fontsource.org did not describe ${family}: reload to try again`);
  return !!meta.subsets?.includes('arabic');
}

/** The arabic file of a face. */
function arabicFileUrl(family, weight, style) {
  const id = fontsourceId(family);
  return `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-arabic-${weight}-${style}.woff2`;
}

/** faces = { Amiri: ['400', '700'] }, as for loadFonts, after it: the whole
 *  FONTS object may be passed, its families without an arabic subset are
 *  left alone. Adds the arabic file of every listed weight of each Arabic
 *  family (the latin files come from loadFonts) and loads it. `text` is
 *  the sample: fails when it holds an Arabic-script character the arabic
 *  file does not cover. List every weight the pages set in Arabic: a weight
 *  left to buildWithFonts gets the latin file only, and its Arabic letters
 *  fall back to a system face. Resolves to the number of files loaded. */
async function loadArabicFonts(faces, text = '') {
  kitStatus('Loading fonts…');
  let loaded = 0;
  try {
    const outside = [...new Set(text)].filter((ch) => /\p{Script=Arabic}/u.test(ch) && !inArabicRange(ch.codePointAt(0)));
    if (outside.length) throw new Error(`Fontsource's arabic files have no ${outside.slice(0, 12).join(' ')}`);
    for (const [family, specs] of Object.entries(faces)) {
      if (!(await isArabicFamily(family))) continue;
      for (const spec of new Set(specs)) {
        const weight = parseInt(spec, 10);
        const style = spec.endsWith('i') ? 'italic' : 'normal';
        const face = new FontFace(family, `url(${arabicFileUrl(family, weight, style)}) format('woff2')`,
          { weight: String(weight), style, unicodeRange: arabicRange() });
        document.fonts.add(await face.load().catch(() => {
          throw new Error(`Fontsource has no arabic file for ${family} ${weight} ${style}`);
        }));
        loaded++;
      }
    }
  } catch (error) {
    kitFail(error);
    throw error;
  }
  return loaded;
}

/** The PDF font provider for recipes with Arabic faces: a family with an
 *  arabic subset gets its arabic file when its pages set Arabic letters
 *  (`request.codePoints`), then its latin file, and its latin-ext file for
 *  the letters beyond latin (transliteration: ā ḥ ʿ). The arabic file comes
 *  first: it also holds the space and the brackets, so a line of Arabic is
 *  shaped as one run and not cut at every space. Any other family goes to
 *  fontsourceProvider (the "pdf" block). */
async function arabicPdfProvider(family, weight, style, request) {
  if (!(await isArabicFamily(family))) return fontsourceProvider(family, weight, style);
  const meta = await fontsourceMeta(family);
  const weights = meta.weights?.length ? meta.weights : [400, 700];
  const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a));
  const s = style === 'italic' && !meta.styles.includes('italic') ? 'normal' : style;
  const wanted = [...(request?.codePoints ?? [])];
  const id = fontsourceId(family);
  const urls = [];
  if (!wanted.length || wanted.some(inArabicRange)) urls.push(arabicFileUrl(family, w, s));
  urls.push(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-${w}-${s}.woff2`);
  if (meta.subsets.includes('latin-ext') && wanted.some((cp) => /[Ā-˿Ḁ-ỿ]/u.test(String.fromCodePoint(cp)))) {
    urls.push(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-ext-${w}-${s}.woff2`);
  }
  return Promise.all(urls.map(async (url) => {
    const res = await fetch(url);
    if (!res.ok) throw new Error(`Fontsource file ${url} (${res.status})`);
    return decompressWoff2(new Uint8Array(await res.arrayBuffer()));
  }));
}

// ─── Kit · book v1 ── books bound on either edge · postext.dev/cookbook ──────
// A book bound on the right (Arabic, Hebrew or Persian text, vertical
// Chinese, or page.binding 'right') opens from what a Latin reader calls
// the back: page 1 lies alone on the left of the spine, then [3 | 2].

/** showPages for a book bound on either edge. A right-bound book (the
 *  document says so: doc.binding is 'right' for page.binding 'right', for
 *  text that runs right to left and for vertical text, when the binding is
 *  left to 'auto') lies on the desk as it opens: page 1 alone on the left
 *  of the spine, then [3 | 2], the spine shade on each page's inner edge.
 *  `binding` ('left' | 'right') overrides the document's. */
function showBook(docs, { binding, ...options } = {}) {
  const count = showPages(docs, options);
  const right = (binding ?? [docs].flat()[0]?.binding) === 'right';
  if (!document.getElementById('pt-kit-book')) {
    // The pages keep direction ltr, as in a left-bound book: a canvas takes
    // the direction its element inherits, and under the spread's rtl a run
    // painted for an ltr canvas would end where the engine starts it.
    document.head.insertAdjacentHTML('beforeend', `<style id="pt-kit-book">
      .pt-spread[dir="rtl"] canvas { direction: ltr; }
      .pt-spread[dir="rtl"] figure:first-child canvas { box-shadow: inset 14px 0 14px -14px rgb(0 0 0 / .18),
        0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
    </style>`);
  }
  // Each pair stays [verso, recto] in the page; right to left, the verso
  // sits on the right. Phones stack the pages in reading order either way.
  for (const spread of document.querySelectorAll('#pages > .pt-spread')) spread.dir = right ? 'rtl' : 'ltr';
  document.getElementById('pages').dataset.binding = right ? 'right' : 'left';
  return count;
}

// ─── /Kit ───────────────────────────────────────────────────────────────────────
```

## Variations

### Put the commentary on the inner side

Some presses set the ḥāshiya by the spine, so the text keeps the wider outer margin.

```diff
-const layout = { layoutType: 'oneAndHalf', sideColumnRole: 'floats', sideColumnSide: 'outer',
+const layout = { layoutType: 'oneAndHalf', sideColumnRole: 'floats', sideColumnSide: 'inner',
```

### Box each gloss

A thin rule round each gloss, as some later Cairo prints have, is the callout’s own border.

```diff
-  stripe: { enabled: false }, border: { enabled: false },
+  stripe: { enabled: false }, border: { enabled: true, width: pt(0.4), color: col('rule') },
```

## Pitfalls

- **Tag an Arabic book 'ar', not with LANG.** A recipe's editions are en and es, but an Arabic sample is Arabic in both: `locale: LANG` would set it left to right, bind it on the left, number its pages 1 2 3 and caption its figures Figure or Figura. Write the tag yourself: 'ar' (Arabic-Indic digits, the Mashriq convention), a region such as 'ar-EG' or 'ar-SA', or 'ar-MA', 'ar-DZ' or 'ar-TN' for a Maghreb edition with European digits. A Latin page that only quotes Arabic keeps its own locale.
- **Arabic faces need their arabic file, through the arabic block.** Fontsource serves Amiri, Noto Naskh Arabic or Scheherazade New as one file per subset, and the Arabic letters are in the arabic file. loadFonts fetches only latin (and latin-ext), so on screen the Arabic comes from a system face and measures wrong, and fontsourceProvider hands the PDF that latin file, which prints empty boxes. List the arabic kit block, call loadArabicFonts(FONTS, markdown) after loadFonts, with every weight the pages set in Arabic listed in FONTS, and give renderToPdf fontProvider: arabicPdfProvider.
- **Any headings object switches off the H1 page break.** By default an H1 breaks to a recto (always-odd), but passing any headings object resets that default, so chapters run on and span: 'page' does nothing. Restate headings.levels[0].breakBefore: { enabled: true, parity } in every config.
- **Load every face before layout.** Layout measures text with the faces the browser has loaded and caches the widths, so a face that arrives after the first build leaves wrong line breaks and a PDF that no longer matches the screen. Load every weight and style first, and call clearMeasurementCache() before rebuilding when one arrives late.

## Credits

- Recipe: Ignacio Ferro ([@drnachio](https://github.com/drnachio))
- Text: Ibn ʿAqīl’s commentary on the opening of the Alfiyya, with Ibn Mālik’s verses, as ar.wikisource gives it (revision 521625), without the modern editor’s footnotes: Ibn ʿAqīl, Ibn Mālik ([source](https://ar.wikisource.org/wiki/شرح_ابن_عقيل/المجلد_الأول/الكلام_وما_يتألف_منه)), public domain
- Text: The glosses in the margin, the title page, the note on the text and the colophon: Postext Cookbook, original
- Type: Amiri (OFL-1.1), Aref Ruqaa (OFL-1.1)
- Code: MIT · Sample content: MIT

## Related

- [Nº 110 · A qasida on a diwan page, each line in two hemistichs](https://postext.dev/en/cookbook/qasida-diwan-page.md): One :::verse block sets al-Mutanabbī’s forty-six bayts in two columns of hemistichs, each half stretched with kashidas to one width. · Level 2 (Intermediate) · Poetry
- [Nº 001 · Textbook with a margin column](https://postext.dev/en/cookbook/textbook-margin-column.md): A column-and-a-half page whose outer column holds only floats: span 'side' figures and glosses stack there, and captionSide moves the other captions into it. · Level 3 (Advanced) · Textbooks
- [Nº 032 · Annotated classic with margin glosses](https://postext.dev/en/cookbook/annotated-classic-glosses.md): Alice’s mad tea-party as an annotated edition: green and red glosses in the outer margin, beside the lines they explain, each called by a letter in its colour. · Level 3 (Advanced) · Fiction, drama & literary prose