أقسام صفحات الدليل¶

تُعرَّف أقسام الدليل تقليديًا كما يلي:

1 أوامر المستخدم (البرامج)

الأوامر التي يمكن للمستخدم تنفيذها من داخل صدفة.

2 نداءات النظام

الدوال التي تغلف العمليات التي تؤديها النواة.

3 نداءات المكتبة

جميع دوال المكتبة باستثناء مغلفات نداءات النظام (معظم دوال libc).

4 الملفات الخاصة (الأجهزة)

الملفات الموجودة في /dev والتي تتيح الوصول إلى الأجهزة عبر النواة.

5 تنسيقات الملفات وملفات الضبط

يصف تنسيقات الملفات المتنوعة المقروءة بشريًا وملفات الضبط.

6 الألعاب

الألعاب والبرامج الصغيرة المسلية المتاحة على النظام.

7 نظرة عامة، وأعراف، ومتفرقات

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

8 أوامر إدارة النظام

أوامر مثل mount(8)، وكثير منها لا يمكن إلا للجذر (root) تنفيذها.

حزمة الماكرو¶

ينبغي ترميز صفحات الدليل الجديدة باستخدام حزمة groff an.tmac الموصوفة في man(7). هذا الاختيار يهدف رئيسًا إلى الاتساق: فالعالبية العظمى من صفحات دليل لينكس الحالية مُرمزة باستخدام هذه الماكروهات.

أعراف تخطيط ملف المصدر¶

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

سطر العنوان¶

يجب أن يكون الأمر الأول في صفحة الدليل هو أمر TH:

وسطاء الأمر هي كما يلي:

title

عنوان صفحة الدليل.

section

رقم القسم الذي يجب وضع صفحة الدليل فيه (مثلاً، 7).

التاريخ

تاريخ آخر تغيير جوهري أُجري على صفحة الدليل. (ضمن مشروع صفحات الدليل، تتم معالجة التحديثات اللازمة لهذه الطوابع الزمنية آليًا بواسطة سكربتات، لذا لا داعي لتحديثها يدويًا كجزء من رقعة.) يجب كتابة التواريخ بصيغة YYYY-MM-DD.

المصدر

اسم وإصدار المشروع الذي يوفر صفحة الدليل (ليس بالضرورة الحزمة التي توفر الوظيفة).

قسم-الدليل

عادة، يجب أن يكون هذا فارغًا، حيث ستكون القيمة المبدئية جيدة.

الأقسام داخل صفحة الدليل¶

توضح القائمة أدناه الأقسام التقليدية أو المقترحة. يجب أن تتضمن معظم صفحات الدليل على الأقل الأقسام المميزة. رتب صفحة دليل جديدة بحيث توضع الأقسام بالترتيب الموضح في القائمة.

حيثما ينطبق عنوان تقليدي، يرجى استخدامه؛ فهذا النوع من الاتساق يمكن أن يجعل المعلومات أسهل في الفهم. إذا اضطررت لذلك، يمكنك إنشاء عناوينك الخاصة إذا كانت تجعل الأمور أسهل في الفهم (يمكن أن يكون هذا مفيدًا بشكل خاص للصفحات في القسمين 4 و5). ومع ذلك، قبل القيام بذلك، فكر فيما إذا كان بإمكانك استخدام العناوين التقليدية، مع بعض الأقسام الفرعية (.SS) داخل تلك الأقسام.

توضح القائمة التالية بالتفصيل محتويات كل قسم من الأقسام المذكورة أعلاه.

الاسم

اسم صفحة الدليل هذه.

See man(7) for important details of the line(s) that should follow the .SH NAME command. All words in this line (including the word immediately following the "\-") should be in lowercase, except where English or technical terminological convention dictates otherwise.

المكتبة

المكتبة التي توفر رمزًا.

يعرض الاسم الشائع للمكتبة، وبين قوسين، اسم ملف المكتبة، وإذا لزم الأمر، راية الموصل (linker flag) اللازمة لربط برنامج بها: (libfoo[, -lfoo]).

