DocBook के साथ प्रलेखन विकसित करना

ऐसा हुआ कि हमारी परियोजनाओं में तकनीकी दस्तावेज का रखरखाव पूरी तरह से डेवलपर्स के कंधों पर टिकी हुई है, सिद्धांत के अनुसार: परियोजना कोड में बदलाव किए गए - प्रलेखन को अद्यतन किया। दस्तावेज़ स्वयं Word दस्तावेज़ों का एक संग्रह था जो VCS के तहत स्रोत कोड के साथ संग्रहीत थे। विकास संगठन के लिए यह दृष्टिकोण लंबे समय से मौजूद है, लेकिन कुछ साल पहले हमने एमएस ऑफिस के अलावा अन्य उपकरणों का उपयोग करके परियोजना के प्रलेखन को बनाए रखने की संभावना का ध्यान रखने का फैसला किया था।


इसके कई कारण थे:

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

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

इस प्रकार, एमएस वर्ड का हमारा विकल्प निम्नलिखित मानदंडों को पूरा करना था:

1. दस्तावेज़ भंडारण के लिए पाठ प्रारूप - वीसीएस में इसके साथ सुविधाजनक काम के लिए।
2. दस्तावेज़ की डिजाइन और स्टाइल की व्यापक संभावनाओं के लिए समर्थन।
3. अंतिम दस्तावेज़ को टुकड़ों में विघटित करने की क्षमता - पुन: उपयोग के लिए।
4. विभिन्न स्वरूपों में अंतिम दस्तावेज प्रकाशित करने की क्षमता।

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

डॉकबुक क्या है?

अचानक, अगर किसी को पता नहीं है, दस्तावेज़ का वर्णन करने के लिए DocBook एक मानक है और सामग्री को मानकीकृत करने के अलावा कुछ भी उपयोगी नहीं है। इसके अलावा, मानक काफी पुराना है, और कई, किसी कारण से, पहले से ही अप्रचलित माना जाता है।

डॉकबुक प्रारूप में एक दस्तावेज़ लिखना HTML के साथ काम करने के लिए बहुत समान है, केवल इसके उपयोग के लिए टैग और नियमों के अपने स्वयं के सेट का उपयोग किया जाता है।

<book> <chapter> <title>First Chapter</title> <para>Hello world!</para> </chapter> </book> 

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

DocBook दस्तावेज़ परिवर्तित करें

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



DocBook -xsl आमतौर पर परिवर्तन के लिए उपयोग किया जाता है (हालांकि अधिक विदेशी तरीके हैं)। बॉक्स से बाहर, यह पहले से ही कई दस्तावेज़ स्वरूपों का समर्थन करता है - html, xsl-fo, manpages, आदि। यदि आपको एक अलग प्रस्तुति प्रारूप की आवश्यकता है, तो आप रूपांतरणों की श्रृंखला जारी रख सकते हैं। तो पीडीएफ में एक दस्तावेज प्राप्त करने के लिए आमतौर पर निम्नलिखित योजना का उपयोग करें:



और यहीं से मस्ती शुरू होती है। DocBook-xsl में डिफ़ॉल्ट रूप से लागू की गई शैलियाँ आपको एक ऐसा दस्तावेज़ प्राप्त करने की अनुमति देती हैं जो दिखने में सामान्य लगता है, लेकिन आमतौर पर, अनुकूलन अभी भी आवश्यक है।

डॉकबुक-एक्सएसएल स्टाइल डेवलपर्स ने इस अवसर का ध्यान रखा और इसके लिए विशेष तंत्र लागू किए:

• प्रत्येक समर्थित स्वरूपों के लिए एक दस्तावेज़ बनाने के लिए सबसे आम पैरामीटर एक अलग param.xsl फ़ाइल में निकाले गए हैं और उनमें से प्रत्येक के लिए अधिक या कम विस्तृत विवरण है।
• कस्टम पैटर्न बनाने के लिए विशेष पैटर्न हैं।
• उनके बाद के पुनर्परिभाषित के लिए डिफ़ॉल्ट रूप से विशेष, खाली टेम्पलेट्स का अस्तित्व।

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

Xslt और fo प्रोसेसर को चुनना

DocBook-xsl के साथ काम करने के लिए, आपको xslt संस्करण 1.0 का समर्थन करने वाला xslt प्रोसेसर चाहिए। (संस्करण 2.0 के लिए docbook-xsl का कार्यान्वयन है, लेकिन मुझे नहीं पता कि यह कितना स्थिर है)। वर्तमान में, कई प्रकार के प्लेटफार्मों के लिए कई कार्यशील समाधान हैं - इसलिए इसके साथ कोई समस्या नहीं होनी चाहिए। हमारी परियोजनाओं में, हम सैक्सन का उपयोग करते हैं, हालांकि पुराना संस्करण सैक्सन 9.1.0.8J है, क्योंकि EXSLT एक्सटेंशन के लिए अंतिम फ्रीवेयर समर्थन पूरी तरह से हटा दिया गया है (दस्तावेज़ रूपरेखा के लिए आवश्यक है) और कोई निश्चितता नहीं थी कि शैलियों के साथ आने वाले सिंटैक्स हाइलाइटिंग का समर्थन करने वाला सैक्सॉन एक्सटेंशन एक नए में काम करेंगे।

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

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

