اس منصوبے کے بارے میں

اس کتاب کی منصوبہ جاتی دستاویزات: یہ کیسے ترتیب دی گئی ہے، اسے کیسے بنایا اور جانچا جاتا ہے، اور سچائی کا ماخذ کہاں ہے۔ کتاب کے لیے فہرستِ مضامین دیکھیں۔

منصوبے کا نقشہ

• کتاب: locales/ کے تحت چار لوکیلز میں شائع ہوتی ہے؛ دیکھیں spec/locales.md۔ یہ لوکیل، en-gb-oxendict/topics/ (63 فائلیں)، en-gb-oxendict/front-matter/، اور حصہ 9 کے ضمیمے ہاتھ سے لکھا ہوا ماخذ ہیں؛ en-001، en-gb، اور en-us اسی سے اخذ ہوتے ہیں۔
• سچائی کا ماخذ: ریپوزٹری کی جڑ میں spec/ (سائٹ پر شائع نہیں ہوتا)۔ ڈھانچہ spec/structure.md میں، تحریر کے اصول spec/conventions.md میں، اور ہجے spec/oxford-spelling.md میں بیان ہیں۔ باقی سب کچھ مطابقت کے لیے بنایا جاتا ہے۔
• ٹولنگ: tools/localize.py باقی تین لوکیلز اخذ کرتا ہے؛ tools/gen_nav.py نیویگیشن بناتا ہے؛ tests/validate.py تفصیل نافذ کرتا ہے؛ justfile ان سب کو جوڑتا ہے۔
• شراکت کاروں کے لیے رہنمائی: ریپوزٹری کی جڑ میں AGENTS.md، اور شراکت کے حصے کی رہنما۔

بنانا اور جانچنا

توثیق کا سیٹ Python 3 پر چلتا ہے، دوسری کسی انحصار کے بغیر اور نیٹ ورک کے بغیر۔ کام just کے ذریعے چلتے ہیں۔

just test    # validate structure, style, links, and spec-vs-disk
just nav     # regenerate the generated navigation files
just check   # nav, then test
just stats   # topic and word counts

یہ ریپوزٹری کتاب کا مواد اور تفصیل رکھتی ہے۔ اسے ویب سائٹ میں الگ ریپوزٹری software-engineering-metrics.github.io تبدیل کرتی ہے۔

یہاں تفصیل پر مبنی ترقی کیسے کام کرتی ہے

تفصیل پہلے آتی ہے۔ spec/structure.md بیان کرتی ہے کہ کون سے موضوعات موجود ہیں اور ان کی نمبرنگ کیسے ہوتی ہے۔ spec/conventions.md بیان کرتی ہے کہ موضوعات کیسے لکھے جائیں۔ موضوعات دونوں کو پورا کرنے کے لیے لکھے جاتے ہیں۔ tools/gen_nav.py موضوعات سے نیویگیشن اخذ کرتا ہے اور tests/validate.py نتیجے کو تفصیل کے مقابل دوبارہ جانچتا ہے۔ اگر کوئی موضوع اور تفصیل کبھی الگ ہو جائیں تو ٹیسٹ ناکام ہوتا ہے، اور یہی انہیں دوبارہ ہم آہنگ کرنے کا اشارہ ہے۔

اس سے انحراف باہر رہتا ہے: تبدیلی تب ہی “مکمل” ہوتی ہے جب تفصیل، موضوعات، تیار کردہ نیویگیشن، اور ٹیسٹ سب متفق ہوں۔

ڈیزائن کے فیصلے جنہیں جاننا مفید ہے

• ہموار، اعشاری نمبر والے موضوعات۔ فائلیں locales/<locale>/topics/PP-CC-slug.md ہیں، ہر لوکیل میں ایک ہی سلگ۔ حصے مکمل اعداد ہیں؛ موضوعات اعشاری ہیں؛ N.0 حصے کا تعارف ہے۔ اس سے شناخت کنندگان مستحکم رہتے ہیں اور ٹولنگ ڈائریکٹری کے درخت کے بغیر ترتیب اور گروہ بندی کر سکتی ہے۔
• ایک ہاتھ سے لکھا لوکیل، تین اخذ شدہ۔ en-gb-oxendict آکسفورڈ ہجے ہے، زیادہ تر بین الاقوامی معیار سازی کے اداروں کا ہاؤس اسٹائل (دیکھیں spec/oxford-spelling.md)؛ en-001، en-gb، اور en-us اس سے میکانکی طور پر اخذ ہوتے ہیں، اس لیے ترجمے ماخذ سے کبھی نہیں بھٹکتے۔
• تیار کردہ نیویگیشن۔ فہرستِ مضامین، مواد کے صفحات، اور موضوعات کا اشاریہ تیار ہوتے ہیں، اس لیے وہ موضوعات سے کبھی نہیں بھٹکتے۔
• آف لائن، انحصار سے پاک ٹیسٹ۔ سیٹ صرف معیاری لائبریری استعمال کرتا ہے، اس لیے ہر جگہ چلتا ہے، بشمول CI اور pre-commit hooks۔
• باہمی حوالے سادہ متن رہتے ہیں۔ نثر موضوعات کو ان کے اعشاری نمبر سے حوالہ دیتی ہے (“موضوع 2.1 دیکھیں”)، جیسا تفصیل چاہتی ہے؛ رینڈر کرنے والی سائٹ ان حوالوں کو لنکس میں بدلنے کی ذمہ دار ہے۔
• طویل ڈیش نہیں، اصول کے لحاظ سے اور ٹیسٹ کے لحاظ سے۔ ایک دانستہ اسلوبی انتخاب، جو نافذ کیا جاتا ہے تاکہ کتاب بڑھنے کے ساتھ درست رہے۔
• ہر میٹرکس کا خاندان اپنی ہیرا پھیری کی راہ کا نام لیتا ہے۔ یہ ٹیمپلیٹ کا وہ واحد اصول ہے جس کا بہن منصوبے software-engineering-guide میں کوئی ہم منصب نہیں: یہ اس لیے موجود ہے کہ اس کتاب کا پورا موضوع پیمائش ہے، اس لیے پیمائش کا اپنا خطرہ اعلیٰ درجے کا ہونا چاہیے، مضمر نہیں۔

مزید مطالعہ

• تصنیف : موضوعات لکھنا اور ترمیم کرنا۔
• نیویگیشن : تیار کردہ فائلیں کیسے کام کرتی ہیں۔
• ٹیسٹنگ : ٹیسٹ کیا جانچتے ہیں اور ناکامیاں کیسے ٹھیک کی جائیں۔
• مثالیں : چھوٹی، ٹھوس مثالیں۔
• تبدیلیوں کا لاگ : قابلِ ذکر تبدیلیوں کی تاریخ۔