صفحة الدليل

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

بشكل افتراضي، manيستخدم عادةً برنامج تنسيق مثل برنامج nroffمع حزمة ماكرو أو mandoc ، وأيضًا برنامج عرض صفحات طرفية مثل moreأو lessلعرض مخرجاته على شاشة المستخدم.

تُعرف صفحات الدليل (man pages) غالبًا بأنها شكلٌ إلكترونيٌّ من أشكال توثيق البرامج، ^{[ 1 ]} على الرغم من أن manالأمر لا يتطلب اتصالًا بالإنترنت، وذلك لأن صفحات الدليل متاحةٌ من خلال واجهة سطر الأوامر باستخدام manالأمر نفسه، أو من خلال واجهة مستخدم رسومية باستخدام عارض صفحات الدليل، بدلًا من أن تكون متاحةً فقط في شكلٍ مطبوع. غالبًا ما يُحدد متغير البيئة MANPATH قائمةً بمسارات الدليل للبحث عن صفحات التوثيق المختلفة. يعود تاريخ صفحات الدليل إلى زمنٍ كان فيه التوثيق المطبوع هو السائد.

في بعض البرامج، اعتبارًا من عام 1987، كانت الوثائق عبارة عن صفحات مطبوعة متاحة للمستخدمين في الموقع. ^{[ 2 ]} في بعض المواقع، كانت هذه الوثائق مُنظمة في مجلدات فولاذية، ومثبتة معًا في رف قراءة فولاذي متجانس، مثبت بمسامير على طاولة أو منضدة، مع تنظيم الصفحات لتسهيل تحديث المعلومات واستبدالها وإضافة الأخطاء والإضافات. وكانت الكتيبات الشائعة حول الحواسيب الصغيرة تُعلن عنها للبيع في مجلدات ذات أوراق منفصلة مع تحديثات منتظمة. ^{[ 3 ]}

في أول عامين من تاريخ يونكس ، لم تكن هناك وثائق رسمية. ^{[ 4 ]} نُشر دليل مبرمج يونكس لأول مرة في 3 نوفمبر 1971. كتب دينيس ريتشي وكين تومسون أولى صفحات الدليل الفعلية بناءً على إصرار مديرهما دوغ ماكلروي في عام 1971. إلى جانب صفحات الدليل، ضمّ دليل المبرمج أيضًا مجموعة من الأوراق القصيرة، بعضها دروس تعليمية (مثل الاستخدام العام ليونكس، ولغة البرمجة سي ، وأدوات مثل ياك )، والبعض الآخر أوصاف أكثر تفصيلًا لميزات نظام التشغيل. في البداية، كانت النسخة المطبوعة من الدليل تُحفظ في مجلد واحد، ولكن مع إصدار PWB/UNIX والطبعة السابعة من Research Unix ، قُسّم إلى مجلدين، وشكّلت صفحات الدليل المطبوعة المجلد الأول. ^{[ 5 ]}

قلدت الإصدارات اللاحقة من الوثائق إيجاز صفحات الدليل الأولى. أضاف ريتشي قسم "كيفية البدء" إلى مقدمة الطبعة الثالثة ، وقدمت لوريندا تشيري المرجع الجيبي "البطاقة الأرجوانية" للطبعتين السادسة والسابعة . ^{[ 4 ]} سُميت إصدارات البرنامج نسبةً إلى مراجعة الدليل؛ فعلى سبيل المثال، جاءت الطبعة السابعة من دليل مبرمج يونكس مع الطبعة السابعة أو الإصدار 7 من يونكس. ^{[ 6 ]}

