किसी परियोजना के दस्तावेज़ के लिए asciidoc का उपयोग करना

जब हमारे फ्रीलांस समूह को परियोजना के दस्तावेजीकरण के कार्य का सामना करना पड़ा, तो निम्नलिखित आवश्यकताएं तैयार की गईं:

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

नतीजतन, मौजूदा समाधानों का अध्ययन करने के बाद, मैं AsciiDoc प्रणाली पर रहा। यह एक उपयोगिता है जो नियमित पाठ फ़ाइलों (बहुत सरल और सहज मार्कअप का उपयोग करके) को लगभग किसी भी चीज़ (HTML, docbook, man, आदि) में परिवर्तित करती है। AsciiDoc को चुनने के कारण इस प्रकार हैं:

1. बहुत ही सरल और सहज मार्कअप लैंग्वेज। वास्तव में, AsciiDoc मार्कअप के साथ एक टेक्स्ट फ़ाइल को देखते हुए, आपने तुरंत यह भी अनुमान नहीं लगाया कि यह केवल एक नियमित पाठ फ़ाइल नहीं है, बल्कि एक "मार्कअप फ़ाइल" है - यह एक नियमित, बड़े करीने से संरचित टेक्स्ट फ़ाइल की तरह लगती है। वास्तव में, AsciiDoc की खोज करने से पहले, मैंने कई वर्षों तक सादे पाठ फ़ाइलों को एक ही शैली में लिखा, बिना किसी विचार के बाद में उन्हें अन्य प्रारूपों में परिवर्तित कर दिया! स्पष्ट "मार्कअप" की कमी से पाठ को नियमित पाठ संपादक में पढ़ना और संपादित करना बहुत आसान हो जाता है ।
2. वास्तव में, तकनीकी दस्तावेज के लिए "सही" प्रारूप DocBook है । लेकिन इस प्रारूप में प्रलेखन लिखने के लिए, पेन के साथ, कि विशेष उपयोगिताओं की मदद से ... brrr! और AsciiDoc भी DocBook प्रारूप में परिवर्तित कर सकता है। इस प्रकार, प्रलेखन के थोक को एक सरल और सुविधाजनक AsciiDoc पाठ प्रारूप में लिखना संभव है, और उसके बाद ही इसे DocBook और "कंघी" में परिवर्तित करें यह विशिष्ट DocBook सुविधाओं का उपयोग करके जो AsciiDoc में नहीं हैं - यह समय पर लेखन प्रलेखन को गति और सरल कर सकता है, भले ही। इसे DocBook प्रारूप में सौंप दिया जाना चाहिए।
3. AsciiDoc खुद docbook के अलावा आदमी और html फॉर्मेट में बदल सकता है, और अगर आपको कुछ और चाहिए, तो आप इसे docbook से किसी अन्य फॉर्मेट में बदल सकते हैं।
4. उत्पन्न html की उपस्थिति सीएसएस के माध्यम से कॉन्फ़िगर की गई है (हालांकि, समय के लिए, डिफ़ॉल्ट सेटिंग्स मेरे साथ काफी ठीक हैं)।
5. AsciiDoc काफी छोटा है, फुर्तीला है, और एक ही समय में अविश्वसनीय रूप से एक्स्टेंसिबल उपयोगिता है (हालांकि, मुझे अभी तक इसका विस्तार करने की आवश्यकता नहीं है)।

इसके बाद, मैंने जल्दी से CGIshka पर नेविगेट किया, जिसे जब बुलाया गया, तो परियोजना के अंदर अनुरोधित यूआरएल के अनुरूप प्रलेखन के साथ एक .txt फ़ाइल मिली, इसे asciidoc को html (कैशिंग HTML पृष्ठों के साथ मूल .txt फ़ाइल परिवर्तित होने तक) का उपयोग करके परिवर्तित किया और परिणामी लौटाया। एचटीएमएल।



परिणामस्वरूप, सिस्टम अब निम्नानुसार काम करता है:

1. साधारण .txt फाइलें निर्देशिका में स्थानीय रूप से आपके पसंदीदा पाठ संपादक में प्रलेखन के साथ लिखी जाती हैं
2. डेवलपर्स के बीच इन फ़ाइलों को प्रोजेक्ट सोर्स कोड (पैच या svn) के समान साझा किया जाता है
3. टेक्स्ट फ़ाइल को संपादित करने के ठीक बाद, आप संबंधित url पर जा सकते हैं और इसे html-format में देख सकते हैं (html को अगले परिवर्तन पर पुनर्जीवित किया जाएगा और अगले परिवर्तन तक कैश किया जाएगा)
4. हमने अभी तक ऐसा नहीं किया है, लेकिन वास्तव में एसाइसीडॉक प्रारूप, विकी पर इस्तेमाल किए गए मार्कअप से मौलिक रूप से भिन्न नहीं है, इसलिए वेब के माध्यम से संपादन दस्तावेज की संभावना प्रदान करने में कोई समस्या नहीं होनी चाहिए।

संदर्भ:

• AsciiDoc वेबसाइट पर आप इसकी क्षमताओं का पूरा विवरण पा सकते हैं, साथ ही साइट के स्रोत पृष्ठों को .txt प्रारूप में देखें (हाँ, AsciiDoc वेबसाइट asciidoc :) में लिखी गई है।
• मैंने एक चीट शीट बनाई। प्लेट बहुत प्रासंगिक है, क्योंकि AsciiDoc में संभावनाओं की एक जंगली संख्या है, लेकिन एक बहुत छोटी संख्या वास्तव में पर्याप्त है, और मैं इस छोटी सूची को हाथ में लेना चाहता हूं।
• वर्णन करता है कि कैसे asciidoc को स्थापित और कॉन्फ़िगर करना है, विम के लिए हाइलाइटिंग और मेरे CGI को मक्खी पर html बनाने के लिए।