الإعدادات: الإطارات

#أنماط الإطارات

تُعرِّف الخاصية calloutStyles أنماط الإطارات (callouts) المسمّاة التي يطبّقها المستند بالحاوية :::callout{type="…"}: الملاحظات والنصائح والتحذيرات وأهداف التعلّم، وكل محتوى يُفصل عن النص الجاري في إطار ملوّن الخلفية أو محاط بحدّ. يأتي افتراضيًا نمط محايد واحد هو note (خلفية رمادية فاتحة، بلا حدّ ولا شريط جانبي (stripe) ولا أيقونة ولا عنوان)، فتعمل :::callout دون أي إعداد؛ وتعريف calloutStyles يستبدل هذه القائمة الافتراضية.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Note' },
    {
      id: 'objectives',
      name: 'Learning objectives',
      title: 'Objectives',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Warning',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};

:::callout{type="objectives"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
 
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::

#الحاوية :::callout

يفتح السطرُ :::callout{type="<id>"} الإطار، ويغلقه سطر فيه ::: وحدها. يقبل السياج خمس سمات: type (معرّف النمط)، وtitle (يتجاوز عنوان النمط)، وspan وplacement وcolumns (تتجاوز قيم النمط)؛ ويُخرَج المحتوى الواقع بينهما داخل الإطار: عنوان اختياري، ثم الفقرات أو القوائم أو الاقتباسات الكتلية أو الصيغ أو الموارد المضمّنة، وكلٌّ منها يُنضَّد بتنسيق body / lists من النمط (وتحتفظ العناوين بأنماطها المعتادة). تندمج الهوامش بين العناصر الأبناء كما في النص الجاري؛ ويخرج داخل الإطار عن شبكة خطوط الأساس، ثم يعود التدفق إليها بعد الإطار بمسافة لا تقل عن marginBottom تحته (الأولوية للشبكة، والهامش حدّ أدنى، وهو العرف نفسه الذي تتبعه الموارد). أما النمط ذو snapToGrid: false فيحتفظ بقيمة marginBottom الدقيقة بدلًا من ذلك، ويبقى النص الذي يلي الإطار خارج الشبكة حتى العنوان التالي أو نهاية القائمة. والعنوان الذي يسبق الإطار مباشرةً يبقى معه.

حدود هذا الإصدار:

• يُبقى الإطار كاملًا ما لم يحدّد نمطه keepTogether: false. فإن لم تتسع له المساحة المتبقية في العمود انتقل كاملًا إلى العمود أو الصفحة التالية، وكذلك يخرج من عمود فارغ قصّرته نطاقات العناصر العائمة أو حدّ أقصى للنطاق (band cap)، ما دام عمود كامل يتسع له. أما الإطار الأطول من عمود كامل فيُقسم بدلًا من ذلك، كالإطار القابل للتقسيم؛ ولا يوضع رغم ذلك ويفيض إلا الإطار الذي لا يقسمه أي قطع (شكل أو جدول أطول من العمود، أو splitMinLines لا يحقّقه أي قطع)؛ وعندئذ يسجّل الإخراج تحذير calloutOverflow (VDTDocument.warnings) يعرضه Sandbox. ومجموعة :::columns تُقطع كالإطار الذي يحيط بها، بين أعمدتها الفرعية (منذ postext 1.25)؛ ولا تبقى كاملة، فتفيض بالطريقة نفسها، إلا مع layout.flowColumns: false أو داخل إطار متداخل. والإطار القابل للتقسيم يترك الجزء الذي يتسع (عناصر أبناء كاملة، أو أسطر فقرة بما لا يقل عن splitMinLines على كل جانب، ويكفي الشكل أو الجدول أو الصيغة المنفصلة وحده لجانب) ثم يستمر في إطار بلا أيقونة في العمود أو الصفحة التالية، بلا عنوان ما لم يكرّره النمط، ومع علامة اختيارية تحت الجزء الذي يتركه (انظر علامات الإطار المقسوم).
• تُفسح العناصر العائمة المجال للإطار غير القابل للتقسيم. فحين تكون الكتلة التي تلي الإشارة إلى شكل مباشرةً إطارًا keepTogether، لا تُؤخذ الخانة التي لا تترك للإطار عمودًا من النطاق الحالي يستقر فيه (العمود الذي يحوي الإشارة أو عمود فارغ بعده، وكان يتسع له قبل العنصر العائم): ينتقل الشكل إلى خانته التالية، وهي عادةً الصفحة التالية، ويبقى الإطار في التدفق، كما يضعه المنضِّد، بدلًا من دفع الإطار خارج الصفحة وترك العمود للشكل وحده.
• في التخطيط متعدد الأعمدة يجعل span: 'page' الإطارَ كتلة ممتدة (span block): يُخرَج بكامل عرض المحتوى ويقسم الصفحة إلى نطاقات أعمدة، فتُغلق أعمدة النص فوقه عند خط القطع، ويأخذ الإطار عمودًا خاصًا به بكامل العرض، ويُفتح تحته نطاق جديد من أعمدة النص، فيستمر التدفق تحت الإطار في كل الأعمدة. وحيث تكون الأعمدة مستوية (في أعلى الصفحة، أو مباشرةً تحت عنوان افتتاحي span: 'page'، أو مباشرةً تحت كتلة ممتدة أخرى، أو مباشرةً تحت نطاق عائم علوي) يقطع الإطار هناك ببساطة. أما إذا ورد في منتصف الصفحة والأعمدة غير متساوية، فيُوضع كما يضعه المنضِّد: يُقطع النص فوقه قطعًا مستويًا عبر كل الأعمدة (يعيد المحرّك تنفيذ التوزيع وقد قُصّرت أعمدة النطاق إلى العدد نفسه من أسطر الشبكة، فيفيض النص من عمود إلى عمود على نحو طبيعي وتظل كل قواعد الأسطر اليتيمة والأرامل والإبقاء مع التالي سارية)، ويمتد الإطار على الصفحة، وتُستأنف الأعمدة تحته. ويتطلب القطع جولتين إضافيتين من التوزيع؛ وحين لا يترك خط القطع متسعًا للإطار مع الحدّ الأدنى لأسطر الأرملة من النص تحته، أو لا يتسع أي ترتيب بعد بضع محاولات، ينتقل الإطار إلى أعلى الصفحة التالية. ويلتزم النص فوقه بالقطع: الفقرة التي لا يمكن أن تبدأ في الأسطر القليلة التي يحتفظ بها عمود تحت شكل فوق القطع تنتقل إلى العمود التالي (فيقف الشكل وحده في عموده)، وحين تظل كتلة ما تتجاوز القطع، يُؤخذ القطع أدنى بسطر بدلًا من موضع انتهاء تلك الكتلة. والإطار المقسوم الذي يفتح النطاق يُقطع هناك أيضًا، فلا تتجاوز بقيته القطع أبدًا. ومع headings.balancing.beforeSpan (القيمة الافتراضية) يُقطع النطاق الذي يتركه خلفه قطعًا مستويًا، كالنطاق الذي يختم الفصل، وحين يسمح النمط بالتقسيم (keepTogether: false) يختم جزءُ الإطار الذي يتسع تحت الأعمدة المسوّاة الصفحةَ ويفتح الباقي الصفحة التالية؛ ومع beforeSpan: false تُوازن الصفحة التي يتركها كالمعتاد، دون فرض فاصل صفحة. والعنوان الذي يسبق الكتلة الممتدة مباشرةً لا ينتقل معها. وفي التخطيطات أحادية العمود يكون span: 'page' ببساطة داخل التدفق.
• placement: 'fixed' يُخرج الإطار من التدفق: يُخرَج الإطار (width: 'auto' يضيق على قدر العنوان، و'fill' يأخذ عرض عمود النص تحت نقطة الإرساء) ويُثبَّت في الصفحة التي يرد فيها ضمن التدفق، في الموضع الذي يصفه fixed.anchor / fixed.offset، وهو افتراضيًا الزاوية السفلية اليسرى من منطقة المحتوى. وتتخلى أعمدة النص التي يغطيها عن تلك المنطقة (تُقطع من الأسفل، أو من الأعلى إن كان العمود لا يزال فارغًا)، تمامًا كنطاق العناصر العائمة؛ وحين تكون المنطقة مشغولة بنص أو عنصر عائم أو كتلة ممتدة، ينتقل الإطار إلى الصفحة التالية. والإطار الثابت الذي يختم الفصل (أي تكون الكتلة التالية صفحة افتتاح فصل، أو :::part، أو إطارًا حاجزًا للعناصر العائمة، أو نهاية المستند) يسوّي أولًا الأعمدة فوقه (headings.balancing.trailing)، فتنتهي الصفحة الختامية القصيرة مستويةً مع الشارة تحتها. ويقع الإطار وأبناؤه في page.floats ويُرسمون خارج قصّ الأعمدة في كل مُخرِج.
• placement: 'top' | 'bottom' يعوّم الإطار كما يُعوَّم المورد: يغادر التدفق حيث يرد ويأخذ أول نطاق حرّ بعد تلك النقطة (قدم الصفحة الحالية مع 'bottom'، أو رأس الصفحة التالية التي يفتحها التدفق أو قدمها) بعرض العمود (span: 'column') أو بكامل عرض المحتوى (span: 'page')؛ ويملأ النص الذي يليه الصفحة التي غادرها. ويذهب إطاره وأبناؤه إلى page.floats، كما في الإطار الثابت. والإطار العائم الذي يتصدّر صفحة جديدة يوضع قبل الأشكال المنتظرة لتلك الصفحة، والشكل المذكور في صفحة سابقة الذي يتسع بعدئذ تحته يأخذ بقية تلك الصفحة حتى لو بقي أقل من ثلاثة أسطر نص (صفحة معرض: إطار وشكل، بلا نص بينهما). والإطار span: 'side' لا يطفو أبدًا: يتراصّ بجانب النص أيًّا كان موضعه. ومع columns أكبر من 1 (في النمط أو سمةً في السياج، منذ postext 1.18) يشغل الإطار span: 'column' هذا العدد من الأعمدة المتجاورة: رأس سلسلة من الأعمدة الفارغة التي تبدأ على مستوى واحد، أو أسفل العمود الحالي والأعمدة الفارغة التي تليه، كما في :::callout{placement="top" columns="2"}.
• width: 'auto' يضيق على قدر العنوان فقط، ويتجاهل العناصر الأبناء.
• :::callout المتداخل داخل إطار آخر إطار مستقل: يُخرَج بنمطه الخاص (الخلفية، والحدّ، ونصف قطر الزوايا، والحشوة، والشريط الجانبي، والعنوان، والأيقونة، والعلامة، واللسان، والتنسيق الطباعي) بكامل العرض الداخلي لأبيه ويتراصّ عنصرًا ابنًا واحدًا فيه، وتندمج marginTop / marginBottom الخاصة به مع جيرانه. ويُتجاهل span وplacement الخاصان به (من السياج أو من النمط)، فالإطار المتداخل يجري دائمًا داخل أبيه، ويُتجاهل كذلك floatBarrier وsnapToGrid. وتتداخل الإطارات إلى أي عمق، ويمكن أن تقع داخل مجموعة :::columns (كلٌّ منها كاملًا في عمود واحد). وحين ينقسم الأب، يقع القطع قبل الإطار المتداخل أو بعده، أو داخله إن سمح النمط المتداخل بالتقسيم؛ ويعيد كل جزء رسم الإطارات التي يقطعها، والإطار المتداخل المستمر من الجزء السابق يُسقط عنوانه وأيقونته، كتتمة الإطار في المستوى الأعلى.
• مجموعة :::columns{count=N} … ::: بين العناصر الأبناء تُخرج تلك العناصر في N أعمدة متساوية العرض، يفصل بينها columnGap، داخل الإطار: تُقطع السلسلة عند حدود الكتل أو الأسطر التي تسوّي الأعمدة على أفضل وجه (الفقرة أو عنصر القائمة المقطوع في منتصفه يستمر في رأس العمود التالي بلا نقطة تعداده)، ويبدأ كل عمود من أعلى المجموعة ويكون ارتفاع المجموعة بارتفاع أطول أعمدتها؛ وتعود العناصر التي تليها إلى كامل العرض. والإطار الذي ينقسم (keepTogether: false، أو الأطول من عمود) يقطع داخل المجموعة أيضًا، بين أعمدتها: فالمجموعة المتعرّجة (snake) تملأ أعمدتها واحدًا بعد آخر وتستمر في الجزء التالي، والمتوازية (breaks) تستمر تيارًا تيارًا (منذ postext 1.25؛ انظر صيغة المستند › :::columns). وتحلّ gap في السياج محلّ columnGap لتلك المجموعة، وترسم rule خطًا على طول كل فاصل بين الأعمدة. استخدمها لملخّص من عمودين للنقاط الرئيسية، أو لوضع جداول إطار عريض جنبًا إلى جنب.
• السمة السادسة للسياج، label، تُطبع على لسان التسمية في النمط (انظر label أعلاه): :::callout{type="box" label="BOX 1-1" title="The octet rule"}؛ ومن دون label في النمط تُتجاهل السمة.

في VDT يكون الإطار كتلة إطار type: 'callout' تقع زخرفته (الخلفية، والشريط الجانبي، والأيقونة، والعنوان) في designOverlay، تليها كتلها الأبناء في العمود نفسه؛ ويحمل الإطار وكل ابن containerId الخاص بالسياج. والإطار المتداخل كتلة إطار type: 'callout' مستقلة بين الأبناء، تليها كتلها؛ وهي تحتفظ بـcontainerId الخاص بسياج المستوى الأعلى (فيظل التوزيع والموازنة يريان وحدة واحدة) وتضيف calloutPath، أي معرّفات حاويات الأسيجة المتداخلة المحيطة بها، من الخارج إلى الداخل (ومعرّف الإطار المتداخل نفسه هو آخر مدخل). ويعطي ملف PDF الموسوم كل إطار متداخل عنصر Div داخل عنصر أبيه. وتُحلّ صور الأيقونات كما تُحلّ صور الموارد: سجل الصور في canvas، والخيار resourceImageUrl في HTML، ومزوّد resourceBytes في PDF.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => every inherited field filled from the resolved sections; the optional
//    locale picks the language of the continuation strings
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined for the built-in `note` default; static defaults dropped

#المبرهنات المرقّمة والبراهين

النمط الذي فيه numbering يعدّ إطاراته، كما تعدّ الحزمة amsthm في LaTeX بيئات المبرهنات (منذ postext 1.19). يطبع كل إطار تسميته ورقمه، «Theorem 2.» في أول فقرته الأولى، ويلي title السياج الرقمَ بين قوسين: يبدأ :::callout{type="theorem" title="Bradley–Terry"} بـ«Theorem 2 (Bradley–Terry).». والإطار الذي يُفتح بمعرّف ({#thm:main}) هدفٌ للإحالات، فتطبع «Theorem 2» (:ref{id="thm:main"})، ويطبع \ref{thm:main} أو style=number الرقم 2.

البرهان نمطٌ تسميته بلا رقم وله علامة ختام:

calloutStyles: [
  { id: 'theorem', numbering: { label: 'Theorem' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lemma', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definition' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Proof', counter: false, bold: false, italic: true } },
]

وفي كتاب يُخرَج فصلًا فصلًا تستمر العدّادات من الفصل السابق (LayoutContinuation.statementCounters، التي تملؤها continuationAfter)، ويعطي مخطّط الكتاب مرساة كل إطار مرقّم تسميتها (OutlineEntry.numberLabel)، فتطبعها الإحالة من فصل آخر.

#التنسيق الطباعي داخل الإطار

ينضّد الإطار محتواه بتنسيق body وlists الخاص به؛ وكل ما عدا ذلك يحتفظ بأنماط المستند:

• الفقرات تأخذ body الخاص بالإطار: الخط، والحجم، وتباعد الأسطر، واللون، وألوان التوكيد، والأوزان، وitalic، وsmallCaps، والمحاذاة، وتقسيم الكلمات بالواصلة، والإزاحة البادئة، والتباعد بين الفقرات. والحقل غير المُعيَّن يرث bodyText. ولون التوكيد الموروث يحتفظ بارتباطه بلوحة الألوان، فيتغيّر النص العريض والمائل وتسميات :ref داخل الإطار مع colorPalette كما تتغيّر خارجه. (حتى postext 1.4 كان النص العريض في الإطار يبقى #295AA3 أيًّا كان اللون الرئيسي.)
• القوائم النقطية تأخذ lists الخاص بالإطار (رمز التعداد، واللون، وحجم الرمز ووزنه، والإزاحة، والفاصل، والتباعد بين العناصر) فوق unorderedLists، ونصّها هو نص الإطار. وlists.bulletChar أو lists.color المختلف عن قيمة المستند (unorderedLists) يستبدل رمز التعداد أو اللون في كل المستويات؛ أما المكرِّر لقيمة المستند أو غير المُعيَّن فيترك لكل مستوى قيمته (unorderedLists.levels)، فتبقى الشرطات المتداخلة في الإطار.
• القوائم المرقّمة تأخذ lists.indent وgap وitemSpacing، وتأخذ lists.color متى حدّده النمط، حتى لو كان لون رموز التعداد في المستند؛ والنمط الذي لا يحدّده يُبقي الأرقام بلون orderedLists.color. (حتى postext 1.4 لم يكن اللون يصل إلى الأرقام إلا إذا اختلف عن unorderedLists.color، فلم يكن لتعيينه على ذلك اللون نفسه أي أثر.) أما الرقم نفسه (خطه وحجمه وفاصله) فيأتي من orderedLists العام، لأن lists لا يضم إلا حقول رموز التعداد: نسّق أرقام الإطار هناك.
• :::paragraphs داخل الإطار تستخدم نمط الفقرة الخاص بها، وكذلك في الإطارات المتداخلة. والحقول التي لا يحدّدها النمط ترث bodyText الخاص بالمستند، لا body الخاص بالإطار (ولا ميله ولا أحرفه الكبيرة الصغيرة).
• مجموعات :::columns لا نمط خاصًا بها: تتشارك الأعمدة كلها تنسيق نص الإطار وقوائمه، ويحدّد columnGap الفاصل بينها.
• الاقتباسات الكتلية تأخذ خط نص الإطار وحجمه وأوزانه (مائلة ورمادية، كما في النص الجاري)، وأحرفه الكبيرة الصغيرة. والعناوين تحتفظ بأنماط العناوين؛ والصيغ المنفصلة بإعدادات الرياضيات.
• الأشكال والجداول تحتفظ بأنماط التعليقات والجداول في المستند، بالعرض الداخلي للإطار؛ ويتبع وزناها العادي والعريض أوزانَ body في الإطار.
• الشارات (chips) تحتفظ بنمط الشارة الخاص بها؛ ويُقرأ حجم em نسبةً إلى حجم نص الإطار.
• :::space يُقاس بأسطر نص الإطار (انظر :::space لمعرفة المواضع التي يُسقط فيها).
• الإطار المتداخل يأخذ نمطه الخاص كاملًا؛ ويُتجاهل span وplacement وfloatBarrier وsnapToGrid الخاصة به.

#علامات الإطار المقسوم

حين ينقسم الإطار عبر الأعمدة أو الصفحات (keepTogether: false، أو إطار أطول من عمود)، يبدأ كل جزء بعد الأول بلا عنوان ولا أيقونة، ولا شيء افتراضيًا يخبر القارئ بأن الإطار مستمر. ويضيف خياران العلامات التي يستعملها الكتاب أو السيناريو:

• repeatTitle: true يكرّر العنوان في رأس كل تتمة، متبوعًا بـcontinuedSuffix، فيكون افتراضيًا «Key points (cont.)». ويأخذ العنوان المكرَّر نمط العنوان، فمع textTransform: 'uppercase' يعطي «HAMLET (CONT'D)» كما في السيناريو. وتبقى الأيقونة ولسان التسمية في الجزء الأول.
• continuesMarkerEnabled: true يضع continuesMarker («Continued»، أو «Continúa» في مستند إسباني) تحت السطر الأخير من كل جزء له تتمة، داخل الإطار، بخط نص الإطار وحجمه: مائلًا ما لم يكن continuesMarkerItalic مساويًا false، ومحاذيًا لليمين ما لم يحدّد continuesMarkerAlign القيمة 'left' أو 'center'. وتأخذ العلامة مساحة في الجزء الذي تختمه، ويُختار القطع بحيث تتسع لها.

calloutStyles: [{
  id: 'speech',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: "(CONT'D)",
  continuesMarkerEnabled: true,
  continuesMarker: '(MORE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::

ينتهي الجزء الذي يختم الصفحة بـ«(MORE)»، وتبدأ الصفحة التالية بـ«HAMLET (CONT'D)». وكلاهما من لوازم ترقيم الصفحات: في ملف PDF الميسَّر هما عنصران زخرفيان (artifacts)، وفي HTML يُخفيان عن التقنيات المساعدة، فيُقرأ العنوان مرة واحدة. وفي VDT هما كتلتا نص في designOverlay تحملان العلامة artifact: true.