موجز

ملخص موجز لواجهة الأمر أو الدالة.

بالنسبة للأوامر، يعرض هذا صيغة الأمر ووسطائه (بما في ذلك الخيارات)؛ يُستخدم الخط العريض للنص كما هو، والخط المائل للإشارة إلى الوسطاء القابلة للاستبدال. تحيط الأقواس المربعة ([]) بالوسطاء الاختيارية، وتفصل الأشرطة العمودية (|) بين الخيارات، ويمكن تكرار علامات الحذف (...). بالنسبة للدوال، يعرض أي تصريحات بيانات مطلوبة أو توجيهات #include، يليه تصريح الدالة.

عندما يجب تعريف ماكرو اختبار ميزة من أجل الحصول على تصريح دالة (أو متغير) من ملف ترويسة، فيجب أن يشير قسم الموحز إلى ذلك، كما هو موصوف في feature_test_macros(7).

الضبط

تفاصيل الضبط لجهاز ما.

يظهر هذا القسم عادةً في صفحات القسم 4 فقط.

الوصف

شرح لما يفعله البرنامج أو الدالة أو التنسيق.

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

عند وصف سلوك جديد أو رايات جديدة لنداء نظام أو دالة مكتبة، توخَّ الحذر لتدوين إصدار النواة أو مكتبة C الذي أدخل التغيير. الطريقة المفضلة لتدوين هذه المعلومات للرايات هي كجزء من قائمة .TP، بالشكل التالي (هنا، لراية نداء نظام جديدة):

يعد تضمين معلومات الإصدار مفيدًا بشكل خاص للمستخدمين المقيدين باستخدام إصدارات قديمة من النواة أو مكتبة C (وهو أمر شائع في الأنظمة المضمنة، على سبيل المثال).

الخيارات

وصف لخيارات سطر الأوامر التي يقبلها البرنامج وكيفية تغييرها لسلوكه.

ينبغي ألا يظهر هذا القسم إلا في صفحات الدليل من القسمين 1 و 8.

المعاملات

وصف لمعاملات الدالة أو البرنامج، وكيفية تغييرها لسلوكه.

حالة الخروج

قائمة بقيم حالة الخروج المحتملة للبرنامج والظروف التي تؤدي إلى إرجاع هذه القيم.

ينبغي ألا يظهر هذا القسم إلا في صفحات الدليل من القسمين 1 و 8.

قيمة الإرجاع

بالنسبة لصفحات القسمين 2 و 3، يقدم هذا القسم قائمة بالقيم التي سيرجعها روتين المكتبة إلى المستدعِي والظروف التي تؤدي إلى إرجاع هذه القيم.

الأخطاء

بالنسبة لصفحات الدليل من القسمين 2 و 3، هذه قائمة بالقيم التي قد توضع في errno في حال وقوع خطأ، مع معلومات حول سبب هذه الأخطاء.

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

يجب أن تكون قائمة الأخطاء مرتبة أبجديًا.

البيئة

قائمة بكافة متغيرات البيئة التي تؤثر على البرنامج أو الدالة وكيفية تأثيرها.

FILES

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

اذكر مسار الدليل الكامل لهذه الملفات، واستخدم عملية التثبيت لتعديل جزء الدليل ليتناسب مع تفضيلات المستخدم. بالنسبة للعديد من البرامج، يكون موقع التثبيت المبدئي في /usr/local، لذا يجب أن تستخدم صفحة الدليل الأساسية /usr/local كأساس.

السمات

ملخص للسمات المتنوعة للدالة (أو الدوال) الموثقة في هذه الصفحة. انظر attributes(7) لمزيد من التفاصيل.

الإصدارات

ملخص للأنظمة التي تؤدي فيها واجهة برمجة التطبيقات (API) بشكل مختلف، أو حيث توجد واجهة برمجة تطبيقات مماثلة.

