الإعدادات: الحواشي والإحالات

#الحواشي السفلية

تحدد الخاصية footnotes أين تذهب الحواشي المستشهد بها عبر [^id]، وكيف تُرقَّم وكيف تبدو. الترميز موصوف في صيغة المستند.

interface FootnotesConfig {
  placement?: 'column' | 'chapterEnd' | 'spread'; // Foot of the citing column, after the chapter, or beside the text of a spread.
  numbering?: 'chapter' | 'document' | 'page' | 'column' | 'spread'; // Start again at each chapter, run on, or start again on each page / column / spread.
  numberFormat?: string;      // decimal, lower-roman, circled-decimal (①)…
  symbols?: string[];         // رموز الإحالة التي يكتبها numberFormat: 'symbols'.
  markerPosition?: 'auto' | 'superscript' | 'inline' | 'side' | 'right'; // Raised, on the baseline, beside the word, or right of a vertical line.
  markerSize?: Dimension;     // Inline, side or right marker size; em is the text around it.
  numberGap?: 'en' | 'em';    // Space after the note's own number.
  chapterEndAlign?: 'foot' | 'text';   // chapterEnd: notes at the column foot, or under the text.
  fontSize?: Dimension;       // Note size; em is the body size.
  lineHeight?: Dimension;     // Note leading; em is the note size.
  color?: ColorValue;         // Note colour; the body colour when unset.
  textAlign?: TextAlign;      // The body alignment when unset.
  hangingIndent?: Dimension;  // Indent of a note's turnover lines.
  spaceBetween?: Dimension;   // Space between two notes.
  spaceAbove?: Dimension;     // Space between the text and the rule; em is the body size.
  spaceBelowRule?: Dimension; // Space between the rule and the first note.
  separator?: {
    enabled?: boolean;        // Draw the rule.
    width?: number;           // Rule length, a fraction of the column width.
    lineWidth?: Dimension;    // Rule thickness.
    color?: ColorValue;       // The note colour when unset.
  };
}

footnotes: {
  fontSize: { value: 7.5, unit: 'pt' },
  lineHeight: { value: 9.5, unit: 'pt' },
  hangingIndent: { value: 0.8, unit: 'em' },
  separator: { width: 0.25, lineWidth: { value: 0.4, unit: 'pt' } },
}

الكتب اليابانية. المستند الياباني (locale: 'ja'، منذ postext 1.16) يعطي الحقول التي يتركها دون ضبط قيم JLReq §4.2. فالكتاب العمودي يضع حواشيه بعد الفصل (placement: 'chapterEnd'، 後注)، مرقّمة بحسب الفصل، مع علامات （{n}） على يمين السطر (markerPosition: 'right'، والأرقام قائمة بحسب cjk.uprightDigits)؛ والأفقي يضعها في أسفل الصفحة، مرقّمة لكل صفحة، مع علامات مرفوعة. وكلاهما يرسم الخط الفاصل بطول ثلث عرض السطر (separator.width: 1/3)، والحواشي بعد الفصل تأخذ numberGap: 'em' ومسافة بادئة معلّقة بعرض 2 em. والقيمة الصريحة هي التي تُعتمد، وتُحفظ عند الحفظ (يقارن stripFootnotesDefaults بالقيم الافتراضية للمستند نفسه)؛ وتُحسم المستندات الصينية والعربية واللاتينية كما كانت. وتعيد footnoteDocumentDefaults(locale, writingMode, placement?) هذه القيم. واكتب العلامة قبل 。 التي تختم الجملة (先生[^1]。): فهي تبقى مع الحرف الذي قبلها، و。 لا تفتتح سطرًا أبدًا. انظر الإخراج الياباني › الحواشي.

كيف تُخرَج الحواشي في أسفل العمود:

• الحاشية والاستشهاد يتشاركان العمود. قبل أن يضع الإخراج سطرًا، يضيف ارتفاع الحواشي التي يستشهد بها ذلك السطر لأول مرة (والخط الفاصل، مع أول حاشية في العمود). والسطر الذي لا تتسع حواشيه تحته ينتقل إلى العمود التالي مع بقية فقرته، وفق قاعدتي الأسطر اليتيمة والأرامل. تتقلص مساحة النص في العمود بمقدار ارتفاع الحواشي، فلا تحسب موازنةُ الأعمدة والشريطُ الختامي للفصل إلا النص.
• عدة حواشي في عمود واحد تتراكم بترتيب الاستشهاد تحت خط فاصل واحد. والحاشية التي يُستشهد بها مرة أخرى لاحقًا تحتفظ برقمها ولا تُنضَّد ثانيةً.
• العناصر العائمة السفلية. الشكل الذي يشغل أسفل عمود بعد وضع حواشيه يوضع فوقها؛ والحواشي التي توضع بعد الشكل تأتي فوقه.
• الإطارات. الحاشية المستشهد بها داخل إطار (ضمن السطر أو عائم أو ثابت) تذهب إلى أسفل العمود الذي يستمر فيه النص بعد الإطار، وهو عادةً العمود نفسه. والإطار الذي يختم المستند يترك حواشيه في أسفل العمود الذي انتهى فيه النص.
• الحدود. لا تُقسَم الحاشية أبدًا: الحاشية الأطول من العمود تفيض منه. والعلامات في التعليقات وخلايا الجداول والعناوين لا تُقرأ (تُطبع كما كُتبت).
• المُخرجات. ترسم Canvas وHTML وPDF الحواشي والعلامات (رقمًا مرفوعًا) والخط الفاصل. في PDF ترتبط كل علامة بحاشيتها، وPDF الموسوم يجعل كل حاشية عنصر Note بمعرّف /ID فريد مُدرج في /IDTree من شجرة البنية (PDF/UA-1). الحواشي كتل VDTBlock عُيّنت فيها footnoteNote، في page.floats؛ والخطوط الفاصلة في page.footnoteAreas.
• التحذيرات. undefinedFootnote (علامة بلا تعريف: يُطبع الرقم فوق حاشية فارغة) وunusedFootnote (تعريف لا تستشهد به أي علامة: لا يُنضَّد).

دالتا الحل والتجريد مماثلتان لنظيراتهما في الأقسام الأخرى:

import { DEFAULT_FOOTNOTES_CONFIG, resolveFootnotesConfig, stripFootnotesDefaults, footnoteDocumentDefaults } from 'postext';
 
resolveFootnotesConfig(config.footnotes, 'ja', 'vertical-rl'); // unset fields take the Japanese vertical defaults

#ترقيم الأسطر

تطبع الخاصية lineNumbers في الهامش رقمَ كل سطر خامس (أو كل سطر رقمه من مضاعفات N) بجوار السطر، كما تفعل الطبعات المحققة ومختارات الشعر والنصوص القانونية والطبعات المدرسية. وهي تعدّ أبيات قصائد :::verse، أو كل أسطر النص. وهي معطّلة افتراضيًا. يُرسم كل رقم على خط قاعدة سطره، بحجم خاص به، ولا يحرّك أي سطر أبدًا: تُخرَج الصفحة تمامًا كما تُخرَج بلا أرقام. منذ postext 1.23.

interface LineNumbersConfig {
  enabled?: boolean;        // معطّلة افتراضيًا.
  count?: 'verse' | 'all';  // أبيات القصائد، أو كل أسطر النص.
  interval?: number;        // اطبع مضاعفات N.
  numberFirst?: boolean;    // اطبع أيضًا أول سطر بعد كل إعادة للعدّ.
  restart?: 'document' | 'chapter' | 'section' | 'page' | 'poem'; // أين يبدأ العدّ من جديد.
  startAt?: number;         // رقم أول سطر بعد إعادة العدّ.
  position?: 'outer' | 'inner' | 'left' | 'right' | 'start' | 'end' | 'side';
  multiColumn?: 'each' | 'gutter' | 'outer-edges'; // الصفحات ذات العمودين أو أكثر.
  gap?: Dimension;          // من النص إلى الرقم؛ وem حجم الرقم.
  align?: 'auto' | 'left' | 'right';
  fontFamily?: string;      // عائلة خط المتن إن لم تُحدَّد.
  fontSize?: Dimension;     // وem حجم المتن.
  fontWeight?: number;      // وزن المتن إن لم يُحدَّد.
  italic?: boolean;
  color?: ColorValue;       // لون المتن إن لم يُحدَّد.
  format?: string;          // decimal، lower-roman، arabic-indic، 一…
}

