हम एक खुले Embox प्रोजेक्ट में प्रलेखन कैसे विकसित करते हैं

शुभ दोपहर

ओपन-सोर्स एमबॉक्स प्रोजेक्ट के डेवलपर्स में से एक के रूप में, मैंने अक्सर (बहुत बार हाल ही में) सुना है कि प्रोजेक्ट दिलचस्प है, लेकिन चूंकि कोई प्रलेखन नहीं है, इसलिए इसका उपयोग नहीं किया जा सकता है। हमने जवाब दिया कि कुछ प्रकार के प्रलेखन थे, कि हम हमेशा सवालों के जवाब दे सकते हैं, कि चरम मामलों में, आप इसे अपने दम पर जानने की कोशिश कर सकते हैं, क्योंकि परियोजना खुली है, लेकिन यह सब फिट नहीं था। मुझे डेवलपर्स के लिए इस बहुत अप्रिय विषय से निपटना था। लेकिन स्वाभाविक रूप से, लेख इस तथ्य के बारे में नहीं है कि प्रलेखन "अप्रिय" है! और कैसे हमने प्रलेखन विकास प्रक्रिया को और अधिक आरामदायक बनाया। वास्तव में, किसी भी अधिक या कम बड़ी परियोजना में, प्रलेखन से संबंधित मुद्दे आवश्यक रूप से उत्पन्न होते हैं।

उन लोगों के लिए जो पढ़ने में बहुत आलसी हैं, मैं तुरंत कहूंगा कि अंत में हम मार्कडाउन प्रारूप में प्रलेखन के विकास के लिए आए थे। खैर, उन लोगों के लिए जो विवरणों में रुचि रखते हैं, किन कारणों से मार्कडाउन, और इस दृष्टिकोण के पेशेवरों और विपक्ष क्या हैं, मैं बिल्ली के लिए पूछता हूं।

मैं विषय की प्रासंगिकता को उचित ठहराकर शुरू करूँगा। इतना ही नहीं Embox में प्रलेखन समस्याएं हैं। उदाहरण के लिए, Google ने तकनीकी लेखकों सीज़न ऑफ़ डॉक्स के लिए Google समर ऑफ़ कोड (GSOC) प्रोग्राम के एनालॉग की घोषणा की है । Kaspersky Lab कंपनी तकनीकी लेखकों के लिए सम्मेलन आयोजित करती है । और कंपनी समानताएं प्रलेखन लिखने के तरीके पर हब पर लेख प्रकाशित करती है। यह सब इंगित करता है कि विषय महत्वपूर्ण है और शायद अवांछनीय रूप से ध्यान से वंचित है।

ऊपर वर्णित लेखों की श्रृंखला प्रलेखन की सही सामग्री को समझती है, लेकिन यदि आप चाहें तो मैं प्रलेखन, प्रौद्योगिकी के विकास की प्रक्रिया पर ध्यान केंद्रित करना चाहता हूं। दरअसल, एक ओपन सोर्स प्रोजेक्ट के लिए, हॉलमार्क विकास प्रक्रिया की एक संपत्ति के रूप में खुलापन है। और हम एक ऐसी प्रक्रिया बनाना चाहते थे जो हमारी परियोजना की आवश्यकताओं को पूरा करे।

हमारे दस्तावेज़ीकरण विकास प्रक्रियाओं के इतिहास में एक छोटा विषयांतर।
एक बार प्रोजेक्ट googlecode पर स्थित था। हमारे पास एक बहुत अच्छा विकी था, कई लोग इसके बारे में भी याद करते हैं, पूछते हैं कि इसे कहां ढूंढें और इसे गिथब में स्थानांतरित करने के लिए कहें, जहां परियोजना अब स्थित है (या किसी अन्य सुलभ स्थान पर)। Googlecode विकि वास्तव में बहुत उपयोगी थी। यह बहुभाषी था और मेरी राय में, गीथुब पर विकी से अधिक विशेषताएं थीं। लेकिन ऐसा हुआ कि, Googlecode के साथ मिलकर, यह गुमनामी में डूब गया है। गिथुब पर वर्तमान विकी परियोजना के बारे में परिचालन जानकारी देने के लिए इसे सौंपे गए कार्य को काफी अच्छी तरह से करता है, लेकिन इस मंच पर पूर्ण प्रलेखन बनाना काफी कठिन है।

