كيفية إنشاء صفحة رجل على نظام Linux

هل تريد أن يبدو برنامج Linux الجديد الخاص بك احترافيًا؟ اعطها صفحة man . سنوضح لك الطريقة الأسهل والأسرع للقيام بذلك.

صفحات الرجل

هناك جزء من الحقيقة في نكتة يونكس القديمة ، "الأمر الوحيد الذي تحتاج إلى معرفته هو man ." تحتوي صفحات man على ثروة من المعرفة ، ويجب أن تكون أول مكان تلجأ إليه عندما تريد التعرف على أمر ما.

يؤدي توفير صفحة man لأداة مساعدة أو أمر كتبته إلى رفعها من جزء مفيد من التعليمات البرمجية إلى حزمة Linux كاملة التكوين. يتوقع الناس توفير صفحة man لبرنامج تمت كتابته لنظام Linux. إذا كنت تدعم Linux في الأصل ، فستكون صفحة man إلزامية إذا كنت تريد أن يؤخذ برنامجك على محمل الجد.

تاريخياً man تمت كتابة صفحات الدليل باستخدام مجموعة من وحدات الماكرو للتنسيق. عندما تطلب من man فتح صفحة ، فإنه يستدعي groff لقراءة الملف وإنشاء إخراج منسق ، وفقًا لوحدات الماكرو في الملف. يتم توجيه الإخراج إلى less ، ثم يتم عرضه لك.

ما لم تقم بإنشاء صفحات man بشكل متكرر ، فإن كتابة واحدة وإدراج وحدات الماكرو يدويًا يعد عملاً شاقًا. يمكن أن يؤدي إنشاء صفحة man يتم تحليلها بشكل صحيح وتبدو بشكل صحيح إلى تجاوز هدفك في تقديم وصف موجز وشامل لأمرك.

يجب أن تركز على المحتوى الخاص بك ، وليس محاربة مجموعة غامضة من وحدات الماكرو.

ذات صلة: كيفية استخدام أمر رجل Linux: الأسرار والأساسيات المخفية

باندوك للانقاذ

يقرأ برنامج pandoc ملفات markdown وينشئ ملفات جديدة بحوالي 40 لغة ترميز مختلفة وتنسيقات مستندات ، بما في ذلك man صفحة الدليل. إنه يحول تمامًا عملية كتابة صفحة man بحيث لا تضطر إلى المصارعة مع الكتابة الهيروغليفية.

للبدء ، يمكنك تثبيت pandoc على Ubuntu باستخدام هذا الأمر:

 sudo apt-get install pandoc 

في Fedora ، الأمر الذي تحتاجه هو ما يلي:

 sudo dnf تثبيت pandoc 

في Manjaro ، اكتب:

 sudo pacman -Syu pandoc 

ذات صلة: كيفية استخدام pandoc لتحويل الملفات على سطر أوامر Linux

أقسام صفحة رجل

تحتوي صفحات man على أقسام تتبع اصطلاح تسمية قياسيًا. يتم تحديد الأقسام التي تحتاجها صفحة man الخاصة بك من خلال تعقيد الأمر الذي تصفه.

كحد أدنى ، تحتوي معظم صفحات الدليل على الأقسام التالية:

• الاسم : اسم الأمر وسطر واحد بليغ يصف وظيفته.
• الملخص : وصف مقتضب للدعوات التي يمكن لأي شخص استخدامها لبدء تشغيل البرنامج. تُظهر هذه أنواع معلمات سطر الأوامر المقبولة.
• الوصف : وصف للأمر أو الوظيفة.
• الخيارات : قائمة بخيارات سطر الأوامر وما يفعلونه.
• أمثلة : بعض الأمثلة على الاستخدام الشائع.
• قيم الخروج : رموز الإرجاع المحتملة ومعانيها.
• البق : قائمة بالأخطاء والمراوغات المعروفة. في بعض الأحيان ، يتم استكمال ذلك (أو استبداله) برابط لتعقب المشكلات الخاص بالمشروع.
• المؤلف : الشخص أو الأشخاص الذين كتبوا الأمر.
• حقوق النشر : رسالة حقوق النشر الخاصة بك. تتضمن هذه أيضًا عادةً نوع الترخيص الذي تم إصدار البرنامج بموجبه.