lineNumbers: {
  enabled: true,
  count: 'verse',
  interval: 5,
  restart: 'document',          // عدّ واحد للكتاب كله
  position: 'outer',
  fontSize: { value: 0.75, unit: 'em' },
  italic: true,
}

ما يُعدّ وما لا يُعدّ:

• لا يُعدّ أبدًا: العناوين، والتعليقات، والجداول والصور، والصيغ المنفصلة، ونصوص التصميم (صفحات الافتتاح والترويسات)، والحواشي السفلية وحواشي آخر الفصل، وجدول المحتويات، ومداخل الفهرس وقائمة المراجع، والصفحات الفارغة.
• الإطارات والنثر. نص الإطار لا يُعدّ، ومع count: 'verse' لا يُعدّ النثر أيضًا، إلا إذا قال نمط الفقرة الذي يُنضَّد به lineNumbers: true؛ والنمط الذي فيه lineNumbers: false لا يُعدّ أبدًا (انظر أنماط الفقرات).
• قصيدة واحدة. يقبل سطر فتح القصيدة numbered=false (لا تُعدّ أبياتها)، وlineStart=N (أول أبياتها رقمه N، ومنه يبدأ العدّ من جديد)، وinterval=N. و:::numbering{lines=N} يعطي السطرَ المعدود التالي الرقمَ N، أينما كان. انظر صيغة المستند › :::verse و:::numbering.

في كتاب يُخرَج فصلًا فصلًا، ينقل restart: 'document' العدّ من فصل إلى الذي يليه عبر continuation.lineNumber. ويعدّ continuationAfter الأبيات من النص؛ أما مع count: 'all' فيتوقف العدّ على الإخراج، فيمرّر التطبيق المضيف lastLineNumber من مستند الفصل السابق، كما يفعل Sandbox.

مع position: 'side' تتقاسم الأرقام العمود الجانبي مع الإطارات والتعليقات والأشكال الجانبية. والرقم الذي يتراكب مع أحدها يُرسم مع ذلك، ولا يتحرك أيٌّ منهما، ويصدر الإخراج تحذير محتوى lineNumberOverlap يشير إلى السطر المرقَّم.

المُخرجات. ترسم Canvas وPDF وعارض HTML وEPUB ذو التخطيط الثابت الأرقام. وفي PDF الموسوم تكون عناصر زخرفية (artifacts) في الإخراج، ويحمل كل منها /ActualText فارغًا، فينتقل النص المنسوخ أو المستخرج من سطر إلى سطر بدونها. ويخفيها مُخرَج HTML عن التقنيات المساعدة (aria-hidden) وعن التحديد وعن النص المنسوخ. أما EPUB المتدفق، الذي ينضّد نظام القراءة أسطره، فيحتفظ بأرقام الأبيات وحدها: عنصر span من الصنف pt-line-number (وaria-hidden هو أيضًا) في هامش البداية من المقطع، بجوار كل بيت يحمل رقمًا في النسخة المطبوعة. وفي VDT تكون الأرقام خانة تصميم في كل صفحة (page.lineNumbers، وكتل نصها معلَّمة بـ artifact) وقائمة علامات (page.lineNumberMarks: number وlabel وcolumnIndex وblockId وlineIndex)؛ ويسجّل المستند lastLineNumber.

غير مدعوم: أرقام الأسطر في النص العمودي، والإحالة المرجعية التي تطبع رقم سطر، والحواشي المربوطة بأرقام الأسطر، وأرقام أسطر خلايا الجداول والتعليقات وقوائم الشيفرة.

في Sandbox هذه الإعدادات هي قسم ترقيم الأسطر في لوحة التصميم. ودالتا الحل والتجريد مماثلتان لنظيراتهما في الأقسام الأخرى؛ والخط والوزن واللون تأتي من المتن:

import { DEFAULT_LINE_NUMBERS_CONFIG, resolveLineNumbersConfig, stripLineNumbersDefaults } from 'postext';
 
resolveLineNumbersConfig(config.lineNumbers, resolvedBodyText); // الخط والوزن واللون غير المحدَّدة تتبع المتن

#الإحالات المرجعية

تحدد الخاصية crossRefs الكلمات التي تطبعها الإحالة المرجعية حول رقم أو صفحة، والنمطَ الذي تأخذه :ref حين لا تحدد نمطًا. يحمل كل قالب {n} حيث يوضع الرقم؛ والقالب الذي يخلو منه يأتي الرقم بعده مسبوقًا بمسافة غير قابلة للكسر ("§" يطبع § 3.2). والقالب غير المعيَّن يتبع لغة المستند: chapter / section / p. بالإنجليزية، وcapítulo / sección / pág. بالإسبانية، و第{n}章 / 第{n}节 / 第{n}页 بالصينية، وهكذا للفرنسية والألمانية والإيطالية والبرتغالية والكتالونية والهولندية.

interface CrossRefsConfig {
  chapter?: string;  // Words around a level-1 heading's number: "chapter {n}".
  section?: string;  // Around any other heading's number: "section {n}".
  page?: string;     // Around a page number: "p. {n}".
  defaultStyle?: 'default' | 'number' | 'title' | 'page'; // A :ref without style=.
}

تأخذ الإحالات لون كل إحالة ووزن خطها وميلها (bodyText.referenceColor، referenceBold، referenceItalic).

#الاستشهادات

تختار الخاصية citations نمط الاستشهاد وطريقة ظهور الاستشهادات وقائمة المراجع. الترميز موصوف في الاستشهادات والمراجع؛ ويطبّق النمطَ الحزمةُ postext-citeproc.

interface CitationsConfig {
  style?: string;          // 'apa', 'ieee', 'chicago-notes-bibliography'… or 'custom'
  customStyle?: string;    // a whole CSL style (.csl XML), used with style: 'custom'
  locale?: string;         // CSL locale; the document language when unset
  link?: boolean;          // citations link to their entries
  marker?: 'style' | 'brackets' | 'parentheses' | 'superscript' | 'corner';
  collapseRanges?: boolean;
  notes?: 'footnote' | 'warichu';
  numbering?: 'book' | 'chapter';
  bibliography?: {
    title?: string;        // unset: the document language's word; '' or ' ': none
    scope?: 'book' | 'chapter';
    auto?: boolean;
    fontSize?: Dimension;
    lineHeight?: Dimension;
    hangingIndent?: Dimension;
    entrySpacing?: Dimension;
    labelWidth?: Dimension;
    labelAlign?: 'left' | 'right';
    doi?: 'link' | 'text' | 'hide';
    includeUncited?: boolean;
    groupByLanguage?: boolean;
  };
}

#جدول المحتويات

تضبط الخاصية toc ما يطبعه التوجيه :::toc (انظر صيغة المستند). تُجمَع المحتويات من مخطّط المستند (outline): كل عنوان برقمه وتسمية صفحته، وكل :::part؛ ولذلك تتبع الفصول: إن غيّرت اسم فصل، أو نقلته إلى جزء آخر، أو غيّرت مؤلفيه، تغيّرت المداخل معه. يتكوّن المدخل من رقم العنوان في عمود خاص به، ثم العنوان، ثم خط الإرشاد (leader) وتسمية الصفحة عند الحافة اليمنى، ثم سطر عنوان فرعي اختياري؛ أما الجزء فصفّ يصمّمه parts.design.

const config: PostextConfig = {
  toc: {
    levels: [{ level: 1, fontWeight: 700, color: { hex: '#00507b', model: 'hex' }, numberWidth: { value: 7.4, unit: 'mm' } }],
    unnumbered: { color: { hex: '#000000', model: 'hex' } },
    pageNumber: { fontWeight: 400, width: { value: 8, unit: 'mm' } },
    leader: { char: '.', gap: { value: 1, unit: 'mm' } },
    subtitle: { enabled: true, attr: 'author', italic: true, fontSize: { value: 8.5, unit: 'pt' } },
    parts: {
      height: { value: 23, unit: 'pt' },
      marginTop: { value: 11.5, unit: 'pt' },
      design: { elements: [/* a band box, 'SECTION {number}', '{titleText}', '{pageNumber}' */] },
    },
  },
};

