انتقل إلى المحتوى الرئيسي
الوصفة رقم 92

دليل الوصفات · الفصل 5 · بنية الكتاب

دليل استخدام تشير إحالاته إلى الصفحات

دليل مالك دراجة تُكتب إحالاته على هيئة «see section 3.2 on page 3»، إلى الأمام وإلى الخلف، وكل رقم وصفحة فيها مأخوذ من الإخراج.

في هذه الصفحة
المُخرَج
Canvas · PDF
المستوى
متوسط
Postext
اختُبرت مع Postext 1.65.0
تتطلب ≥ 1.28.0 · postext-pdf ≥ 1.28.0
الترخيص
حُدّثت في 11 أكتوبر 2026
الشيفرة MIT · النص CC BY 4.0
  • نموذج باللغة الإنجليزية: لا توجد طبعة عربية بعد
  • مقاس القص 148 × 210 مم
  • عمود واحد
  • Archivo 9.3/13
  • Archivo Narrow
  • 4 صفحات
  • المستوى
  • Postext 1.57.1
  • أُخرجت في 64 ms
  • أسطر الشيفرة: 131

باختصار

دليل مالك قصير لدراجة سياحية. حين يحيلك النص إلى قسم آخر يذكر رقم ذلك القسم والصفحة التي هو فيها، وكلاهما رابط.

ما الذي ستنضده

دليل المالك لدراجة سياحية متخيَّلة، Ardena T3: أربع صفحات A5 منضدة بخط Archivo، واسم الطراز في شريط كحلي فوق الصفحة الأولى. الدليل يُقرأ بلا ترتيب، لذا تذكر كل تعليمة تعتمد على أخرى مكانها: see section 3.2 on page 3. يمنح الكاتب عنوانًا أو فقرة أو عبارة في خطوة معرّفًا، ويكتب :ref حيثما أشار النص إليه؛ فيطبع Postext الرقم أو العنوان أو الصفحة ويجعله رابطًا. وتُكتب قائمة المحتويات على الغلاف بالطريقة نفسها، فنقل قسم من مكانه، أو ترجمة الدليل وتركه يعيد التدفق، لا يترك رقمًا قديمًا أبدًا.

تجيب هذه الوصفة عن

  • كيف أحيل إلى قسم والصفحة التي يقع فيها، وأبقي الاثنين صحيحين حين يتغير الكتاب؟

الجواب المختصر

script.js · الأسطر 28–38في الشيفرة الكاملة
// In the Markdown, `## Brakes {#sec-brakes}` names a heading, `:anchor{#warn-pressure}`
// a point in a paragraph and `[close the lever]{#step-close-lever}` a phrase in a step.
// `:ref{id="sec-pad-wear"}` prints "section 3.2", `style=page` "page 3", `style=title`
// the heading's words and `style=pageNumber` the bare 3. The page numbers come from the
// previous layout pass: the engine lays the manual out again until they hold.
const crossRefs = {
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // H2 and H3: "section 3.2"
  page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
};
// Every reference is a link in the PDF and on screen; this makes it look like one.
const references = { referenceColor: col('orange'), referenceBold: true };

المكونات

الخطوط
Archivo, Archivo Narrow (SIL OFL 1.1)
الأصول
لا شيء: كل صورة مرسومة بالشيفرة

طريقة التحضير

#1 · سمِّ ما يشير إليه النص

الشيفرة هي الجواب المختصر أعلاه. تأخذ العناوين معرّفًا على طريقة Pandoc، ### Checking pad wear {#sec-pad-wear}؛ ويبدأ التحذير الخاص بضغط الإطارات بـ:anchor{#warn-pressure}، وهي علامة غير مرئية؛ وآخر خطوة في تركيب العجلة هي [close the lever so that it points backwards]{#step-close-lever}، التي تحتفظ بكلماتها وتمنحها معرّفًا؛ ويُفتتح الإطار بـ:::callout{#box-wet type="note" title="Wet weather"}. والإحالة إلى الخطوة تطبع كلمات الخطوة، والإحالة إلى الإطار تطبع عنوانه.

#2 · هدف واحد وأربع طرق لتسميته

