> 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/mlfat-alfeh/03-writing-your-own-package.md). # كتابة حزمة خاصة بك أحيانًا يكون الخيار الأفضل لاستخدام أوامرك و«ماكرواتك» الخاصة في مستند هو كتابة حزمة جديدة من الصفر. تشرح هذه المقالة البنية الرئيسية لحزمة جديدة. ## مقدمة أول شيء يجب فعله قبل برمجة حزمة جديدة هو تحديد ما إذا كنت تحتاج فعلًا إلى حزمة جديدة أم لا. يُنصح بـ [البحث في CTAN (شبكة أرشيف TeX الشاملة)](http://www.ctan.org/ctan-portal/search/) والتحقق مما إذا كان أحدهم قد أنشأ بالفعل شيئًا مشابهًا لما تحتاج إليه. شيء مهم آخر يجب أخذه في الاعتبار هو [الفرق بين الحزم والفئات](/latex/ar/mlfat-alfeh/01-understanding-packages-and-class-files.md). قد يؤثر اتخاذ الخيار الخاطئ في مرونة المنتج النهائي. ## البنية العامة يمكن وصف بنية جميع ملفات الحزم بشكل تقريبي في الأجزاء الأربعة التالية: * ***التعريف***. يعلن الملف عن نفسه على أنه حزمة مكتوبة بصياغة LaTeX2ε. * ***التصريحات التمهيدية***. هنا يتم استيراد الحزم الخارجية المطلوبة. وكذلك، في هذا الجزء من الملف تُكتب الأوامر والتعريفات اللازمة للخيارات المُعلنة. * ***الخيارات***. تُعلن الحزمة الخيارات وتُعالجها. * ***تصريحات إضافية***. الجسم الرئيسي للحزمة. يُعرَّف هنا تقريبًا كل ما تفعله الحزمة. في الأقسام الفرعية التالية سيُعرض وصف أكثر تفصيلًا للبنية ومثال عملي، *examplepackage.sty*، سيتم تقديمهما. ### التعريف هناك أمران بسيطان يجب أن تحتوي عليهما جميع الحزم: ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/24 Example LaTeX package] ``` الأمر `\NeedsTeXFormat{LaTeX2e}` يحدد إصدار LaTeX الذي ستعمل الحزمة عليه. بالإضافة إلى ذلك، يمكن إضافة تاريخ بين أقواس لتحديد أقل تاريخ إصدار مطلوب. الأمر `ProvidesPackage{examplepackage}[...]` يُعرّف هذه الحزمة على أنها *examplepackage* ويُدرج داخل الأقواس تاريخ الإصدار وبعض المعلومات الإضافية. يجب أن يكون التاريخ بالشكل YYYY/MM/DD [افتح مثالًا على كيفية كتابة حزمة في Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### التصريحات التمهيدية تقوم معظم الحزم بتوسيع الحزم الموجودة وتخصيصها، كما أنها تحتاج أيضًا إلى بعض الحزم الخارجية للعمل. فيما يلي تتم إضافة بعض الشفرة الإضافية إلى الحزمة النموذجية "examplepackage.sty". ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Example package] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} ``` الأوامر في هذا الجزء إما تهيئ بعض المعلمات التي ستُستخدم لاحقًا لإدارة الخيارات، أو تستورد ملفات خارجية. الأمر `\RequirePackage` يشبه كثيرًا الأمر الشهير `\usepackage`، كما أن إضافة معاملات اختيارية بين الأقواس ستعمل أيضًا. والفرق الوحيد هو أن `\usepackage` لا يمكن استخدامه قبل `\documentclass` الأمر. يُنصح بشدة باستخدام `\RequirePackage` عند كتابة حزم أو فئات جديدة. [افتح مثالًا على كيفية كتابة حزمة في Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### الخيارات لإتاحة بعض المرونة في الحزم، تكون بعض الخيارات الإضافية مفيدة جدًا. الجزء التالي في الملف "examplepackage.sty" يعالج المعاملات الممررة إلى عبارة استيراد الحزمة. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Example package] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} \DeclareOption{red}{\renewcommand{\wordcolour}{sharelatexcolour}} \DeclareOption{blue}{\renewcommand{\wordcolour}{mybluecolour}} \DeclareOption*{\PackageWarning{examplepackage}{Unknown ‘\CurrentOption’}} \ProcessOptions\relax ``` فيما يلي وصف للأوامر الرئيسية التي يمكنها التعامل مع الخيارات الممررة إلى الحزمة. الأمر `\DeclareOption{}{}` يتعامل مع خيار معيّن. يأخذ معاملين؛ الأول هو اسم الخيار والثاني هو الشفرة التي ستُنفَّذ إذا تم تمرير الخيار. الأمر `\OptionNotUsed` سيطبع رسالة في المترجم وفي السجلات، ولن يُستخدم الخيار. الأمر `\Declareoption*{}` يتعامل مع كل خيار غير معرّف صراحةً. يأخذ معاملًا واحدًا فقط، وهو الشفرة التي ستُنفَّذ عند تمرير خيار غير معروف. في هذه الحالة سيطبع تحذيرًا باستخدام الأمر التالي: `\PackageWarning{}{}`. انظر [معالجة الأخطاء](#handling-errors) للاطلاع على وصف لما يفعله هذا الأمر. `\CurrentOption` يخزن اسم خيار الحزمة الذي تتم معالجته في لحظة معينة. الأمر `\ProcessOptions\relax` ينفذ الشفرة لكل خيار ويجب إدراجه بعد كتابة جميع أوامر معالجة الخيارات. توجد نسخة بنجمة من هذا الأمر ستنفذ الخيارات بالترتيب الدقيق الذي تحدده الأوامر المستدعية. في المثال، إذا كانت الخيارات *أحمر* أو *blue* تم تمريرها إلى `\usepackage` الأمر `\wordcolor` يُعاد تعريفه. وقد تم تعريف كلٍّ من اللونين ولون الرمادي الافتراضي في [التصريحات التمهيدية](#preliminary-declaration) بعد استيراد *xcolor* الحزمة. [افتح مثالًا على كيفية كتابة حزمة في Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ### تصريحات إضافية في هذا الجزء ستظهر معظم الأوامر. في "examplepackage.sty". فيما يلي يمكنك رؤية ملف الحزمة الكامل. ```latex \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{examplepackage}[2014/08/21 Example package] \RequirePackage{imakeidx} \RequirePackage{xstring} \RequirePackage{xcolor} \definecolor{greycolour}{HTML}{525252} \definecolor{sharelatexcolour}{HTML}{882B21} \definecolor{mybluecolour}{HTML}{394773} \newcommand{\wordcolour}{greycolour} \DeclareOption{red}{\renewcommand{\wordcolour}{sharelatexcolour}} \DeclareOption{blue}{\renewcommand{\wordcolour}{mybluecolour}} \DeclareOption*{\PackageWarning{examplepackage}{Unknown ‘\CurrentOption’}} \ProcessOptions\relax %%بيئة مرقمة \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent \textbf{بيئتي~\theexample. #1} \rmfamily}{\medskip} %%تُضاف الكلمات المهمة إلى الفهرس وتُطبع بلون مختلف \newcommand{\important}[1] {\IfSubStr{#1}{!} {\textcolor{\wordcolour}{\textbf{\StrBefore{#1}{!}~\StrBehind{#1}{!}}}\index{#1}} {\textcolor{\wordcolour}{\textbf{#1}}\index{#1}\kern-1pt} } ``` تُعرّف هذه الحزمة البيئة الجديدة `مثال`، وأمرًا جديدًا `\important`، الذي يطبع الكلمات بلون خاص ويضيفها إلى الفهرس. لفهم كل أمر بالكامل، راجع [دليل المراجع](#reference-guide) والروابط في [قسم القراءة الإضافية](#further-reading). فيما يلي مستند يستخدم الحزمة *examplepackage.sty*. ```latex \documentclass{article} \usepackage[utf8]{inputenc} \usepackage[red]{examplepackage} \makeindex \title{Package Example} \author{Team Learn ShareLaTeX} \date{ } \begin{document} \maketitle \section{Introduction} في هذا المستند تُختبر حزمة جديدة. تتيح هذه الحزمة بيئات مرقمة خاصة البيئات \begin{example} هذا النص داخل بيئة خاصة، ويُطبع بعض النص بخط عريض في البداية، ويتم تعيين مسافة بادئة جديدة. \end{example} كما يوجد أمر خاص لـ \important{مهم!كلمات} الذي سيُ طُبع بلون \important{خاص} اعتمادًا على المعامل المستخدم في عبارة استيراد \important{الحزمة}. لأنه \important{مهم}. \printindex \end{document} ``` ![WrittingPackagesEx1.png](/files/69076aacc3f0b265bbd656ff47cd286f8f6a93e3) لاحظ الأمر ```latex \usepackage[red]{examplepackage} ``` [افتح مثالًا على كيفية كتابة حزمة في Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## معالجة الأخطاء عند تطوير حزم جديدة، من المهم التعامل مع الأخطاء المحتملة لإبلاغ المستخدم بأن شيئًا ما قد حدث خطأ. توجد أربعة أوامر رئيسية للإبلاغ عن الأخطاء في المترجم. * `\PackageError{*package-name*}{*error-text*}{*help-text*}`. يأخذ ثلاثة معاملات، كل واحد منها داخل أقواس: اسم الحزمة، ونص الخطأ الذي سيُعرض (وسيتم إيقاف عملية الترجمة مؤقتًا)، ونص المساعدة الذي سيُطبع إذا ضغط المستخدم على "h" عند توقف الترجمة بسبب الخطأ. * `\PackageWarning{*package-name*}{*warning-text*}`. في هذه الحالة سيُعرض النص، لكن عملية الترجمة لن تتوقف. وسيظهر رقم السطر الذي حدث فيه التحذير. * `\PackageWarningNoLine{*package-name*}{*warning-text*}`. يعمل تمامًا مثل الأمر السابق، لكنه لن يعرض السطر الذي حدث فيه التحذير. * `\PackageInfo{*package-name*}{*info-text*}`. في هذه الحالة ستُطبع المعلومات في المعامل الثاني فقط في ملف السجل، بما في ذلك رقم السطر. [افتح مثالًا على كيفية كتابة حزمة في Overleaf](https://www.sharelatex.com/project/new/template?zipUrl=/project/53f11ec1eceb82a67658cb02/download/zip\&templateName=PackageExample\&compiler=pdflatex) ## دليل المراجع **قائمة بالأوامر المستخدمة عادةً في الحزم والفئات** * `\newcommand{*name*}{*definition*}`. يُعرّف [أمرًا جديدًا](/latex/ar/alawamr/01-commands.md#defining-a-new-command)، المعامل الأول هو اسم الأمر الجديد، والمعامل الثاني هو ما سيفعله الأمر. * `\renewcommand{}{}`. بنفس معنى `\newcommand` ولكنه سيستبدل أمرًا موجودًا. * `\providecommand{}{}`. يعمل تمامًا مثل `\newcommand` ولكن إذا كان الأمر معرّفًا بالفعل فسيُتجاهل هذا الأمر بصمت. * `\CheckCommand{}{}`. يكون التركيب نفسه مثل `\newcommand`، ولكن بدلًا من ذلك سيتحقق مما إذا كان الأمر موجودًا وكان له التعريف المتوقع؛ وسيعرض LaTeX تحذيرًا إذا لم يكن الأمر هو ما `\CheckCommand` كان متوقعًا. * `\setlength{}{}`. يضبط طول العنصر الممرَّر كمعامل أول إلى القيمة المكتوبة كمعامل ثانٍ. * `\mbox{}`. ينشئ صندوقًا يحتوي العناصر المكتوبة داخل الأقواس. * `\fbox{}`. بنفس معنى `\mbox`، لكن يتم في الواقع طباعة صندوق حول المحتويات. ## قراءة إضافية لمزيد من المعلومات، انظر * [فهم الحزم وملفات الأصناف](/latex/ar/mlfat-alfeh/01-understanding-packages-and-class-files.md) * [كتابة فئة خاصة بك](/latex/ar/mlfat-alfeh/04-writing-your-own-class.md) * [الأوامر](/latex/ar/alawamr/01-commands.md) و [البيئات](/latex/ar/alawamr/02-environments.md) * [الأطوال في LaTeX](/latex/ar/altnsyq/01-lengths-in-latex.md) * [استخدام الألوان في LaTeX](/latex/ar/altnsyq/13-using-colors-in-latex.md) * [الإدارة في مشروع كبير](/latex/ar/bnyh-almstnd/07-management-in-a-large-project.md) * [LaTeX2ε للحزم ولمؤلفي الحزم](http://www.latex-project.org/guides/clsguide.pdf) * [ملاحظات حول البرمجة في tex](http://pgfplots.sourceforge.net/TeX-programming-notes.pdf) * [دقائق بدلًا من ساعات: استخدام موارد LaTeX](https://tug.org/pracjourn/2005-4/hefferon/hefferon.pdf) * [رفيق LaTeX. الطبعة الثانية](http://ptgmedia.pearsoncmg.com/images/9780201362992/samplepages/0201362996.pdf) --- # 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/mlfat-alfeh/03-writing-your-own-package.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.