المعايير

وصف لأي معايير أو اتفاقيات تتعلق بالدالة أو الأمر الذي تصفه صفحة الدليل.

المصطلحات المفضلة للاستخدام مع المعايير المختلفة مدرجة كعناوين في standards(7).

يجب أن يشير هذا القسم إلى المعايير الحالية التي تتوافق معها واجهة برمجة التطبيقات.

إذا لم تكن واجهة برمجة التطبيقات محكومة بأي معايير ولكنها موجودة بشكل شائع في أنظمة أخرى، فاذكرها. إذا كان الاستدعاء خاصًا بلينكس أو بـ GNU، فاذكر ذلك. وإذا كان متاحًا في أنظمة BSD، فاذكر ذلك.

إذا كان هذا القسم يتكون من مجرد قائمة بالمعايير (كما هو شائع)، فأنهِ القائمة بنقطة ('.').

التاريخ

ملخص موجز لإصدارات نواة لينكس أو glibc التي ظهر فيها استدعاء النظام أو دالة المكتبة، أو تغير فيها تشغيلها بشكل كبير.

كقاعدة عامة، ينبغي أن تتضمن كل واجهة جديدة قسم HISTORY في صفحة دليلها. لسوء الحظ، لا تتضمن العديد من صفحات الدليل الحالية هذه المعلومات (نظرًا لعدم وجود سياسة للقيام بذلك وقت كتابتها). نرحب بالرقع البرمجية لمعالجة هذا الأمر، ولكن من وجهة نظر المبرمجين الذين يكتبون تعليمات برمجية جديدة، فمن المحتمل أن تهم هذه المعلومات فقط في حالة واجهات النواة التي أضيفت في لينكس 2.4 أو أحدث (أي التغييرات منذ لينكس 2.2)، ودوال المكتبة التي أضيفت إلى glibc منذ الإصدار 2.1 (أي التغييرات منذ glibc 2.0).

توفر صفحة دليل syscalls(2) أيضًا معلومات حول إصدارات النواة التي ظهرت فيها استدعاءات النظام المختلفة لأول مرة.

يجب ذكر الإصدارات القديمة من المعايير هنا، بدلاً من قسم STANDARDS، على سبيل المثال، SUS و SUSv2 و XPG، أو معايير تنفيذ SVr4 و 4.xBSD.

ملاحظات

ملاحظات متنوعة.

For Section 2 and 3 man pages you may find it useful to include subsections (SS) named Linux Notes and glibc Notes.

في القسم 2، استخدم العنوان C library/kernel differences لتمييز الملاحظات التي تصف الفروق (إن وجدت) بين دالة غلاف مكتبة C لاستدعاء النظام وواجهة استدعاء النظام الخام التي توفرها النواة.

تنبيهات

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

العلل

قائمة بالقيود، والعيوب المعروفة أو المضايقات، وغيرها من الأنشطة المشكوك فيها.

أمثلة

مثال واحد أو أكثر يوضح كيفية استخدام هذه الدالة، أو الملف، أو الأمر.

For details on writing example programs, see Example programs below.

المؤلفون

قائمة بمؤلفي التوثيق أو البرنامج.

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

الإبلاغ عن العلل

لا يستخدم مشروع man-pages قسم REPORTING BUGS في صفحات الدليل. بدلاً من ذلك، تُقدم المعلومات المتعلقة بالإبلاغ عن العلل في قسم COLOPHON الذي يولده سكربت. ومع ذلك، تستخدم مشاريع مختلفة قسم REPORTING BUGS. ويوصى بوضعه بالقرب من تذييل الصفحة.

حقوق النشر

لا يستخدم مشروع man-pages قسم COPYRIGHT في صفحات الدليل. بدلاً من ذلك، يتم الاحتفاظ بمعلومات حقوق النشر في مصدر الصفحة. في الصفحات التي يتوفر فيها هذا القسم، يوصى بوضعه بالقرب من تذييل الصفحة، فوق SEE ALSO مباشرة.