في الطبعة الرابعة ، تم تنسيق صفحات الدليل باستخدام حزمة troff للتنسيق ^{[ 4 ]} ومجموعة -manوحدات الماكرو الخاصة بها (والتي نُقحت بالكامل بين الطبعتين السادسة والسابعة من الدليل ^{[ 5 ]} ، ولكنها لم تشهد تغييرات جذرية منذ ذلك الحين). في ذلك الوقت، اعتُبر توفر التوثيق الإلكتروني عبر نظام صفحات الدليل إنجازًا كبيرًا. وحتى يومنا هذا، يأتي كل تطبيق سطر أوامر تقريبًا في أنظمة يونكس مزودًا بصفحة دليل، ويرى العديد من مستخدمي يونكس أن افتقار برنامج ما لصفحات الدليل دليل على تدني جودته أو عدم اكتماله. بل إن بعض المشاريع، مثل دبيان ، تبذل جهدًا كبيرًا لكتابة صفحات دليل للبرامج التي تفتقر إليها. كما تُوزع الإصدارات الحديثة من نظام 4.4BSD صفحات الدليل كأحد الأشكال الأساسية لتوثيق النظام (بعد استبدال -manوحدات الماكرو القديمة بالوحدات الأحدث -mdoc).

كان هناك سرٌّ خفيٌّ في نسخة man-db من أمر man، يُتيح للأمر إرجاع عبارة "gimme gimme gimme" عند تشغيله في الدقيقة 00:30 (إشارة إلى أغنية ABBA " Gimme! Gimme! Gimme!" (A Man After Midnight) ). أُضيف هذا السرّ في عام 2011 ^{[ 7 ]،} ولكن جرى تقييده في البداية ^{[ 8 ]} ، ثم أُزيل في عام 2017 ^{[ 9 ]} بعد اكتشافه أخيرًا. ^{[ 10 ]}

التنسيق الافتراضي لصفحات الدليل هو troff ، باستخدام إما حزمة الماكرو man (الموجهة نحو المظهر) أو mdoc (الموجهة نحو الدلالة). وهذا يُتيح إمكانية كتابة صفحة الدليل بصيغة PostScript و PDF وغيرها من الصيغ المختلفة لعرضها أو طباعتها.

تحتوي بعض أنظمة يونكس على حزمة لأمر man2html ، مما يُمكّن المستخدمين من تصفح صفحات الدليل (man pages) باستخدام متصفح HTML. أما الأنظمة التي تحتوي على groff وman-db، فيُفضّل استخدام مخرجات HTML الأصلية عالية الجودة ( man --html ) بدلاً من ذلك. يسمح برنامج GNU Emacs المسمى WoMan (اختصارًا لـ "بدون man") بتصفح صفحات الدليل من المحرر. ^{[ 11 ]}

في عام ٢٠١٠، أوقفت OpenBSD استخدام troff لتنسيق صفحات الدليل لصالح mandoc ، وهو مُترجم/مُنسق متخصص لصفحات الدليل يدعم الإخراج بصيغ PostScript و HTML و XHTML والطرفية. ويقتصر دعمه على مجموعة فرعية من troff المستخدمة في صفحات الدليل، وتحديدًا تلك التي تستخدم وحدات mdoc البرمجية.

لقراءة صفحة دليل لأحد أوامر نظام يونكس، يمكن للمستخدم كتابة ما يلي:

man <command_name> 

يُشار إلى الصفحات تقليديًا باستخدام الصيغة "الاسم(القسم)": على سبيل المثال، ftp(1). يشير القسم إلى الطرق المختلفة التي يمكن من خلالها الإشارة إلى الموضوع - على سبيل المثال، كاستدعاء نظام، أو أمر shell (سطر الأوامر) أو حزمة، أو ملف تكوين حزمة، أو كبنية برمجية / رأس.

قد يظهر اسم الصفحة نفسه في أكثر من قسم من الدليل، كما هو الحال عند تطابق أسماء استدعاءات النظام ، أو أوامر المستخدم ، أو حزم الماكرو . ومن الأمثلة على ذلك: ` man(1)< اسم man(7)الصفحة >` و`<اسم الصفحة>`، أو `<اسم الصفحة>` و`<اسم الصفحة>`. تختلف صيغة الوصول إلى قسم الدليل غير الافتراضي بين تطبيقات الدليل المختلفة.exit(2)exit(3)

على سبيل المثال، في نظامي التشغيل Solaris و illumos، تكون صيغة القراءة printf(3C)كالتالي:

