المرجع التقنيّ الرسميّ للغة البرمجة العربية ص (Sad): النحو، الكلمات المحجوزة الأربعون، الأنواع المدمجة، العوامل وأسبقيّتها، والميزات المتقدّمة — مكتوبًا كـ mdBook عربيّ (RTL) يُنشَر آليًّا على GitHub Pages.
هذا المستودع هو الوجه المنشور للتوثيق التقنيّ للغة ص الموجَّه للمستخدم: من يكتب برامج بلغة ص ويريد مرجعًا دقيقًا للنحو والكلمات والأنواع والعوامل والميزات.
| المستودع | الجمهور | المحتوى |
|---|---|---|
sadlang-docs (هذا) |
مستخدمو اللغة | مرجع اللغة نفسها: نحو، كلمات، أنواع، عوامل، ميزات |
dev-guide |
مطوّرو المترجم | الأنظمة الداخلية: المعجمي/النحوي/AST/SIR/LLVM/المفسّر |
s-programming-language |
الجميع | شيفرة المصدر + language-truth/ (مصدر الحقيقة) + وثائق/ |
التوثيق مُوسوم بالإصدار عبر قناتين تُبنيان معًا عند كل نشر، فيكتب المطوّر التوثيق وقت التطوير دون أن يراه المستخدم قبل الإصدار الرسميّ:
| القناة | المسار | المصدر | الجمهور |
|---|---|---|---|
| 📕 المستقرّ | / |
فرع sadlang |
المستخدم (الافتراضيّ) |
| 🚧 القادم | /next/ |
فرع dev |
المطوّر (ميزات غير منشورة) |
لكلّ قناة تُعاد توليد صفحات المرجع من language-truth/ في فرعها — فمثلًا تظهر رموز
أمان العدم بصيغتها المنشورة في «المستقرّ» وبصيغتها القادمة في «القادم» تلقائيًّا.
لافتة أعلى كل صفحة تتيح التنقّل بين القناتين. يبنيهما deploy.yml.
فرعٌ واحد يُبنى مرّتين، فالنثر مشتركٌ بين القناتين بطبيعته. لتوثيق ميزةٍ ما زالت
على dev، لُفّها بكتلةٍ تُحذف عند بناء المستقرّ:
<!-- قادم:بداية -->
هذه الفقرة لا تظهر إلّا في /next/.
<!-- قادم:نهاية -->ويحرس ذلك ثابتٌ مقيس لا وعدٌ مكتوب:
بناءُ القناة المستقرّة لا يحوي معرِّفًا غائبًا عن SoT المستقرّ.
scripts/channel_gate.py يشتقّ قائمة المراقبة من
(رموز dev − رموز sadlang) — لا قائمةَ إذنٍ مكتوبةً بيدٍ تتعفّن — ثمّ يمسح النثر عنها
بحدود كلمة، ويُفشل الـCI. لماذا مُشتقّة ومقيسة: قبل البوّابة كان التسرّب صفرًا لكنّه
صفرٌ بالصدفة لا بالحراسة؛ لا شيء كان يمنع الفقرة التالية.
ولمَ لا فرعُ dev في مستودع التوثيق؟ لأنّه يعيد بناءَ نسختين تتباعدان — وهي
العلّة عينها التي اقتُلعت بإخراج الصفحات المشتقّة من git. حلٌّ يناقض أخاه ليس حلًّا.
الحقيقة الرسمية للقواعد والكلمات والأنواع تعيش داخل المستودع الأساسيّ في
language-truth/
(ملفّات YAML مُحكَّمة بمخطّطات JSON). هذا المستودع يعرض ويشرح تلك الحقيقة بصيغة
قابلة للقراءة، ولا يخترع قواعد جديدة. عند أيّ تعارض، language-truth/ هو الفيصل.
صفحات المرجع التابعة تُولَّد عند كلّ بناء من language-truth/، ولا توجد في git:
| الصفحة (مُولَّدة) | المصدر |
|---|---|
src/reference/keywords.md |
language-truth/keywords.yaml |
src/reference/operators.md |
language-truth/operators.yaml |
src/reference/types.md |
language-truth/keywords.yaml + types.yaml |
src/reference/sadui-properties.md |
language-truth/ui_props.yaml |
python scripts/gen_reference.py --fetch dev # يجلب SoT بنفسه ويولّدلماذا لا تُودَع؟ النسخةُ المودَعةُ لمشتقٍّ تنجرف عن أصلها حتمًا — حدث مرّتين
(القضيّتان #1 و#8). وحين لا تُودَع، يصير الانجراف مستحيلًا بنيويًّا لا مرصودًا
بعد أسابيع. الثمن أنّ الحارس القديم (--check) فقد معناه، وكان معناه ضعيفًا أصلًا:
يقارن مخرج المولّد بمخرج المولّد من مصدرٍ متحرّك — طرفان من أصلٍ واحد. بدلَه
اختباراتٌ ذهبيّة على لقطة SoT مجمَّدة تقيس المولّد وحده: tests/.
- المولّد:
scripts/gen_reference.py— و--fetchفيه هو مسار الجلب الوحيد الذي يستعمله المساهم وci.ymlوdeploy.ymlمعًا. - بيان المنشأ:
sync/sources.yaml— وصفيّ لا تنفيذيّ.
cargo install mdbook mdbook-mermaid # مرّة واحدة
mdbook-mermaid install . # توليد أصول المخطّطات
pip install pyyaml # للمولّد
python scripts/gen_reference.py --fetch dev # ⚠️ لازم: صفحات المرجع غير مودَعة
mdbook serve --open # تطوير حيّ على المتصفّح
mdbook build # بناء ثابت في book/الخطوة الرابعة ليست اختياريّة، وفخُّها مقيس: SUMMARY.md يشير إلى صفحات
reference/ المُولَّدة، وmdBook لا يفشل إن غابت — بل يُنشئ جذاذةً من العنوان وحده
(٣٢ بايتًا) ويبني بنجاح، فتُنشَر صفحات مرجعٍ بيضاء بصمت. لذلك يسبق البناءَ حارسٌ في
السيرين: python scripts/gen_reference.py --verify. مرّة واحدة تكفي (تُخبَّأ في .sot-cache/).
sadlang-docs/
├── book.toml # إعداد mdBook (عربي RTL، سمة navy، mermaid)
├── src/
│ ├── SUMMARY.md # فهرس الكتاب (شجرة الفصول)
│ ├── introduction.md # المقدّمة
│ ├── getting-started/ # البدء: التثبيت + أوّل برنامج
│ ├── language/ # دروس اللغة موضوعًا موضوعًا
│ └── reference/ # المرجع الدقيق: الكلمات/العوامل/الأنواع/النحو
├── theme/ # دعم RTL + تكبير الخط (عربيّ)
├── tests/ # لقطة SoT مجمَّدة + الذهبيّ + اختبارات المولّد
└── .github/workflows/ # ci.yml (ذهبيّ + بناء القناتين + روابط) + deploy.yml
اقرأ CONTRIBUTING.md. باختصار: عدّل تحت src/، شغّل mdbook build
محليًّا، افتح PR إلى main. الـCI يشغّل الاختبارات الذهبيّة ويبني القناتين ويفحص
الروابط؛ الدمج في main ينشر تلقائيًّا. والدفع المباشر إلى main يمرّ بالفحص نفسه.
التوثيق متاح للعموم تحت رخصة المنظمة (راجع المستودع الأساسيّ للغة ص).