يطبع :ref{id="sec-pad-wear"} section 3.2 بالكلمة المأخوذة من crossRefs.section؛ ويطبع style=page page 3 بالكلمة المأخوذة من crossRefs.page؛ ويطبع style=title Checking pad wear؛ ويطبع style=pageNumber الرقم المجرد 3. وتجمع قائمة المحتويات على الغلاف الرقم المجرد والعنوان والصفحة المجردة، فتُقرأ كجدول محتويات. وفي الإسبانية تطبع الإحالات نفسها apartado 3.2 وpágina 3، لأن القوالب تتبع لغة الطبعة.

#3 · الصفحات تستقر من تلقاء نفسها

رقم الصفحة لا يُعرف إلا بعد إخراج الدليل. يُخرج المحرّك الدليل، ويقرأ الصفحة التي وقع فيها كل هدف، ثم يعيد الإخراج حتى لا تتغير أي إحالة، وهي الحلقة نفسها التي تملأ جدول المحتويات. والنص الذي يطول بالترجمة، أو القسم الذي يُنقل إلى البداية، يغيّر الصفحات، وتتبعها الإحالات، إلى الأمام وإلى الخلف.

#4 · الأرقام تأتي من عدّاد المستوى الثاني

script.js · الأسطر 42–47في الشيفرة الكاملة
const H2 = { level: 2, numberingTemplate: '{2}', numberSeparator: '   ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(15), lineHeight: pt(LEAD * 1.5), color: col('navy'),
  marginTop: pt(LEAD), marginBottom: pt(LEAD / 3) };
const H3 = { level: 3, numberingTemplate: '{2}.{3}', numberSeparator: '  ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(10.5), lineHeight: pt(LEAD), color: col('ink'),
  marginTop: pt(LEAD / 2), marginBottom: pt(LEAD / 4) };

في الدليل عنوان واحد من المستوى الأول، هو اسم الطراز على الغلاف، لذا تُرقَّم أقسامه من المستوى الثاني: يُنتج {2} من 1 إلى 5، ويُنتج {2}.{3} 1.1 و1.2.

#5 · الغلاف هو صفحة افتتاح ذلك العنوان

script.js · الأسطر 51–73في الشيفرة الكاملة
const BAND = 104; // mm from the trim's top
const label = { fontFamily: DISPLAY, fontWeight: 700, textTransform: 'uppercase',
  letterSpacing: pt(1.6), align: 'left' };
const cover = {
  enabled: true,
  minHeight: mm(BAND - PAGE.top + 8), // the contents start 8 mm under the band
  slot: { elements: [
    { kind: 'box', id: 'band', style: { backgroundColor: col('navy') },
      placement: { ...at('page', 'top-left'), size: { width: 'fill', height: mm(BAND) } } },
    { kind: 'box', id: 'stripe', style: { backgroundColor: col('orange') },
      placement: { ...at('page', 'top-left', 0, BAND), size: { width: 'fill', height: mm(2.5) } } },
    { kind: 'text', id: 'kicker', content: '{attr.kicker}', ...label, fontSize: pt(9),
      color: col('tint'), placement: at('container', 'top-left', 0, 6) },
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: DISPLAY, fontWeight: 700,
      fontSize: pt(58), lineHeight: 1, color: col('paper'), align: 'left',
      placement: at('container', 'top-left', -1, 30) },
    { kind: 'text', id: 'subtitle', content: '{attr.subtitle}', fontFamily: TEXT,
      fontSize: pt(11), color: col('paper'), align: 'left',
      placement: at('container', 'top-left', 0, 55) },
    { kind: 'text', id: 'edition', content: '{attr.edition}', ...label, fontSize: pt(7.5),
      color: col('tint'), placement: at('container', 'top-left', 0, 74) },
  ] },
};

عمق الشريط 104 مم، نصف الصفحة، ويختمه شريط برتقالي. والعنوان التمهيدي والعنوان الفرعي وسطر الطبعة سمات للعنوان، فتغيّرها الطبعة الإسبانية في نصها الخاص.