man -s 3c printf

في أنظمة لينكس ومشتقات بي إس دي، سيكون الاستدعاء نفسه كالتالي:

رجل 3 طباعة

يبحث هذا الأمر عن دالة printf في القسم 3 من صفحات الدليل. من المرجح أن يتضمن اسم الملف الفعلي هذا القسم. وبالاستمرار في هذا المثال، سيكون الملف printf.3.gz ملفًا مضغوطًا لصفحة الدليل في القسم 3 الخاص بدالة printf .

ينقسم الدليل عمومًا إلى ثمانية أقسام مرقمة. ترث معظم الأنظمة اليوم (مثل BSD ، ^{[ 17 ]} و macOS و Linux ، ^{[ 18 ]} و Solaris 11.4) نظام الترقيم المستخدم في Research Unix ، ^{[ 19 ] [ 20 ]} بينما يستخدم System V ترتيبًا مختلفًا: ^{[ 21 ]}

توجد واجهات برمجة تطبيقات POSIX في كل من القسمين 2 و 3، حيث يحتوي القسم 2 على واجهات برمجة تطبيقات يتم تنفيذها كاستدعاءات نظام، بينما يحتوي القسم 3 على واجهات برمجة تطبيقات يتم تنفيذها كإجراءات مكتبة.

في بعض الأنظمة، قد يتم تضمين أقسام إضافية، مثل:

تُقسّم بعض الأقسام إلى أقسام فرعية باستخدام لاحقة؛ على سبيل المثال، في بعض الأنظمة، يُخصّص القسم 3C لاستدعاءات مكتبة لغة C، والقسم 3M لمكتبة الرياضيات، وهكذا. ونتيجةً لذلك، يُدمج القسم 8 (أوامر إدارة النظام) أحيانًا في القسم الفرعي 1M من قسم الأوامر الرئيسي. بعض لواحق الأقسام الفرعية لها معنى عام يشمل جميع الأقسام.

(يميل القسم 3 إلى أن يكون الاستثناء، حيث يحتوي على العديد من اللواحق للغات المختلفة.)

تقوم بعض إصدارات البرامج manبتخزين النسخ المنسقة من آخر الصفحات التي تمت زيارتها. ومن هذه النسخ صفحة "cat" ، التي يتم تمريرها ببساطة إلى برنامج عرض الصفحات لعرضها.

تتبع جميع صفحات الدليل تصميمًا موحدًا مُحسَّنًا للعرض على شاشة عرض نصية بسيطة بنظام ASCII ، وقد لا تتضمن أي شكل من أشكال التمييز أو التحكم في الخط. قد تشمل الأقسام الموجودة ما يلي: ^{[ 23 ] : بنية الدليل}

اسم

اسم الأمر أو الوظيفة، متبوعًا بوصف من سطر واحد لما يفعله.

ملخص

في حالة الأوامر، يُقدّم وصفٌ رسميٌّ لكيفية تشغيلها وخيارات سطر الأوامر التي تقبلها. أما بالنسبة لوظائف البرامج، فيُقدّم قائمةٌ بالمعاملات التي تقبلها الوظيفة وملف الرأس الذي يحتوي على تعريفها.

وصف

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

أمثلة

بعض الأمثلة على الاستخدام الشائع.

انظر أيضاً

قائمة بالأوامر أو الوظائف ذات الصلة.

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

يمكن كتابة صفحات الدليل باستخدام manوحدات الماكرو القديمة أو الجديدة doc. ^{[ 24 ]}man توفر مجموعة وحدات الماكرو وظائف نصية منسقة أساسية ، مع توجيهات لسطر العنوان، وعناوين الأقسام، ونوع الخط (غامق، صغير، مائل)، والفقرات، وإضافة/تقليل المسافة البادئة. ^{[ 25 ]} تتميز اللغة الأحدث mdocبطابع دلالي أكثر، وتحتوي على وحدات ماكرو متخصصة لمعظم الأقسام القياسية مثل اسم البرنامج، والملخص، وأسماء الوظائف، وأسماء المؤلفين. يمكن استخدام هذه المعلومات لتنفيذ بحث دلالي عن الأدلة بواسطة برامج مثل mandoc . على الرغم من أنها تتضمن أيضًا توجيهات للتحكم المباشر في التنسيق، فمن المتوقع أن تغطي وحدات الماكرو المتخصصة معظم حالات الاستخدام. ^{[ 23 ]} يراعي كل من مشروعي mandoc وgroff mdocالتنسيق المفضل للمستندات الجديدة. ^{[ 26 ]}

