> 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/altnsyq/10-counters.md). # العدادات ## مقدمة إلى عدّادات LaTeX إن التنضيد القائم على LaTeX هو شكل متخصص من البرمجة: فأنت تستخدم لغة تنضيد (أوامر LaTeX) لتقديم «تعليمات» ينتج عنها مخرج: مستند LaTeX المترجم على شكل ملف PDF. وكما هو الحال في أي مسعى برمجي، فمن المحتمل أنك ستحتاج إلى أن يخزّن LaTeX مؤقتًا قيمًا صحيحة لإعادة استخدامها لاحقًا في مستندك (الكود)—وقد ترغب في: * تنضيد تلك الأعداد الصحيحة المخزنة في مستندك * توفير ترقيم تلقائي لبعض عناصر مستندك * استخدامها كمتغيرات للتحكم في الشيفرة الشرطية (أو الحلقات) * تغيير قيمها وتحديثها بزيادتها/إنقاصها باستخدام قيمة ثابتة ما * إعادة ضبطها إلى قيم مختلفة تمامًا مثل هذه الأنشطة المتعلقة بمعالجة الأعداد الصحيحة شائعة جدًا في لغات البرمجة «العادية» مثل Javascript وC وLua أو أي لغة أخرى تختارها، حيث تقوم عادةً بتصريح (إنشاء اسم لـ) متغير (ليحتوي على عدد صحيح) ثم تعيين قيمة له. وتوفر لغة التنضيد LaTeX قدرات مماثلة، وإن كانت مُنفذة بطريقة مختلفة تمامًا، كما سنستكشف أدناه. في الجوهر، عدّاد LaTeX هو اسم «متغير LaTeX» يُستخدم لتخزين قيم صحيحة يمكن استخدامها في الأفعال المذكورة أعلاه، وفي أشياء كثيرة أخرى أيضًا. يستخدم LaTeX نفسه العديد من العدادات الداخلية التي توفر ترقيم الصفحات والأقسام والجداول والأشكال والقوائم النقطية/المرقمة، إلخ. تشرح هذه المقالة كيفية الوصول إلى تلك العدادات وتعديلها وكيفية إنشاء عدادات جديدة واستخدامها. ## أوامر LaTeX للعمل مع العدادات فيما يلي قائمة بأوامر العدادات في LaTeX مع روابط إلى وصفها في الأقسام التالية. إنشاء العدادات وزيادتها: * [`\newcounter{somecounter}[anothercounter]`](#newcountersomecounteranothercounter) * [`\setcounter{somecounter}{number}`](#setcountersomecounternumber) * [`\addtocounter{somecounter}{number}`](#addtocountersomecounternumber) * [`\stepcounter{somecounter}`](#stepcountersomecounter) * [`\refstepcounter{somecounter}`](#refstepcountersomecounter) الوصول إلى قيم العدادات وطباعتها: * [`\arabic{somecounter}`](#arabicsomecounter) * [`\roman{somecounter}`](#romansomecounter) * [`\Roman{somecounter}`](#romanoutput) * [`\alph{somecounter}`](#alphsomecounter) * [`\Alph{somecounter}`](#alphoutput) * [`\fnsymbol{somecounter}`](#fnsymbolsomecounter) * [`\value{somecounter}`](#valuesomecounter) أوامر عدادات أخرى: * [`\counterwithin{somecounter}{anothercounter}`](#counterwithinsomecounteranothercounter) * [`\counterwithout{somecounter}{anothercounter}`](#counterwithoutsomecounteranothercounter) ### إنشاء العدادات وزيادتها #### \newcounter{somecounter}\[anothercounter] يُستخدم لتعريف عداد جديد. الوسيط الثاني، المحاط بـ `[]`، اختياري، لكن عند استخدامه فإنه يعرّف `*somecounter*` بوصفه عدادًا جديدًا يُعاد ضبطه عندما يتم زيادة `*anothercounter*` . `\newcounter` يُستخدم كثيرًا بصيغته الأبسط `\newcounter{*somecounter*}` التي تنشئ `*somecounter*` وتهيّئه ليحتوي على 0. * **ملاحظة** : لكل عداد يتم إنشاؤه بواسطة الأمر `\newcounter` ، فإنه *أيضًا* يعرّف أمرًا يمكن استخدامه لتنضيد قيمة العداد. على سبيل المثال، `\newcounter{*mycounter*}` يعرّف أمرًا يسمى `\the*mycounter*`. يوضَّح مثال في مقطع كود LaTeX التالي الذي يمكنك فتحه في Overleaf، بوصفه مستندًا كاملاً، باستخدام الرابط الموفَّر: ```latex \newcounter{mycounter} \setcounter{mycounter}{42} يمكنك الآن كتابة \verb|\themycounter| للحصول على \themycounter. ``` [افتح هذا المقطع من LaTeX في Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+newcounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnewcounter%7Bmycounter%7D%0A%5Csetcounter%7Bmycounter%7D%7B42%7D%0AYou+can+now+write+%5Cverb%7C%5Cthemycounter%7C+to+obtain+%5Cthemycounter.%0A%5Cend%7Bdocument%7D) ينتج هذا المثال $$\text{You can now write }\verb|\themycounter|\text{ to obtain 42.}$$ * **ملاحظة** : إذا `*mycounter*` كان قد تم تعريفه بالفعل فسوف يُصدر LaTeX الخطأ `c@mycounter already defined`، كما يوضّح المثال التالي الذي يمكنك فتحه في Overleaf. ```latex \newcounter{mycounter} ... الكثير من الشيفرة ... لكننا ننسى ونكتب \verb|\newcounter{mycounter}| مرة أخرى \newcounter{mycounter} ``` [افتح هذا ***شيفرة تولّد خطأ*** في Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+newcounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnewcounter%7Bmycounter%7D%0A...lots+of+code...+but+we+forget+and+write+%5Cverb%7C%5Cnewcounter%7Bmycounter%7D%7C+again%0A%5Cnewcounter%7Bmycounter%7D%0A%5Cend%7Bdocument%7D) #### \setcounter{somecounter}{number} يعيّن `*somecounter*` ليحتوي على القيمة `*number*`. * **ملاحظة**: `*number*` يمكن أن تكون موجبة أو سالبة. يُوضَّح مثال في مقطع كود LaTeX التالي الذي يمكنك فتحه في Overleaf، بوصفه مستندًا كاملاً، باستخدام الرابط الموفَّر: ```latex \noindent أنشئ عدادًا جديدًا \texttt{myvar} وعيّن له القيمة \texttt{42}. \vspace{10pt} \newcounter{myvar} \setcounter{myvar}{42} \noindent كتابة \verb|\themymar| تُنسّق \texttt{\themyvar}. \vspace{10pt} \noindent بعد ذلك، سنغيّر \texttt{myvar} إلى \texttt{-42}، بكتابة \verb|\setcounter{myvar}{-42}| \setcounter{myvar}{-42}. الآن، كتابة \verb|\themyvar| تُخرج \texttt{\themyvar}. ``` [افتح هذا المقطع من LaTeX في Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+newcounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnoindent+Create+a+new+counter+%5Ctexttt%7Bmyvar%7D+and+assign+it+the+value+%5Ctexttt%7B42%7D.%0A%5Cvspace%7B10pt%7D%0A%0A%5Cnewcounter%7Bmyvar%7D%0A%5Csetcounter%7Bmyvar%7D%7B42%7D+%0A%0A%5Cnoindent+Writing+%5Cverb%7C%5Cthemymar%7C+typesets+%5Ctexttt%7B%5Cthemyvar%7D.%0A%5Cvspace%7B10pt%7D%0A%0A%5Cnoindent+Next%2C+we%27ll+change+%5Ctexttt%7Bmyvar%7D+to+%5Ctexttt%7B-42%7D%2C+writing+%5Cverb%7C%5Csetcounter%7Bmyvar%7D%7B-42%7D%7C%0A%5Csetcounter%7Bmyvar%7D%7B-42%7D.+Now%2C+writing+%5Cverb%7C%5Cthemyvar%7C+outputs+%5Ctexttt%7B%5Cthemyvar%7D.%0A%5Cend%7Bdocument%7D) #### \addtocounter{somecounter}{number} يزيد العداد `*somecounter*` بمقدار `*number*`. * **ملاحظة**: `*number*` يمكن أن تكون موجبة لزيادة قيمة العداد، أو سالبة لإنقاصها. على سبيل المثال: ```latex \addtocounter{somecounter}{-1} % يُنقص somecounter بمقدار 1 ``` يُوضَّح مثال في مقطع كود LaTeX التالي الذي يمكنك فتحه في Overleaf، بوصفه مستندًا كاملاً، باستخدام الرابط الموفَّر: ```latex \noindent أنشئ عدادًا جديدًا \texttt{myvar} وعيّن له القيمة \texttt{42}. \vspace{10pt} \newcounter{myvar} \setcounter{myvar}{42} \noindent كتابة \verb|\themymar| تُنسّق \texttt{\themyvar}. \vspace{10pt} \noindent بعد ذلك، سنغيّر \texttt{myvar} إلى \texttt{142} بكتابة \verb|\addtocounter{myvar}{100}|\addtocounter{myvar}{100}. الآن، كتابة \verb|\themyvar| تُخرج \texttt{\themyvar}. ``` [افتح هذا المقطع من LaTeX في Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+addtocounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnoindent+Create+a+new+counter+%5Ctexttt%7Bmyvar%7D+and+assign+it+the+value+%5Ctexttt%7B42%7D.%0A%5Cvspace%7B10pt%7D%0A%0A%5Cnewcounter%7Bmyvar%7D%0A%5Csetcounter%7Bmyvar%7D%7B42%7D+%0A%0A%5Cnoindent+Writing+%5Cverb%7C%5Cthemymar%7C+typesets+%5Ctexttt%7B%5Cthemyvar%7D.%0A%5Cvspace%7B10pt%7D%0A%0A%5Cnoindent+Next%2C+we%E2%80%99ll+change+%5Ctexttt%7Bmyvar%7D+to+%5Ctexttt%7B142%7D+by+writing+%5Cverb%7C%5Caddtocounter%7Bmyvar%7D%7B100%7D%7C%5Caddtocounter%7Bmyvar%7D%7B100%7D.+Now%2C+writing+%5Cverb%7C%5Cthemyvar%7C+outputs+%5Ctexttt%7B%5Cthemyvar%7D.%0A%5Cend%7Bdocument%7D) #### \stepcounter{somecounter} يزيد `*somecounter*` بمقدار 1. ويُوضَّح مثال في مقطع كود LaTeX التالي الذي يمكنك فتحه في Overleaf، بوصفه مستندًا كاملاً، باستخدام الرابط الموفَّر: ```latex إذا أنشأنا عدادًا جديدًا بكتابة \verb|\newcounter{mycounter}| \newcounter{mycounter} فإن العداد \texttt{mycounter} يُنشأ و يُهيّأ بصفر، كما يمكنك أن ترى إذا كتبت \verb|\themycounter|: \texttt{mycounter} يخزّن حاليًا: \themycounter. إذا كتبنا الآن \verb|\stepcounter{mycounter}|\stepcounter{mycounter} فإن \verb|\themycounter| يحتوي الآن على القيمة \themycounter. ``` [افتح هذا المقطع من LaTeX في Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+stepcounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0AIf+we+create+a+new+counter+by+writing+%5Cverb%7C%5Cnewcounter%7Bmycounter%7D%7C%0A%5Cnewcounter%7Bmycounter%7D+then+the+counter+%5Ctexttt%7Bmycounter%7D+is+created+and+%0Ainitialized+to+zero%2C+as+you+can+see+if+you+write+%5Cverb%7C%5Cthemycounter%7C%3A%0A%5Ctexttt%7Bmycounter%7D+currently+stores%3A+%5Cthemycounter.+%0A%0AIf+we+now+write+%5Cverb%7C%5Cstepcounter%7Bmycounter%7D%7C%5Cstepcounter%7Bmycounter%7D+then+%0A%5Cverb%7C%5Cthemycounter%7C+now+contains+the+value+%5Cthemycounter.%0A%5Cend%7Bdocument%7D) #### \refstepcounter{somecounter} يزيد `*somecounter*` بمقدار 1 ويجعله مرئيًا لآلية الإحالة، مع تعيين القيمة أيضًا بحيث يمكنك استخدام `\label` لاحقًا. **مثال باستخدام \refstepcounter** يستخدم المثال التالي `\refstepcounter` لإنشاء عداد جديد لـ `مثال` بيئة ويستخدم `\label` و `\ref` لتوضيح الإحالة باستخدام `مثال` متغير العداد. ```latex \documentclass{article} \newcounter{example}[section] \newenvironment{example}[1][]{\refstepcounter{example}\par\medskip \noindent\textbf{Example~\theexample. #1} \rmfamily}{\medskip} \begin{document} \section{Three examples} \begin{example} أنشئ وسمًا في هذا المثال الأول \verb|\label{ex:1}|\label{ex:1}. هذا هو المثال الأول. سيُعاد ضبط عداد \texttt{example} في بداية كل \verb|\section| جديدة في المستند. \end{example} \begin{example} وإليك مثالًا مرقّمًا آخر. أنشئ وسمًا ثانيًا \verb|\label{ex:2}|\label{ex:2} للإشارة إليه لاحقًا. في المثال \ref{ex:1} نقرأ... شيئًا ما. \end{example} \begin{example} وإليك مثالًا مرقّمًا آخر: استخدم \verb|\theexample| لتنضيد الرقم المخصّص حاليًا لعداد \texttt{example}: وهو \theexample. \end{example} \section{قسم آخر} لقد بدأنا للتو قسمًا جديدًا، ما يعني أن عداد \texttt{example} قد تم ضبطه على \theexample. سنشير إلى الأمثلة من القسم السابق (المثالان \ref{ex:1} و\ref{ex:2}). هذا قسم حشو لا غرض له إطلاقًا سوى احتواء نص. يمكن تنضيد عداد \texttt{section} لهذا القسم باستخدام \verb|\thesection|: وهو مُعيَّن حاليًا إلى قيمة \thesection. \begin{example} هذا هو المثال الأول في هذا القسم: فقد جرى زيادة عداد \texttt{example} وأصبح مضبوطًا الآن على \theexample. \end{example} \end{document} ``` [افتح هذا `\refstepcounter` المثال في Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=An+example+using+refstepcounter\&snip=%5Cdocumentclass%7Barticle%7D%0A%0A%5Cnewcounter%7Bexample%7D%5Bsection%5D%0A%5Cnewenvironment%7Bexample%7D%5B1%5D%5B%5D%7B%5Crefstepcounter%7Bexample%7D%5Cpar%5Cmedskip%0A+++%5Cnoindent%5Ctextbf%7BExample%7E%5Ctheexample.+%231%7D+%5Crmfamily%7D%7B%5Cmedskip%7D%0A%0A%5Cbegin%7Bdocument%7D%0A%5Csection%7BThree+examples%7D%0A%5Cbegin%7Bexample%7D%0ACreate+a+label+in+this+first+example+%5Cverb%7C%5Clabel%7Bex%3A1%7D%7C%5Clabel%7Bex%3A1%7D.+This+is+the+first+example.+The+%5Ctexttt%7Bexample%7D+counter+will+be+reset+at+the+start+of+each+new+each+document+%5Cverb%7C%5Csection%7C.%0A%5Cend%7Bexample%7D%0A%0A%5Cbegin%7Bexample%7D%0AAnd+here%27s+another+numbered+example.+Create+a+second+%5Cverb%7C%5Clabel%7Bex%3A2%7D%7C%5Clabel%7Bex%3A2%7D+to+later+reference+this+one.+In+Example+%5Cref%7Bex%3A1%7D+we+read...+something.+%0A%5Cend%7Bexample%7D%0A%0A%5Cbegin%7Bexample%7D%0AAnd+here%27s+another+numbered+example%3A+use+%5Cverb%7C%5Ctheexample%7C+to+typeset+the+number+currently+assigned+to+the+%5Ctexttt%7Bexample%7D+counter%3A+it+is++%5Ctheexample.%0A%5Cend%7Bexample%7D%0A%0A%5Csection%7BAnother+section%7D%0AWe%27ve+just+started+a+new+section+meaning+that+the++%5Ctexttt%7Bexample%7D+counter+has+been+set+to+%5Ctheexample.++%0AWe%27ll+reference+examples+from+the+previous+section+%28Examples+%5Cref%7Bex%3A1%7D+and+%5Cref%7Bex%3A2%7D%29.++This+is+a+dummy+section+with+no+purpose+whatsoever+but+to+contain+text.+The+%5Ctexttt%7Bsection%7D+counter+for+this+section+can+be+typeset+using+%5Cverb%7C%5Cthesection%7C%3A+it+is++currently+assigned+the+value+of+%5Cthesection.%0A%0A%5Cbegin%7Bexample%7D%0AThis+is+the+first+example+in+this+section%3A+the+%5Ctexttt%7Bexample%7D+counter+has+been+stepped+and+now+set+to+%5Ctheexample.+%0A%5Cend%7Bexample%7D%0A%5Cend%7Bdocument%7D) **ملخص الشيفرة** في هذا المثال، تم تعريف البيئة الجديدة `مثال` ، وتحتوي هذه البيئة على 3 أوامر خاصة بالعدّ: * `\newcounter{example}[section]` : ينشئ عدادًا جديدًا يُسمّى `مثال` سيُعاد ضبطه إلى 0 كلما زاد عداد `section` . يمكنك وضع أي عداد آخر بدلًا من `section` أو حذف المعامل إذا كنت لا تريد إعادة ضبط عدادك تلقائيًا. * `\refstepcounter{example}` : يزيد `مثال` العداد بمقدار 1 ويجعله مرئيًا لآلية الإحالة، بحيث يمكنك استخدام `\label` لاحقًا. * `\theexample` : يطبع القيمة الحالية للعداد `مثال`. لمزيد من المعلومات عن البيئات المعرَّفة من المستخدم، انظر [المقالة عن تعريف البيئات الجديدة](/latex/ar/alawamr/02-environments.md#defining-a-new-environment) ### الوصول إلى قيم العدادات وطباعتها المناقشات التالية مبنية على الإعدادات الافتراضية في LaTeX قبل تطبيق أي تخصيصات تفرضها الحزم التي يحمّلها المستخدم. #### \arabic{somecounter} إخراج تمثيل `*somecounter*` بوصفه أعدادًا عربية: 1، 2، 3... #### \roman{somecounter} إخراج تمثيل `*somecounter*` بوصفه رقمًا رومانيًا صغيرًا: i، ii، iii... * **ملاحظة** : إذا `*somecounter*` $$\leq$$ `0` لا يتم إنتاج أي مخرج. بالإضافة إلى ذلك، فإن تحويل *شديدة* القيم الصحيحة الكبيرة إلى أرقام رومانية صغيرة قد يستغرق وقتًا طويلًا لإتمامه — كما ينتج سلسلة طويلة من `m` محارف (تمثل العدد `1000`). * **نصيحة** : إذا كنت مهتمًا بالخوارزمية التي يستخدمها TeX لتحويل الأعداد العربية إلى أرقام رومانية، فيمكنك قراءة المزيد عنها في هذه المقالة عن [الخوارزميات للأرقام الرومانية](https://www.hanshq.net/roman-numerals.html#tex). #### \Roman{somecounter} إخراج تمثيل `*somecounter*` بوصفه رقمًا رومانيًا كبيرًا: I, II, III... * **ملاحظة** : إذا `*somecounter*` $$\leq$$ `0` لا يتم إنتاج أي مخرج. بالإضافة إلى ذلك، فإن تحويل *شديدة* القيم الصحيحة الكبيرة إلى أرقام رومانية كبيرة قد يستغرق وقتًا طويلًا لإتمامه — كما ينتج سلسلة طويلة من `M` محارف (تمثل العدد `1000`). * **نصيحة** : إذا كنت مهتمًا بالخوارزمية التي يستخدمها TeX لتحويل الأعداد العربية إلى أرقام رومانية، فيمكنك قراءة المزيد عنها في هذه المقالة عن [الخوارزميات للأرقام الرومانية](https://www.hanshq.net/roman-numerals.html#tex). #### \alph{somecounter} إخراج تمثيل `*somecounter*` بوصفه حرفًا صغيرًا حيث a=1، b=2، c=3... * **ملاحظة**: `*somecounter*` يجب أن تكون في النطاق `1` $$\leq$$ `*somecounter*` $$\leq$$ `26`، وإلا فسوف يطلق الخطأ `! خطأ LaTeX: العداد كبير جدًا.` #### \Alph{somecounter} إخراج تمثيل `*somecounter*` بوصفه حرفًا كبيرًا حيث A=1، B=2، C=3... * **ملاحظة**: `*somecounter*` يجب أن تكون في النطاق `1` $$\leq$$ `*somecounter*` $$\leq$$ `26`، وإلا فسوف يطلق الخطأ `! خطأ LaTeX: العداد كبير جدًا.` #### \fnsymbol{somecounter} إخراج تمثيل `*somecounter*` بوصفه رمز حاشية حيث 1 =∗، 2 =†... * **ملاحظة**: `*somecounter*` يجب أن تكون في النطاق `1` $$\leq$$ `*somecounter*` $$\leq$$ `9`، وإلا فسوف يطلق الخطأ `! خطأ LaTeX: العداد كبير جدًا.` | | | | -------------------- | --------------------------------- | | قيمة `*somecounter*` | المحرف المنسّق بواسطة `\fnsymbol` | | 1 | \* | | 2 | † | | 3 | ‡ | | 4 | § | | 5 | ¶ | | 6 | ∥ | | 7 | ∗∗ | | 8 | †† | | 9 | ‡‡ | #### مثال على طباعة قيم العدادات يوضّح المثال التالي استخدام الأوامر `\arabic{*somecounter*}`, `\roman{*somecounter*}`, `\Roman{*somecounter*}`, `\alph{*somecounter*}`, `\Alph{*somecounter*}`، و `\fnsymbol{*somecounter*}`. ```latex \newcounter{somecounter} \setcounter{somecounter}{9} \begin{itemize} \item \verb|\arabic{somecounter}| يُنسّق قيمة \texttt{somecounter} على هيئة \arabic{somecounter} لـ \thesomecounter{} \item \verb|\roman{somecounter}| يُنسّق قيمة \texttt{somecounter} على هيئة \roman{somecounter} لـ \thesomecounter{} \item \verb|\Roman{somecounter}| يُنسّق قيمة \texttt{somecounter} على هيئة \Roman{somecounter} لـ \thesomecounter{} \item \verb|\alph{somecounter}| يُنسّق قيمة \texttt{somecounter} على هيئة \alph{somecounter} لـ \thesomecounter{} \item \verb|\Alph{somecounter}| يُنسّق قيمة \texttt{somecounter} على هيئة \Alph{somecounter} لـ \thesomecounter{} \item \verb|\fnsymbol{somecounter}| يُنسّق قيمة \texttt{somecounter} على هيئة \fnsymbol{somecounter} لـ \thesomecounter{} \end{itemize} ``` [افتح هذا المقطع من LaTeX في Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Converting+counter+values\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnewcounter%7Bsomecounter%7D%0A%5Csetcounter%7Bsomecounter%7D%7B9%7D%0A%5Cbegin%7Bitemize%7D%0A++++%5Citem+%5Cverb%7C%5Carabic%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as+%5Carabic%7Bsomecounter%7D+%0A++++%5Citem+%5Cverb%7C%5Croman%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as++%5Croman%7Bsomecounter%7D%0A++++%5Citem+%5Cverb%7C%5CRoman%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as++%5CRoman%7Bsomecounter%7D%0A++++%5Citem+%5Cverb%7C%5Calph%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as++%5Calph%7Bsomecounter%7D%0A+++%5Citem+%5Cverb%7C%5CAlph%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as++%5CAlph%7Bsomecounter%7D%0A++++%5Citem+%5Cverb%7C%5Cfnsymbol%7Bsomecounter%7D%7C+typesets+the+%5Ctexttt%7Bsomecounter%7D+value+of++%5Cthesomecounter%7B%7D+as++%5Cfnsymbol%7Bsomecounter%7D%0A%5Cend%7Bitemize%7D%0A%5Cend%7Bdocument%7D) ينتج هذا المثال المخرجات التالية: ![مثال على تحويل العدادات في LaTeX](/files/a1d6aab9ced0b600dae8923e5dc493058259acc2) #### \value{somecounter} الغرض من هذا الأمر، كما هو موضح في شيفرة مصدر LaTeX، هو «للوصول إلى قيمة العداد كعدد TeX»: أي إنك تستخدم `\value{somecounter}` في الحالات التي يتوقع فيها LaTeX معالجة قيمة رقمية. **ملاحظات خلفية (اختيارية) حول الأمر \value** من المغري أن نعتقد أن الأمر `\value{*somecounter*}` سوف *تحرير* يُنسّق قيمة `*somecounter*`، لكن هذا ليس صحيحًا. فهو مخصّص للاستخدام داخل أوامر أخرى للوصول إلى قيمة العداد كعدد TeX، على عكس الأمر `\thesomecounter` الذي ينتج التمثيل المطبوع لـ `*somecounter*`. داخل شيفرة مصدر LaTeX، `\value` مُعرَّف على النحو التالي: ```latex \def\value#1{\csname c@#1\endcsname} ``` وبالتالي، `\value{*somecounter*}` ينشئ مثيلاً من تسلسل الأوامر الداخلي في LaTeX `\c@somecounter` الذي يحتوي على قيمة العداد `*somecounter*`. **مثال** يوضّح المثال التالي حالة استخدام أساسية واحدة لـ `\value`. ```latex \noindent ابدأ بتصريح عدادين جديدين: \begin{verbatim} \newcounter{first} \newcounter{second} \end{verbatim} \newcounter{first} \newcounter{second} \noindent لاحقًا في شيفرتك، تقوم بتعيين قيمهما: \begin{verbatim} \setcounter{first}{100} \setcounter{second}{50} \end{verbatim} \setcounter{first}{100} \setcounter{second}{50} \noindent ثم تكتب المزيد من شيفرة \LaTeX{}...\vspace{10pt} \noindent في مرحلة ما قد نرغب في إضافة قيمة العداد \texttt{second} إلى العداد \texttt{first}. إحدى الطرق لفعل ذلك هي استخدام \verb|\value| للحصول على القيمة \textit{الحالية} المخزنة في العداد \texttt{second}: \begin{verbatim} \addtocounter{first}{\value{second}} \end{verbatim} \addtocounter{first}{\value{second}}\noindent يمكن إخراج قيمة \texttt{first} بواسطة \verb|\thefirst|: \thefirst. يمكننا أيضًا كتابة \verb|\the\value{first}| والتي تُنسّق أيضًا \the\value{first}. ومع ذلك، فإن كتابة \verb|\value{first}| ستولّد الخطأ \texttt{Missing number, treated as zero} لأن \LaTeX{} سيحاول عندئذ تنفيذ الأمر الداخلي \verb|\c@first|. ألغِ تعليق السطر التالي لتوليد الخطأ: \begin{verbatim} %\value{first} \end{verbatim} %\value{first} ``` [افتح مقطع الشيفرة هذا في Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+the+value+command\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cnoindent+Start+by+declaring+two+new+counters%3A%0A%5Cbegin%7Bverbatim%7D%0A%5Cnewcounter%7Bfirst%7D%0A%5Cnewcounter%7Bsecond%7D++++%0A%5Cend%7Bverbatim%7D%0A%0A%5Cnewcounter%7Bfirst%7D%0A%5Cnewcounter%7Bsecond%7D%0A%0A%5Cnoindent+Sometime+later+in+your+code+you+set+their+values%3A%0A%5Cbegin%7Bverbatim%7D%0A%5Csetcounter%7Bfirst%7D%7B100%7D%0A%5Csetcounter%7Bsecond%7D%7B50%7D++++%0A%5Cend%7Bverbatim%7D%0A%0A%5Csetcounter%7Bfirst%7D%7B100%7D%0A%5Csetcounter%7Bsecond%7D%7B50%7D++%0A%5Cnoindent+Then+you+write+more+%5CLaTeX%7B%7D+code...%5Cvspace%7B10pt%7D%0A%0A%5Cnoindent+At+some+point+we+might+want+to+add+the+value+of+counter+%5Ctexttt%7Bsecond%7D+to+counter+%5Ctexttt%7Bfirst%7D.+One+way+to+do+that+is+using+%5Cverb%7C%5Cvalue%7C+to+obtain+the+%5Ctextit%7Bcurrent%7D+value+stored+in+the+%5Ctexttt%7Bsecond%7D+counter%3A%0A%0A%5Cbegin%7Bverbatim%7D%0A%5Caddtocounter%7Bfirst%7D%7B%5Cvalue%7Bsecond%7D%7D%0A%5Cend%7Bverbatim%7D%0A%0A%5Caddtocounter%7Bfirst%7D%7B%5Cvalue%7Bsecond%7D%7D%5Cnoindent+The+value+of+%5Ctexttt%7Bfirst%7D+can+be+output+by+%5Cverb%7C%5Cthefirst%7C%3A+%5Cthefirst.+We+can+also+write+%5Cverb%7C%5Cthe%5Cvalue%7Bfirst%7D%7C+which+also+typesets+%5Cthe%5Cvalue%7Bfirst%7D.+However%2C++writing+%5Cverb%7C%5Cvalue%7Bfirst%7D%7C+will+generate+the+error+%5Ctexttt%7BMissing+number%2C+treated+as+zero%7D+because+%5CLaTeX%7B%7D+then+tries+to+execute+the+internal+command+%5Cverb%7C%5Cc%40first%7C.+Uncomment+the+following+line+to+generate+the+error%3A%0A%5Cbegin%7Bverbatim%7D%0A%25%5Cvalue%7Bfirst%7D%0A%5Cend%7Bverbatim%7D%0A%25%5Cvalue%7Bfirst%7D%0A%5Cend%7Bdocument%7D) ينتج هذا المثال المخرجات التالية: ![مثال باستخدام الأمر \value](/files/7c805f62d357e86a9c0dd77716398fcb396faea0) ### أوامر عدادات أخرى نصف هنا الأوامر `\counterwithin` و `\counterwithout` التي نشأت في حزمة [`chngcntr` الحزمة](https://ctan.org/pkg/chngcntr) لكنها أُدمجت الآن في LaTeX نفسه — انظر [أخبار LaTeX، أبريل 2018](https://www.latex-project.org/news/latex2e-news/ltnews28.pdf). الحزمة `chngcntr` [توثيق الحزمة](https://mirror.ox.ac.uk/sites/ctan.org/macros/latex/contrib/chngcntr/chngcntr.pdf) تورد التعليقات التالية التي تساعد على فهم الغرض من هذه الأوامر: تشغيل `\counterwithin`: > قد يكون من المرغوب أحيانًا تغيير عداد تم تعريفه بواسطة `\newcounter{}` ليعمل كما لو أنه قد تم تعريفه على أنه `\newcounter{}[]`. توفّر الحزمة الأمر `\counterwithin{}{}` الذي يحقق ذلك. تشغيل `\counterwithout`: > وبالمثل، فإن الأمر `\counterwithout{}{}` يغيّر عدادًا تم إنشاؤه بواسطة `\newcounter{}[]` ليعمل كما لو أنه قد تم إنشاؤه بواسطة `\newcounter{}`. في الجوهر، يوفّر هذان الأمران طريقة لربط (`\counterwithin`) أو فصل (`\counterwithout`) عدّادين بعد أن يتم تعريفهما. **\counterwithin{somecounter}{anothercounter}** يعيد الضبط `*somecounter*` إلى 0 كلما تم زيادة `*anothercounter*` ، وهي آلية تربط العدادين. وإضافةً إلى إنشاء هذا الربط، يعيد هذا الأمر تعريف ما يُنسَّق بواسطة `\the*somecounter*`: فبدلًا من إخراج قيمة العداد `*somecounter*` فهو ينتج `**.**`. والصيغة النجمية (`\counterwithin*{somecounter}{anothercounter}`) لا تعيد تعريف تنسيق الطباعة لـ `*somecounter*`، كما يوضّح المثال التالي — اختر الرابط أسفل الشيفرة لفتحه في Overleaf: ```latex \documentclass{article} \begin{document} \section{A short example} \newcounter{example} \counterwithin{example}{section} \newcounter{exampletwo} \counterwithin*{exampletwo}{section} \setcounter{example}{100} \setcounter{exampletwo}{100} \begin{itemize} \item \verb|\theexample| يُنسّق \theexample \item \verb|\theexampletwo| يُنسّق \theexampletwo \end{itemize} \end{document} ``` [افتح هذا `\counterwithin` المثال في Overleaf](https://www.overleaf.com/docs?engine=\&snip_name=Example+of+starred+version+of+counterwithin\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Csection%7BA+short+example%7D%0A%5Cnewcounter%7Bexample%7D%0A%5Ccounterwithin%7Bexample%7D%7Bsection%7D%0A%5Cnewcounter%7Bexampletwo%7D%0A%5Ccounterwithin%2A%7Bexampletwo%7D%7Bsection%7D%0A%5Csetcounter%7Bexample%7D%7B100%7D%0A%5Csetcounter%7Bexampletwo%7D%7B100%7D%0A%5Cbegin%7Bitemize%7D%0A%5Citem+%5Cverb%7C%5Ctheexample%7C+typesets+%5Ctheexample%0A%5Citem+%5Cverb%7C%5Ctheexampletwo%7C+typesets+%5Ctheexampletwo%0A%5Cend%7Bitemize%7D%0A%5Cend%7Bdocument%7D) ينتج هذا المثال المخرجات التالية: ![استخدام الأمر \counterwithin](/files/3fd4fc5cce81b53dba8e5fa4e5cb927eef882ee1) يمكنك استخدام `\counterwithin` مع العدادات القياسية التي يوفرها LaTeX، مثل: * `section` : تُستخدم بواسطة `\section` الأمر * `equation` المستخدمة في الـ `equation` البيئة أو مع العدادات التي أنشأتها. **مثال على \counterwithin و\counterwithin\*** يوفّر الكود التالي مثالًا أكثر اكتمالًا على استخدام `\counterwithin` و `\counterwithin*`؛ اختر الرابط أسفل الشيفرة لفتحه في Overleaf: ```latex \documentclass{article} \counterwithin{equation}{section} \newcounter{example} \counterwithin*{example}{section} \newenvironment{example}[1][]{% \stepcounter{example}% \par\vspace{5pt}\noindent \fbox{\textbf{Example~\thesection.\theexample}}% \hrulefill\par\vspace{10pt}\noindent\rmfamily}% {\par\noindent\hrulefill\vrule width10pt height2pt depth2pt\par} \begin{document} \section{First equation} بعض النص التمهيدي... \begin{example} \begin{equation} f(x)=\frac{x}{1+x^2} \end{equation} \end{example} \subsection{More detail} \begin{example} هنا نناقش \begin{equation} f(x)=\frac{x+1}{x-1} \end{equation} ... لكن لا نقول شيئًا \end{example} \subsubsection{Even more detail} \begin{example} \begin{equation} f(x)=\frac{x^2}{1+x^3} \end{equation} \begin{equation} f(x+\delta x)=\frac{(x+\delta x)^2}{1+(x+\delta x)^3} \end{equation} \end{example} \section{Third equation} \begin{example} الدالة التالية... \begin{equation} f_1(x)=\frac{x+1}{x-1} \end{equation} ... هي دالة \begin{equation} f_2(x)=\frac{x^2}{1+x^3} \end{equation} \begin{equation} f_3(x)=\frac{3+ x^2}{1-x^3} \end{equation} \end{example} \end{document} ``` [افتح هذا `\counterwithin` المثال في Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Example+of+using+counterwithin\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Ccounterwithin%7Bequation%7D%7Bsection%7D%0A%5Cnewcounter%7Bexample%7D%0A%5Ccounterwithin%2A%7Bexample%7D%7Bsection%7D%0A%5Cnewenvironment%7Bexample%7D%5B1%5D%5B%5D%7B%25%0A%5Cstepcounter%7Bexample%7D%25%0A%5Cpar%5Cvspace%7B5pt%7D%5Cnoindent%0A%5Cfbox%7B%5Ctextbf%7BExample%7E%5Cthesection.%5Ctheexample%7D%7D%25%0A%5Chrulefill%5Cpar%5Cvspace%7B10pt%7D%5Cnoindent%5Crmfamily%7D%25%0A%7B%5Cpar%5Cnoindent%5Chrulefill%5Cvrule+width10pt+height2pt+depth2pt%5Cpar%7D%0A%5Cbegin%7Bdocument%7D%0A%5Csection%7BFirst+equation%7D%0ASome+introductory+text...%0A%5Cbegin%7Bexample%7D%0A%5Cbegin%7Bequation%7D%0A++++f%28x%29%3D%5Cfrac%7Bx%7D%7B1%2Bx%5E2%7D%0A%5Cend%7Bequation%7D%0A%5Cend%7Bexample%7D%0A%0A%5Csubsection%7BMore+detail%7D%0A%5Cbegin%7Bexample%7D%0AHere+we+discuss%0A%5Cbegin%7Bequation%7D%0A++++f%28x%29%3D%5Cfrac%7Bx%2B1%7D%7Bx-1%7D%0A%5Cend%7Bequation%7D%0A...+but+don%27t+say+anything%0A%5Cend%7Bexample%7D%0A%0A%5Csubsubsection%7BEven+more+detail%7D%0A%5Cbegin%7Bexample%7D%0A%5Cbegin%7Bequation%7D%0A++++f%28x%29%3D%5Cfrac%7Bx%5E2%7D%7B1%2Bx%5E3%7D%0A%5Cend%7Bequation%7D%0A%5Cbegin%7Bequation%7D%0A++++f%28x%2B%5Cdelta+x%29%3D%5Cfrac%7B%28x%2B%5Cdelta+x%29%5E2%7D%7B1%2B%28x%2B%5Cdelta+x%29%5E3%7D%0A%5Cend%7Bequation%7D%0A%5Cend%7Bexample%7D%0A%0A%5Csection%7BThird+equation%7D%0A%5Cbegin%7Bexample%7D%0AThe+following+function...%0A%5Cbegin%7Bequation%7D%0A++++f_1%28x%29%3D%5Cfrac%7Bx%2B1%7D%7Bx-1%7D%0A%5Cend%7Bequation%7D%0A..is+a+function%0A%5Cbegin%7Bequation%7D%0A++++f_2%28x%29%3D%5Cfrac%7Bx%5E2%7D%7B1%2Bx%5E3%7D%0A%5Cend%7Bequation%7D%0A%5Cbegin%7Bequation%7D%0A++++f_3%28x%29%3D%5Cfrac%7B3%2B+x%5E2%7D%7B1-x%5E3%7D%0A%5Cend%7Bequation%7D%0A%5Cend%7Bexample%7D%0A%5Cend%7Bdocument%7D) ينتج هذا المثال المخرجات التالية: ![استخدام الأمر \counterwithin](/files/4cb67ad891d48c4d7026183e61ac717d64f465b3) **ملخص الشيفرة** * `\newcounter{example}` : هذا ينشئ عدادًا جديدًا لاستخدامه في بيئتنا، يُسمّى أيضًا `مثال` * `\counterwithin*{example}{section}` : هذا يربط `مثال` عدادنا مع العداد `section` المستخدم داخل الأمر `\section` : في كل مرة نصدر فيها أمر `\section` ، فإن `مثال` العداد يُعاد ضبطه إلى الصفر. لاحظ أننا استخدمنا الصيغة النجمية `\counterwithin*` لتجنب إعادة تعريف `\theexample` * بعد ذلك، ننشئ بيئة جديدة تُسمّى أيضًا `مثال`. داخل تلك البيئة نستخدم `\stepcounter{example}` لزيادة عداد البيئة. لاحظ أيضًا أننا نكتب `\textbf{Example~\thesection.\theexample}` لإخراج **مثال** `<رقم القسم>.<رقم المثال>` ```latex \newenvironment{example}[1][]{% \stepcounter{example}% \par\vspace{5pt}\noindent \fbox{\textbf{Example~\thesection.\theexample}}% \hrulefill\par\vspace{10pt}\noindent\rmfamily}% {\par\noindent\hrulefill\vrule width10pt height2pt depth2pt} ``` **\counterwithout{somecounter}{anothercounter}** `\counterwithout{*somecounter*}{*anothercounter*}` يزيل الرابط بين `*somecounter*` و `*anothercounter*` بحيث يصبحان مستقلين. لأي زوج من العدادات، يمكنك التبديل بين استخدام `\counterwithout` و `\counterwithin`، كما يوضّح المثال التالي بالنسبة إلى `مثال` و `section` العدادات — يمكنك فتح هذا المثال في Overleaf باستخدام الرابط الموفَّر أسفل الشيفرة. ```latex \section{First equation} \begin{example} \begin{equation} f(x)=\frac{x}{1+x^2} \end{equation} \end{example} \subsection{Second equation} \begin{example} \begin{equation} f(x)=\frac{x+1}{x-1} \end{equation} \end{example} \vspace{6pt}\noindent لاحظ كيف يُعاد تعيين العداد \texttt{example} في بداية القسم \ref{sec:n0}. \section{Third equation} \label{sec:n0} \begin{example} \begin{equation} f(x)=\frac{x+1}{x-1} \end{equation} \end{example} \vspace{6pt}\noindent هنا، كتبنا \verb|\counterwithout{example}{section}| بحيث لا يُعاد تعيين \texttt{example} بعد الآن في بداية القسم. في القسمين \ref{sec:n1} و\ref{sec:n2} يستمر العداد \texttt{example} في الازدياد. \counterwithout{example}{section} \section{المعادلة الرابعة} \label{sec:n1} \begin{example} \begin{equation} f(x)=\frac{x^2+x^3}{1+x^3} \end{equation} \end{example} \section{المعادلة الخامسة} \label{sec:n2} \begin{example} \begin{equation} f(x,k)=\frac{x^2-x^k}{1+x^3} \end{equation} \end{example} ``` [افتح هذا `\counterwithout` المثال في Overleaf]() ينتج هذا المثال المخرجات التالية: ![استخدام الأمر counterwithout](/files/5523fb75e907bfc48339eaf271c7f0682f101d04) ## مثال ### enumerate ال `enumerate` تستخدم بيئة القائمة أربعة *عدّاد* متغيرات تتابع قيمة الوسم الحالية لكل مستوى: | | | | ----------- | ---------------------------- | | **المستوى** | **`enumerate`** متغير العداد | | المستوى 1 | `enumi` | | المستوى 2 | `enumii` | | المستوى 3 | `enumiii` | | المستوى 4 | `enumiv` | يمكن تغيير هذه العدادات باستخدام `\setcounter` الأمر. انظر إلى المثال أدناه—وهو ليس بالضرورة أفضل حل (انظر إلى [تسرد Overleaf](/latex/ar/asasyat-latex/04-lists.md) المقالة لمزيد من المعلومات): ```latex يوضح هذا المثال إحدى طرق تغيير ترقيم قائمة؛ هنا، يتم تغيير قيمة العداد \texttt{enumi} لبدء ترقيم القائمة عند 4 (ويزداد بواسطة الأمر \verb|\item|): \begin{enumerate} \setcounter{enumi}{3} \item شيء ما. \item شيء آخر. \item عنصر آخر. \item العنصر الأخير في القائمة. \end{enumerate} ``` [افتح هذا المثال في Overleaf](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Modifying+an+enumerate+counter\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cbegin%7Bdocument%7D%0A%5Csection%7BIntroduction%7D%0AThis+example+shows+one+way+to+change+the+numbering+of+a+list%3B+here%2C+changing+the+value+of+the+%5Ctexttt%7Benumi%7D+counter+to+start+the+list+numbering+at+4+%28it+is+incremented+by+the+%5Cverb%7C%5Citem%7C+command%29%3A%0A%0A%5Cbegin%7Benumerate%7D%0A%5Csetcounter%7Benumi%7D%7B3%7D%0A%5Citem+Something.%0A%5Citem+Something+else.%0A%5Citem+Another+element.%0A%5Citem+The+last+item+in+the+list.%0A%5Cend%7Benumerate%7D%0A%5Cend%7Bdocument%7D) ينتج هذا المثال المخرجات التالية: ![تعديل عدّاد القائمة المرقمة](/files/17eac378365f1d8b0056a0907b93d1529b3c7f0e) ## العدادات الافتراضية في LaTeX | الاستخدام | الاسم | | --------------------- | --------------------------------------------------------------------------------------------------- | | لبنية المستند |