बेशक, किसी भी ओपन सोर्स प्रोजेक्ट के लिए, आपको ऑनलाइन (जल्दी से सुलभ) दस्तावेज दोनों की आवश्यकता होती है, जिसकी भूमिका विकी द्वारा निभाई जाती है, और ऑफ़लाइन उपलब्ध पूर्ण प्रलेखन, क्योंकि परियोजना के सार और विचारधारा को समझना बहुत आसान है। इसके अलावा, एक एकल दस्तावेज़ पर ऑफ़लाइन खोज करना, विकी विकी पृष्ठों के बजाय, बहुत आसान है।

संभवतः सबसे अच्छा विकल्प मुझे पता है कि एआरएम प्रलेखन है । अर्थात्, ऑनलाइन दस्तावेज़, जहाँ सभी वर्गों में खोज होती है, लेकिन पीडीएफ प्रारूप में डाउनलोड के लिए एक विशिष्ट दस्तावेज़ उपलब्ध है। दुर्भाग्य से, Embox क्षमताओं के मामले में अभी तक एआरएम के स्तर तक नहीं पहुंचा है। इसलिए, हमें ऑफ़लाइन संस्करण को अलग से करना पड़ा। इसके लिए, हमने Google डॉक्स सेवा का उपयोग किया। यह सुविधाजनक है क्योंकि: यह आपको विभिन्न प्रारूपों में डेटा डाउनलोड करने, सहयोग करने और एक अंतर्निहित संस्करण नियंत्रण प्रणाली की अनुमति देता है। हमने विकी से कुछ जानकारी स्थानांतरित की, संरचना निर्धारित की, क्योंकि ऑफ़लाइन संस्करण को विकसित करने का लक्ष्य समग्र दस्तावेज बनाना था, और कई दस्तावेजों को विकसित करना शुरू किया। लेकिन काफी तेजी से, हम समस्याओं में भाग गए। जानकारी पुरानी थी, विकी के डेटा ऑफ़लाइन दस्तावेज़ से डेटा से मेल नहीं खाते थे, और सबसे महत्वपूर्ण बात, हम पूर्ण दस्तावेज़ बनाने में सक्षम नहीं थे। एक संरचना थी, लेकिन चूंकि यह उपयोगकर्ताओं से अच्छी प्रतिक्रिया प्राप्त करना संभव नहीं था, इसलिए यह निकला कि केवल इसके निर्माता ही प्रलेखन को समझ सकते हैं। यह निश्चित रूप से एक सेवा समस्या नहीं है, लेकिन तथ्य, जैसा कि वे कहते हैं, स्पष्ट है। हमें इस समस्या के लिए एक अलग दृष्टिकोण की तलाश करनी थी।

फिर हमने पुराने विकी से डेटा को विकी गिथब में स्थानांतरित करने की कोशिश की, लेकिन फिर भी हम जल्दी से समस्याओं में भाग गए। हमने पाया कि सूचना का हिस्सा पुराना है, भाग नहीं जोड़ा गया है, भाग स्पष्ट नहीं था कि इसे उपयोगकर्ता के अनुकूल रूप में कैसे प्रस्तुत किया जाए। समस्या के समाधान के लिए खोज जारी रखते हुए, कुछ बिंदु पर, हमने जीईटी रिपॉजिटरी का उपयोग करके भी टीईएक्स में दस्तावेज विकसित करने पर विचार किया, लेकिन जल्दी से एहसास हुआ कि यह पहले से ही बहुत अधिक था। हालांकि इस विचार का प्रभाव पड़ा।

हमने यह तय करने का निर्णय लिया कि हम दस्तावेज़ीकरण से क्या चाहते हैं, जिसका अर्थ है विकासशील प्रलेखन की प्रक्रिया से, हम सामग्री को कोष्ठक के बाहर छोड़ देते हैं:

• प्रलेखन को पाठ प्रारूप में रखा जाना चाहिए क्योंकि यह संस्करण नियंत्रण प्रणाली के रूप में गिट का उपयोग करने वाला था
• दस्तावेज़ में ऑनलाइन (विकी) और ऑफ़लाइन (अलग-अलग दस्तावेज़, उदाहरण के लिए, पीडीएफ में) संस्करण होने चाहिए
• ऑनलाइन और ऑफलाइन प्रलेखन आसानी से सिंक्रनाइज़ करने में सक्षम होना चाहिए।
• प्रलेखन में ऐसे खंड (अध्याय) शामिल होने चाहिए, जिन्हें अलग से विकसित या अध्ययन किया जा सकता है, लेकिन जिनसे आप पूर्ण प्रलेखन की रचना कर सकते हैं

अंक में से कोई भी मार्कडाउन के उपयोग के विपरीत नहीं है, और यह दिलचस्प था क्योंकि यह पहले से ही विकी पर उपयोग किया जाता है। आप निश्चित रूप से, एक अलग प्रारूप का उपयोग कर सकते हैं और इसे मार्कडाउन में बदल सकते हैं। लेकिन आवश्यकताओं की एक और सूची संकलित करने के बाद, इस बार विभिन्न प्रकार की सामग्री (चित्र, पाठ, स्वरूपण) को जोड़ने की क्षमता के लिए, हम इस निष्कर्ष पर पहुंचे कि मार्कडाउन हमारी सभी मौजूदा जरूरतों को पर्याप्त रूप से संतुष्ट करता है। और "मार्कटैड टू पीडीएफ" विषय पर बहुत पहले गूगल ने दिखाया कि मार्कडाउन को अन्य प्रारूपों में बदलने के विकल्प मौजूद हैं और काफी लोकप्रिय हैं।

मार्कडाउन को पीडीएफ में बदलने के लिए कई विकल्प हैं , लेकिन पैंडॉक अब तक सबसे लोकप्रिय है। यह उपयोगिता किसी भी पाठ प्रारूप को किसी भी पाठ प्रारूप में बदल सकती है। इसके अलावा, यह ब्रैकट है। इसलिए, यह न केवल हमारे लिए परिचित है, बल्कि विभिन्न स्वरूपों में प्रलेखन बनाने के लिए स्क्रिप्ट में भी बनाया जा सकता है।

हमने उपयोगिता पर फैसला किया और अगले छोटे प्रश्न के बारे में सोचना शुरू किया, जिसे हमें हल करना था, अर्थात् एक एकल दस्तावेज़ कैसे बनाया जाए, और अलग-अलग मार्कडाउन फ़ाइलों से प्राप्त विभिन्न अध्यायों के साथ बहुत सारी पीडीएफ फाइलें नहीं थीं। पहली इच्छा बस वांछित अनुक्रम में "फाइलों को बचाने" (विभिन्न फ़ाइलों से पाठ को मर्ज करने) की थी, लेकिन यह बहुत सरल हो गया, पैंडोक खुद ही फाइलों की सूची के साथ काम करने में पूरी तरह से सक्षम है। इससे हमें उस समस्या को आंशिक रूप से हल करने की अनुमति मिली, जिसमें हमें विभिन्न दस्तावेजों की आवश्यकता होती है, जिसमें सामग्री अंतर हो सकती है। उदाहरण के लिए, हम तीन दस्तावेज़ उत्पन्न करते हैं और तीनों में एक संक्षिप्त विवरण अनुभाग होता है। हम सभी दस्तावेज़ों के लिए सूची में केवल इस फ़ाइल को सूचीबद्ध करते हैं।

हम पृष्ठों को कवर करने के लिए एक समान सिद्धांत लागू करते हैं जहां दस्तावेज़ का शीर्षक निहित है, और इसी तरह। हमने केवल प्रत्येक दस्तावेज़ के लिए हेडर के साथ फाइलें बनाई हैं और उन्हें पैंडोक के लिए स्रोत सूची में पहली फ़ाइलों के रूप में शामिल किया है।