अनुकूलन शैली

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

एकमात्र बिंदु जिसे मैं रोकना चाहता हूं और जो, सबसे पहले, भ्रमित हो सकता है कि दस्तावेज़ के फ़ॉन्ट और भाषा को कॉन्फ़िगर करना है। डिफ़ॉल्ट रूप से, सिरिलिक वर्णमाला का समर्थन नहीं करने वाले फोंट xsl-fo में शामिल हैं, और यदि आप इन मापदंडों को ओवरराइड नहीं करते हैं या उनमें कोई गलती करते हैं (आपको यह सुनिश्चित करने की आवश्यकता है कि निर्दिष्ट प्रोसेसर के साथ काम करने के लिए फ़ॉइस प्रोसेसर को कॉन्फ़िगर किया गया है, तो हम सबसे अधिक संभावना प्रोसेसर से एक अपठनीय आउटपुट प्राप्त करेंगे। दस्तावेज़। दस्तावेज़ की भाषा पुस्तक (अध्याय, पुस्तक, आदि) के तत्वों के नाम के लिए ऑटोटेक्स्ट के निर्माण को प्रभावित करती है। सिद्धांत रूप में, केवल इन मापदंडों को सेट करने से आप पहले ही "सही" दस्तावेज़ प्राप्त कर सकते हैं। इसके अलावा, सबसे अधिक संभावना है कि दस्तावेज़ के कवर पृष्ठ की उपस्थिति को बदलने की इच्छा होगी। यह विशेष रूप से docbook-xsl में तैयार किए गए टेम्पलेट का उपयोग करके किया जा सकता है। ऐसा करने के लिए, आपको "ड्राइवर" से कनेक्ट करने के लिए अनुकूलित डिज़ाइन शैली प्राप्त करने के लिए फ़ाइल के अपने संस्करण "/fo/titlepage.templates.xml" को परिभाषित करना होगा और xslt प्रोसेसर और टेम्पलेट "/fo/titlepage.templates.xsl" का उपयोग करना होगा। कुछ मामलों में, अंतर्निहित कॉन्फ़िगरेशन तंत्र पर्याप्त नहीं हैं, और फिर आपको ड्राइवर में मूल डॉकबुक-एक्सएसएल शैलियों को स्पष्ट रूप से फिर से परिभाषित करना होगा।

निष्कर्ष

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

हमारी टीम को DocBook में तकनीकी दस्तावेज बनाए रखने के लिए स्विच किए हुए एक वर्ष से अधिक समय बीत चुका है, और हम अब किसी अन्य विकल्प की कल्पना नहीं करते हैं। वह सब जो हम DocBook पर स्विच करके हासिल करना चाहते थे - हमने हासिल किया:

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

स्वाभाविक रूप से, पेशेवरों के अलावा, नुकसान भी हैं:

• इस समय कंपनी की अन्य डिवीजनों के साथ बातचीत में सबसे अधिक समस्या है। स्पष्ट कारणों के लिए, केवल हमारी टीम ने DocBook पर स्विच किया, बाकी सभी लोग MS Word का उपयोग करते हैं, और जब हमें डेटा का आदान-प्रदान करने की आवश्यकता होती है, तो हमें इसे मैन्युअल रूप से करना होगा। सौभाग्य से, यह बहुत दुर्लभ है, और आमतौर पर पाठ के पैराग्राफ के एक जोड़े तक सीमित है।
• दस्तावेज़ स्वरूपण के लिए कुछ गैर-मानक डॉकबुक दृष्टिकोणों को लागू करने की जटिलता, विशेष रूप से, परिदृश्य अभिविन्यास में अक्सर कई पृष्ठों का विस्तार करने की आवश्यकता होती है, लेकिन अभी भी यह नहीं सीखा है कि यह कैसे करना है (हमारी शर्म की बात है) और हमें इस पल को किसी भी तरह से अलग करना होगा। लेकिन मुझे 100% यकीन है कि यह किया जा सकता है, और इसलिए इस समस्या की अनसुलझे प्रकृति को कम तत्काल आवश्यकता द्वारा समझाया जा सकता है। उदाहरण के लिए, जब हमें किसी दस्तावेज़ में सूत्र सम्मिलित करने की आवश्यकता होती है, तो यह MathML को पेंच करने के लिए दोपहर से भी कम समय लेता है।

और इस लेख का उद्देश्य उन पाठकों को व्यक्त करना है जो कार्यालय कार्यक्रमों में तकनीकी दस्तावेज विकसित कर रहे हैं कि अधिक उपयुक्त उपकरण हैं। जो लोग कुछ समय से DocBook या DITA की ओर देख रहे हैं, उनके लिए संक्रमण को बढ़ावा देना और संकेत देना सबसे मुश्किल हिस्सा है! यह सुनना भी बहुत दिलचस्प होगा कि अन्य टीमों द्वारा क्या दृष्टिकोण अपनाया गया और उनके कार्यान्वयन का अनुभव।

संदर्भ:

• http://docbook.sourceforge.net/
• DocBook XSL: पूरी गाइड
  
• http://www.docbook.ru/
  

एक उदाहरण:

• https://github.com/