> 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/mqalat-mtamqh/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md). # مقدمة إلى Kpathsea وكيف تبحث محركات TeX عن الملفات ## مقدمة تقدم هذه المقالة مقدمة حول كيفية تحديد محركات TeX للملفات اللازمة لتنضيد مستندك—باستخدام LaTeX أو أي حزمة ماكرو أخرى. وعلى الرغم من أن Overleaf يخفف عن المستخدمين تحديات إدارة تثبيت TeX ([TeX Live](https://www.tug.org/texlive/))، فإن الأساسيات الخاصة بكيفية بحث محركات TeX عن الملفات ستكون مفيدة/مثيرة للاهتمام إذا أردت إنشاء بنية مجلدات تساعدك على إدارة مشروعك في Overleaf. لماذا قد يكون ذلك صحيحًا؟ إذا خزنت بعض ملفات مشروعك في Overleaf داخل مجلدات، فقد لا يعثر LaTeX على تلك الملفات لأن محرك TeX (المترجم) قد لا *يعرف* أنه يحتاج إلى البحث في تلك المجلدات—وبالتالي لن يعثر على الملفات التي تحتويها. ولتجنب ذلك، يمكنك إنشاء ملف إعداد وإضافته إلى مشروعك يُسمّى [ملف latexmkrc](https://mg.readthedocs.io/latexmk.html#configuration-files) يمكن استخدامه لإخبار محرك TeX بأن مجلداتك موجودة وأن عليه البحث فيها. إذا أردت الانتقال مباشرة إلى مثال يوضح ملف latexmkrc، يمكنك قراءة هذه المقالة المساعدة: [كيفية استخدام latexmkrc مع Overleaf: أمثلة وتقنيات](/latex/ar/mqalat-mtamqh/28-how-to-use-latexmkrc-with-overleaf.md). قد لا يكون من الواضح فورًا كيف يعمل ملف latexmkrc هذا، أو لماذا يعمل. وإذا أردت معرفة السبب، وربما تطوير فهم أفضل لاستخدامه مع إمكانات إعداد إضافية لمشروعك، فتابع القراءة... في نهاية هذه المقالة سنمرّ على [مثال عملي](#kpathsea-and-texinputs-latexmkrc-file-to-the-rescue)—باستخدام معرفتنا بكيفية بحث TeX عن الملفات—لإنشاء ملف latexmkrc لإدارة المجلدات المتداخلة التي تحتوي على ملفات الرسوميات الخاصة بك. ## TeX والاستقلالية عن المنصة عندما أنشأ Knuth برنامج TeX، كانت الاستقلالية عن المنصة مبدأً أساسيًا يوجّه تصميمه وتنفيذه، وتنعكس تلك الفلسفة في جميع العمليات الداخلية لـ TeX (مثل استخدام الحسابات الصحيحة، ومعالجة السلاسل النصية «المحلية الصنع»، وإدارة الذاكرة، إلخ). وحتى اليوم، ما تزال الاستقلالية عن المنصة في محركات TeX الحديثة تثير الأسئلة والنقاشات في المنتديات العامة؛ على سبيل المثال، انظر هذا النقاش على tex.stackexchange: [هل XeTeX وLuaTeX يعتمدان على المنصة؟](https://tex.stackexchange.com/questions/94297/are-xetex-and-luatex-platform-dependent) الذي يحتوي على تعليقات وملاحظات أدلى بها عدد من خبراء TeX المعروفين. ومع ذلك، دعونا الآن نضع التفاصيل الدقيقة جانبًا ونلاحظ أن محركات TeX ما تزال تحتاج إلى أن تكون شديدة القابلية للنقل—أي قادرة على العمل على عدة أنظمة تشغيل وإنتاج نتائج «متطابقة». ومن الجوانب الأساسية للقابلية للنقل البحث عن الملفات بطريقة مستقلة عن المنصة. ## محركات TeX لا تبحث عن الملفات... حقًا!? لا، محركات TeX لا *تحرير* تبحث عن الملفات *بأنفسها*. عند معالجة `.tex` ملف قد يحدد محرك TeX الحاجة إلى فتح ملف معين، لكنه *يفوّض* مهمة العثور عليه إلى جزء آخر من البرمجيات يُسمّى [*Kpathsea*](https://tug.org/kpathsea/)؛ وهي مكتبة برمجية خارجية ليست جزءًا من *اللب* من الشيفرة المصدرية لمحركات TeX. وما يوفّره Kpathsea هو، في الواقع، واجهة برمجية ([واجهة برمجة التطبيقات](https://en.wikipedia.org/wiki/Application_programming_interface)) يمكن لمحركات TeX (بالإضافة إلى BibTeX وMetaPost وتطبيقات أخرى) استدعاؤها كلما احتاجت إلى فتح ملف معين: إذ يتولى Kpathsea العمل الفعلي المتمثل في تحديد موقع ذلك الملف. عندما كتب Knuth محرك TeX الأصلي—الذي تنحدر منه، في النهاية، جميع محركات TeX الأخرى—كانت مشكلة العثور على الملفات/فتحها تحديًا كبيرًا، ويرجع ذلك جزئيًا إلى اختلاف منظومة التقنية اختلافًا شديدًا في ذلك الوقت. وفي الحقيقة، يشير Knuth في الشيفرة المصدرية لـ TeX إلى إدخال/إخراج الملفات بوصفه «آفة القابلية للنقل» (انظر الصفحة 12، القسم 25 من [تيكس: البرنامج](https://www.amazon.co.uk/Computers-Typesetting-TeX-Program-TEX/dp/0201134373)). أدرك مجتمع TeX الحاجة إلى توحيد (تقييس) البحث عن الملفات في TeX—*والبرمجيات المرتبطة بـ TeX*—وقرر تزويد TeX بالأدوات اللازمة لذلك. ولمعالجة المشكلة الشائكة جدًا المتمثلة في إيجاد طريقة مستقلة عن المنصة للعثور على الملفات، كتب Karl Berry، وهو عضو بارز في مجتمع TeX، البرمجيات التي تحل مشكلة *المسار*-البحث: وهو حل سماه [**Kpathsea**](http://tug.org/texinfohtml/kpathsea.html)—وهو مشتق من **K**arl’s **المسار** **البحر**ث (انظر هذا [مقابلة مع Karl Berry](http://www.tug.org/interviews/berry.html)). يمكننا أن نلاحظ أنه يُسمّى K**المسار**sea وليس K**قابل للتحرير**لأنه، كما أن [الوثائق](http://tug.org/texinfohtml/kpathsea.html) يذكر، فهو مكتبة بحث عن \*المسارات\*. ومن المهم إدراك أن Kpathsea لا يُستخدم فقط بواسطة محركات TeX؛ فبرامج متعددة مرتبطة بـ TeX، بما في ذلك BibTeX وMetaPost، تستخدم Kpathsea أيضًا للبحث عن ملفات الإدخال. باختصار، كلما احتاجت ماكروات TeX/LaTeX إلى فتح ملف معين، فإن الأوامر التي تُبنى منها تلك الماكروات ستتحول، في النهاية، إلى تعليمات TeX منخفضة المستوى (بدائيات TeX) ينفذها محرك TeX فعليًا. وإذا تضمنت تلك التعليمات الحاجة إلى فتح ملف، فسيتصل محرك TeX بـ Kpathsea قائلًا، في الجوهر: «رجاءً اعثر على هذا الملف»؛ وإذا نجح ذلك البحث في Kpathsea فسيُفتح الملف. أما إذا لم يتمكن Kpathsea من تحديد موقع الملف، فسيُبلَّغ محرك TeX بذلك وسيتوقف التنفيذ ليظهر الخطأ الشهير `` ! لا أستطيع العثور على الملف `...` `` الحقيقة هي أن Kpathsea لا يستطيع العثور عليه. ### ملاحظات حول LuaTeX من الناحية الدقيقة، ينبغي أن نُحذّر في هذا القسم من أن LuaTeX يوفّر آلية للمستخدم لتقديم كود البحث عن الملفات الخاص به عبر استخدام *الاستدعاءات العكسية*. يتيح LuaTeX للمستخدمين كتابة دوال بلغة البرمجة Lua وتسجيلها مع LuaTeX بحيث يستدعي تلك الدالة المعرّفة من قبل المستخدم في مراحل معينة أثناء تنفيذ LuaTeX—ومن هنا جاء مصطلح *الاستدعاءات العكسية*هذا أسلوب قوي جدًا، ويمكن للقارئ المهتم العثور على مزيد من المعلومات في القسم 9 من [دليل LuaTeX المرجعي](http://www.pragma-ade.com/general/manuals/luatex.pdf) (في وقت كتابة هذا النص، يشير ذلك الرابط إلى LuaTeX 1.09). ### ملف إعداد Kpathsea: texmf.cnf يحتوي كل تثبيت لـ TeX على ملف نصي يُسمّى `texmf.cnf` وهو ملف إعدادات يستخدمه Kpathsea: ويحتوي على العديد من «متغيرات الإعداد» التي تحدد المسارات التي سيستخدمها Kpathsea للبحث عن أنواع مختلفة من الملفات التي قد تحتاجها محركات TeX (أو BibTeX وMetaPost وغيرها). كما سنرى أدناه، فإن «متغيرات الإعداد» هذه تحدد مسارات بحث مُنشأة مما يُسمّى *عناصر المسار*، باستخدام تراكيب ومتغيرات ومعلمات مختلفة لتعريف كل عنصر مسار باعتباره «قالبًا» يعالجه Kpathsea لتوليد المجلدات الفعلية الملموسة التي سيبحث فيها. لإعطائك مثالًا ملموسًا، إليك أحد متغيرات الإعداد التي تحدد مسارات البحث لخطوط OpenType—لا تقلق الآن بشأن معنى بناء هذا المسار: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` الأهم هنا هو أن الملف `texmf.cnf` (الذي يقرأه Kpathsea) يعرّف متغير إعداد يُسمّى `OPENTYPEFONTS` الذي يُستخدم لتحديد المسار/المسارات التي سيستخدمها Kpathsea للبحث عن خطوط OpenType. ولا يبدو الطرف الأيمن من علامة «=» مثل أي مسار تراه على جهاز عادي لأنه مُنشأ باستخدام متغيرات ومعلمات مختلفة لتعريف كل مسار على أنه «قالب» أو «مخطط» سيستخدمه Kpathsea لتوليد مجلدات حقيقية للبحث فيها. ### مفهوم «المسار» لدى Kpathsea لعل المفهوم الأساسي الذي ينبغي استيعابه هو تصور Kpathsea لـ«المسار»: البنية الأساسية التي يستخدمها Kpathsea لتحديد موقع ملف معين. وكما رأينا في `OPENTYPEFONTS` المثال أعلاه، فإن تصور Kpathsea للمسار يبدو مختلفًا جدًا عن المسارات التي اعتدنا استخدامها على أجهزة سطح المكتب أو الأجهزة المحمولة. وللاقتباس من [الوثائق](http://tug.org/texinfohtml/kpathsea.html#Searching-overview): > ... أن *مسار بحث* هو قائمة مفصولة بنقطتين رأسيتين من *عناصر المسار*، وهي أسماء مجلدات مع بعض «الإضافات الزخرفية». —لكن لاحظ أن الفاصلة المنقوطة (`;`) تُستخدم أيضًا للفصل بين *عناصر المسار*. لاحقًا سنشير بإيجاز إلى طبيعة بعض تلك «الإضافات الزخرفية». في `OPENTYPEFONTS` مثالنا توجد ثلاثة عناصر مسار، يفصل بينها كل منها باستخدام الفاصلة المنقوطة (`;`): ![صورة تُظهر عناصر المسار الموجودة في تعريف مسار Kpathsea](/files/4a9dd0fb87b74dd3831d9137063fe5f5aa482a2b) 1. `.` (أي المجلد الحالي) 2. `$TEXMF/fonts/{opentype,truetype}//` 3. `$OSFONTDIR//` لاحظ أن الشرطتين المائلتين المزدوجتين (`//`) في عنصر مسار تعني البحث في المجلدات الفرعية (بشكل تكراري). عادةً ما يحتوي `texmf.cnf` الملف على العديد من «متغيرات الإعداد» لتعريف مسارات البحث لأنواع الملفات التي يمكن لـ Kpathsea البحث عنها. ## Kpathsea: نظرة عامة موجزة جدًا Kpathsea مكتبة متقدمة—ذات كثير من التفاصيل الدقيقة والفروق—وحتى نظرة سريعة إلى [الوثائق](http://tug.org/texinfohtml/kpathsea.html) تُظهر بوضوح أننا لا نستطيع الخوض في جميع التفاصيل. ومع ذلك، يمكننا محاولة تقديم نظرة عامة عمّا تفعله—لمساعدتك على توجيه التفكير وتقديم نقطة انطلاق لمزيد من القراءة. ### الغرض الأساسي من Kpathsea كما هو مذكور في التوثيق، فإن الغرض الأساسي من Kpathsea هو «إرجاع اسم ملف من قائمة مجلدات يحددها المستخدم» وأن تلك المجلدات (مسارات البحث) تُحدَّد باستخدام «بعض الإضافات الزخرفية». ### تلك «الإضافات الزخرفية» إن «بعض الإضافات الزخرفية» المذكورة أعلاه تشمل معلمات ومتغيرات مختلفة يستخدمها Kpathsea لبناء مسارات البحث الخاصة به (أو «قوالب المسار») بحيث يمكنه تعريف المسارات بطريقة أكثر عمومية. عندما يكون محرك TeX قيد التشغيل فعليًا، يمكن لـ Kpathsea استخدام القيمة الحالية لتلك المعلمات/المتغيرات لتحديد المسارات الفعلية عبر استبدال تلك المتغيرات بقيمها الحقيقية (وقت التشغيل). ويمكنك بسهولة تمييز تلك المتغيرات (داخل عناصر المسار) لأنها تبدأ بـ `$` الرمز. وعليه نقول إن Kpathsea *يُوسّع* عنصر مسار، أي إنه يحوّل تلك المعلمات والمتغيرات: فيحوّل «قالب» المسار إلى الاسم الفعلي لمجلد واحد أو أكثر من المجلدات المادية التي سيبحث فيها عن ملف. وهذا يوفّر قدرًا كبيرًا من المرونة، ويعني أن Kpathsea قد يُنشئ قائمة من المجلدات المقابلة لعنصر مسار واحد—على سبيل المثال، إذا طُلب منه البحث في المجلدات الفرعية. ### العودة إلى مثال OpenType سنربط الخيوط المختلفة معًا ونستكشف `OPENTYPEFONTS` بقدرٍ أكبر قليلًا من التفصيل: ``` OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR// ``` لننظر في عنصري المسار التاليين `$TEXMF/fonts/{opentype,truetype}//` و `$OSFONTDIR//`. هنا يلاحظ Kpathsea استخدام الأقواس المعقوفة `{...}` ويتعامل مع `$TEXMF/fonts/{opentype,truetype}` على أنه يمثل *عنصرين* من عناصر المسار: 1. `$TEXMF/fonts/opentype//` 2. `$TEXMF/fonts/truetype//` وأن *المجلدات الفرعية* في كلا عنصري المسار ينبغي أيضًا البحث فيها (ويُشار إلى ذلك باللاحقة `//`). **ملاحظة**: راجع توثيق Kpathsea حول [توسيع المجلدات الفرعية](http://tug.org/texinfohtml/kpathsea.html#Subdirectory-expansion) للاطلاع على تنبيه مهم بشأن ترتيب البحث في المجلدات الفرعية، على أي مستوى، (إذ إن ذلك غير محدد). سنورد بعض الملاحظات حول `$TEXMF` أدناه. #### $OSFONTDIR// `$OSFONTDIR` هو متغير يجب تحديد قيمته كمتغير بيئة يحتوي على موقع تخزين الخطوط: وستعتمد القيمة الدقيقة، بالطبع، على نظام التشغيل المستخدم لتشغيل TeX. لاحظ أن اللاحقة هنا `//` تأمر Kpathsea بالبحث في المجلدات الفرعية عند البحث عن خطوط OpenType. التعريف الافتراضي لـ `OSFONTDIR` داخل `texmf.cnf` هي: ``` OSFONTDIR = /please/set/osfontdir/in/the/environment ``` لذا فهو بالتأكيد شيء تحتاج إلى ضبطه إذا أردت استخدامه—فإن متغير البيئة لديك سيُعطي الأولوية على هذا التعريف «الافتراضي» الموجود في `texmf.cnf`. إذا قمتَ بالفعل بتعيين متغير البيئة `OSFONTDIR` فحينئذٍ، أثناء التشغيل، أينما رأى Kpathsea `$OSFONTDIR` كجزء من عنصر مسار (في `texmf.cnf`) يمكنه استبدال المتغير `$OSFONTDIR` بالقيمة الفعلية المخزنة في متغير البيئة `OSFONTDIR`. وتذكّر أنه عند استخدامه داخل `texmf.cnf` عناصر المسار نحدد المتغير `$OSFONTDIR`—مع بادئة `$`—لإخبار Kpathsea بأن هذا متغير يجب أن *القيمة* يستخدمه. #### ملاحظات موجزة حول $TEXMF `TEXMF` هو متغير إعداد آخر مُعرّف في `texmf.cnf`؛ فعلى سبيل المثال، في التوزيعة الرئيسية لـ TeX Live سترى: ``` TEXMF = {$TEXMFAUXTREES$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST} ``` لا تحتاج إلى الانشغال بتفاصيل هذا التعريف لـ `TEXMF`—لن نستعرض كل التفاصيل، ولكن يكفي أن نلاحظ أن `$TEXMF` المتغير يُستخدم داخل عناصر المسار لأنه يعرّف سلسلة من المجلدات العليا (المشار إليها باسم «أشجار texmf») التي يمكنك من خلالها بدء البحث عن الملفات. `TEXMF` يكون مفيدًا جدًا إذا كنت تريد، أو تحتاج، إلى تقسيم تثبيت TeX عبر عدة مجلدات (أو «أشجار» مجلدات). على سبيل المثال، وجود مجموعة رئيسية أو أساسية من حزم TeX/LaTeX (مثل TeX Live) ومجموعة أخرى من الملفات والمجلدات تُستخدم لتخزين حزم LaTeX المحلية—أو ربما لتخزين ملفات إعداد محلية أو نسخ مخصصة من الحزم القياسية. إن تقسيم تثبيت TeX بهذه الطريقة قد يجعل من الأسهل إدارة ترقية المجموعة الرئيسية/الأساسية (التوزيعة) من حزم TeX/LaTeX لأن مجموعتك المحلية تكون منفصلة عن الملفات الرئيسية التي يتم تحديثها عند ترقية توزيع/تثبيت TeX Live لديك. للحصول على مزيد من التفاصيل حول إدارة تثبيتات TeX الأكثر تعقيدًا، يُحال القارئ المهتم إلى هاتين الورقتين: * [إدارة أشجار TDS متعددة](http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf) بقلم Michael J Downes؛ * [التعامل مع أشجار texmf](http://www.ntg.nl/maps/27/17.pdf) بقلم Siep Kroonenberg. #### بنية مجلدات TeX كل من أدار تثبيتًا لـ TeX يعرف أن أنظمة TeX الحديثة، مثل TeX Live، تحتوي على عشرات الآلاف من الملفات التي تشمل نطاقًا هائلًا من أنواع الملفات. وقد صُممت بنية مجلدات TeX (TDS) على أنها «مخطط» لأفضل الممارسات لتنظيم المجموعة الضخمة من الملفات في تثبيت TeX عامل، وهي موصى بها بشدة للاستخدام مع Kpathsea. للمزيد من المعلومات يُوجَّه القارئ إلى مواصفة TDS: [بنية دليل لملفات TeX](https://www.tug.org/tds/tds.pdf). ## أنواع ملفات Kpathsea تحتاج مجموعة التطبيقات التي تستخدم Kpathsea إلى الوصول إلى نطاق واسع من أنواع الملفات، لذا يستخدم Kpathsea «متغير إعداد» لتحديد المسار/المسارات لكل نوع من الملفات (أو مجموعة ملفات) يدعمه. ويحتوي التوثيق على الإنترنت على قائمة كاملة (انظر أيضًا [جدول الملخص أدناه](#table-listing-kpathsea-config-variables))، لكن فيما يلي «متغيرات الإعداد» لأنواع الملفات الأكثر شيوعًا: | | | | -------------------- | --------------------------------------- | | **متغير الإعداد** | **أمثلة على أنواع الملفات** | | TEXINPUTS | ملفات مصدر TeX وملفات الأشكال/الرسوميات | | BIBINPUTS, BSTINPUTS | ملفات مصدر ببليوغرافيا BibTeX | | TTFONTS | خطوط TrueType المتجهية | | OPENTYPEFONTS | خطوط OpenType المتجهية | `TEXINPUTS` هو متغير إعداد مهم بشكل خاص لأنه يحدد المكان الذي يحصل منه محرك TeX على ملفات المصدر المدخلة. لاحظ أن ملفات الصور تُعد ملفات إدخال ويمكن أيضًا البحث عنها باستخدام المسار المحدد بواسطة `TEXINPUTS`. ### بعض الفروق الدقيقة في Kpathsea كما ذُكر، لدى Kpathsea الكثير من الفروق الدقيقة التي لا يمكننا استعراضها هنا بالتفصيل. ومع ذلك، إليك بعض الميزات التي قد يرغب بعض القراء في استكشافها: * **قاعدة بيانات أسماء الملفات:** لتقليل عمليات البحث على القرص يمكن لـ Kpathsea الاستفادة من « [ملف قاعدة بيانات لأسماء الملفات يُسمّى ls-R](http://tug.org/texinfohtml/kpathsea.html#Filename-database) الذي يربط الملفات بالمجلدات». ويوفّر TeX Live واحدًا منها، بالإضافة إلى الأدوات اللازمة لتحديثه إذا أُضيفت ملفات جديدة. * **البيئة**، بالإضافة إلى «متغيرات الإعداد» (مثل `OPENTYPEFONTS` )، يستفيد Kpathsea أيضًا بذكاء من [البيئة](https://en.wikipedia.org/wiki/Environment_variable)؛ فعلى سبيل المثال، يمكن استخدام القيمة وقت التشغيل لمتغيرات البيئة لتعريف عناصر المسار في `texmf.cnf` الملف (وربما لتجاوز متغيرات بنفس الاسم المُعرَّفة في `texmf.cnf`). * **اسم البرنامج:** من الجوانب الدقيقة ولكن الأساسية في سلوك Kpathsea أنه يمكنه استخدام اسم البرنامج التنفيذي (مثل محرك TeX) لبناء تراكيب مسارات بحث خاصة بالبرنامج. وهذا يمنح قدرًا كبيرًا من المرونة لأن البحث في المسارات يمكن توجيهه إلى ملفات خاصة بمحرك TeX معين. على سبيل المثال، بالنسبة إلى LuaTeX/LuaLaTeX: ``` TEXINPUTS.lualatex = .;$TEXMF/tex/{lualatex,latex,luatex,generic,}// TEXINPUTS.luatex = .;$TEXMF/tex/{luatex,plain,generic,}// ``` * **العثور على `texmf.cnf`**، والسؤال الذي قد تطرحه هو: كيف يعرف Kpathsea أين `texmf.cnf` يتم تخزينه؟ والإجابة هي متغير بيئة يُسمّى `TEXMFCNF`. يجب ضبطه (على الجهاز/المنصة التي تشغّل TeX) على المسار حيث `texmf.cnf` يتم تخزينه. #### تصحيح مشاكل Kpathsea من غير المرجح أن يحتاج مستخدمو Overleaf إلى هذه الأدوات، لكننا نذكرها استكمالًا للفائدة: * **kpsewhich**: برنامج مستقل (مضمّن في TeX Live) يمكن استخدامه لاختبار إعداداتك: تحديد قيمة المتغيرات والعثور على الملفات. ويُحال القراء المهتمون إلى [التوثيق على الإنترنت](http://tug.org/texinfohtml/kpathsea.html#Invoking-kpsewhich) للحصول على مزيد من المعلومات. * **البيئة**: يدعم Kpathsea متغير بيئة يُسمّى [`KPATHSEA_DEBUG`](http://www.tug.org/texinfohtml/kpathsea.html#Debugging) للمساعدة في تصحيح سلوكه. يمكنك ضبط `KPATHSEA_DEBUG` على قيم مختلفة وفقًا لكمية معلومات التصحيح التي تحتاجها. إن ضبط `KPATHSEA_DEBUG=-1` سيُنتج *كمية كبيرة* من البيانات. ## وأخيرًا: المجلدات وملفات الأشكال وlatexmkrc إذًا، ما علاقة ما سبق بـ latexmkrc؟ إذا قرأت هذه المقالة [كيفية استخدام latexmkrc مع Overleaf: أمثلة وتقنيات](/latex/ar/mqalat-mtamqh/28-how-to-use-latexmkrc-with-overleaf.md) فسترى أن شيفرة (Perl) في مثال latexmkrc تضبط قيمة متغير بيئة `TEXINPUTS`: ``` $ENV{'TEXINPUTS'}='./tex//:' . $ENV{'TEXINPUTS'}; ``` لاحظ أن النقطتين الرأسيتين (:) المستخدمة هنا (`./tex//**:**`) هي *شديدة* مهمّة. إذا حذفتَ تلك النقطتين الرأسيتين فقد يعجز TeX/LaTeX عن العثور على ملفات النظام الحيوية، مثل حزم LaTeX! ما يفعله ملف latexmkrc هذا، في الواقع، هو إضافة مسار مجلد علوي (`./tex` في المثال أعلاه) إلى المتغير المحدد من النظام `TEXINPUTS` لمتغير البيئة بحيث عندما يستخدم Kpathsea المتغير `$TEXINPUTS` فسيدرك حينها أن المجلد `/tex//` ينبغي البحث فيه للعثور على ملفات الإدخال. وإذا نظرت بعناية فسترى أن المسار الفعلي المستخدم هو `./tex//:` موقع `//` يأمر Kpathsea بالبحث في مجلد tex بشكل تكراري—أي النظر داخل أي مجلدات فرعية موجودة في `tex` المجلد. وكما ذُكر، أضفنا أيضًا رمز النقطتين الرأسيتين المهم. يمكننا استخدام التقنية نفسها تمامًا لملفات الأشكال. ### ملاحظة جانبية حول BibTeX كما ذُكر، يستخدم برنامج BibTeX أيضًا Kpathsea للبحث عن ملفات الإدخال الخاصة به؛ وعلى وجه الخصوص: * موقع `BSTINPUTS` متغير الإعداد (مسار البحث) يُستخدم للبحث عن `.bst` الملفات؛ * و `BIBINPUTS` متغير الإعداد (مسار البحث) سيُستخدم للبحث عن `.bib` ملفات .bib. إذا أضفتَ ملفات `.bst` أو `.bib` جديدة إلى مشروع Overleaf لديك، يمكنك استخدام التقنية أدناه لتوجيه BibTeX إلى مكان العثور على هذه الملفات—عليك استبدال `TEXINPUTS` مع `BSTINPUTS` و/أو `BIBINPUTS`. ### TEXINPUTS واستخدام مجلدات متداخلة لملفات الرسوميات إذا كان مشروعك يحتوي على الكثير من ملفات الرسوميات فقد يكون من الملائم إنشاء مجموعة من المجلدات لتخزينها وإدارتها. فعلى سبيل المثال، تُظهر لقطة الشاشة التالية قسمًا من مشروع Overleaf يستخدم مجلدًا علويًا يُسمّى **`graphics`**: ![صورة تُظهر مجلدات متداخلة في مشروع Overleaf](/files/8f18612f687f5e0ca1eba160d73055ee9fc65304) هناك العديد من المجلدات الفرعية (المتداخلة) التي تحتوي على رسوميات لأقسام مختلفة من مستندنا. لنفترض أن لدينا بنية المجلد أعلاه ونريد استخدام `graphicx` الحزمة (`\usepackage{graphicx}`) وأننا نحاول فعل ذلك بهذه الطريقة: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% من أفضل الممارسات عدم استخدام امتداد الملف \end{document} ``` لن ينجح الأمر وستحصل على خطأ مثل هذا: ``` ! خطأ LaTeX: لم يتم العثور على الملف `endlinechar'. l.4 \includegraphics{endlinechar} لم أتمكن من العثور على الملف بأيٍّ من هذه الامتدادات: .pdf,.PDF,.ai,.AI,.png,.PNG,.jpg,.JPG,.jpeg,.JPEG,.jp2,.JP2,.jpf,.JPF,.bmp,.BMP, ,.ps,.PS,.eps,.EPS,.mps,.MPS,.pz,.eps.Z,.ps.Z,.ps.gz,.eps.gz ``` ينشأ هذا الخطأ لأن ملف الرسوميات الخاص بنا مخزن في موقع لا يعرفه TeX/LaTeX (وKpathsea)، وبالتالي لا يمكنه العثور عليه—والمسار إلى ملف الرسوميات هو: ``` ./graphics/Introduction/Chapter1/Section1/Subsection3/endlinechar.png ``` **ملاحظة**، ومن المتعارف عليه عمومًا كأفضل ممارسة أن ***تتجنب أحرف المسافة في أسماء المجلدات***. ورغم أنه من الممكن بالتأكيد وجود مسافات في أسماء المجلدات، وباستخدام التقنيات الموضحة أدناه، فإننا نحذّر من ذلك لأسباب تتعلق بقابلية نقل المستند خارج منصة Overleaf. كما هو موضح في هذه [مقالة مساعدة من Overleaf](/latex/ar/mzyd-mn-almwdhwaat/27-inserting-images.md) يمكنك، بالطبع، استخدام المجلدات لتخزين الرسوميات، لكن عليك إخبار LaTeX بمكان تخزينها. هنا سننظر في حلين: * استخدام الأمر \graphicspath; * باستخدام معرفتنا بـ Kpathsea و `TEXINPUTS`. ### استخدام \graphicspath ال `graphicx` توفر الحزمة `\graphicspath` الأمر الذي يمكنك استخدامه لإعلان المسارات التي توجد فيها رسومياتك؛ لذا يمكننا فعل شيء كهذا: ```latex \graphicspath{{./graphics/Introduction/Chapter1/Section1/Subsection3/}} ``` وسيعثر LaTeX الآن على أي رسوميات مخزنة تحت ذلك المسار. **ملاحظة**، إذا *يجب* كانت لديك مسافات في أسماء المجلدات، فستحتاج إلى وضع المسارات بين علامتي اقتباس مزدوجتين (`"..."`): ```latex \graphicspath{{"./graphics/Introduction/Chapter 1/Section 1/Subsection 3/"}} ``` **ملاحظة**، ويمكنك إعلان مسارات متعددة هكذا: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` حيث `...` تعني مسارات إضافية موضوعة بين أقواس معقوفة. **ملاحظة**، ونبدأ المسار بـ `./graphics` وليس فقط `/graphics`. تشير النقطة (.) إلى نظام التشغيل بأن المسار نسبي إلى مجلد العمل الحالي. ال `\graphicspath` يعمل الأمر بشكل جيد، ولكن إذا كان لديك العديد من المجلدات فقد يصبح من الممل جدًا إضافة كل مسار؛ بالإضافة إلى ذلك، فإن المسارات المُعرَّفة عبر `\graphicspath` لن تعود تعمل إذا أعدتَ تسمية المجلدات أو إعادة هيكلتها. هل توجد طريقة أسهل؟ نعم، يمكنك استخدام ملف latexmkrc! #### \graphicspath والبحث التكراري (المجلدات الفرعية) لاحظ أن هناك نقاشات/مجادلات على الإنترنت حول ما إذا كانت بعض الأنظمة تدعم/تُمكّن `\graphicspath` البحث التكراري في المجلدات الفرعية إذا أضفت `//` في نهاية المسار: انظر، على سبيل المثال، هذه النقاشات على tex.stackexchange: * [البحث التكراري في \graphicspath في LaTeX](https://tex.stackexchange.com/questions/25443/latex-graphicspath-recursive-search); * [\graphicspath لـ MikTeX](https://tex.stackexchange.com/questions/3131/graphicspath-for-miktex). لأقصى قدر من التوافق، ينبغي أن تفترض أن `\graphicspath` لا يدعم البحث التكراري في المجلدات. ### Kpathsea وTEXINPUTS (ملف latexmkrc ينقذ الموقف) **تنبيه:** لاحظ أن التقنية التالية تعمل جيدًا على Overleaf وعلى تثبيتات TeX المحلية المُهيأة بشكل مناسب؛ **لكن** إذا استخدمتَ ملف latexmkrc فقد يصبح مشروعك غير متوافق مع تثبيتات TeX الأخرى، مثل تلك المستخدمة من قبل الناشرين وأنظمة تقديم المجلات عبر الإنترنت. قد تدعم تثبيتات TeX التابعة لجهات خارجية استخدام latexmkrc أو قد لا تدعمه. إذا كنت بحاجة إلى تصدير مشروع Overleaf لاستخدامه في مكان آخر، أو أردت تقديمه إلى مجلة، فيجب أن تزيل أي أحرف مسافة من أسماء المسارات، ولتحسين التوافق، أضف `\graphicspath` أمرًا يعرّف جميع المسارات: ```latex \graphicspath{{path1}{path2}{path3}...{pathN}} ``` حيث `...` تعني مسارات إضافية موضوعة بين أقواس معقوفة. التقنية الموضحة أدناه (باستخدام `TEXINPUTS`) تم اختبارها بنجاح على Overleaf مع محركات pdfTeX وXeTeX وLuaTeX (أي خيارات المترجم pdfLaTeX وXeLaTeX وLuaLaTeX في قائمة Overleaf): ![صورة تُظهر كيفية اختيار مترجم LaTeX على Overleaf](/files/3b19d3fd6d957e407e8da5845364f2195fb2c70e) بالعودة إلى مثالنا، نريد استخدام هذه الشيفرة (مع مجلدات متداخلة بعمق) وسنستخدم ملف latexmkrc لتحقيق ذلك: ```latex \documentclass{article} \usepackage{graphicx} \begin{document} \includegraphics{endlinechar}% من أفضل الممارسات عدم استخدام امتداد الملف \end{document} ``` إليك لقطة شاشة تُظهر أن الشيفرة أعلاه تعمل دون مشاكل: لقد وجد LaTeX ملف الرسوميات الخاص بنا (`endlinechar.png`) رغم أنه موجود في بنية مجلدات متداخلة بعمق (من دون أي مسافات في أسماء المجلدات). ![صورة تُظهر مشروعًا بمجلدات متداخلة وهو يُترجم على Overleaf](/files/269493ef7079951473d665a1711de460a0bfb606) إذًا، كيف فعلنا ذلك؟ كل ما عليك فعله هو: * إنشاء ملف جديد، من دون امتداد، وتسميته latexmkrc؛ * إضافة السطر التالي إلى ذلك الملف: ``` $ENV{'TEXINPUTS'}='./graphics//:'.$ENV{'TEXINPUTS'}; ``` سيعرف Kpathsea الآن المجلدات الموجودة تحت `**الرسومات**` وَبسبب `//` فإنه سيفحص المجلدات الفرعية أيضًا. لاحظ مرة أخرى أن النقطتين الرأسيتين في `./graphics//:` هي في الواقع *شديدة* مهمّة. إذا حذفتَ تلك النقطتين الرأسيتين فقد يعجز TeX/LaTeX عن العثور على ملفات النظام الحيوية، مثل حزم LaTeX! وباستخدام مثال المشروع البسيط أعلاه، يمكنك الآن تجميعه ثم voilà! يعثر LaTeX على ملف الرسومات الخاص بك — ويمكنك إعادة تسمية المجلدات أو إعادة تنظيمها تحت /graphics، ولن يمنع ذلك LaTeX من العثور عليها. ## جدول يسرد «متغيرات إعداد Kpathsea» الجدول التالي ملخص مستخلص من [البيانات المدرجة في وثائق Kpathsea](http://tug.org/texinfohtml/kpathsea.html#Supported-file-formats). | | | | | --------------------------------------------------- | ----------------------------------------------------- | ------------------------------ | | **متغير إعداد Kpathsea** | **وصف نوع الملف** | **لاحقة الملف** | | AFMFONTS | مقاييس خطوط Adobe | .afm | | MFBASES, TEXMFINI | تفريغ ذاكرة Metafont | .base | | BIBINPUTS, TEXBIB | المصدر الببليوغرافي لـ BibTeX | .bib | | BLTXMLINPUTS | ملفات ببليوغرافيا BibLaTeXML لـ Biber | .bltxml | | BSTINPUTS | نمط BibTeX | .bst | | CLUAINPUTS | مكتبات ديناميكية لـ Lua | .dll و .so | | CMAPFONTS | ملفات خرائط المحارف | .cmap | | TEXMFCNF | ملفات الإعداد أثناء التشغيل | .cnf | | CWEBINPUTS | ملفات إدخال CWEB | .w، .web، .ch | | TEXCONFIG | ملفات Dvips 'config.\*'، مثل config.ps | | | ENCFONTS | متجهات الترميز | .enc | | TEXFORMATS, TEXMFINI | تفريغ ذاكرة TeX | .fmt | | FONTCIDMAPS | تعيين CJK | .cid | | FONTFEATURES | أساسًا لميزات خطوط OpenType | .fea | | FONTS, GFFONTS, GLYPHFONTS, TEXFONTS | رستر خطوط عام | .gf | | TEXPICTS, TEXINPUTS | أشكال Encapsulated PostScript | .eps, .epsi | | TEXINDEXSTYLE, INDEXSTYLE | ملفات نمط makeindex | .ist | | LIGFONTS | ملفات تعريف الربط الحرفي | .lig | | TEXMFDBS | قواعد بيانات أسماء الملفات | | | TEXFONTMAPS | خرائط الخطوط | .map | | MPMEMS, TEXMFINI | تفريغ ذاكرة MetaPost | .mem | | MPSUPPORT | ملفات دعم MetaPost، المستخدمة بواسطة DMP | | | MFINPUTS | مصدر Metafont | .mf | | MFPOOL, TEXMFINI | سلاسل برنامج Metafont | .pool | | MFTINPUTS | ملف نمط MFT | .mft | | MISCFONTS | ملفات متعلقة بالخطوط لا تندرج تحت الفئات الأخرى | | | MLBIBINPUTS, BIBINPUTS, TEXBIB | مصدر ببليوغرافيا MlBibTeX | .mlbib, .mlbib | | MLBSTINPUTS, BSTINPUTS | نمط MlBibTeX | .mlbst, .bst | | MPINPUTS | مصدر MetaPost | .mp | | MPPOOL, TEXMFINI | سلاسل برنامج MetaPost | .pool | | OCPINPUTS | ملفات العمليات المترجمة لـ Omega | .ocp | | OFMFONTS, TEXFONTS | مقاييس خط Omega | .ofm, .tfm | | OPENTYPEFONTS | خطوط OpenType | | | OPLFONTS, TEXFONTS | قوائم خصائص Omega | .opl | | OTPINPUTS | ملفات عمليات الترجمة لـ Omega | .otp | | OVFFONTS, TEXFONTS | خطوط Omega الافتراضية | .ovf | | OVPFONTS, TEXFONTS | قوائم خصائص Omega الافتراضية | .ovp | | PDFTEXCONFIG | ملفات إعداد خاصة بـ PDFTeX | | | PROGRAMFONTS, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS | خطوط نقطية مضغوطة | .pk | | TEXPSHEADERS, PSHEADERS | PostScript قابل للتنزيل | .pro | | RISINPUTS | ملفات ببليوغرافيا RIS، أساسًا لـ Bibe | .ris | | SFDFONTS | ملفات تعريف الخطوط الفرعية | .sfd | | TEXINPUTS | مصدر TeX | .tex | | TEXDOCS | ملفات التوثيق لنظام TeX | | | TEXSOURCES | ملفات المصدر لنظام TeX | | | TEXMFSCRIPTS | ملفات تنفيذية مستقلة عن البنية تُوزَّع في أشجار texmf | | | TEXPOOL, TEXMFINI | سلاسل برنامج TeX | .pool | | TFMFONTS, TEXFONTS | مقاييس خط TeX | .tfm | | TRFONTS | خطوط Troff | | | TTFONTS | خطوط TrueType المتجهية | .ttf, ,TTF, .ttc, .TTC, .dfont | | T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS | خطوط Type 1 المخططة في PostScript | .pfa, .pfb | | T42FONTS | خطوط Type 42 المخططة في PostScript | | | VFFONTS, TEXFONTS | الخطوط الافتراضية | .vf | | WEBINPUTS | ملفات إدخال WEB | .web, .ch | | WEB2C | ملفات خاصة بتنفيذ web2c | | --- # 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/mqalat-mtamqh/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.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.