script.js · الأسطر 13–20في الشيفرة الكاملة
const palette = {
  ink: '#1b1f24', navy: '#1d2c3c', orange: '#b8471b', tint: '#f7e7de', rule: '#d5cfc8',
  muted: '#5c636b', paper: '#ffffff',
};
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.orange })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));

الوصفة كاملة

Sandbox
// ═══ Postext Cookbook · Nº 092 · A manual whose references point to pages ══════════
// https://postext.dev/en/cookbook/manual-see-page-references
// Code: MIT · Text: original (CC BY 4.0) · Pictures: none
// Fonts: Archivo, Archivo Narrow (SIL OFL 1.1) · Needs postext ≥ 1.28.0
import { buildDocumentWithFonts, renderPageToCanvas } 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 = 'manual-see-page-references';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a navy cover band and one signal orange for numbers and references
const palette = {
  ink: '#1b1f24', navy: '#1d2c3c', orange: '#b8471b', tint: '#f7e7de', rule: '#d5cfc8',
  muted: '#5c636b', paper: '#ffffff',
};
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.orange })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const TEXT = 'Archivo', DISPLAY = 'Archivo Narrow';
const PAGE = { w: 148, h: 210, top: 20, bottom: 20, inner: 18, outer: 15 }; // mm: A5, mirrored
const LEAD = 13; // pt
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });

// #region answer: the words a reference prints, and references that are links
// In the Markdown, `## Brakes {#sec-brakes}` names a heading, `:anchor{#warn-pressure}`
// a point in a paragraph and `[close the lever]{#step-close-lever}` a phrase in a step.
// `:ref{id="sec-pad-wear"}` prints "section 3.2", `style=page` "page 3", `style=title`
// the heading's words and `style=pageNumber` the bare 3. The page numbers come from the
// previous layout pass: the engine lays the manual out again until they hold.
const crossRefs = {
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // H2 and H3: "section 3.2"
  page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
};
// Every reference is a link in the PDF and on screen; this makes it look like one.
const references = { referenceColor: col('orange'), referenceBold: true };
// #endregion

// #region numbers: sections 1–5 and 1.1, 1.2… under the one level-1 heading
const H2 = { level: 2, numberingTemplate: '{2}', numberSeparator: '   ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(15), lineHeight: pt(LEAD * 1.5), color: col('navy'),
  marginTop: pt(LEAD), marginBottom: pt(LEAD / 3) };
const H3 = { level: 3, numberingTemplate: '{2}.{3}', numberSeparator: '  ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(10.5), lineHeight: pt(LEAD), color: col('ink'),
  marginTop: pt(LEAD / 2), marginBottom: pt(LEAD / 4) };
// #endregion

يعمل ملف script.js المجمّع كما هو: الصقه في سكربت الوحدة (module) لأي صفحة، أو افتح الوصفة على CodePen. مجلد الوصفة على GitHub ↗ (يفتح في تبويب جديد)

تنويعات

#استعمل «p.» في الإحالات

الكتاب المرجعي الكثير الإحالات إلى الصفحات يوفّر المساحة بالاختصار.

-  page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
+  page: t({ en: 'p. {n}', es: 'pág. {n}' }),

#اترك الإحالات بلون الحبر

حين تكون معظم الصفحة إحالات، أبقها بلون النص وبالأسود العريض؛ فهي تبقى روابط في PDF وعلى الشاشة.

-const references = { referenceColor: col('orange'), referenceBold: true };
+const references = { referenceColor: col('ink'), referenceBold: true };

أخطاء شائعة

  • الإحالة إلى :anchor بلا نمط تطبع الصفحة، لأن المرساة غير المرئية لا كلمات لها. استعمل [words]{#id} حين يجب أن تقتبس الإحالة النص.
  • يجب أن يكون المعرّف فريدًا في الكتاب. تصل الإحالات إلى أول {#sec-brakes}، وتُدرج لوحة الفحوص في Sandbox المعرّفَ الثاني بوصفه duplicateAnchor.

الحقوق

الوصفة
Ignacio Ferro
النص
نص أصلي, CC BY 4.0
الخطوط
Archivo (SIL OFL 1.1) · Archivo Narrow (SIL OFL 1.1)
الشيفرة
MIT، مثل Postext
SandboxPDF