انظر أيضًا

قائمة مفصولة بفواصل لصفحات دليل ذات صلة، وقد يتبعها صفحات أو مستندات أخرى ذات صلة.

يجب ترتيب القائمة حسب رقم القسم ثم أبجديًا حسب الاسم. لا تنهِ هذه القائمة بنقطة.

عندما تحتوي قائمة SEE ALSO على العديد من أسماء صفحات الدليل الطويلة، ولتحسين النتيجة المرئية للمخرجات، قد يكون من المفيد استخدام التوجيهات .ad l (عدم المحاذاة لليمين) و .nh (عدم الوصل). يمكن منع وصل أسماء الصفحات الفردية بسبق الكلمات بالسلسلة "\%".

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

موجز¶

لف نموذج (أو نماذج) الدالة في زوج .nf/.fi لمنع الملء.

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

int snprintf(size_t size;
             char str[restrict size], size_t size,
             const char *restrict format, ...);

بشكل عام، عندما يُعرض أكثر من نموذج دالة في SYNOPSIS، لا ينبغي فصل النماذج بأسطر فارغة. ومع ذلك، يمكن إضافة أسطر فارغة (باستخدام .P) في الحالات التالية:

•

لفصل القوائم الطويلة من نماذج الدوال إلى مجموعات ذات صلة (انظر على سبيل المثال list(3))؛

•

في الحالات الأخرى التي قد تحسن من قابلية القراءة.

في قسم SYNOPSIS، قد يلزم استكمال نموذج دالة طويل في السطر التالي. يُزاح سطر الاستكمال وفقًا للقواعد التالية:

(1)

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

int tcsetattr(int fd, int optional_actions,
              const struct termios *termios_p);

(2)

ولكن، عندما تتطلب دوال متعددة في SYNOPSIS أسطر استكمال، وتكون أسماء الدوال ذات أطوال مختلفة، فقم بمحاذاة كافة أسطر الاستكمال لتبدأ في نفس العمود. يوفر هذا تصييرًا أجمل في مخرجات PDF (لأن SYNOPSIS يستخدم خطًا متغير العرض حيث تظهر المسافات أضيق من معظم المحارف). كمثال:

int getopt(int argc, char * const argv[],
           const char *optstring);
int getopt_long(int argc, char * const argv[],
           const char *optstring,
           const struct option *longopts, int *longindex);

قيمة الإرجاع¶

الصياغة المفضلة لوصف كيفية تعيين errno هي "يتم تعيين errno للإشارة إلى الخطأ" أو ما شابه ذلك. هذه الصياغة متسقة مع الصياغة المستخدمة في كل من POSIX.1 و FreeBSD.

السمات¶

لاحظ ما يلي:

•

لف الجدول في هذا القسم في زوج .ad l/.ad لتعطيل ملء النص وزوج .nh/.hy لتعطيل الوصل.

•

تأكد من أن الجدول يشغل عرض الصفحة بالكامل من خلال استخدام وصف lbx لأحد الأعمدة (عادةً العمود الأول، وإن كان في بعض الحالات العمود الأخير إذا كان يحتوي على الكثير من النص).

•

استخدم أزواج ماكرو T{/T} بحرية للسماح بتقسيم خلايا الجدول عبر عدة أسطر (مع مراعاة أن الصفحات قد تُصيّر أحيانًا بعرض أقل من 80 عمودًا).

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

استخدام لغة محايدة جنسانياً¶

بقدر الإمكان، استخدم لغة محايدة جنسانياً في نص صفحات الدليل. استخدام ضمير الغائب للجمع (هم، إياهم، أنفسهم، ملكهم) كضمير مفرد محايد جنسانياً هو أمر مقبول.

اتفاقيات التنسيق لصفحات الدليل التي تصف الأوامر¶

بالنسبة لصفحات الدليل التي تصف أمرًا (عادة في القسمين 1 و 8)، يتم دائمًا تحديد المعاملات باستخدام الخط المائل، حتى في قسم SYNOPSIS.