जैसा कि आप शायद अनुमान लगाते हैं, यह (विभिन्न फ़ाइलों की एक सूची) बहुभाषावाद के साथ समस्या को हल करती है, हम सिर्फ वांछित भाषा के साथ फाइलों को निर्दिष्ट करते हैं।

चलो रूसी के बारे में थोड़ा और बात करते हैं। पीडीएफ जेनरेट करते समय, पंडोक लेटेक्स को रेंडरिंग, स्पेल चेकर और इसी तरह बैकेंड के रूप में उपयोग करता है। डिफ़ॉल्ट रूप से, सिरिलिक प्रदर्शित नहीं होता है और एक अज्ञात चरित्र के बारे में एक त्रुटि प्रदर्शित होती है। यह बहुत ही सरल रूप से हल किया गया है, बस "बेबल रूसी" निर्दिष्ट करें।

--- ... header-includes: - \usepackage[russian]{babel} --- 

यह ध्यान दिया जाना चाहिए कि यह इंगित करने के लिए अधिक सही है

 --- ... header-includes: - \usepackage[russian, english]{babel} --- 

और पाठ में लेटेक्स कमांड का उपयोग करें

 \selectlanguage{russian} \foreignlanguage{english}{ English text } 

या

 \begin{otherlanguage}{english} Text in english \end{otherlanguage} 

लेकिन जब से हम विकि पर संभावित हस्तांतरण के लिए "साफ" मार्कडाउन रखना चाहते थे, और यह पता चला कि बाबेल निर्देश हमारे उद्देश्यों के लिए पर्याप्त था, हमने इसे जटिल नहीं बनाने का फैसला किया और इसे छोड़ दिया।

बेशक, हम किसी भी तरह से दस्तावेज़ों को प्रारूपित नहीं करना चाहते थे, लेकिन कम से कम एक समान दिखना चाहते थे। और यहाँ लेटेक्स ने हमारी फिर से मदद की। तथ्य यह है कि चूंकि पैंडॉक लेटेक्स का उपयोग करता है, आप इसके लिए लेटेक्स टेम्पलेट निर्दिष्ट कर सकते हैं। यह केवल --template विकल्प के साथ किया जाता है

 pandoc --template=embox_pandoc.latex ... 

आपके द्वारा एक टेम्पलेट संकलित करने और उसे निर्दिष्ट करने के बाद, सभी दस्तावेज़ों को बनाते समय, आपको अधिक या कम समान शैली में दस्तावेज़ मिलते हैं। "कम या ज्यादा" - क्योंकि कई समस्याएं हैं जिन्हें हम हल नहीं कर पाए हैं। उदाहरण के लिए, कोड के एकल ब्लॉक का गठन। मार्कडाउन में, कोड के एक ब्लॉक को निर्दिष्ट करना संभव है, ताकि यह प्रारूपित न हो और सिंटैक्स हाइलाइटिंग संभवतः चालू हो। लेकिन हम केवल एक-लाइन ब्लॉक बनाने में कामयाब रहे। उत्पन्न लेटेक्स कोड को देखने के बाद यह निकला।

यही है, ऐसे मामले थे जब एक ही ब्लॉक को अलग-अलग दस्तावेजों पर थोड़ा अलग तरीके से रखा गया था।

सिरिलिक वर्णमाला से संबंधित एक और बिंदु, अर्थात्, रूसी भाषा का उपयोग। जैसा कि ऊपर उल्लेख किया गया है, रूसी भाषा का उपयोग करने के लिए, हेडर में रूसी बेबल को निर्दिष्ट करने के लिए पर्याप्त निकला। लेकिन हमने कुछ विषमताओं का सामना किया, उदाहरण के लिए, कोई बोल्ड हाइलाइटिंग और अन्य स्वरूपण विषमताएं नहीं थीं। प्रारंभ में, हमने इस तथ्य पर पाप किया कि रूसी कैप में निर्दिष्ट है, न कि किसी टेम्पलेट में। वे समस्या का अध्ययन करने लगे। यह पता चला कि एक अच्छे तरीके से आपको न केवल उपयोग करने की आवश्यकता है

 \usepackage[russian, english]{babel} 

