# 带脚注、引文和索引的阿拉伯文论文

> 阿拉伯文期刊论文：脚注«(١)»按页编号，按阿拉伯语区域设置排出的CSL引文与脚注同列，索引排序时忽略冠词ال。

- HTML版本: https://postext.dev/zh/cookbook/arabic-research-article
- 食谱 No. 107 · 图书结构 · 难度 3 (高级) · 输出: Canvas, PDF
- 体裁: 论文与学术出版物
- 需要 postext ≥ 1.15.0, postext-pdf ≥ 1.15.0 · 已用 1.15.0, postext-pdf 1.15.0 测试，日期 2026-10-04
- 页面: [٨٧](https://postext.dev/cookbook/arabic-research-article/en/p01.webp?v=47b8aa2d), [٨٨](https://postext.dev/cookbook/arabic-research-article/en/p02.webp?v=47b8aa2d), [٨٩](https://postext.dev/cookbook/arabic-research-article/en/p03.webp?v=47b8aa2d), [٩٠](https://postext.dev/cookbook/arabic-research-article/en/p04.webp?v=47b8aa2d), [٩١](https://postext.dev/cookbook/arabic-research-article/en/p05.webp?v=47b8aa2d)
- PDF: https://postext.dev/cookbook/arabic-research-article/en/arabic-research-article.pdf?v=47b8aa2d
- 在沙盒中打开: https://postext.dev/zh/sandbox#recipe=arabic-research-article&lang=en (.postext: https://postext.dev/cookbook/arabic-research-article/en/arabic-research-article.postext)
- 最后更新: 2026-10-04
- 其他语言: [en](https://postext.dev/en/cookbook/arabic-research-article.md), [es](https://postext.dev/es/cookbook/arabic-research-article.md), [ca](https://postext.dev/ca/cookbook/arabic-research-article.md), [ar](https://postext.dev/ar/cookbook/arabic-research-article.md)

## 简单来说

一份阿拉伯文学术期刊的五页：论文、脚注、参考文献和索引。索引像阿拉伯文索引那样把الكشيدة排在ك下，而不是冠词ال下。

## 成品一览

一份虚构阿拉伯文期刊某一期中的五页，开本17 × 24 cm，从第87页开始：一篇研究卡希达两端对齐是否会减慢阅读的论文，正文用12 pt的Amiri，小节标题用Noto Kufi Arabic。脚注排在每页底部，按阿拉伯期刊的习惯每页从«(١)»重新编号；在Markdown里写作`[@ayalon2016]`的引文也是脚注，用芝加哥注释体和阿拉伯语CSL区域设置排出。后面是参考文献，阿拉伯文著作在前，最后是两栏索引。索引把الكشيدة排在ك下，把الصحف اليومية排在ص下：冠词ال不计入排序。[采用芝加哥注释的历史论文](https://postext.dev/zh/cookbook/history-essay-chicago-notes.md)用英文做了同样的事。

**这份食谱回答的问题:**

- 阿拉伯文文章怎样用脚注和参考文献引用来源？
- 阿拉伯文文章怎样用脚注和参考文献引用来源？

## 简短回答

```js
// script.js, 行 35–58
// Citations are written [@ayalon2016, 45] in the text; a note style puts each one in a
// footnote, numbered with the author's own [^notes]. The CSL locale is Arabic: ص for a page.
registerCitationEngine(createCiteprocEngine({ styles: STYLES, locales: LOCALES }));
const citations = {
  style: 'chicago-notes-bibliography', notes: 'footnote', locale: 'ar',
  bibliography: { fontSize: em(0.9), lineHeight: pt(17), hangingIndent: em(2),
    entrySpacing: pt(2) },
};
const footnotes = {
  markerTemplate: '({n})', // «(١)», in the document's digits
  numbering: 'page', // from (١) again on every page, as Arabic journals number them
  noteNumberPosition: 'inline', // the note opens with (١) on the line, not raised
  fontSize: pt(10), lineHeight: pt(18), spaceBetween: pt(2), // 1.8 ×: tanwīn clears the line
  textAlign: 'start', // ragged from the right: a Latin title would open wide gaps
  separator: { width: 0.3, lineWidth: pt(0.5), color: col('red') }, // on the start side
};
// The index sorts by the word after the article: الكشيدة files under ك, not under ا.
// ignoreArticle is already true for an Arabic index; it is written out to be seen.
const index = {
  ignoreArticle: true,
  fontFamily: TEXT, fontSize: pt(10.5), lineHeight: pt(16), indent: em(1.2),
  main: { bold: true }, // the page that defines the term
  groups: { fontFamily: LABEL, fontSize: pt(10), fontWeight: 700, color: col('red') },
};
```

## 用料

**讲解**

- [以阿拉伯文为文档语言](https://postext.dev/zh/docs/arabic-layout.md#开始一本阿拉伯文书): locale设为'ar'（可带任意地区）时，题注和续表字样使用阿拉伯文（شكل، جدول، يتبع），日期用阿拉伯文写出，引文使用CSL阿拉伯文区域设置，索引按阿拉伯文排序，并且不断词。
- [索引排序忽略冠词](https://postext.dev/zh/docs/configuration.md#索引): index.ignoreArticle（阿拉伯文默认开启）在排序和分组时忽略冠词ال：البصرة归入ب，排在بدر和بغداد之间，印出时保持原样；hamza和alif的各种形式一起排序。
- [注释体引用](https://postext.dev/zh/docs/document-format.md#引用与参考文献): 注释体样式（芝加哥注释体、OSCOLA、GB/T 7714注释）把每条引用排成脚注，后续引用用简略形式，中文也可排成行内双行夹注。

**还用到**

- [脚注](https://postext.dev/zh/docs/document-format.md#脚注)
- [按引用样式排的引用](https://postext.dev/zh/docs/document-format.md#引用与参考文献)
- [由参考文献数据生成的文献表](https://postext.dev/zh/docs/document-format.md#引用与参考文献)
- [索引](https://postext.dev/zh/docs/document-format.md#索引)
- [从右向左的文字](https://postext.dev/zh/docs/arabic-layout.md#文字方向与双向算法)
- [阿拉伯文字体](https://postext.dev/zh/docs/arabic-layout.md#字体)
- [生成数字所用的数码](https://postext.dev/zh/docs/configuration.md#文档语言)
- [编号标题](https://postext.dev/zh/docs/configuration.md#按级别覆盖)
- [标题样式](https://postext.dev/zh/docs/configuration.md#标题样式)
- [设计过的章首页](https://postext.dev/zh/docs/configuration.md#通栏与高级设计)
- [书眉与页码](https://postext.dev/zh/docs/configuration.md#页眉与页脚)
- [标注框](https://postext.dev/zh/docs/configuration.md#标注框样式)
- [导出PDF](https://postext.dev/zh/docs/configuration.md#生成pdf)
- [反方向的段落](https://postext.dev/zh/docs/arabic-layout.md#文档块与行内方向)
- [各栏齐底](https://postext.dev/zh/docs/configuration.md#各栏齐底)
- [标题属性](https://postext.dev/zh/docs/document-format.md#标题属性)
- [纸张颜色](https://postext.dev/zh/docs/configuration.md#页面)
- [按页面角色显示书眉](https://postext.dev/zh/docs/configuration.md#文本元素)
- [段落样式](https://postext.dev/zh/docs/configuration.md#段落样式)
- [嵌入PDF的字体](https://postext.dev/zh/docs/configuration.md#为什么需要字体提供函数)
- [右翻书](https://postext.dev/zh/docs/configuration.md#装订)
- [罗马数字页码的前置部分](https://postext.dev/zh/docs/document-format.md#numbering)
- [分节版式](https://postext.dev/zh/docs/configuration.md#标题样式)
- [不编号的章](https://postext.dev/zh/docs/configuration.md#标题样式)

**配置一览**

- [`bodyText`](https://postext.dev/zh/docs/configuration.md#正文), [`calloutStyles`](https://postext.dev/zh/docs/configuration.md#标注框样式), [`citations`](https://postext.dev/zh/docs/configuration.md#引用), [`colorPalette`](https://postext.dev/zh/docs/configuration.md#调色板), [`footer`](https://postext.dev/zh/docs/configuration.md#页眉与页脚), `footnotes`, [`header`](https://postext.dev/zh/docs/configuration.md#页眉与页脚), [`headingStyles`](https://postext.dev/zh/docs/configuration.md#标题样式), [`headings`](https://postext.dev/zh/docs/configuration.md#标题), [`index`](https://postext.dev/zh/docs/configuration.md#索引), [`layout`](https://postext.dev/zh/docs/configuration.md#版式), [`locale`](https://postext.dev/zh/docs/configuration.md#断词), [`page`](https://postext.dev/zh/docs/configuration.md#页面), [`paragraphStyles`](https://postext.dev/zh/docs/configuration.md#段落样式)

**API**

- [`LOCALES`](https://postext.dev/zh/docs/document-format.md#引用与参考文献), [`STYLES`](https://postext.dev/zh/docs/document-format.md#引用与参考文献), [`buildDocument`](https://postext.dev/zh/docs/configuration.md#构建文档), [`clearMeasurementCache`](https://postext.dev/zh/docs/configuration.md#测量缓存), [`createCiteprocEngine`](https://postext.dev/zh/docs/document-format.md#引用与参考文献), [`decompressWoff2`](https://postext.dev/zh/docs/configuration.md#浏览器字体提供函数fontsource--woff2), [`registerCitationEngine`](https://postext.dev/zh/docs/document-format.md#引用与参考文献), [`renderPageToCanvas`](https://postext.dev/zh/docs/configuration.md#把页面渲染为位图), [`renderToPdf`](https://postext.dev/zh/docs/configuration.md#生成pdf)

**字体**

- Amiri (OFL-1.1), Noto Kufi Arabic (OFL-1.1)

## 做法

### 1 · 脚注、引文和索引在一处设置

代码见上文的[简短回答](#简短回答)。脚注设置是阿拉伯文图书需要的三项：`markerTemplate: '({n})'`加圆括号，`numbering: 'page'`每页重新编号，`noteNumberPosition: 'inline'`让脚注以行内的«(١)»开头；数字采用文档的数字系统，分隔线在右侧（[脚注](/zh/docs/arabic-layout#脚注)）。引文与脚注共用编号。`citations.locale: 'ar'`给出阿拉伯语的CSL术语，比如期号用عدد。`index.ignoreArticle`按ال后面的词给条目排序，并合并哈姆宰的各种写法，所以أميري和الأعمدة都排在ا下（[目录与索引](/zh/docs/arabic-layout#目录与索引)）；阿拉伯文索引默认就打开它，这里写出来是为了让人看到。

![Opening page ٩١: فهرس الأعلام والموضوعات.](https://postext.dev/cookbook/arabic-research-article/en/p05.webp?v=47b8aa2d)

*索引：两栏从右开始，字母为红色，الكشيدة在ك下并有参见。*

### 2 · 没有色带的论文刊头

```js
// script.js, 行 62–75
const centred = (y, extra = {}) => ({ anchor: { to: 'container', edge: 'top' },
  offset: { y: mm(y) }, size: { width: 'fill' }, ...extra });
const line = (id, content, family, size, colour, y, extra = {}) => ({ kind: 'text', id,
  content, fontFamily: family, fontSize: pt(size), color: col(colour), align: 'center',
  overflow: 'wrap', placement: centred(y), ...extra });
const masthead = { enabled: true, minHeight: mm(70), slot: { elements: [
  line('journal', JOURNAL, LABEL, 9, 'red', 0, { fontWeight: 700 }),
  line('issue', '{attr.issue}', LABEL, 8, 'muted', 6),
  { kind: 'rule', id: 'rule', thickness: pt(0.5), color: col('rule'),
    placement: centred(13) },
  line('title', '{titleText}', TEXT, 22, 'ink', 18, { fontWeight: 700, lineHeight: 1.45 }),
  line('author', '{attr.author}', TEXT, 13, 'ink', 45),
  line('affiliation', '{attr.affiliation}', TEXT, 10, 'muted', 52),
] } };
```

论文标题是一级标题，由一个设计绘制：期刊名和期号、一条细线、两行居中的标题和作者。期号那一行用阿拉伯-印度数字输入，因为设计的属性是作者的文字，引擎不会改写。页码从87开始（`page.pageNumbering.startAt`），页码显示论文在这一期中的位置。

### 3 · 从外侧角排起的书眉

```js
// script.js, 行 79–89
const head = (id, content, parity, edge, x) => ({ kind: 'text', id, content, parity,
  pages: 'body', fontFamily: LABEL, fontSize: pt(7.5), color: col('muted'), align: edge,
  placement: { anchor: { to: 'page', edge: `top-${edge}` }, offset: { x: mm(x), y: mm(13) } } });
const folio = (id, parity, edge, x) => ({ ...head(id, '{pageNumber}', parity, edge, x),
  fontWeight: 700, color: col('red') });
const header = { elements: [
  folio('r-folio', 'even', 'right', -SIDE.outer),
  head('r-head', JOURNAL, 'even', 'right', -(SIDE.outer + 9)),
  head('l-head', 'سلمى الخطيب: أثر الكشيدة في سرعة القراءة', 'odd', 'left', SIDE.outer + 9),
  folio('l-folio', 'odd', 'left', SIDE.outer),
] };
```

右页书眉是期刊名，左页是作者和简短标题，页码都在外侧角。页眉元素保持物理位置，所以在这种装订方式下位于右边的偶数页锚定在`top-right`。

## 完整食谱

一个文件，由食谱文件夹合成，示例文本和排版食谱的公共工具包都已内联；它自己排出页面。要运行它，把它放进空白页面的`<script type="module">`，或粘贴到新建CodePen的JS面板里（设为模块）。它从esm.sh导入postext，不需要安装或构建。

- 食谱文件夹: https://github.com/drnachio/postext/tree/main/cookbook/arabic-research-article

### script.js

```js
// ═══ Postext Cookbook · Nº 107 · An Arabic research article with notes, citations and an index ═══
// https://postext.dev/en/cookbook/arabic-research-article
// Code: MIT · Text: original Arabic prose (CC BY 4.0) · Pictures: none
// Fonts: Amiri, Noto Kufi Arabic (SIL OFL 1.1) · Needs postext ≥ 1.15.0
import {
  buildDocument, renderPageToCanvas, clearMeasurementCache, registerCitationEngine,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
import { createCiteprocEngine, STYLES, LOCALES } from 'https://esm.sh/postext-citeproc';

const LANG = 'en'; // @lang: the language of the frame; the article is Arabic in both editions
const RECIPE = 'arabic-research-article';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a journal's dark red on a warm white
const palette = {
  ink: '#1d1a19', // text
  red: '#7d2028', // the accent: the journal's name, section numbers, the notes' rule
  rose: '#f1e4e1', // the abstract's ground
  rule: '#c8bcb5', // hairlines
  muted: '#655d58', // running heads, the colophon
  paper: '#fffdfa',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.red })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const [TEXT, LABEL] = ['Amiri', 'Noto Kufi Arabic'];
const [BODY, LEAD] = [12, 20]; // pt: Amiri, partly vocalised, at 1.67 × the size
const TRIM = { width: 170, height: 240 }; // mm: 17 × 24 cm, the Arab journal
const SIDE = { inner: 22, outer: 18 }; // mm
const JOURNAL = 'مجلة دراسات الكتاب والنشر';

// #region answer: notes «(١)» per page, the citations among them, an index without ال
// Citations are written [@ayalon2016, 45] in the text; a note style puts each one in a
// footnote, numbered with the author's own [^notes]. The CSL locale is Arabic: ص for a page.
registerCitationEngine(createCiteprocEngine({ styles: STYLES, locales: LOCALES }));
const citations = {
  style: 'chicago-notes-bibliography', notes: 'footnote', locale: 'ar',
  bibliography: { fontSize: em(0.9), lineHeight: pt(17), hangingIndent: em(2),
    entrySpacing: pt(2) },
};
const footnotes = {
  markerTemplate: '({n})', // «(١)», in the document's digits
  numbering: 'page', // from (١) again on every page, as Arabic journals number them
  noteNumberPosition: 'inline', // the note opens with (١) on the line, not raised
  fontSize: pt(10), lineHeight: pt(18), spaceBetween: pt(2), // 1.8 ×: tanwīn clears the line
  textAlign: 'start', // ragged from the right: a Latin title would open wide gaps
  separator: { width: 0.3, lineWidth: pt(0.5), color: col('red') }, // on the start side
};
// The index sorts by the word after the article: الكشيدة files under ك, not under ا.
// ignoreArticle is already true for an Arabic index; it is written out to be seen.
const index = {
  ignoreArticle: true,
  fontFamily: TEXT, fontSize: pt(10.5), lineHeight: pt(16), indent: em(1.2),
  main: { bold: true }, // the page that defines the term
  groups: { fontFamily: LABEL, fontSize: pt(10), fontWeight: 700, color: col('red') },
};
// #endregion

// #region masthead: the journal's name, the article's title and its author, centred
const centred = (y, extra = {}) => ({ anchor: { to: 'container', edge: 'top' },
  offset: { y: mm(y) }, size: { width: 'fill' }, ...extra });
const line = (id, content, family, size, colour, y, extra = {}) => ({ kind: 'text', id,
  content, fontFamily: family, fontSize: pt(size), color: col(colour), align: 'center',
  overflow: 'wrap', placement: centred(y), ...extra });
const masthead = { enabled: true, minHeight: mm(70), slot: { elements: [
  line('journal', JOURNAL, LABEL, 9, 'red', 0, { fontWeight: 700 }),
  line('issue', '{attr.issue}', LABEL, 8, 'muted', 6),
  { kind: 'rule', id: 'rule', thickness: pt(0.5), color: col('rule'),
    placement: centred(13) },
  line('title', '{titleText}', TEXT, 22, 'ink', 18, { fontWeight: 700, lineHeight: 1.45 }),
  line('author', '{attr.author}', TEXT, 13, 'ink', 45),
  line('affiliation', '{attr.affiliation}', TEXT, 10, 'muted', 52),
] } };
// #endregion

// #region heads: the journal on the right-hand page, the author and title on the left
const head = (id, content, parity, edge, x) => ({ kind: 'text', id, content, parity,
  pages: 'body', fontFamily: LABEL, fontSize: pt(7.5), color: col('muted'), align: edge,
  placement: { anchor: { to: 'page', edge: `top-${edge}` }, offset: { x: mm(x), y: mm(13) } } });
const folio = (id, parity, edge, x) => ({ ...head(id, '{pageNumber}', parity, edge, x),
  fontWeight: 700, color: col('red') });
const header = { elements: [
  folio('r-folio', 'even', 'right', -SIDE.outer),
  head('r-head', JOURNAL, 'even', 'right', -(SIDE.outer + 9)),
  head('l-head', 'سلمى الخطيب: أثر الكشيدة في سرعة القراءة', 'odd', 'left', SIDE.outer + 9),
  folio('l-folio', 'odd', 'left', SIDE.outer),
] };
// #endregion

const config = () => ({ // a factory: the engine caches resolved configs per object
  locale: 'ar', // written out, never LANG (gotcha: arabic-locale-tag)
  colorPalette, citations, footnotes, index,
  page: { width: mm(TRIM.width), height: mm(TRIM.height), dpi: 150,
    backgroundColor: col('paper'), pageNumbering: { startAt: 87 },
    margins: { top: mm(24), bottom: mm(22), left: mm(SIDE.inner), right: mm(SIDE.outer),
      mirror: true } },
  layout: { layoutType: 'single' },
  bodyText: { fontFamily: TEXT, fontSize: pt(BODY), lineHeight: pt(LEAD), color: col('ink'),
    boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
    textAlign: 'justify', firstLineIndent: em(1.5), indentAfterHeading: false,
    optimalLineBreaking: true, avoidWidows: true, avoidOrphans: true },
  headings: { fontFamily: LABEL, fontWeight: 700, color: col('ink'),
    balancing: { enabled: false }, // no space added over the heads to fill a page
    levels: [
    // Restated: any headings object drops the H1 break (gotcha: headings-drop-h1-break).
    { level: 1, breakBefore: { enabled: true, parity: 'any' }, marginTop: pt(0),
      marginBottom: pt(0), advancedDesign: masthead },
    // ١- المقدمة: the section number in the document digits, a hyphen after it.
    { level: 2, fontSize: pt(12), lineHeight: pt(LEAD), numberingTemplate: '{2}-',
      numberSeparator: ' ', color: col('red'), marginTop: pt(LEAD), marginBottom: pt(4) },
  ] },
  headingStyles: [
    { id: 'unnumbered', numbered: false }, // the abstract, the references, the index
    // The index: a title across the page and two columns, the first on the right.
    { id: 'index', numbered: false, span: 'page', breakBefore: { enabled: true, parity: 'any' },
      advancedDesign: { enabled: false }, fontSize: pt(18), lineHeight: pt(30),
      marginBottom: pt(LEAD),
      layout: { layoutType: 'double', gutterWidth: mm(8) } },
  ],
  calloutStyles: [{ id: 'abstract', background: col('rose'),
    padding: { top: mm(3.5), right: mm(5), bottom: mm(3.5), left: mm(5) },
    marginTop: pt(0), marginBottom: pt(0),
    titleStyle: { fontFamily: LABEL, fontSize: pt(9), fontWeight: 700, color: col('red') },
    body: { fontSize: pt(10.5), lineHeight: pt(17), firstLineIndent: pt(0) } }],
  paragraphStyles: [{ id: 'colophon', fontFamily: TEXT, fontSize: pt(9), lineHeight: pt(13),
    color: col('muted'), textAlign: 'left', firstLineIndent: pt(0), marginTop: pt(LEAD) }],
  header, footer: { elements: [] },
});

// ─── 2 · Content ────────────────────────────────────────────────────────────
const markdown = String.raw`---
title: "أثر الكشيدة في سرعة قراءة النص العربي المطبوع"
---

# أثر الكشيدة في سرعة قراءة النص العربي المطبوع: تجربة على قرّاء جامعيين {issue="المجلد ١٤ · العدد ٣ · خريف ٢٠٢٦" author="سلمى الخطيب" affiliation="قسم علوم المعلومات والنشر، جامعة المثال"}

:::callout{type="abstract" title="ملخص"}
تبحث هذه الدراسة في أثر ضبط السطور بالكشيدة في سرعة قراءة النص العربي المطبوع وفي فهمه. قرأ ستون طالبًا جامعيًا نصوصًا مضبوطة بثلاث طرق: بالمسافات وحدها، وبالكشيدة وحدها، وبمزيج منهما. ولم تختلف سرعة القراءة اختلافًا ذا دلالة بين الطرق الثلاث، غير أن القرّاء فضّلوا الطريقة المختلطة، وكانت أخطاء الفهم في الكشيدة الكثيفة أعلى قليلًا.
:::

## المقدمة

يملأ :index[الطابع]{term="الطباعة العربية"} العربي السطر حتى نهايته بإحدى وسيلتين: أن يوسّع المسافات بين الكلمات، أو أن يمدّ بعض الحروف المتصلة بما يسمّى :index[الكشيدة]{main}:index{term="الكشيدة" seealso="المسافات بين الكلمات"} أو :index[التطويل]{see="الكشيدة"}. والوسيلة الثانية قديمة قِدم الخط نفسه، عرفها :index[النسّاخ] قبل المطبعة، ثم نقلها صانعو :index[الحروف المعدنية] إلى صناديقهم في صورة قطع خاصة تُدسّ بين أجزاء الكلمة.[@nemeth2017] وحين انتقلت الطباعة العربية إلى الحاسوب، صار المدّ عملية آلية يقوم بها البرنامج، وصار السؤال عن مقداره ومواضعه سؤالًا تقنيًا قبل أن يكون جماليًا.[^raqim]

[^raqim]: تُبنى قواعد المواضع الجائزة للمدّ في البرامج الحديثة على ما وصفه الخطاطون في خط :index[النسخ]، ولا سيما المنع بعد الكاف واللام، وقبل الحروف المستديرة في آخر الكلمة.

ولا يكاد يُختلف في أن الكشيدة جزء من :index[جماليات الصفحة العربية]، لكن أثرها في القراءة لم يُدرس إلا قليلًا. فالدراسات القليلة المتاحة اعتمدت على تقدير القرّاء للنص، لا على قياس قراءتهم له،[@hashimi2019, ٧٧; @attar2021] والمعايير الدولية تكتفي بوصف المواضع التي يجوز فيها المدّ دون أن تحدد مقداره.[@alreq] ويحاول هذا البحث أن يقيس الأثر قياسًا مباشرًا.

## الكشيدة في الطباعة العربية

حين أُنشئت :index[مطبعة بولاق]{term="بولاق، مطبعة"} في عشرينيات القرن التاسع عشر، سُبكت حروفها على نماذج من الخط الذي يكتبه النسّاخ، وصار الكتاب المطبوع بعد ذلك بعقود سلعة يقرؤها جمهور واسع.[@ayalon2016] وكان صفّاف الحروف يضبط السطر بقطع من المدّ يدسّها بين أجزاء الكلمة، إلى أن ظهرت آلات :index[الصف الآلي] في القرن العشرين فقلّصت عدد أشكال الحروف تقليصًا كبيرًا.[@nemeth2017]

وقد عادت الكشيدة في :index[الصحف اليومية] بعد انتشار :index[الصف الرقمي]، لأنها تسمح بضبط :index[الأعمدة الضيقة] دون أن تتسع المسافات اتساعًا ظاهرًا. غير أن بعض المصممين يرون أن الإكثار منها يجعل الصفحة مضطربة، وأن العين تتعثر بالكلمات الممدودة كما تتعثر بالفجوات الواسعة.[@attar2021, ٥٢]

## منهج التجربة

شارك في التجربة ستون طالبًا وطالبة من :index[جامعة المثال]، تتراوح أعمارهم بين ١٩ و٢٦ سنة، وكلهم يقرأ العربية لغةً أولى. وقرأ كل منهم تسعة نصوص قصيرة من المقالات الصحفية، طول كل منها نحو ٣٠٠ كلمة، على صفحات مطبوعة بخط :index[أميري]{term="أميري، خط"} بحجم ١٣ نقطة.[^font]

[^font]: اختير خط أميري لأنه يرسم الكشيدة منحنية، كما في الطباعة البولاقية، فيكون الفرق بين الطرق الثلاث أوضح مما هو في الخطوط التي ترسمها خطًا مستقيمًا.

وضُبطت النصوص بثلاث طرق: بالمسافات وحدها، وبالكشيدة وحدها مع مسافات ثابتة، وبمزيج يوسّع :index[المسافات بين الكلمات] بمقدار الربع أولًا ثم يمدّ الحروف. وقيس زمن القراءة بالثواني، ثم أجاب القارئ عن خمسة أسئلة في الفهم، وأخيرًا رتّب الطرق الثلاث بحسب تفضيله.:index{term="تفضيل القرّاء"}

## النتائج والمناقشة

لم تختلف :index[سرعة القراءة] اختلافًا ذا دلالة بين الطرق الثلاث: كان المتوسط ٢١٤ كلمة في الدقيقة للمسافات، و٢٠٩ للكشيدة، و٢١٧ للطريقة المختلطة. أما :index[أخطاء الفهم]{term="الفهم، أخطاء"} فكانت أعلى قليلًا في الكشيدة وحدها، ولا سيما في السطور التي مُدّت فيها ثلاث كلمات أو أكثر.

وفضّل ٣٨ مشاركًا الطريقة المختلطة، و١٤ المسافات وحدها، و٨ الكشيدة وحدها. وهذا يتفق مع ما يذهب إليه الطابعون من أن الكشيدة تحسن قليلًا ولا تحسن كثيرًا،[@hashimi2019, ٨١] ومع ما تقترحه الإرشادات الحديثة من توزيع الفراغ على المسافات والمدّ معًا.[@alreq]

ولهذه النتائج حدود واضحة: فالنصوص قصيرة، والقرّاء من فئة عمرية واحدة، والخط واحد. ويحتاج الأمر إلى تجارب على :index[خطوط أخرى]{term="الخطوط الطباعية"}، وعلى :index[القراءة على الشاشة]، حيث يتغير عرض السطر بتغير الجهاز.

## المراجع {style="unnumbered"}

:::bibliography{title=""}

:::paragraphs{style="colophon" dir=ltr}
A specimen article written in Arabic for the Postext Cookbook. The journal, its author, her experiment and the Arabic works by al-Hashimi and al-Attar are invented; the books by Ayalon and Nemeth and the W3C document are real.
:::

# فهرس الأعلام والموضوعات {style="index"}

:::index

:::references{format=csl-yaml}
- id: nemeth2017
  type: book
  language: en
  author: [{family: Nemeth, given: Titus}]
  title: "Arabic type-making in the machine age: the influence of technology on the form of Arabic type, 1908–1993"
  publisher: Brill
  publisher-place: Leiden
  issued: 2017
- id: ayalon2016
  type: book
  language: en
  author: [{family: Ayalon, given: Ami}]
  title: "The Arabic print revolution: cultural production and mass readership"
  publisher: Cambridge University Press
  publisher-place: Cambridge
  issued: 2016
- id: alreq
  type: webpage
  language: en
  author: [{literal: W3C}]
  title: "Arabic & Persian layout requirements"
  URL: https://www.w3.org/TR/alreq/
- id: hashimi2019
  type: book
  language: ar
  author: [{literal: منى الهاشمي}]
  title: "الحرف العربي على الشاشة: دراسة في المقروئية"
  publisher: دار المثال
  publisher-place: بيروت
  issued: {literal: "٢٠١٩"}
- id: attar2021
  type: article-journal
  language: ar
  author: [{literal: كريم العطار}]
  title: "التطويل في الصحف اليومية العربية"
  container-title: مجلة دراسات الكتاب والنشر
  volume: "٩"
  issue: "٢"
  page: "٤٥-٦٨"
  issued: {literal: "٢٠٢١"}
:::
`; // content.<lang>.md: the same Arabic article in both

// ─── 3 · Fonts ──────────────────────────────────────────────────────────────
const FONTS = { // every face the pages use, loaded before the build (gotcha: fonts-first)
  Amiri: ['400', '700'], // TEXT: the article, notes, references, index; bold emphasis
  'Noto Kufi Arabic': ['400', '700'], // LABEL: masthead, section heads, running heads
};

// ─── 4 · Build & show ───────────────────────────────────────────────────────
await loadFonts(FONTS, markdown);
// Each Arabic face's letters live in a file of their own (gotcha: arabic-fonts-subset).
await loadArabicFonts(FONTS, markdown);
const doc = await buildWithFonts(() => buildDocument({ markdown }, config()), markdown);
showBook(doc, { title: t({ en: 'An Arabic research article',
  es: 'Un artículo académico árabe' }) });
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 ───────────────────────────────────────────────────────────────────────
```

## 变化

### 全文连续编号脚注

许多现代阿拉伯文期刊按文章而不是按页给脚注编号。

```diff
-  numbering: 'page', // from (١) again on every page, as Arabic journals number them
+  numbering: 'chapter',
```

### 用著者—出版年制引用

```diff
-  style: 'chicago-notes-bibliography', notes: 'footnote', locale: 'ar',
+  style: 'apa', locale: 'ar',
```

## 常见问题

- **阿拉伯文书标记为'ar'，不要用LANG.** 食谱的版本是en和es，但阿拉伯文示例在两个版本里都是阿拉伯文：`locale: LANG`会让它从左向右排、左装订、页码印成1 2 3，并把图标注为Figure或Figura。自己写出标记：'ar'（阿拉伯-印度数字，马什里克惯例），或带地区的'ar-EG'、'ar-SA'；马格里布版本用欧洲数字，写'ar-MA'、'ar-DZ'或'ar-TN'。只引用阿拉伯文的拉丁文页面保留自己的locale。
- **阿拉伯文字体需要通过arabic块加载其arabic文件.** Fontsource把Amiri、Noto Naskh Arabic或Scheherazade New按子集分成多个文件提供，阿拉伯字母在arabic文件里。loadFonts只获取latin（以及latin-ext），所以屏幕上的阿拉伯文来自系统字体，测量不准；fontsourceProvider交给PDF的也是这个latin文件，印出来是空框。列出kit中的arabic块，在loadFonts之后调用loadArabicFonts(FONTS, markdown)，并在FONTS中列出页面用于阿拉伯文的每个字重，再给renderToPdf传fontProvider: arabicPdfProvider。
- **传入任何headings对象都会关掉H1换页.** 默认情况下，H1换页到右页（always-odd），但只要传入headings对象，这个默认值就会被重置，于是各章接排，span: 'page'也不起作用。在每份配置中重新写明headings.levels[0].breakBefore: { enabled: true, parity }。
- **标题样式会继承其级别的分页设置.** headingStyles中的条目没有写出的字段都取自它所属的标题级别，breakBefore也不例外。在:::pagebreak之后以H1设置样式的目录页或版权页会继承parity 'odd'，结果落在一张空白页之后。给这类样式设置breakBefore: { enabled: false }。
- **排版前加载所有字体.** 排版用浏览器已加载的字体测量文字，并缓存宽度，所以首次构建之后才到的字体会造成断行错误，PDF也不再与屏幕一致。先加载所有字重和样式；有字体迟到时，重新构建前调用clearMeasurementCache()。

- CSL样式写出的标点属于样式本身：脚注各部分之间的逗号、分号和引号是拉丁标点，如الهاشمي, الحرف العربي。日期和数字来自数据，所以阿拉伯文著作写`issued: {literal: "٢٠١٩"}`，定位词写成`[@hashimi2019, ٧٧]`；拉丁文著作保留0–9。
- 引用拉丁文著作的脚注或参考文献条目跟随阿拉伯文页面的方向：句末句号落在行的左端。

## 致谢

- 食谱: Ignacio Ferro ([@drnachio](https://github.com/drnachio))
- 文字: A research article written in Arabic for the recipe; its journal, author, experiment and Arabic sources are invented: Postext Cookbook, 原创
- 字体: Amiri (OFL-1.1), Noto Kufi Arabic (OFL-1.1)
- 代码: MIT · 示例内容: CC-BY-4.0

## 相关食谱

- [No. 089 · 用芝加哥注释体排历史论文](https://postext.dev/zh/cookbook/history-essay-chicago-notes.md): 一篇四页的历史论文：正文写[@key, 87]，引文按芝加哥注释体排成页脚注，首次完整、再次简略，文末附参考书目。 · 难度 2 (中级) · 论文与学术出版物
- [No. 072 · 随正文变动的教科书索引](https://postext.dev/zh/cookbook/back-of-book-index.md): 在正文讲解术语的地方做标记，由:::index分两栏印出，页码由buildBundle找出，支持页码范围和交叉引用。 · 难度 3 (高级) · 教科书
- [No. 109 · 印欧洲数字的马格里布版阿拉伯文书](https://postext.dev/zh/cookbook/maghreb-edition-european-digits.md): 为摩洛哥印制的阿拉伯文书中的一章：locale 'ar-MA'保持从右向左和右侧装订，并把引擎生成的每个数字写作1、2、3。 · 难度 1 (基础) · 手册、指南与参考书