يجب دائمًا تنسيق اسم الأمر وخياراته بالخط العريض.

اتفاقيات التنسيق لصفحات الدليل التي تصف الدوال¶

بالنسبة لصفحات الدليل التي تصف دوال (عادة في القسمين 2 و 3)، يتم دائمًا تحديد المعاملات باستخدام الخط المائل، حتى في قسم SYNOPSIS، حيث يتم تحديد باقي الدالة بالخط العريض:

int myfunction(int argc, char **argv);

يجب تحديد أسماء المتغيرات، مثل أسماء المعاملات، بالخط المائل.

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

    .BR fcntl ()

(استخدام هذا التنسيق، بدلاً من استخدام "\fB...\fP()" يجعل من الأسهل كتابة أدوات تحلل ملفات مصدر صفحة الدليل).

استخدام أسطر برمجية دلالية¶

في مصدر صفحة الدليل، يجب بدء الجمل الجديدة في أسطر جديدة، ويجب تقسيم الجمل الطويلة إلى أسطر عند فواصل العبارات (الفاصلة، والفاصلة المنقوطة، والنقطتان الرأسيتان، وما إلى ذلك)، ويجب تقسيم العبارات الطويلة عند حدود الجمل. هذا الاتفاق، المعروف أحيانًا باسم "الأسطر البرمجية الدلالية"، يجعل من السهل رؤية تأثير الرقع البرمجية، والتي غالبًا ما تعمل على مستوى الجمل أو العبارات الفردية.

قوائم¶

توجد أنواع مختلفة من القوائم:

فقرات موسومة

تُستخدم هذه القوائم للوسوم وأوصافها. عندما تكون الأوسمة ثوابت (سواء كانت ماكرو أو أرقامًا) فإنها تكون بالخط العريض. استخدم ماكرو .TP.

ومثال على ذلك هو هذا القسم الفرعي "فقرات موسومة" نفسه.

القوائم المرتبة

تُسبق العناصر برقم بين قوسين (1)، (2). تمثل هذه العناصر مجموعة من الخطوات التي تتبع ترتيبًا معينًا.

عند وجود خطوات فرعية، تُرقم مثل (4.2).

القوائم الموضعية

تُسبق العناصر برقم (فهرس) بين قوسين مربعين [4]، [5]. تمثل هذه حقولًا في مجموعة. الفهرس الأول سيكون:

قائمة البدائل

تُسبق العناصر بحرف بين قوسين (أ)، (ب). تمثل هذه مجموعة من البدائل الحصرية (عادةً).

القوائم المنقطة

تُسبق العناصر برموز نقطية (\[bu]). وعادةً ما يُغطى أي شيء لا يناسب مكاناً آخر بهذا النوع من القوائم.

ملاحظات مرقمة

ليست قائمة حقاً، لكن صيغتها مطابقة لـ "القوائم الموضعية".

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

اصطلاحات التنسيق (عام)¶

ينبغي فصل الفقرات بوسوم مناسبة (عادةً إما .P أو .IP). لا تفصل بين الفقرات باستخدام أسطر فارغة، لأن هذا يؤدي إلى تصيير رديء في بعض تنسيقات المخرجات (مثل PostScript وPDF).