إذا نظرت إلى بعض صفحات man الأكثر تعقيدًا ، فسترى أن هناك العديد من الأقسام الأخرى أيضًا. على سبيل المثال ، جرب man man . ومع ذلك ، لا يتعين عليك تضمينهم جميعًا - فقط أولئك الذين تحتاجهم حقًا. صفحات man ليست مكانًا للكلمة.

بعض الأقسام الأخرى التي ستراها بشكل متكرر بشكل معقول هي:

• راجع أيضًا : أوامر أخرى متعلقة بالموضوع قد يجدها البعض مفيدة أو ذات صلة.
• الملفات : قائمة الملفات المضمنة في الحزمة.
• المحاذير : نقاط أخرى يجب أن تعرفها أو احترس منها.
• التاريخ : تاريخ التغيير للأمر.

أقسام الدليل

يتكون دليل Linux man جميع صفحات الدليل ، والتي يتم تقسيمها بعد ذلك إلى هذه الأقسام المرقمة:

1. البرامج القابلة للتنفيذ: أو أوامر shell.
2. استدعاءات النظام: الوظائف التي توفرها النواة.
3. مكالمات المكتبة: وظائف داخل مكتبات البرنامج.
4. ملفات خاصة.
5. صيغ الملفات واصطلاحاتها: على سبيل المثال ، “/ etc / passwd”.
6. ألعاب.
7. متفرقات: حزم واتفاقيات ماكرو ، مثل groff .
8. أوامر إدارة النظام: محجوزة عادة للجذر.
9. إجراءات Kernel: لا يتم تثبيتها عادةً افتراضيًا.

يجب أن تشير كل صفحة man إلى القسم الذي تنتمي إليه ، ويجب أيضًا تخزينها في المكان المناسب لذلك القسم ، كما سنرى لاحقًا. تنتمي صفحات man الخاصة بالأوامر والأدوات المساعدة إلى القسم الأول.

شكل صفحة الرجل

ليس من السهل تحليل تنسيق الماكرو groff بصريًا. في المقابل ، فإن تخفيض السعر سهل للغاية.

يوجد أدناه صفحة رجل في groff .

نفس الصفحة معروضة أدناه في التخفيضات.

المسألة الأمامية

تشكل الأسطر الثلاثة الأولى شيئًا يسمى المادة الأمامية . يجب أن تبدأ جميعها بعلامة النسبة المئوية ( % ) ، بدون مسافات بادئة ولكن واحدة بعد ذلك ، متبوعة بـ:

• السطر الأول: يحتوي على اسم الأمر ، متبوعًا بقسم الدليل بين قوسين ، بدون مسافات. يصبح الاسم القسمين الأيمن والأيسر man رأس صفحة الدليل. حسب الاصطلاح ، يكون اسم الأمر بأحرف كبيرة ، على الرغم من أنك ستجد الكثير بخلاف ذلك. يصبح أي شيء يتبع اسم الأمر ورقم القسم اليدوي هو القسم الأيسر من التذييل. من الملائم استخدام هذا لرقم إصدار البرنامج.
• السطر الثاني: اسم (أسماء) المؤلف (المؤلفين). يتم عرضها في قسم المؤلفين man تم إنشاؤه تلقائيًا في صفحة الدليل. ليس عليك إضافة قسم "المؤلفون" - فقط قم بتضمين اسم واحد على الأقل هنا.
• السطر الثالث: التاريخ ، والذي يصبح أيضًا الجزء الأوسط من التذييل.

اسم