على الرغم من أن صفحات الدليل (man pages) تُعرض، وفقًا لـ troff، كنصوص مكتوبة بخط روماني بحجم 10 نقاط ، إلا أن هذا التمييز غالبًا ما يكون غير ذي جدوى لأن صفحات الدليل تُعرض في الطرفية (TTY) بدلًا من عرضها على الورق. ونتيجةً لذلك، نادرًا ما يُستخدم ماكرو "small font". ^{[ 27 ]} من ناحية أخرى، تدعم الطرفية النصوص العريضة والمائلة عبر معيار ECMA-48 ، ويُصدرها groff's grottyعند الطلب عند اكتشاف طرفية تدعمها. مع ذلك، لا يدعم دليل BSD (mandoc) النصوص العريضة والمسطرة (كبديل للنصوص المائلة) إلا عبر تسلسل مسح الشاشة ثم إعادة الكتابة على الآلة الكاتبة، والذي يحتاج إلى ترجمة إلى معيار ECMA-48 less. ^{[ 28 ] [ 29 ]}

استُخدمت بعض الأدوات لتحويل المستندات إلى صفحات دليل بتنسيق أقل تعقيدًا. من الأمثلة على ذلك أداة GNU help2man، التي تأخذ --helpمُخرَجًا ومحتوى إضافيًا لإنشاء صفحة دليل. ^{[ 30 ]} قد لا يكون الدليل أكثر فائدة من المُخرَج المذكور، ولكن هذا لا يُمثّل مشكلة لبرامج GNU لأن texinfo هو نظام التوثيق الرئيسي. ^{[ 31 ]} يدعم عدد من الأدوات، بما في ذلك pandoc وronn وmd2man، التحويل من Markdown إلى صفحات دليل. تُصدر جميع هذه الأدوات manتنسيقًا مختلفًا، لأن Markdown ليس مُعبِّرًا بما يكفي لمُطابقة المحتوى الدلالي لـ mdoc. يحتوي DocBook على مُحوِّل man(7) مُدمج - بجودة رديئة للغاية، وفقًا لمُطوِّر mandoc ^{[ 32 ]} الذي كتب مُحوِّل mdoc(7) مُنفصلًا.

تُكتب صفحات الدليل عادةً باللغة الإنجليزية، ولكن قد تتوفر ترجمات إلى لغات أخرى على النظام. من المعروف أن نظام جنو man-dbوأداة mandoc manيبحثان عن صفحات الدليل المترجمة ضمن المجلدات الفرعية. ^{[ 33 ] [ 18 ] : نظرة عامة [ 17 ]}

• قائمة أوامر يونكس
• قائمة تطبيقات الخطة 9
• info
• apropos
• ملف التعليمات
• اقرأ الدليل
• ManOpen – أداة إدارة رسومية لنظامي التشغيل NeXT و macOS

• تاريخ صفحات دليل نظام يونكس (UNIX Manpages) للحصول على تاريخ المصدر الأساسي لصفحات دليل نظام يونكس (UNIX Manpages).
• مستودع صفحات الدليل لنظامي التشغيل UNIX و Linux يحتوي على ما يقرب من 300,000 صفحة دليل منسقة بشكل جيد.
• ماذا تعني الأرقام في صفحة الدليل؟
• صفحات دليل FreeBSD ، freebsd.org – تحتوي أيضًا على صفحات دليل لأنظمة Darwin و Debian و HP-UX و IRIS و NetBSD و OpenBSD و NextSTEP و SunOS وغيرها
• مشروع صفحات دليل لينكس