- جزء
- فصل
- قسم
- قسم فرعي
- قسم فرعي فرعي
- فقرة
- فقرة فرعية
- صفحة

| | للأشكال الطافية |

- معادلة
- شكل
- جدول

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

- حاشية سفلية
- حاشية سفلية للصفحة المتعددة

| | لـ `enumerate` البيئة |

- enumi
- enumii
- enumiii
- enumiv

| ## قراءة إضافية لمزيد من المعلومات، انظر: * [البيئات](/latex/ar/alawamr/02-environments.md) * [الأوامر](/latex/ar/alawamr/01-commands.md) * [القوائم](/latex/ar/asasyat-latex/04-lists.md) * [ترقيم الصفحات](/latex/ar/altnsyq/03-page-numbering.md) * [الأقسام والفصول](/latex/ar/bnyh-almstnd/01-sections-and-chapters.md) * [التعابير الرياضية](/latex/ar/alryadhyat/01-mathematical-expressions.md) * [إدراج الصور](/latex/ar/mzyd-mn-almwdhwaat/27-inserting-images.md) * [الجداول](/latex/ar/alashkal-waljdawl/01-tables.md) * [كتابة الامتحانات في LaTeX](/latex/ar/khas-balmjal/09-typesetting-exams-in-latex.md) * [كتابة حزمة خاصة بك](/latex/ar/mlfat-alfeh/03-writing-your-own-package.md) * [كتابة فئة خاصة بك](/latex/ar/mlfat-alfeh/04-writing-your-own-class.md) * [المقدمة التي ليست قصيرة جدًا إلى LaTeX2ε](http://www.ctan.org/tex-archive/info/lshort/) --- # 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/altnsyq/10-counters.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.