تسميات الصفحات هي التي يطبعها المستند. يعيد buildDocument() إخراج المستند الذي يحوي :::toc بتسميات الجولة السابقة حتى تستقر (ثلاث جولات إضافية على الأكثر)؛ أما المضيف الذي يُخرج كتابًا فصلًا فصلًا فيقدّم بدلًا من ذلك مخطّط الكتاب كله في PostextContent.outline، مجمَّعًا من contentOutline() (العناوين والأجزاء من النص وحده) وoutlineFromDoc() (المداخل نفسها بتسميات الصفحات في إخراجٍ ما)، ويعيد إخراج فصل المحتويات كلما تغيّر outlineKey() لذلك المخطّط. يحمل كل مدخل عنوانٍ الرقمَ number الذي تطبعه المحتويات، ويحمل العنوان المرقّم كذلك counter الخاص به: العدّ الجاري لمستواه بعد أي startAt، أيًّا كان ما يطبعه القالب، وهو ما يعرضه المضيف بجانب الفصل في قوائمه الخاصة.

#الفهرس الأبجدي

تضبط الخاصية index ما يطبعه التوجيه :::index (انظر صيغة المستند): المصطلحات المعلَّمة بـ :index[…] و:index{term="…"} في النص، مرتّبةً ومجمّعةً حسب الحرف الأول (وفي الصينية حسب الحرف الأول من قراءة pinyin أو حسب عدد الضربات، وفي اليابانية حسب صف غوجوون، انظر groupBy)، ولكل منها الصفحات التي يقع فيها. يتكوّن المدخل من مصطلحه، ففاصل، فأرقام صفحاته؛ وتليه مداخله الفرعية، بخطوة إزاحة واحدة لكل مستوى، وتتدلّى أسطره الملتفّة بمقدار turnoverIndent فلا تصطفّ أبدًا مع مدخل فرعي.

const config: PostextConfig = {
  headingStyles: [
    // The index in two columns, under its own heading.
    { id: 'index', numbered: false, layout: { layoutType: 'double', gutterWidth: { value: 6, unit: 'mm' } } },
  ],
  index: {
    fontSize: { value: 8.5, unit: 'pt' },
    lineHeight: { value: 11, unit: 'pt' },
    rangeFormat: 'chicago',
    groups: { fontFamily: 'Source Sans 3', fontWeight: 700, color: { hex: '#8a1c1c', model: 'hex' } },
  },
};

تأتي أرقام الصفحات من مخطّط الكتاب، كما تأتي أرقام المحتويات: يُدرج computeOutline() وcontentOutline() علامات الفهرس في النص مداخلَ من النوع 'indexMark' (مع indexMark.path وsort وsee وseeAlso وmain وrange وindex)، ويعطي outlineFromDoc() كلًّا منها الصفحة التي وقعت عليها، وهي ما يسجّله البناء في doc.indexMarks ({ sourceStart, pageIndex } لكل علامة). يعيد buildDocument() إخراج المستند الذي يطبع فهرسه بنفسه حتى تستقر الأرقام؛ أما المضيف الذي يُخرج كتابًا فصلًا فصلًا فيسلّم الفصلَ الذي يحوي :::index مخطّطَ الكتاب كله في PostextContent.outline. يقسم tocOutline() وindexOutline() المخطّط إلى ما تقرؤه المحتويات وما يقرؤه الفهرس، ليتمكّن المضيف من ربط كل فصل بالجزء الذي يطبعه: فلا يعيد Sandbox إخراج فصل الفهرس إلا حين تتحرّك علامة، ولا فصل المحتويات إلا حين يتحرّك عنوان. ويخبر contentOutline() كذلك هل يطبع النص فهرسًا (hasIndex).