> 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/qaadh-almarfh/149-using-the-stop-on-first-error-compilation-mode.md).

# استخدام وضع التجميع إيقاف عند أول خطأ

تشرح هذه المقالة كيفية استخدام **إيقاف عند أول خطأ** وضع التجميع في Overleaf، إلى جانب مراجعة بعض الموضوعات الخلفية المهمة، بما في ذلك:

* ما هو [وضع تجميع LaTeX](#introduction-to-latex-errors-and-compilation)?
* [أوضاع التجميع في Overleaf](#compilation-modes-on-overleaf)
* كيف **إيقاف عند أول خطأ** يمكن أن يكون [مفيد للتنقيح](#benefits-of-using-the-stop-on-first-error-mode)

لتخطي المعلومات الخلفية يمكنك الانتقال مباشرةً إلى القسم الذي يشرح [كيفية تفعيل وضع التجميع «التوقف عند أول خطأ»](#the-stop-on-first-error-compilation-mode).

## مقدمة إلى أخطاء LaTeX والتجميع

تحويل مستند LaTeX إلى ملف PDF مُنسّق هو نتيجة عملية تُسمى *التجميع*: برنامج تنفيذي، يُعرف باسم «مترجم LaTeX»، يقرأ محتوى مستندك وينفذ أوامر LaTeX المكوِّنة له لإنشاء ملف PDF المُنسّق.

عند كتابة ترميز LaTeX (الكود) من الطبيعي جدًا أن ترتكب أخطاء، والتي أثناء التجميع تتسبب في أن يصدر المترجم رسائل خطأ تحاول شرح ما الذي *يعتقد* أنه تسبب في المشكلة(المشكلات). وكما هو الحال مع لغات البرمجة الأخرى، يمكن لخطأ واحد في كود LaTeX لمستندك أن يطلق سلسلة متتابعة من الأخطاء، لكل منها رسالته المقابلة. في Overleaf، تُبلَّغ رسائل أخطاء التجميع إلى المستخدم عبر [إشعار أحمر بجوار **إعادة التحويل** الزر](#overleafs-latex-error-reporting)، ويمكنك النقر على **لوحة السجلات وملفات الإخراج** الأيقونة لعرضها.

### التعامل مع الأخطاء: أوضاع التجميع

مترجمات LaTeX، والمعروفة أيضًا باسم [محركات TeX](/latex/ar/mqalat-mtamqh/55-what-s-in-a-name-a-guide-to-the-many-flavours-of-tex.md)، تحتوي على *أوضاع تجميع* مدمجة (يمكن للمستخدم اختيارها) تحدد كيفية التعامل مع الأخطاء. وتستخدم القائمة النقطية التالية تسمية Overleaf *التفسيرية/الوصفيّة الخاصة بها* لكل واحد من تلك الأوضاع:

* **حاول التجميع رغم الأخطاء**—بمعنى آخر، استمر في محاولة التجميع رغم مواجهة الأخطاء، على أمل الأفضل، وقد ينتج ملف PDF لكنه قد يحتوي على أخطاء تنسيقية.
* **إيقاف عند أول خطأ**—في الواقع «ينسحب» عند أول علامة على وجود مشكلة، ويعرض رسالة للمستخدم ويخرج دون إنشاء ملف PDF. وهذا يتجنب إثارة سلسلة لاحقة من الأخطاء، مما يتيح لك التركيز على إصلاح أول خطأ وإعادة تجميع المستند.
* **إيقاف التجميع مؤقتًا للتفاعل مع المستخدم**—يُوقف التجميع مؤقتًا لتقديم المساعدة وتوفير آليات تمكّن المستخدمين من إصلاح الأخطاء ومتابعة التجميع. هذا ممكن مع تثبيت LaTeX محلي، لكنه غير عملي على Overleaf.

## أوضاع التجميع في Overleaf

لإدارة عملية تجميع LaTeX، يستخدم Overleaf [أداة بناء تُسمى latexmk](/latex/ar/qaadh-almarfh/064-how-does-overleaf-compile-my-project.md) والتي تستخدم افتراضيًا وضع تجميع تشير إليه Overleaf باسم **حاول التجميع رغم الأخطاء:** ستحاول أداة البناء إنشاء ملف PDF مُنسّق، حتى لو وُجدت [أخطاء تجميع LaTeX](/latex/ar/asasyat-latex/05-errors.md).

في **حاول التجميع رغم الأخطاء** في وضع التجميع هذا لا يتوقف مترجم LaTeX إذا اكتُشفت أخطاء؛ بل يحاول تخمين نية المستخدم بأفضل صورة ويطبق «إصلاحات» بناءً على ذلك التخمين—وقد يتم أيضًا «تجاوز» الكود المشكل. المترجم *قد* يعود إلى حالة يمكن أن تكتمل فيها عملية التجميع في النهاية لإنشاء ملف PDF، على الرغم من أن ملف PDF الناتج قد يحتوي على مخرجات غير صحيحة. وغالبًا ما تكون الأخطاء التي تم العثور عليها شديدة جدًا، أو كثيرة جدًا، بحيث لا يستطيع مترجم LaTeX إصلاحها، لذا قد «ينسحب» أيضًا دون إنتاج ملف PDF.

### إبلاغ Overleaf عن أخطاء LaTeX

كما ذُكر أعلاه، تُبلَّغ رسائل الخطأ المُولَّدة أثناء التجميع إلى المستخدم عبر إشعار أحمر بجوار **إعادة التحويل** الزر:

![لقطة شاشة تُظهر أخطاء LaTeX المُبلَّغ عنها في Overleaf](/files/2b0c6355940b45e1762b943db5dd368dddbcf848)

يمكنك النقر على **لوحة السجلات وملفات الإخراج** الأيقونة لعرض مزيد من التفاصيل حول الخطأ(الأخطاء). على سبيل المثال، إذا كنت قد كتبت عن طريق الخطأ `\texbf{word}` بدلاً من `\textbf{word}`، فسيظل Overleaf يعرض معاينة PDF مُجمَّعًا مع رسالة الخطأ بشأن الأمر غير المُعرَّف، لكن «word» لن تكون بخط عريض في ملف PDF!

## وضع التجميع «التوقف عند أول خطأ»

يمكن للمستخدمين الآن تغيير وضع تجميع LaTeX بالتبديل إلى **إيقاف عند أول خطأ** الوضع الذي يتسبب في إنهاء Overleaf للتجميع فور اكتشاف أول خطأ.

### كيفية تفعيل «التوقف عند أول خطأ»

حدد المثلث الصغير بجوار **إعادة التحويل** الزر ثم اختر **إيقاف عند أول خطأ** من **إعادة التحويل** القائمة المنسدلة:

![لقطة شاشة تُظهر كيفية تمكين وضع التجميع إيقاف عند أول خطأ](/files/2c7cd91a80d032382f08a17bd8811b3ede2f2eca)

#### نطاق إعداد هذا الوضع

ال **إيقاف عند أول خطأ** الوضع هو إعداد خاص بكل مستخدم ولكل مشروع على حدة. سيؤدي تفعيل هذا الوضع إلى *تحتوي* التأثير في مشاريعك الأخرى، أو أي متعاونين في المشروع نفسه.

### إيقاف «التوقف عند أول خطأ»

عندما **إيقاف عند أول خطأ** مُفعّلًا، يمكنك العودة إلى وضع التجميع الافتراضي عن طريق اختيار الزر الأزرق **تعطيل «التوقف عند أول خطأ»** الموجود في مربع الحوار الذي يظهر عند حدوث خطأ في التجميع:

![لقطة شاشة تُظهر رسالة فشل التجميع](/files/5e4aaf167fccfa099a33538e58d18b40b28f09ee)

يمكنك أيضًا الانتقال إلى **إعادة التحويل** القائمة المنسدلة، ثم اختيار **حاول التجميع رغم الأخطاء** الوضع:

![لقطة شاشة تُظهر كيفية تعطيل وضع التجميع «التوقف عند أول خطأ»](/files/4a68239b5ea4f629adaadd28fde27e0af77bcfa4)

### ملاحظات ونصائح إضافية

إذا كان مشروعك خاليًا من أخطاء تجميع LaTeX، فسيظهر عرض PDF مُسبق كالمعتاد. إذا كان مشروعك *لا* يحتوي على أخطاء تجميع LaTeX، سيتوقف التجميع فورًا عند أول خطأ. تُعرض رسالة الخطأ الأولى كما هو موضح في لقطة الشاشة أدناه، بحيث يمكنك التركيز على تنقيح الخطأ في كود المصدر الخاص بك. في هذه اللقطة، يعود الخطأ إلى الاستخدام غير الصحيح لـ `\caption{...}\label{...}` داخل بيئة tabular. ينبغي نقل السطر 15 ليأتي قبل `\begin{tabular}`.

![لقطة شاشة تُظهر خطأ LaTeX نموذجيًا](/files/111ed84cc49ac72c13a782c02db837ab21dddd8c)

انقر على **إعادة التحويل** بعد تصحيح كل خطأ، ثم كرر عملية التنقيح هذه لكل خطأ تجميع لاحق. عندما يصبح مشروعك خاليًا من أخطاء LaTeX، فإن **إيقاف عند أول خطأ** الوضع سيعرض ملف الـPDF الذي جرى تجميعه بنجاح.

### فوائد استخدام وضع «التوقف عند أول خطأ»

* **يساعد في تنقيح مهلات التجميع.** بعض أنواع أخطاء التجميع شديدة الخطورة جدًا (مثل الاستدعاء العودي غير المقصود) بحيث يمكنها أن تمنع **حاول التجميع رغم الأخطاء** وضع التجميع، مما يؤدي إلى [انتهاء مهلة التجميع](/latex/ar/qaadh-almarfh/038-fixing-and-preventing-compile-timeouts.md#fatal-compile-errors-blocking-the-compilation) في مشروع Overleaf. إن تفعيل **إيقاف عند أول خطأ** هذا الوضع قد يساعد في تحديد مثل هذه الأخطاء وتنقيحها.
* **لا تدع أخطاءك تتراكم.** قد يفضل بعض المستخدمين سلوك محررات LaTeX الأخرى، حيث تتوقف عملية التجميع عند أول خطأ LaTeX يتم العثور عليه، حتى يتمكنوا من تصحيح الخطأ قبل إعادة التجميع. إن منع الأخطاء من التراكم—ومنعها من إطلاق فيضان من الأخطاء اللاحقة—يتجنب الحاجة إلى تنقيح أكثر من 100 رسالة خطأ في التجميع، وهو أمر قد يصبح صعبًا ومملًا بعض الشيء.
* **يمكن أن يؤدي تفعيل وضع «التوقف عند أول خطأ» إلى اكتشاف أخطائك بسرعة (إن وُجدت).** إذا كان لديك مستند كبير أو معقد يستغرق وقتًا أطول في التجميع، فإن **حاول التجميع رغم الأخطاء** هذا الوضع يتطلب منك الانتظار حتى يكتمل التجميع. وإذا كانت هناك أخطاء تحتاج إلى إصلاحها، فقد يستغرق الأمر وقتًا طويلاً لأنك ستضطر إلى الانتظار قبل أن تتمكن من رؤية أول خطأ في التجميع ومحاولة إصلاحه.
* **إن تعلم تنقيح الأخطاء جزء أساسي من تعلم LaTeX.** ال **إيقاف عند أول خطأ** يمكن أن يساعد هذا الوضع مبتدئي LaTeX على تعلم واعتماد عادات جيدة لكتابة كود LaTeX مبكرًا، وربما يسرّع رحلتهم إلى إتقان LaTeX. قد تبدو أخطاء LaTeX غريبةً ومبهمةً إلى درجة مغرية جدًا لتجاهلها وترك المترجم يواصل العمل—على أمل أن يظهر ملف PDF في النهاية، حتى لو كان ذلك الـPDF يحتوي على أخطاء تنسيقية. وعلى المدى الطويل، يمكن أن يؤدي تجاهل أخطاء التجميع إلى عادات برمجية سيئة قد تُوقعك في مشكلة مستقبلًا، ربما أثناء تقديم ورقة مهمة لمجلة! إذا كنت تُدرِّس صفًا عن LaTeX، فيمكن لطلابك استخدام **إيقاف عند أول خطأ** هذا الوضع لتطوير مهارات تنقيح أخطاء LaTeX.

## أخطاء لا يبدو أنها تنشأ داخل ملفاتك

إذا أوقفت التجميع يدويًا في **حاول التجميع رغم الأخطاء** الوضع، ثم فعّلت **إيقاف عند أول خطأ**، فقد ينتج عن التجميع التالي بعض رسائل الخطأ التي تبدو عشوائية، مثل `! File ended while scanning use of \@writefile`، والتي لا يبدو أنها تنشأ من داخل ملفاتك. قد ترجع هذه الأخطاء إلى ملفات مبتورة تم إنشاؤها بواسطة التجميع غير المكتمل السابق، وبقيت منه. في هذه الحالة، قد ترغب في إجراء [إعادة التجميع من البداية](/latex/ar/qaadh-almarfh/028-clearing-the-cache.md) حتى يكون للتجميع التالي، وهو لا يزال في **إيقاف عند أول خطأ** الوضع، فرصة للبدء من جديد وعرض أول خطأ ذي صلة. إذا كنت لا تزال تتلقى أخطاء من ملف يبدو غير موجود—مثل، `output.aux`, `output.toc` إلخ—فألقِ نظرة على [صفحة المساعدة هذه](/latex/ar/qaadh-almarfh/066-how-to-find-and-fix-errors-reported-in-generated-files.md).

## بعض التفاصيل منخفضة المستوى

ال **حاول التجميع رغم الأخطاء** يعمل وضع التجميع `latexmk` بالأعلام التالية:

```latex
latexmk -f -interaction=nonstopmode …
```

ال **إيقاف عند أول خطأ** سيشغّل وضع التجميع latexmk بالأعلام التالية بدلًا من ذلك:

```latex
latexmk -halt-on-error -interaction=nonstopmode …
```

وبما أنك هنا، فقد يهمك أيضًا قراءة المزيد عن [كيفية استخدام Overleaf لـ `latexmk` الأداة](/latex/ar/qaadh-almarfh/064-how-does-overleaf-compile-my-project.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/qaadh-almarfh/149-using-the-stop-on-first-error-compilation-mode.md?ask=<question>&goal=<endgoal>
```

`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.