> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/ar/mzyd-mn-almwdhwaat/22-how-tex-macros-actually-work-part-4.md). # كيف تعمل وحدات TeX الماكرو فعليًا: الجزء 4 [الجزء 1](/latex/ar/mzyd-mn-almwdhwaat/19-how-tex-macros-actually-work-part-1.md) [الجزء 2](/latex/ar/mzyd-mn-almwdhwaat/20-how-tex-macros-actually-work-part-2.md) [الجزء 3](/latex/ar/mzyd-mn-almwdhwaat/21-how-tex-macros-actually-work-part-3.md) [الجزء 4](/latex/ar/mzyd-mn-almwdhwaat/22-how-tex-macros-actually-work-part-4.md) [الجزء 5](/latex/ar/mzyd-mn-almwdhwaat/23-how-tex-macros-actually-work-part-5.md) [الجزء 6](/latex/ar/mzyd-mn-almwdhwaat/24-how-tex-macros-actually-work-part-6.md) ## مقدمة ونظرة عامة في الأجزاء 1–3 تعمقنا في بعض التفاصيل الخلفية منخفضة المستوى تمهيدًا لفهم كيفية عمل وحدات ماكرو TeX. في هذا المقال سنأخذ “نفسًا من الهواء” لمراجعة بعض المبادئ العملية الأساسية لوحدات ماكرو TeX استعدادًا للغوص العميق مرة أخرى في الجزأين 5 و6. طوال هذا المقال سنعرض أمثلة لوحدات ماكرو مُعرَّفة باستخدام الأمر البدائي في TeX `\def`: لن نستخدم الأمر، الذي قد يكون أكثر ألفة، في LaTeX `\newcommand`، وهناك سبب وجيه جدًا لذلك: هدفنا هو فهم المبادئ الأساسية الكامنة وراء سلوك وحدات الماكرو في TeX، ولكن لفعل ذلك نحتاج إلى استخدام الأوامر الأساسية *المضمنة في* برنامج TeX. أوامر LaTeX، مثل `\newcommand`، هي نفسها وحدات ماكرو: أوامر ذات سلوك مبرمج محدد تُبنى، في نهاية المطاف، من طبقات من أوامر TeX البدائية منخفضة المستوى. ولنفهم السلوك الأساسي لـ TeX بشكل أفضل علينا استخدام البدائيات الخاصة بـ TeX، لا وحدات ماكرو LaTeX. ### إلى أين نتجه؟ في الجوهر، نعمل نحو شرح لوحدات الماكرو باعتبارها شكلًا متخصصًا من قائمة رموز: عندما تطلب من TeX تعريف وحدة ماكرو فإنه ينشئ تسلسلًا من الرموز (قائمة رموز) ويخزنها في ذاكرته مرتبطة باسم تحدده. في الجزأين 5 و6 سننظر في قوائم رموز وحدات الماكرو بتفصيل أكبر، ولكن إذا كنت تفضل الانتقال من هذا المقال لقراءة بعض المعلومات الخلفية فيمكنك العثور عليها في [ما هي قائمة رموز TeX؟](/latex/ar/mqalat-mtamqh/54-what-is-a-tex-token-list.md) تتضمن قوائم الرموز لوحدات الماكرو، ومعلماتها، بعض اللمسات الإضافية التي سنفصلها خطوة خطوة—مع استخدام الكثير من الأمثلة. ولتفهم أفضل لسلوكيات معالجة وحدات الماكرو في TeX، هناك عامل رئيسي واحد يجب تذكره: TeX يفكر في الأحرف فقط في المرحلة الأولى جدًا من معالجة الإدخال: ومن تلك النقطة فصاعدًا تكون كلها رموزًا! وخلال هذا المقال، والمقالات المتبقية في هذه السلسلة، سنستكشف الدور الذي تلعبه الرموز في وحدات ماكرو TeX. ## الأجزاء الأربعة لوحدة ماكرو ### تذكير: معاملات الماكرو ووسائط الماكرو قبل أن نبدأ، يجدر بنا أن نذكر أنفسنا بالفرق بين *معاملات* وحدة الماكرو و *الوسائط*وسائطها، لأننا سنستخدم المصطلحين معًا طوال هذا المقال. لنفترض أنك عرّفت وحدة ماكرو \foo ``` \def\foo#1#2{هذا هو #1، وهذا هو #2} ``` البنى (الرموز) `#1`, `#2` (حتى `#9`تُسمّى *معاملات*معاملات وحدة الماكرو: فكّر فيها على أنها “عناصر نائبة” للبيانات الفعلية التي ستستخدمها عند استدعاء وحدة الماكرو: ``` \foo{alpha}{beta} ``` هنا، `alpha` و `beta` هما *الوسائط* الوسائط المستخدمة مع هذا الاستدعاء لـ \foo: وسائط وحدة الماكرو هي القيم الفعلية التي تُدخل في عناصر المعاملات النائبة (`#1`, `#2`... `#9`) المستخدمة عند تعريف وحدة الماكرو. ### تعريف وحدة ماكرو: لها 4 عناصر سنبدأ بما قد يبدو تعريفًا رسميًا قليلًا لوحدة ماكرو، لكنه يوفر إطارًا مفيدًا للمناقشات اللاحقة. يتكون أي تعريف لوحدة ماكرو من 4 أجزاء: ``` <بدائية ماكرو TeX><اسم الماكرو><نص المعامل>{<نص الاستبدال>} ``` حيث: * `<بدائية ماكرو TeX>`: أحد `\def`, `\edef`, `\gdef` أو `\xdef`; * `<اسم الماكرو>`: الاسم الذي يُعطى لأمر وحدتك الماكرو، مثل `\foo`; * `<نص المعامل>`: قد يكون هذا غائبًا، لكن إذا وُجد فإنه يكون سلسلة من *رموز* التي تظهر قبل `<نص الاستبدال>` لوحدة الماكرو. يمكن أن تحتوي `<نص المعامل>` على معاملات الماكرو (`#1`, `#2`... `#9`) وأنواع رموز أخرى. في الجوهر، وكما سنرى بالتفصيل، فإن `<نص المعامل>` يوفر نوعًا من *قالب الرموز* الذي يستخدمه TeX لمعرفة أي الرموز يريد المستخدم استخدامها كوسائط لوحدة الماكرو: عندما تستدعي وحدة ماكرو، فإن TeX يمرر *وسيط* الرموز إلى `<نص الاستبدال>` لوحدتك الماكرو (وهي أيضًا قائمة رموز); * `{<نص الاستبدال>}`: هذا هو الجسم الفعلي لوحدة الماكرو: إنه سلسلة من الرموز التي تُحقن فيها *الوسائط* عند معالجة وحدة الماكرو (توسيعها). تُمرَّر الوسائط إلى المواضع التي تحددها معاملات الماكرو المستخدمة في التعريف الأصلي. **ملاحظة**: طوال النقاش نفترض أن `<اسم الماكرو>` يتبعها حرف مسافة ذي رمز فئة 10 ليعمل كفاصل لإنهاء `<اسم الماكرو>`. نحن *لم* نُظهر صراحةً حرف المسافة هذا في نصنا/نقاشنا، لكننا نفترض أنه موجود. وبالتحديد، ينبغي أن نمثله شيئًا مثل هذا: ``` <بدائي ماكرو TeX><اسم الماكرو><مسافة><نص المعاملات>{<نص الاستبدال>} ``` ومع ذلك، سنحذف الإدراج الصريح لـ `<مسافة>` حرف، وسنفترض ضمنيًا وجوده. #### ملاحظات حول {} لقد عرضنا استخدام قوسين متعرجين اثنين: `{` و `}` اللذين يحيطان (يفصلان) بالجسم الفعلي لـ `<نص الاستبدال>`لوحدة الماكرو. ومع ذلك، فإن استخدام `{` و `}` هو مجرد اصطلاح متَّبع لأن ما يتوقعه TeX فعليًا هو أن يفتح نص وحدتك الماكرو `<نص الاستبدال>` بحرف ذي رمز فئة 1 (“ابدأ مجموعة”) ويُغلق بحرف ذي رمز فئة 2 (“أنهِ مجموعة”). وبالاصطلاح، فهذان هما `{` و `}` الحرفان على التوالي. ومع ذلك، يمكنك إذا أردت أن تخصص أي زوج من الأحرف للقيام بذلك. على سبيل المثال ``` \catcode`\(=1 \catcode`\)=2 ``` الآن، يمكنك تعريف وحدات ماكرو واستخدامها هكذا: ``` \def\foo #1(Hello, #1) \foo(World!) ``` ويمكنك أيضًا الاستمرار في استخدام `{` و `}` لأننا لم نغيّر رموز الفئات الخاصة بهما—يمكن أن تمتلك عدة أحرف، وفعليًا تمتلك، رمز الفئة نفسه، لذا يمكنك الاستمرار في تعريف وحدات الماكرو بالطريقة المعتادة: ``` \def\foo #1{Hello, #1} \foo{World!} ``` ### و {} المكونات من تعريف وحدة الماكرو الأكثر صلةً بنقاشنا هي `<نص المعامل>` و `{<نص الاستبدال>}`. عند تعريف وحدة ماكرو فإن `<نص المعامل>` هي، في الواقع، قالب رموز صارم يحدد كيفية استخدام وحدة الماكرو. وكما ذُكر، `<نص المعامل>` يمكن أن تكون فارغة، مثلًا، `\def\foo{Some text}` حيث لا يظهر شيء بين اسم الأمر (`\foo`) والقوس المعقوف الافتتاحي `{` الذي يعلن هنا بداية `<نص الاستبدال>`. **ملاحظة**: قد يعرف بعض القراء آلية “hashquote” في TeX (`#{`) لكننا لن نتطرق إليها هنا. ### وفواصل الماكرو هذا المقال بعينه ليس مصممًا كمراجعة شاملة تمامًا لكتابة وحدات الماكرو، لكنه يستحق مراجعة قصيرة، مع بعض الأمثلة، تُظهر أن `<نص المعامل>` يمكن أن يصبح `<نص المعامل>` أن تحتوي على: * **معاملات الماكرو**: (`#1`, `#2`,... `#9`) التي تعمل كـ“عناصر نائبة” للقيم التي سيوفرها المستخدم عند تشغيله وحدة الماكرو— *الوسائط*; * **رموز الفاصل**: رموز اعتباطية، متداخلة بين/حول رموز المعاملات، وتُستخدم لتحديد الحد الفاصل بين معاملات الماكرو. يمكنك التفكير في تلك الفواصل على أنها تُشكّل نوعًا من “الترقيم” الذي يجعل `<نص المعامل>` قالب رموز” ستحتاج إلى اتباعه عندما تستخدم وحدة الماكرو. لا تُطبَع رموز الفاصل. فما الذي يعنيه هذا فعليًا—لننظر إلى بعض الأمثلة. الـ `<نص المعامل>` تقع بين اسم وحدة الماكرو والقوس المعقوف الأيسر `{` لتعريف وحدة الماكرو. #### الفواصل: المثال 1 لنفترض أننا نعرّف وحدة ماكرو بسيطة `\foo` كما يلي: ``` \def\foo ABC{hello, there} ``` * `<نص المعامل>` = `ABC` * لا توجد رموز معاملات (`#1`, `#2`,... `#9`) * الفواصل هي *الرموز الثلاثة الأحرف* `ABC` لكنها في هذا المثال زائدة إلى حد ما، وتُستخدم فقط كمثال. الرموز الثلاثة الأحرف `ABC` تُعامل كفواصل: ليست شيئًا يُطبَع بل “ترقيمًا” يُتوقع أن يكون حاضرًا عند استدعاء وحدة الماكرو—عندما تستخدم وحدة الماكرو `\foo` يجب أن توفر الفواصل نفسها التي كانت موجودة عند تعريفها. إذا كتبت `\foo ABC` داخل نصك فسيتم تنضيد `hello, there`—رموز الأحرف `ABC` لا تُطبَع، لكن TeX قام، بعناية شديدة، بالتحقق من أنها كانت موجودة في استدعائك لـ `\foo`. يبحث TeX عن تلك الفواصل (“الترقيم”) ويزيلها (يمتصها) كما ترى في صورة شاشة Overleaf التالية: `ABC` لا يُطبَع: ![Overleaf يشغّل وحدة ماكرو في TeX](/files/5a402b0bcb0883bedb62ee35ebedfb1f20d1a6de) إذا حاولت استخدام `\foo` من دون `ABC` فواصل، فسيشتكي TeX `استخدام \foo لا يطابق تعريفه.`: ![عرض خطأ في TeX على Overleaf](/files/e55657eb7bae8062e83ae70d6a74fdbc7d63c3a4) في المثال أعلاه، بعد اكتشاف `\foo` يتوقع TeX رؤية الرموز الثلاثة الأحرف `ABC` لكنّه لا يرى ذلك: بل يرى رمز الحرف لـ `w` ويكتشف على الفور أن هناك شيئًا خاطئًا. #### الفواصل: المثال 2 الحقيقة المثيرة للاهتمام، وربما المفاجئة، هي أن الفواصل يمكن أن تكون رموز أوامر اعتباطية—including أوامر لم *تُعرَّف حتى*. على سبيل المثال، يمكننا تعريف `\foo` كما يلي: ``` \def\foo A\bob B\anne{Hello \TeX{}} ``` * `<نص المعامل>` = `A\bob B\anne` * لا توجد رموز معاملات (`#1`, `#2`,... `#9`) * الفواصل هي الرموز `A\bob B\anne` لكن مرة أخرى، في هذا المثال، هي زائدة وتوجد فقط لأغراض النقاش. لاحظ أن `\bob` و `\anne` هي أوامر خيالية كانت *غير معرَّفة*—ولا حاجة إلى تعريفها. عندما تستدعي وحدة ماكرو، يفحص TeX `<نص المعامل>` الموجود *في استدعاء الماكرو* ويقارنه، رمزًا برمز، مع نسخة “قالب الرموز” *المخزنة في الذاكرة*—التي أُنشئت عند تعريف وحدة الماكرو. يفحص TeX *المستخدمة في استدعاء الماكرو* ويحوّل ببساطة أي أوامر يجدها هناك إلى قيمتها العددية كرموز: إنه لا يحاول تنفيذ تلك الأوامر، ولذلك لا يهم أن `\bob` و `\anne` لم تكن معرَّفة قط. إن TeX يستخدم ببساطة قالب الرموز المخزن في الذاكرة كدليل يمكّنه من معرفة أي الرموز في `<نص المعامل>` استدعاء الماكرو هي الوسائط الفعلية التي يجب تمريرها إلى `<نص الاستبدال>`. وكما ترى من مقطع شاشة Overleaf التالي، فإن أيًا من رموز الأحرف (`مشروع` و `B`) داخل `A\bob B\anne` لم يُطبَع، ولم تسبب أوامرنا غير المعرَّفة `\bob` و `\anne` أي مشاكل. وقد جرى *امتصاص* كل هذه الرموز بواسطة TeX أثناء مطابقته لاستخدامك لـ `\foo` مع التعريف (قالب الرموز) لـ `\foo` (قائمة رموز) المخزن في الذاكرة. ![Overleaf يشغّل وحدة ماكرو في TeX](/files/905c620c0fe83c47edc7fd22b29b868d0b3d475b) #### الفواصل: المثال 3 يمكنك أن تتخللها فواصل مختلفة (رموز أحرف، رموز أوامر) مع معاملات الماكرو، كما في هذا المثال: ``` \def\foo A\bob#1B\anne#2\jane#3bye!{Hello from \TeX{} to \#1=#1, \#2=#2 and \#3=#3} ``` * `<نص المعامل>` = `A\bob#1B\anne#2\jane#3bye!` * هناك 3 رموز معاملات للماكرو: `#1`, `#2`, `#3` * هذه المرة، تُفصل المعاملات (`#1`, `#2`, `#3`) بمزيج من الرموز: `A\bob#1B\anne#2\jane#3bye!` هنا، تكون قد زودت TeX، في الواقع، بقالب سيحاول مطابقة استدعائك لـ `\foo`: سيمر عبر استدعاء الماكرو الخاص بك، *رمزًا برمز*، ويتوقع أن يطابق (يجد): * الرمزين `مشروع` و `\bob` قبل أن `#1` * الرمزين `B` و `\anne` قبل أن `#2` * الرمز `\jane` قبل المعامل `#3` و *الأربعة رموز الأحرف* `b`, `y`,`e` و `!` بعد `#3`. **تذكّر**: يفكر TeX بالرموز لذا `bye!` هو *الأربعة رموز الأحرف*. هناك طريقتان يمكننا بهما استخدام هذه الوحدة—يمكننا وضع أي وسائط متعددة الرموز بين أقواس معقوفة لتوفير مجموعة: ``` \foo A\bob{This}B\anne{That}\jane{Other}bye! ``` ومع ذلك، فإن *ليس ضروريًا* لأن تعريف وحدتنا الماكرو يحتوي على فواصل توفر قالب رموز. يمكن لـ TeX استخدام ذلك القالب لانتقاء الرموز الخاصة بكل وسيطة من بين رموز هي فواصل فقط. يمكننا استخدام وحدة الماكرو لدينا هكذا: ``` \foo A\bob ThisB\anne That\jane Otherbye! ``` ويمكن لـ TeX انتقاء الوسائط لإنتاج النتيجة نفسها كما عند استخدام المجموعات `{...}`: ![Overleaf يشغّل وحدة ماكرو في TeX باستخدام الفواصل](/files/dec7bfa6529d5aa67ccc59a3860332d47e4ae6f8) لاحظ كيف استطاع TeX أن يحدد بدقة أي الرموز طابقت المعاملات `#1` و `#3`: ![Overleaf يشغّل وحدة ماكرو في TeX باستخدام الفواصل](/files/3005fb4ba9a6535ca297c6c56dfe965a317ec0de) #### الفواصل: المثال 4 (الأمر كله يتعلق بالرموز، لا بالأحرف!) فيما يلي مثال قصير يوضح أنه عند العمل مع وحدات الماكرو، من المهم أن نتذكر أننا حقًا في عالم *رموز* و **تحتوي** *محارف*… سنعرّف وحدة الماكرو القصيرة التالية حيث A وB حرفان يعملان كفواصل وكلاهما له رمز الفئة 11. يعمل هذا من دون مشاكل: ``` \documentclass{article} \begin{document} \def\foo A#1B{Hello, #1} \foo AGrahamB \end{document} ``` ويطبَع `Hello, Graham`. ومع ذلك، إذا غيّرت رمز الفئة لـ A أو B إلى شيء غير 11، فسيفشل استدعاء الماكرو. لنفترض أننا غيّرنا رمز الفئة لـ B إلى 12، باستخدام ``\catcode`B=12`` ونحاول استدعاء الماكرو مرة أخرى، كما من قبل: ``` \documentclass{article} \begin{document} \def\foo A#1B{Hello, #1} \foo AGrahamB % This works \catcode`\B=12\relax \foo AGrahamB \end{document} ``` ويفشل مع خطأ محيّر إلى حد ما: ``` هل تسارعت الحجة؟ GrahamB \end {document} ! انتهى الملف أثناء مسح استخدام \foo. <نص مُدرَج> \par <*> main.tex أظن أنك نسيت `}'، مما جعلني أقرأ ما بعد الموضع الذي أردتني أن أتوقف عنده. سأحاول التعافي؛ لكن إذا كان الخطأ خطيرًا، فمن الأفضل أن تكتب الآن `E' أو `X' وتصلح ملفك. ! توقف طارئ. <*> main.tex *** (أُلغيت المهمة، لم يتم العثور على \end صالح) ``` ![Overleaf يعرض خطأ في وحدة ماكرو TeX](/files/b479707d8a3a986ade78e02f1b6d9038b4cf09e0) للأسف، فإن اقتراح TeX الافتراضي لـ ``أظن أنك نسيت `}'`` هو **غير صحيح**، لأنه ليس ناتجًا عن قوس ناقص (`}`). #### ماذا حدث؟ يحاول TeX مطابقة `\foo` ماكرو *الاستدعاء* مع `\foo` ماكرو *التعريف* المخزن في ذاكرته. عندما تستدعي وحدة ماكرو تحتاج إلى وسيطة واحدة أو أكثر، يتعين على TeX أن يفحص (يمسح) استخدامك لوحدة الماكرو ليحدد *الوسائط* الذي تقدمه لتلك الوحدة. هنا، يتوقع TeX أن تكون الوسيطة محصورة بين A (رمز فئة 11) وB (رمز فئة 11). تذكّر: TeX يفكر بـ *رموز*, **تحتوي** *محارف*. قيم الرموز لـ A وB، $$\mathrm{T\_A}$$ و $$\mathrm{T\_B}$$ على التوالي، هي: $$\mathrm{T\_A = 256 \times 11 + 65 = 2881}$$ $$\mathrm{T\_B = 256 \times 11 + 66 =2882}$$ ومع ذلك، بينما يواصل TeX بحثه يرى B *لكن* والآن أصبح له رمز فئة 12، وينتج عن ذلك قيمة رمزية مختلفة: $$\mathrm{T'\_B= 256 \times 12 + 66 =3138}$$ في `\foo` في تعريف الماكرو، كانت القيمة الرمزية لـ B (المستخدمة كفاصل) هي 2882، لكن TeX يرى الآن قيمة رمزية 3138: يظن أن هذا مجرد رمز آخر مخصص للاستخدام في *وسيط* المقدَّمة إلى `\foo`. وبقدر ما يهم TeX، فإن الرمز الأخير من الوسيطة لم يُعثر عليه بعد، لذلك يذهب للحصول على رمز آخر في بحثه عن B ذي رمز الفئة 11. عندها، ولذا، تفشل وحدة الماكرو: ففي محاولته للعثور على الوسيطة، “يتجاوز” TeX ويبدأ في قراءة رموز لم تكن تنوي أن تصبح جزءًا من وسيطة `\foo` استدعاء الماكرو. وما يحدث بعد ذلك يعتمد على الرموز التي يكتشفها TeX بعد B—فهي ستطلق `هل تسارعت الحجة؟` أخطاءً في مثالنا، يتجاوز TeX الحد ويمتص تدفق الرموز `\end {document}` ويصل بسرعة إلى نهاية الملف، ومن ثم تظهر رسالة الخطأ: ``` ! انتهى الملف أثناء مسح استخدام \foo ``` ## الجزء 5 كما رأينا أعلاه، فإن `<نص المعامل>` القسم من تعريف وحدتنا الماكرو يمكن أن يتراوح من بسيط للغاية إلى مزيج معقد من معاملات الماكرو المتداخلة مع رموز الأحرف ورموز الأوامر التي تعمل كفواصل. يستطيع TeX معالجة المجموعات المختلفة من الرموز الموجودة في `<نص المعامل>` لاستخراج الوسائط المقدَّمة إلى وحدة ماكرو—وكشف متى نحاول استخدام وحدة ماكرو بشكل غير صحيح. وكيف يفعل ذلك هو موضوع المقال التالي في السلسلة. [الجزء 1](/latex/ar/mzyd-mn-almwdhwaat/19-how-tex-macros-actually-work-part-1.md) [الجزء 2](/latex/ar/mzyd-mn-almwdhwaat/20-how-tex-macros-actually-work-part-2.md) [الجزء 3](/latex/ar/mzyd-mn-almwdhwaat/21-how-tex-macros-actually-work-part-3.md) [الجزء 4](/latex/ar/mzyd-mn-almwdhwaat/22-how-tex-macros-actually-work-part-4.md) [الجزء 5](/latex/ar/mzyd-mn-almwdhwaat/23-how-tex-macros-actually-work-part-5.md) [الجزء 6](/latex/ar/mzyd-mn-almwdhwaat/24-how-tex-macros-actually-work-part-6.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/ar/mzyd-mn-almwdhwaat/22-how-tex-macros-actually-work-part-4.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.