أسماء الملفات (سواء كانت مسارات، أو مراجع لملفات ترويسة) تكون دائماً بخط مائل (مثل <stdio.h>)، باستثناء قسم المُلخص (SYNOPSIS)، حيث تكون الملفات المضمنة بخط عريض (مثل #include <stdio.h>). عند الإشارة إلى تضمين ملف ترويسة قياسي، حدد ملف الترويسة محاطاً بأقواس زاوية، بالطريقة المعتادة في لغة C (مثل <stdio.h>).

الماكروهات الخاصة، التي تكون عادةً بأحرف كبيرة، تكتب بخط عريض (مثل MAXINT). استثناء: لا تجعل NULL بخط عريض.

عند تعداد قائمة من رموز الأخطاء، تكون الرموز بخط عريض (تستخدم هذه القائمة عادةً ماكرو .TP).

الأوامر الكاملة، إذا كانت طويلة، يجب أن تُكتب في سطر مزاح بمفردها، مع سطر فارغ قبل الأمر وبعده، على سبيل المثال

man 7 man-pages

إذا كان الأمر قصيراً، فيمكن تضمينه داخل النص، بتنسيق مائل، على سبيل المثال، man 7 man-pages. في هذه الحالة، قد يكون من المفيد استخدام مسافات غير قاطعة (\~) في أماكن مناسبة من الأمر. خيارات الأوامر يجب أن تُكتب بخط مائل (مثل -l).

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

عند عرض أمثلة لجلسات الصدفة، يجب تنسيق مدخلات المستخدم بخط عريض، على سبيل المثال

$ date;
Thu Jul  7 13:01:27 CEST 2016

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

    .BR intro (2)

(تضمين رقم القسم في الإحالات المرجعية يتيح لأدوات مثل man2html(1) إنشاء صفحات تحتوي على روابط تشعبية صحيحة.)

محارف التحكم يجب أن تُكتب بخط عريض، وبدون علامات اقتباس؛ على سبيل المثال، ^X.

الإملاء¶

بدءاً من الإصدار 2.59، يتبع man-pages اصطلاحات الإملاء الأمريكية (سابقاً، كان هناك مزيج عشوائي من الإملاء البريطاني والأمريكي)؛ يرجى كتابة جميع الصفحات والترقيعات الجديدة وفقاً لهذه الاصطلاحات.

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

•

تميل الإنجليزية الأمريكية إلى استخدام الصيغ "backward"، و "upward"، و "toward"، وما إلى ذلك، بدلاً من الصيغ البريطانية "backwards"، و "upwards"، و "towards"، وما إلى ذلك.

•

الآراء منقسمة حول "acknowledgement" مقابل "acknowledgment". الصيغة الأخيرة هي الغالبة، ولكنها ليست عالمية الاستخدام في الإنجليزية الأمريكية. تستخدم POSIX ورخصة BSD الهجاء الأول. في مشروع Linux man-pages، نستخدم "acknowledgement".

أرقام إصدارات BSD¶

المخطط التقليدي لكتابة أرقام إصدارات BSD هو x.yBSD، حيث x.y هو رقم الإصدار (مثل 4.2BSD). تجنب صيغاً مثل BSD 4.3.

استخدام الأحرف الكبيرة¶

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

.SS Unicode under Linux

إزاحة تعريفات الهياكل وسجلات جلسات الصدفة وما إلى ذلك¶

عند تضمين تعريفات الهياكل وسجلات جلسات الصدفة وما إلى ذلك في النص الجاري، أزحها بمقدار 4 مسافات (أي كتلة محاطة بـ .in +4n و .in)، ونسقها باستخدام ماكروهات .EX و .EE، وأحطها بعلامات فقرة مناسبة (إما .P أو .IP). على سبيل المثال:

.P
.in +4n
.EX
int
main(int argc, char *argv[])
{


    return 0;
}
.EE
.in
.P

المصطلحات المفضلة¶

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

انظر أيضًا مناقشة الوصل بواصلة للمركبات النعتية أدناه.

مصطلحات ينبغي تجنبها¶

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

العلامات التجارية¶

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

DG/UX

HP-UX

UNIX

UnixWare

NULL، وNUL، والمؤشر الصفري (null pointer)، والبايت الصفري (null byte)¶

المؤشر الصفري هو مؤشر لا يشير إلى شيء، ويُشار إليه عادةً بالثابت NULL. من ناحية أخرى، NUL هو البايت الصفري، وهو بايت قيمته 0، ويُمثل في لغة C عبر ثابت المحارف '\0'.

المصطلح المفضل للمؤشر هو "null pointer" أو ببساطة "NULL"؛ تجنب كتابة "NULL pointer".

المصطلح المفضل للبايت هو "null byte". تجنب كتابة "NUL"، لأنه يسهل الخلط بينه وبين "NULL". تجنب أيضاً المصطلحين "zero byte" و "null character". البايت الذي ينهي سلسلة C النصية ينبغي وصفه بأنه "the terminating null byte"؛ ويمكن وصف السلاسل النصية بأنها "null-terminated"، لكن تجنب استخدام "NUL-terminated".

الارتباطات التشعبية¶

بالنسبة للارتباطات التشعبية، استخدم زوج ماكرو .UR/.UE (انظر groff_man(7)). ينتج عن هذا ارتباطات تشعبية مناسبة يمكن استخدامها في متصفح الويب، عند تصيير صفحة باستخدام، على سبيل المثال:

BROWSER=firefox man -H pagename

استخدام .e.g و .i.e و .etc و .a.k.a وما شابه ذلك¶

بشكل عام، ينبغي تجنب استخدام الاختصارات مثل "e.g." و "i.e." و "etc." و "cf." و "a.k.a."، لصالح صياغات كاملة مناسبة ("على سبيل المثال"، "أي"، "إلى آخره"، "قارن بـ"، "يُعرف أيضاً بـ").

المكان الوحيد الذي قد تكون فيه هذه الاختصارات مقبولة هو في التعقيبات الاعتراضية القصيرة (e.g., like this one).

ضع دائماً نقاطاً في مثل هذه الاختصارات، كما هو موضح هنا. بالإضافة إلى ذلك، يجب أن يتبع "e.g." و "i.e." دائماً فاصلة.

الشرطات الطويلة (Em-dashes)¶

طريقة كتابة الشرطة الطويلة (em-dash)—وهي الرمز الذي يظهر عند طرفي هذه العبارة الفرعية—في *roff هي باستخدام الماكرو "\[em]". (على طرفية ASCII، تُصيّر الشرطة الطويلة عادةً كشرطتين، ولكن في السياقات الطباعية الأخرى تُصيّر كشرطة طويلة). ينبغي كتابة الشرطات الطويلة دون مسافات محيطة بها.

الوصل بواصلة للمركبات النعتية¶

ينبغي وصل المصطلحات المركبة بواصلة عندما تُستخدم نعتياً (أي لوصف اسم يتبعها). بعض الأمثلة:

32-bit value

command-line argument

floating-point number

run-time check

user-space function

wide-character string

الوصل بواصلة مع البادئات multi و non و pre و re و sub وما إلى ذلك¶

الميل العام في اللغة الإنجليزية الحديثة هو عدم الوصل بواصلة بعد البادئات مثل "multi" و "non" و "pre" و "re" و "sub" وما إلى ذلك. ينبغي أن تتبع صفحات الدليل هذه القاعدة عموماً عندما تُستخدم هذه البادئات في تراكيب إنجليزية طبيعية مع لواحق بسيطة. تعطي القائمة التالية بعض الأمثلة على الأشكال المفضلة:

interprocess

multithreaded

multiprocess

nonblocking

nondefault

nonempty

noninteractive

nonnegative

nonportable

nonzero

preallocated

precreate

prerecorded

reestablished

reinitialize

rearm

reread

subcomponent

subdirectory

subsystem

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

non-ASCII

non-English

non-NULL

non-real-time

أخيراً، لاحظ أن "re-create" و "recreate" فعلان مختلفان، والأول هو على الأرجح ما تريده.

توليد الرموز المثلى¶

عندما يلزم استخدام محرف ناقص حقيقي (على سبيل المثال، للأرقام مثل -1، أو للإحالات المرجعية لصفحات الدليل مثل utf-8(7)، أو عند كتابة الخيارات التي تبدأ بشرطة، كما في ls -l)، استخدم الشكل التالي في مصدر صفحة الدليل:

\-

تنطبق هذه الإرشادات أيضاً على أمثلة الكود.

يخدم استخدام علامات الناقص الحقيقية الأغراض التالية:

•

لتوفير تصيير أفضل على الأهداف المختلفة بخلاف طرفيات ASCII، ولا سيما في ملفات PDF وعلى الطرفيات التي تدعم Unicode/UTF-8.

•

لتوليد صور رموز (glyphs) تُنتج علامات طرح حقيقية عند نسخها من الصفحات المصيرة ولصقها في الطرفية.

لإنتاج علامات اقتباس مفردة غير مائلة تُصير بشكل جيد في ASCII و UTF-8 و PDF، استخدم "\[aq]" ("علامة اقتباس علوية")؛ على سبيل المثال

\[aq]C\[aq]

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

عند الحاجة إلى علامة إقحام (^) سليمة تُصير بشكل جيد في كل من الطرفية و PDF، استخدم "\[ha]". هذا ضروري خاصة في عينات البرمجية، للحصول على علامة إقحام مُصيرة بشكل جيد عند التصدير إلى PDF.

يؤدي استخدام محرف "~" المجرد إلى صيرورة رديئة في PDF. بدلاً من ذلك استخدم "\[ti]". هذا ضروري خاصة في عينات البرمجية، للحصول على علامة مدة (tilde) مُصيرة بشكل جيد عند التصدير إلى PDF.

البرامج الأمثلة وجلسات الصدفة¶

قد تتضمن صفحات الدليل برامج أمثلة توضح كيفية استخدام استدعاء نظام أو دالة مكتبية. ومع ذلك، لاحظ ما يلي:

•

يجب أن تُكتب البرامج الأمثلة بلغة C.

•

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

•

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

•

البرمجية المعبرة محل تقدير.

•

يجب إدراج التعليقات حيثما كانت مفيدة. ويجب إنهاء الجمل الكاملة في التعليقات المستقلة بنقطة. وبشكل عام، يجب حذف النقاط في تعليقات "الوسم" (أي التعليقات التي توضع في نفس سطر البرمجية)؛ فهذه التعليقات تكون عادةً عبارات وجيزة وليست جملاً كاملة.

•

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

•

يجب أن تكون البرامج الأمثلة كاملة، وتُصرف دون تحذيرات عند تصريفها باستخدام cc -Wall.

•

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

•

يجب تنسيق البرامج الأمثلة وفقًا لنمط Kernighan و Ritchie، مع إزاحة بمقدار 4 مسافات. (تجنب استخدام محارف TAB في التعليمات البرمجية المصدرية!) يمكن استخدام الأمر التالي لتنسيق برمجيتك المصدرية إلى شيء قريب من النمط المفضل:

indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
    

•

لتحقيق الاتساق، يجب أن تنتهي جميع البرامج الأمثلة باستخدام إما:

exit(EXIT_SUCCESS);
exit(EXIT_FAILURE);
    

تجنب استخدام الأشكال التالية لإنهاء البرنامج:

exit(0);
exit(1);
return n;
    

•

إذا كان هناك نص تفسيري مستفيض قبل البرمجية المصدرية للبرنامج، فافصل البرمجية المصدرية بترويسة قسم فرعي Program source، كما في:

.SS مصدر البرنامج
    

افعل ذلك دائمًا إذا كان النص التفسيري يتضمن سجل جلسة صدفة.

إذا أدرجت سجل جلسة صدفة يوضح استخدام برنامج أو ميزة نظام أخرى:

•

ضع سجل الجلسة فوق قائمة البرمجية المصدرية.

•

أزِح سجل الجلسة بمقدار أربع مسافات.

•

استخدم الخط العريض لنص مدخلات المستخدم، لتمييزه عن المخرجات التي ينتجها النظام.

للحصول على بعض الأمثلة حول كيف يجب أن تبدو البرامج الأمثلة، انظر wait(2) و pipe(2).