मैंने लिनक्स और फ्रीबीएसडी के लिए एक छोटी सी लाइब्रेरी लिखी है, और मैं इसके लिए दस्तावेज लिखने जा रहा हूं। मैंने मैन पेज बनाने के बारे में और जानने की कोशिश की और पुस्तकालयों के लिए मैन पेज बनाने वाली सर्वोत्तम प्रथाओं के निर्देश या विवरण नहीं मिले। विशेष रूप से मुझे इस बात में दिलचस्पी है कि कार्यों के मैन पेजों को किस अनुभाग में रखा जाए? 3? शायद अच्छे उदाहरण या मैनुअल हैं? लाइब्रेरी से प्रत्येक फ़ंक्शन के लिए मैन पेज बनाएं एक बुरा विचार?
जवाबों:
लाइब्रेरी के लिए मैनुअल पेज सेक्शन 3 में जाएंगे।
मैनुअल पृष्ठों के अच्छे उदाहरणों के लिए, ध्यान रखें कि कुछ को विशिष्ट विवरणों के उपयोग से लिखा जाता है और / या विशिष्ट मैक्रो का उपयोग करते हैं जो वास्तव में पोर्टेबल नहीं हैं।
मानव-पृष्ठों की पोर्टेबिलिटी में हमेशा कुछ नुकसान होते हैं, क्योंकि कुछ सिस्टम विशेष सुविधाओं का उपयोग कर सकते हैं (या नहीं कर सकते हैं)। उदाहरण के लिए, दस्तावेज़ीकरण में dialog, मुझे उदाहरण प्रदर्शित करने के लिए विभिन्न प्रणालियों में मतभेदों को ध्यान में रखना (और काम करना पड़ता है) (जो उचित नहीं हैं)।
संबंधित अनुभागों को पढ़ने से शुरू करें man manजहां यह मानक मैक्रोज़ का उल्लेख करता है, और फ्रीबीएसडी और लिनक्स के लिए उन विवरणों की तुलना करता है ।
चाहे आप लाइब्रेरी के लिए एक मैनुअल पेज लिखना चाहें, या फ़ंक्शंस (या फ़ंक्शंस के समूह) के लिए अलग मैनुअल पेज इस बात पर निर्भर करते हैं कि फ़ंक्शंस का विवरण कितना जटिल होगा:
आगे की पढाई:
मैं रोन का उपयोग करता हूं । आप बस मार्कडाउन लिखते हैं, और यह इसे मैनपेज में बदल देगा। इसमें एक (कुछ हद तक कम सक्षम) जेएस क्लोन भी है जिसे चिह्नित-मैन कहा जाता है ।
मैं का उपयोग करके इसके साथ मेरी स्क्रिप्ट का दस्तावेजीकरण किया गया है END_MANसीमांकित heredocs और मेरे C / C ++ कोड एक ही का उपयोग करके END_MANभीतर छोड़कर सीमांकित heredocs /* */। या तो आसानी से sed के साथ निकाला जा सकता है और फिर एक मैनपेज में रेंडर किया जा सकता है। (Inotifywait के साथ थोड़ा UNIX सिग्नल हैकरी के साथ, आप अपने मैनपेज अनुभागों को लाइव देख और निकाल सकते हैं और सोर्स अपडेट के रूप में मैनपेज ब्राउज़र पुनः लोड कर सकते हैं।)
अनुभाग के लिए, तो 3 यह एक उपयोगकर्ता-स्तरीय सी लाइब्रेरी के लिए होगा। आप आदमी (1) में सेक्शन नंबर (अन्य बातों के अलावा) के बारे में पढ़ सकते हैं ।
आप कुछ पठनीय, अच्छी तरह से संरचित उदाहरण आदमी पृष्ठों को देखने चाहते हैं, मैं Plan9 पर एक नज़र था https://swtch.com/plan9port/unix/ पुस्तकालयों जहां की कैसे बहुत रचनाकारों देख सकते हैं cऔर UNIXऔर इसके प्रलेखन सिस्टम शायद इन चीजों के लिए काम करना चाहता है।
अन्य उत्तरों को पूरक करने के लिए, एक और मार्कडाउन भाषा जिसे मैन पेज लिखने में सरल बनाया जा सकता है, वह है ReStructuredText और rst2man कमांड जो कि अजगर-डॉकुटिल्स पैकेज का हिस्सा है ।
यह मार्कडाउन भाषा अपने प्रलेखन के लिए अजगर द्वारा अपनाई गई है , और अच्छे पुराने ट्रॉफ मैन मैक्रोज़ की तुलना में सीखना, लिखना और बनाए रखना बहुत आसान है, जो कि rst2man आपके लिए अपने reStructuredText से उत्पन्न करेगा।
आप HTML के रूप में संदर्भ प्रदान करने के लिए doxygen का उपयोग करके एपीआई का दस्तावेजीकरण कर सकते हैं , और ऑफ़लाइन पढ़ने के लिए मैन पेज और अन्य प्रारूप भी उत्पन्न कर सकते हैं।
Doxygen का लाभ यह है कि यह JavaDoc या PythonDoc जैसे "इनलाइन" प्रलेखन की तरह है, इंटरफ़ेस टिप्पणियों के रूप में दोहरीकरण (या वीवी।, डॉक्स पाठ के रूप में दोहरीकरण टिप्पणी); आप अपने स्रोत / हेडर फ़ाइलों में डॉक्स ग्रंथों को जोड़ते हैं, और इसे वहां से निकाला जाता है, जो आज तक आयोजित होने की संभावनाओं को बेहतर बनाता है।
manमानक पुस्तकालय और syscalls को छोड़कर कभी भी प्रोग्रामिंग के लिए उपयोग नहीं करता हूं।