लेकिन फोंट भी सेट करें

 \usepackage[T1,T2A]{fontenc} \usepackage[utf8]{inputenc} 

लेकिन ऐसा करने के बावजूद, स्थिति को सुधारना संभव नहीं था। यह पता चला कि सभी फ़ॉन्ट सेट में सभी रेंडरिंग विकल्प नहीं होते हैं, विशेष रूप से हमारे में अन्य स्वरूपों पर बोल्ड, इटैलिक और इतने ही नहीं होते हैं। चूंकि समस्या का कोई सरल समाधान नहीं था, इसलिए हमने बेहतर समय तक समस्या पर विचार किया और स्थगित कर दिया। खैर, चूंकि हम एक साफ मार्कडाउन (जो कि लेटेक्स कमांड्स को निर्दिष्ट किए बिना) का उपयोग करना चाहते थे, हमने दोनों भाषाओं के लिए एक सामान्य टेम्पलेट बनाया और हेडर में रूसी भाषा के बारे में संकेत दिया गया।

बस कुछ शब्द मैं आवेदन के इंटरफ़ेस के बारे में कहूंगा। चूंकि, जैसा कि मैंने कहा, कंसोल एप्लिकेशन व्यक्तिगत रूप से हमारे लिए बहुत परिचित हैं और आसानी से स्क्रिप्ट में पैक किए जाते हैं। दरअसल, इंटरफ़ेस सरल है, बेशक आप कई विकल्प निर्धारित कर सकते हैं, लेकिन हमारे उद्देश्यों के लिए यह एक टेम्पलेट, इनपुट फ़ाइलों की सूची और आउटपुट फ़ाइल निर्दिष्ट करने के लिए पर्याप्त है।

 pandoc --template=embox_pandoc.latex <title file> <list of input markdown files> -o <output file> 

इंटरनेट पर आप पा सकते हैं कि पीडीएफ (या अन्य आउटपुट प्रारूप) उत्पन्न करने के लिए आपको --pdf-engine = xelatex विकल्प का उपयोग करके एक प्रोसेसर प्रकार की आवश्यकता होती है, लेकिन डिफ़ॉल्ट रूप से इसका उपयोग किया जाता है यदि आउटपुट फ़ाइल में पीडीएफ एक्सटेंशन होता है। इसलिए, हमें इसकी जरूरत नहीं थी।

हमने एक मेकफाइल में दस्तावेज़ीकरण को इकट्ठा करने के लिए स्क्रिप्ट को पैक किया, ताकि यह काफी परिचित हो जाए। और अब, प्रलेखन प्राप्त करने के लिए आप आवश्यक वातावरण सेट कर सकते हैं, बस कॉल करें

 make [en][ru] 

निष्कर्ष में, संस्करण नियंत्रण प्रणाली के बारे में कुछ शब्द। सिद्धांत जटिल नहीं है (सरल रखें) हमने हर चीज का पालन करने की कोशिश की। और जब से सबसे सरल समाधान जीथब पर एक अलग भंडार का उपयोग करना था, तब हमने किया था । हमें उम्मीद है कि github का उपयोग करने से उपयोगकर्ता प्रतिक्रिया में सुधार होगा। आखिरकार, जैसा कि आप गितुब पर जानते हैं कि ऐसे मुद्दे हैं जिनमें आप कमियों पर चर्चा कर सकते हैं और अपने विचारों और दिशाओं की पेशकश कर सकते हैं।

यह प्रक्रिया हाल ही में कई श्रमिकों के अनुरोध पर शुरू की गई थी! हम "त्वरित शुरुआत" के अंग्रेजी और रूसी संस्करणों को बनाने में कामयाब रहे, साथ ही रूसी उपयोगकर्ता मैनुअल का पहला संस्करण भी । यह प्रक्रिया हमें स्वयं अधिक सुविधाजनक लगी, यही कारण है कि हम इसे जनता के साथ साझा करते हैं।