नेविगेशन: उत्पन्न फ़ाइलें कैसे काम करती हैं

हर लोकेल के लिए, चार नेविगेशन कलाकृतियाँ उस लोकेल के विषयों से उत्पन्न होती हैं, हाथ से नहीं लिखी जातीं (साथ में 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 शीर्षक बदलें (विषय-सूची इसका उपयोग करती है)।

यदि आपने locales/en-gb-oxendict/ के अंतर्गत कुछ बदला हो तो पहले python3 tools/localize.py चलाएँ, ताकि 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 चलाएँ।