تتم الإشارة إلى الأقسام بخطوط تبدأ بعلامة الرقم ( # ) ، وهي العلامة التي تشير إلى رأس في تخفيض السعر. يجب أن تكون علامة الرقم ( #) هي الحرف الأول على السطر ، متبوعة بمسافة.

يحتوي قسم الاسم على سطر واحد سريع يتضمن اسم الأمر ، ومسافة ، وواصلة ( - ) ، ومسافة ، ثم وصفًا قصيرًا جدًا لما يفعله الأمر.

ملخص

يحتوي الملخص على التنسيقات المختلفة التي يمكن أن يتخذها سطر الأوامر. يمكن أن يقبل هذا الأمر نمط بحث أو خيار سطر أوامر. تعني man النجميتان ( ** ) الموجودتان على جانبي اسم الأمر أنه سيتم عرض الاسم بخط عريض على صفحة الدليل. تؤدي علامة النجمة man ( * ) على جانبي نص ما إلى عرض صفحة الدليل تحتها خط.

بشكل افتراضي ، يتبع فاصل الأسطر سطر فارغ. لفرض فاصل ثابت بدون سطر فارغ ، يمكنك استخدام شرطة مائلة للخلف ( \ ).

وصف

يشرح الوصف ما يفعله الأمر أو البرنامج. يجب أن تغطي التفاصيل المهمة بإيجاز. تذكر أنك لا تكتب دليل المستخدم.

يؤدي استخدام علامتي رقم ( ## ) في بداية السطر إلى إنشاء عنوان من المستوى الثاني. يمكنك استخدام هذه لتقسيم الوصف الخاص بك إلى أجزاء أصغر.

خيارات

يحتوي قسم الخيارات على وصف لأي خيارات سطر أوامر يمكن استخدامها مع الأمر. حسب الاصطلاح ، يتم عرض هذه العلامات بالخط العريض ، لذلك قم بتضمين علامتين نجميتين ( ** ) قبلها وبعدها. قم بتضمين الوصف النصي للخيارات في السطر التالي وابدأ بعلامة النقطتين ( : ، متبوعة بمسافة.

إذا كان الوصف قصيرًا بدرجة كافية ، man على نفس سطر خيار سطر الأوامر. إذا كانت طويلة جدًا ، فسيتم عرضها كفقرة ذات مسافة بادئة تبدأ في السطر الموجود أسفل خيار سطر الأوامر.

أمثلة

يحتوي قسم الأمثلة على مجموعة من تنسيقات سطر الأوامر المختلفة. لاحظ أننا نبدأ سطور الوصف بنقطتين ( : ، تمامًا كما فعلنا في قسم الخيارات.

قيم الخروج

يسرد هذا القسم قيم الإرجاع التي يرسلها الأمر الخاص بك مرة أخرى إلى عملية الاستدعاء. قد يكون هذا هو shell إذا قمت باستدعائه من سطر الأوامر ، أو برنامج نصي إذا قمت بتشغيله من برنامج نصي shell. نبدأ سطور الوصف بنقطتين ( : في هذا القسم أيضًا.

البق

يسرد قسم الأخطاء الأخطاء المعروفة ، أو مشاكل التعثر ، أو المراوغات التي يحتاج الناس إلى معرفتها. بالنسبة للمشاريع مفتوحة المصدر ، من الشائع تضمين رابط هنا لتعقب مشكلات المشروع للتحقق من حالة أي أخطاء أو الإبلاغ عن أخطاء جديدة.

حقوق النشر

يحتوي قسم حقوق النشر على بيان حقوق النشر الخاص بك ، وعادةً ، وصف لنوع الترخيص الذي تم إصدار البرنامج بموجبه.

سير عمل فعال

يمكنك تحرير صفحة man الخاصة بك في المحرر المفضل لديك. سيكون معظم تمييز دعم بناء الجملة على دراية بالعلامة التجارية ولون النص لإبراز العناوين ، بالإضافة إلى الخط الغامق والتسطير. هذا رائع بقدر ما يذهب ، لكنك لا تنظر إلى صفحة man المقدمة ، وهذا هو الدليل الحقيقي في الحلوى.

افتح نافذة طرفية في الدليل الذي يحتوي على ملف markdown الخاص بك. مع فتحه في المحرر الخاص بك ، احفظ الملف بشكل دوري على محرك الأقراص الثابتة. في كل مرة تقوم فيها بذلك ، يمكنك تنفيذ الأمر التالي في النافذة الطرفية:

 pandoc ms.1.md -s -t man | / usr / bin / man -l - 

بمجرد استخدام هذا الأمر ، يمكنك الضغط على السهم لأعلى لتكراره ، ثم الضغط على Enter.

يستدعي هذا الأمر أيضًا pandoc في ملف markdown (يُسمى هنا “ms.1.md”):

• يُنشئ الخيار -s (مستقل) صفحة دليل كاملة man أعلى إلى أسفل ، بدلاً من مجرد بعض النصوص بتنسيق man .
• يقوم الخيار -t (نوع الإخراج) مع عامل التشغيل "man" بإخبار pandoc بإنشاء مخرجاته بتنسيق man . لم نطلب من pandoc إرسال مخرجاته إلى ملف ، لذلك سيتم إرساله إلى stdout .

نحن أيضًا نقوم بتوصيل هذا الإخراج إلى man باستخدام الخيار -l (ملف محلي). يخبر man بعدم البحث في قاعدة بيانات man بحثًا عن صفحة man . بدلاً من ذلك ، يجب أن يفتح الملف المحدد. إذا كان اسم الملف - ، man مدخلاته من stdin .

ما يتلخص في هذا هو أنه يمكنك الحفظ من المحرر الخاص بك والضغط على Q لإغلاق man إذا كان يعمل في نافذة المحطة. بعد ذلك ، يمكنك الضغط على السهم لأعلى ، متبوعًا بـ Enter لرؤية نسخة معروضة من صفحة man الخاصة بك ، داخل man مباشرة.

ذات صلة: ما هي stdin و stdout و stderr على Linux؟

إنشاء صفحة رجلك

بعد الانتهاء من صفحة man الخاصة بك ، تحتاج إلى إنشاء نسخة نهائية منها ، ثم تثبيتها على نظامك. يخبر الأمر التالي pandoc بإنشاء صفحة دليل تسمى man ms.1":

 pandoc ms.1.md -s -t man -o ms.1 

يتبع هذا اصطلاح تسمية صفحة الدليل بعد الأمر man يصفه وإلحاق رقم القسم اليدوي كما لو كان امتدادًا للملف.

يؤدي هذا إلى إنشاء ملف "ms.1" ، man صفحتنا الرئيسية الجديدة. أين نضعها؟ سيخبرنا هذا الأمر بالمكان الذي يبحث فيه man عن صفحات man :

 مانباث 

النتائج تعطينا المعلومات التالية:

• / usr / share / man: man المكتبة القياسية لصفحات الدليل. نحن لا نضيف صفحات إلى هذه المكتبة.
• / usr / local / share / man: يشير هذا الرابط الرمزي إلى "/ usr / local / man."
• / usr / local / man: هذا هو المكان الذي نحتاج فيه إلى وضع صفحة man الجديدة.

لاحظ أن الأقسام اليدوية المختلفة موجودة في الدلائل الخاصة بها: man1 و man2 و man3 وما إلى ذلك. إذا لم يكن دليل القسم موجودًا ، فنحن بحاجة إلى إنشائه.

للقيام بذلك ، نكتب ما يلي:

 sudo mkdir / usr / local / man / man1

نقوم بعد ذلك بنسخ ملف "ms.1" إلى الدليل الصحيح:

 sudo cp ms.1 / usr / local / man / man1

يتوقع man ضغط صفحات man ، لذلك سنستخدم gzip :

 sudo gzip /usr/local/man/man1/ms.1

لجعل man يضيف الملف الجديد إلى قاعدة البيانات الخاصة به ، اكتب ما يلي:

 سودو ماندب 

هذا هو! يمكننا الآن استدعاء صفحة man الجديدة لدينا مثل أي صفحة أخرى عن طريق كتابة:

 رجل مللي 

تم العثور على صفحة man الجديدة وعرضها.

تبدو تمامًا مثل أي صفحة man أخرى ، بنص غامق ومسطر ومزود بمسافة بادئة في الأماكن المناسبة.

تظهر سطور الوصف التي تلائم الخيار الذي يصفونه في نفس السطر. تظهر الخطوط الطويلة جدًا بحيث لا يمكن ملاءمتها أسفل الخيار الذي يصفونه.

لقد قمنا أيضًا بإنشاء قسم "المؤلفون" تلقائيًا. يتضمن التذييل أيضًا رقم إصدار البرنامج والتاريخ واسم الأمر ، كما هو محدد في المادة الأمامية.

أذا أردت . . .

بمجرد أن pandoc صفحة man الخاصة بك ، يمكنك أيضًا تحرير الملف بتنسيق groff الماكرو مباشرةً قبل نقله إلى دليل صفحة الدليل man و gzip .