هذا هو الأمر perlpodstyle الذي يمكن تشغيله في مزود الاستضافة المجانية OnWorks باستخدام إحدى محطات العمل المجانية المتعددة على الإنترنت مثل Ubuntu Online أو Fedora Online أو محاكي Windows عبر الإنترنت أو محاكي MAC OS عبر الإنترنت
برنامج:
اسم
perlpodstyle - دليل أسلوب Perl POD
الوصف
هذه إرشادات عامة لكيفية كتابة وثائق POD لنصوص Perl النصية و
وحدات ، بناءً على إرشادات عامة لكتابة صفحات جيدة لـ UNIX. كل هذه
المبادئ التوجيهية ، بالطبع ، اختيارية ، ولكن اتباعها سيجعل وثائقك أكثر
بما يتفق مع الوثائق الأخرى على النظام.
اسم البرنامج الذي يتم توثيقه مكتوب بشكل تقليدي بالخط العريض (باستخدام B <>)
أينما حدث ، كما هو الحال مع جميع خيارات البرنامج. يجب كتابة الحجج بخط مائل
(أنا <>). تتم كتابة أسماء الوظائف بشكل تقليدي بخط مائل ؛ إذا كتبت وظيفة كـ
وظيفة()، Pod :: Man سوف يعتني بهذا من أجلك. يجب أن يكون الرمز أو الأوامر الحرفية
في C <>. يجب أن تكون الإشارات إلى صفحات الدليل الأخرى بالشكل "manpage (section)" أو
"لام "، و Pod :: Man سيقوم تلقائيًا بتنسيق تلك العناصر بشكل مناسب
النموذج الثاني ، مع L <> ، يستخدم لطلب أن يقوم منسق POD بعمل رابط لصفحة الدليل
إذا كان ذلك ممكنا. كاستثناء ، عادة ما يغفل المرء القسم عند الإشارة إلى الوحدة
التوثيق لأنه ليس من الواضح ما هو القسم الذي ستكون فيه وثائق الوحدة ؛ يستخدم
"لام "لمراجع الوحدة بدلاً من ذلك.
عادة ما تكون الإشارات إلى البرامج أو الوظائف الأخرى في شكل مراجع لصفحة الدليل
بحيث يمكن لأدوات الإسناد الترافقي تزويد المستخدم بالروابط وما شابه ذلك. إنه
من الممكن المبالغة في ذلك ، لذا احرص على عدم تشويش مستنداتك أيضًا
الكثير من الترميز. مراجع لبرامج أخرى لم يتم تقديمها كمراجع لصفحة الدليل
يجب إرفاقها في B <>.
يجب تعيين الرؤوس الرئيسية باستخدام التوجيه "= head1" ، وهي تاريخية
مكتوبة بتنسيق ALL UPPER CASE المذهل إلى حد ما ؛ هذا ليس إلزاميا ، لكنه
يوصى بشدة أن يكون للأقسام تسمية متسقة عبر برامج مختلفة
الحزم. يمكن تضمين الرؤوس الثانوية باستخدام "= head2" ، وعادة ما تكون في حالة مختلطة.
الأقسام القياسية لصفحة الدليل هي:
اسم
قسم إلزامي يجب أن تكون قائمة بالبرامج أو الوظائف مفصولة بفواصل
موثقة بواسطة صفحة POD هذه ، مثل:
فو ، بار - برامج لفعل شيء ما
غالبًا ما تكون مفهرسات الصفحات اليدوية انتقائية للغاية بشأن تنسيق هذا القسم ، لذلك
لا تضع أي شيء فيه إلا هذا الخط. كل برنامج أو وظيفة موثقة من قبل
يجب أن يتم سرد صفحة POD هذه ، مفصولة بفاصلة ومسافة. بالنسبة لوحدة لغة Perl ،
فقط أعط اسم الوحدة. يجب أن تفصل شرطة واحدة وشرطة واحدة فقط
قائمة البرامج أو الوظائف من الوصف. لا تستخدم أي ترميز مثل C <>
أو B <> في أي مكان في هذا الخط. يجب ألا يتم تأهيل الوظائف بـ "()" أو
يحب. يجب أن يتناسب الوصف بشكل مثالي مع سطر واحد ، حتى لو كان برنامج الرجل
يستبدل الشرطة ببضع علامات تبويب.
موجز
ملخص استخدام قصير للبرامج والوظائف. هذا القسم إلزامي لـ
القسم 3 صفحات. بالنسبة لوثائق وحدة Perl ، من الملائم عادةً أن يكون لديك امتداد
محتويات هذا القسم عبارة عن مقطع حرفي يعرض بعض الأمثلة (المختصرة) للنموذج
طرق استخدام الوحدة.
الوصف
وصف موسع ومناقشة للبرنامج أو الوظائف ، أو نص
توثيق لصفحات الرجل التي توثق شيئًا آخر. إذا كانت طويلة بشكل خاص ، فهي
فكرة جيدة لتقسيم هذا إلى أقسام فرعية "= head2" توجيهات مثل:
= head2 الاستخدام العادي
= head2 الميزات المتقدمة
= head2 كتابة ملفات التكوين
أو ما هو مناسب لوثائقك.
بالنسبة للوحدة النمطية ، يكون هذا بشكل عام مكان توثيق الواجهات التي يوفرها
تظهر الوحدة النمطية ، عادةً في شكل قائمة بها "= عنصر" لكل واجهة.
اعتمادًا على عدد الواجهات الموجودة ، قد ترغب في وضع تلك الوثائق فيها
افصل بين أقسام الطرق والوظائف وطرق الفصل أو طرق اللحظ بدلاً من ذلك و
احفظ قسم الوصف للحصول على نظرة عامة.
OPTIONS
وصف مفصل لكل خيار من خيارات سطر الأوامر التي يتخذها البرنامج. هذا
يجب أن تكون منفصلة عن وصف استخدام موزعي مثل Pod :: Usage. هذا
يتم تقديمه عادةً على شكل قائمة ، مع كل خيار على أنه "= عنصر" منفصل. المحدد
يجب وضع سلسلة الخيار في B <>. يجب أن تكون أي قيم يأخذها الخيار
المرفقة في I <>. على سبيل المثال ، قسم الخيار --الجزء=مانكست سيكون
قدم مع:
= البند ب <-- القسم> = أنا
الخيارات المرادفة (مثل كل من الأشكال القصيرة والطويلة) مفصولة بفاصلة و a
مسافة على نفس سطر "= item" ، أو مدرجًا اختياريًا كعنصر خاص به مع ملف
إشارة إلى الاسم المتعارف عليه. على سبيل المثال ، منذ ذلك الحين --الجزء يمكن أن يكتب أيضا باسم
-s، ما ورد أعلاه سيكون:
= العنصر B <-s> ، ب <-- القسم> = أنا
يوصى بكتابة الخيار القصير أولاً لأنه يسهل قراءته. الطويل
الخيار طويل بما يكفي لجذب العين إليه على أي حال ويمكن للخيار القصير خلاف ذلك
تضيع في الضوضاء البصرية.
قيمة الإرجاع
ما الذي يعود به البرنامج أو الوظيفة ، في حالة نجاحها. يمكن حذف هذا القسم ل
البرامج التي لا تكون رموز الخروج الخاصة بها مهمة ، بشرط أن ترجع صفرًا عند النجاح
وغير الصفر عند الفشل كما هو المعيار. يجب أن تكون موجودة دائمًا للوظائف.
بالنسبة للوحدات النمطية ، قد يكون من المفيد تلخيص قيم الإرجاع من واجهة الوحدة النمطية
هنا ، أو قد يكون من المفيد مناقشة قيم الإرجاع بشكل منفصل في ملف
توثيق كل وظيفة أو طريقة توفرها الوحدة.
أخطاء
الاستثناءات ورموز إرجاع الخطأ وحالات الخروج وإعدادات الخطأ. عادة ما تستخدم ل
وثائق الوظيفة أو الوحدة ؛ تستخدم وثائق البرنامج التشخيص بدلاً من ذلك. ال
القاعدة العامة هي أن الأخطاء المطبوعة على "STDOUT" أو "STDERR" والمخصصة لها
يتم توثيق المستخدم النهائي في التشخيص أثناء تمرير الأخطاء الداخلية إلى الاستدعاء
تم توثيق البرنامج والمخصص للمبرمجين الآخرين في أخطاء. عند التوثيق
وظيفة تحدد errno ، يجب إعطاء قائمة كاملة بقيم الخطأ المحتملة
هنا.
DIAGNOSTICS
كل الرسائل الممكنة التي يستطيع البرنامج طباعتها وماذا تعني. قد ترغب في
اتبع نفس أسلوب التوثيق مثل وثائق Perl ؛ يرى perldiag(1) من أجل
مزيد من التفاصيل (وانظر إلى مصدر POD أيضًا).
إذا كان ذلك ممكنًا ، فيرجى تضمين تفاصيل حول ما يجب على المستخدم فعله لتصحيح الخطأ ؛
توثيق خطأ على أنه يشير إلى أن "المخزن المؤقت للإدخال صغير جدًا" دون إخبار
المستخدم كيفية زيادة حجم المخزن المؤقت للإدخال (أو على الأقل إخباره بذلك
غير ممكن) ليست مفيدة جدًا.
أمثلة
أعط بعض الأمثلة على استخدامات البرنامج أو الوظيفة. لا تبخل غالبًا ما يجد المستخدمون هذا
الجزء الأكثر فائدة من الوثائق. يتم إعطاء الأمثلة بشكل عام
فقرات حرفية.
لا تقدم مثالاً فقط دون شرح ما يفعله. مضيفا قصير
فقرة تقول ما سيفعله المثال يمكن أن تزيد من قيمة المثال
بشكل هائل.
البيئة
متغيرات البيئة التي يهتم بها البرنامج ، وعادة ما يتم تقديمها كقائمة تستخدم
"= over" و "= item" و "= back". على سبيل المثال:
= أكثر من 6
= عنصر المنزل
يستخدم لتحديد الدليل الرئيسي للمستخدم. F <.foorc> في هذا
تتم قراءة الدليل للحصول على تفاصيل التكوين ، إذا كان موجودًا.
= رجوع
نظرًا لأن متغيرات البيئة تكون عادةً بأحرف كبيرة ، فلا يوجد خاص إضافي
التنسيق مطلوب بشكل عام ؛ انهم صارخون بما فيه الكفاية كما هو.
FILES
جميع الملفات التي يستخدمها البرنامج أو الوظيفة ، وعادة ما يتم تقديمها على شكل قائمة ، وما هي هذه الملفات
يستخدمهم من أجل. يجب تضمين أسماء الملفات في F <>. من المهم بشكل خاص أن
ملفات المستندات التي من المحتمل أن يتم تعديلها.
تحفظات
الأشياء التي يجب الاهتمام بها بشكل خاص ، والتي تسمى أحيانًا التحذيرات.
بق
الأشياء التي تم كسرها أو لا تعمل بشكل صحيح تمامًا.
القيود
الأخطاء التي لا تخطط لإصلاحها. :-)
الملاحظات
تعليق متنوع.
AUTHOR
من كتبه (استخدم المؤلفين لعدة أشخاص). من الجيد تضمين ملف
عنوان البريد الإلكتروني الحالي (أو بعض عناوين البريد الإلكتروني التي يجب إرسال تقارير الأخطاء إليها) أو
بعض معلومات الاتصال الأخرى بحيث يكون لدى المستخدمين طريقة للاتصال بك. يتذكر
تميل وثائق هذا البرنامج إلى التجول في البرية لفترة أطول بكثير مما تتوقع و
اختر طريقة اتصال من المحتمل أن تستمر.
التاريخ
البرامج المشتقة من مصادر أخرى لها هذا أحيانًا. يحتفظ بعض الأشخاص بامتداد
سجل التعديل هنا ، ولكن هذا عادةً ما يستغرق وقتًا طويلاً ويتم الاحتفاظ به بشكل أفضل عادةً
ملف منفصل.
حقوق النشر والترخيص
لحقوق التأليف والنشر
حقوق الطبع والنشر YEAR (s) YOUR NAME (s)
(لا ، (C) ليست مطلوبة. لا ، "جميع الحقوق محفوظة" ليست مطلوبة.)
أسهل طريقة للترخيص هي استخدام نفس الترخيص مثل Perl نفسها:
هذه المكتبة برنامج إلكتروني مجاني؛ يمكنك إعادة توزيعه و / أو
تعديله تحت نفس شروط Perl نفسها.
هذا يجعل من السهل على الأشخاص استخدام الوحدة الخاصة بك مع Perl. لاحظ أن هذا الترخيص
المثال ليس تأييدًا أو شرطًا ، فأنت بالطبع حر في الاختيار
أي ترخيص.
أنظر أيضا
صفحات رجل أخرى للتحقق منها ، مثل رجل(1) رجل(7) ماكليتيس(8) ، أو catman(8).
عادةً ما تكون قائمة بسيطة من صفحات الدليل مفصولة بفواصل ، أو فقرة تعطي الامتداد
اسم العمل المرجعي. مراجع صفحة الرجل ، إذا كانوا يستخدمون المعيار
نموذج "الاسم (القسم)" ، لا يلزم تضمينه في L <> (على الرغم من أنه موصى به) ،
ولكن من المحتمل أن تكون الأشياء الأخرى في هذا القسم مناسبة.
إذا كانت الحزمة تحتوي على قائمة بريدية ، فقم بتضمين عنوان URL أو إرشادات الاشتراك هنا.
إذا كانت الحزمة تحتوي على موقع ويب ، فقم بتضمين عنوان URL هنا.
قد ترغب وثائق المكتبات أو الوحدات النمطية الموجهة للكائنات في استخدام CONSTRUCTORS و
أقسام الطرق ، أو أقسام طرق الفصل وأساليب الحال ، للحصول على تفاصيل
توثيق أجزاء المكتبة وحفظ قسم الوصف لملف
ملخص. قد ترغب الوحدات الكبيرة ذات الواجهة الوظيفية في استخدام FUNCTIONS لنفس الغرض
أسباب. يستخدم بعض الأشخاص "نظرة عامة" لتلخيص الوصف إذا كان طويلاً جدًا.
يختلف ترتيب الأقسام ، على الرغم من أن NAME يجب أن يكون دائمًا هو القسم الأول (يمكنك كسر بعض
بخلاف ذلك) ، ودائمًا ما يتم دائمًا استخدام الاسم والتوليف والوصف والخيارات
تحدث أولاً وبهذا الترتيب إن وجدت. بشكل عام ، راجع أيضًا ، المؤلف ، وما شابه
يجب ترك المواد للنهاية. تقوم بعض الأنظمة أيضًا بنقل التحذيرات والملاحظات لتدوم. ال
يجب أن يكون الطلب المذكور أعلاه معقولًا لمعظم الأغراض.
تستخدم بعض الأنظمة CONFORMING TO للإشارة إلى التوافق مع المعايير ذات الصلة و MT-LEVEL إلى
ملاحظة أمان للاستخدام في البرامج الملولبة أو معالجات الإشارات. هذه العناوين
مفيد بشكل أساسي عند توثيق أجزاء من مكتبة سي.
أخيرًا ، كملاحظة عامة ، حاول ألا تستخدم قدرًا كبيرًا من العلامات. كما هو موثق
هنا وفي Pod :: Man ، يمكنك ترك متغيرات Perl ، وأسماء الوظائف ، وصفحة الدليل بأمان
المراجع ، وما شابه ذلك غير مزخرف بالترميز وسيقوم المترجمون POD بإيجاده
لك. هذا يجعل من السهل تحرير الوثائق في وقت لاحق. لاحظ أن الكثير
المترجمون الحاليون سوف يفعلون الشيء الخطأ مع عناوين البريد الإلكتروني عندما يتم تغليفها في L <> ، لذلك
لا تفعل ذلك.
استخدم perlpodstyle عبر الإنترنت باستخدام خدمات onworks.net
