التنقل: كيف تعمل الملفات المولَّدة

لكل لغة، تُولَّد أربعة عناصر تنقل من مواضيع تلك اللغة، لا تُكتب يدويًا (إضافة إلى README.md الذي يُولَّد مرة واحدة للمحلية المرجعية en-gb-oxendict):

README.md (جدول المحتويات في الصفحة الرئيسية للمستودع؛ للمحلية المرجعية فقط)
locales/<locale>/index.md (الصفحة الرئيسية للموقع المنشور)
locales/<locale>/front-matter/table-of-contents.md
locales/<locale>/topics/09-07-index.md (الفهرس الموضوعي، مع الروابط)

تنتجها tools/gen_nav.py. لا تحرّرها يدويًا، لأن التوليد التالي سيستبدل تغييرك.

متى تعيد التوليد

شغّل just nav (أو python3 tools/gen_nav.py) كلما:

أضفت موضوعًا أو أزلته أو أعدت تسميته أو ترقيمه، أو
غيّرت عنوان موضوع # N.M Title (يستخدمه جدول المحتويات).

شغّل python3 tools/localize.py أولًا إذا غيّرت أي شيء تحت locales/en-gb-oxendict/، حتى تكون مواضيع المحليات الثلاث الأخرى (وعناوينها المولَّدة) محدّثة قبل أن يقرأها gen_nav.py؛ انظر spec/locales.md.

كيف يعمل

لكل محلية، يقرأ gen_nav.py كل ملف locales/<locale>/topics/*.md، ويرتّب بحسب الرقم العشري، ويجمّع بحسب الجزء، ثم:

يبني جدول المحتويات جزءًا بجزء من عنوان H1 لكل موضوع،
يكتبه في locales/<locale>/index.md و locales/<locale>/front-matter/table-of-contents.md (وفي README.md للمحلية المرجعية فقط)،
يمسح المواضيع الجوهرية (الأجزاء من 1 إلى 8) بحثًا عن قائمة ثابتة من المصطلحات الأساسية ويكتب الفهرس الموضوعي في locales/<locale>/topics/09-07-index.md.

أما النص المشترك (الفقرة التمهيدية، و”كيف تقرأ هذا الكتاب”، و”موضوعات شاملة”، وعناوين الأجزاء) فيُوطَّن بالطريقة نفسها التي يُوطَّن بها نثر المواضيع، عبر دوال المحلية في tools/localize.py، فتُقرأ الصفحات المولَّدة طبيعيةً في كل محلية.

تقيم عناوين الأجزاء في القاموس PART_TITLES قرب أعلى السكربت. ويستخدم المولِّد عناوين أجزاء بنمط النقطتين الرأسيتين (“Part 2: Delivery and Flow Metrics”)، ولا يستخدم الشرطات الطويلة أبدًا.

أما اللغات المترجمة يدويًا، فصفحتها الرئيسية وصفحة جدول المحتويات تُكتبان يدويًا (العناوين المترجمة وسطر المقدمة N.0 لكل جزء)، وتجدّد tools/gen_translated_nav.py قوائم المواضيع من عناوين H1 في مواضيع تلك اللغة.

ما لا يمسّه

المواصفات في جذر المستودع (spec/index.md وspec/structure.md وملحقاتها) هي مصدر الحقيقة المكتوب يدويًا. لا يكتبها المولِّد، وليست جزءًا من الموقع المنشور. إذا غيّرت البنية، فحدّث spec/structure.md بنفسك، ثم شغّل just nav للملفات المشتقة وjust test للتأكد من اتساق كل شيء.