وثائق عادية قديمة

لغة التوثيق القديمة البسيطة ( pod ) هي لغة ترميز خفيفة الوزن تستخدم لتوثيق لغة برمجة بيرل والوحدات والبرامج.

صُممت لغة Pod لتكون لغة بسيطة وواضحة، ذات بنية نحوية كافية لتكون مفيدة. وهي تتجنب عمداً آليات الخطوط والصور والألوان والجداول. ومن أهدافها:

• سهل التحليل
• يسهل تحويلها إلى تنسيقات أخرى، مثل XML أو TeX أو Markdown
• سهولة دمج نموذج التعليمات البرمجية
• يسهل قراءته بدون استخدام مُنسِّق pod (أي في شكل شفرة المصدر الخاصة به)
• سهل الكتابة

تم استخدام نسخة موسعة من pod تدعم الجداول والحواشي السفلية تسمى PseudoPOD من قبل O'Reilly & Associates لإنتاج العديد من كتب Perl، وأبرزها كتاب Programming Perl للاري وول وتوم كريستيانسن وجون أوروانت.

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

تُعد لغة Pod هي اللغة المستخدمة في معظم الوثائق في عالم Perl. ويشمل ذلك لغة Perl نفسها، وجميع الوحدات النمطية المنشورة علنًا تقريبًا ، والعديد من البرامج النصية ، ومعظم وثائق التصميم، والعديد من المقالات على موقع Perl.com ومواقع الويب الأخرى ذات الصلة بلغة Perl، والآلة الافتراضية Parrot .

نادراً ما تُقرأ ملفات Pod بصيغتها الأصلية، على الرغم من أنها مصممة لتكون قابلة للقراءة دون الحاجة إلى أداة تنسيق. بدلاً من ذلك، تُقرأ باستخدامأداة perldoc، أو تحويلها إلى صفحات دليل Unix أو صفحات HTML القياسية للويب.

من الممكن أيضًا استخدام pod في سياقات أخرى غير لغة Perl. على سبيل المثال، لإضافة توثيق بسيط إلى نصوص bash البرمجية ، والتي يمكن تحويلها بسهولة إلى صفحات دليل (man pages). ^{[ 1 ]} تعتمد هذه الاستخدامات على حيل خاصة بكل لغة لإخفاء جزء (أجزاء) pod، مثل (في bash) إضافة سطر برمجي قبل قسم POD، :<<=cutوالذي يعمل عن طريق استدعاء أمر bash الذي لا يقوم بأي عملية: ، مع اعتبار كتلة pod بأكملها كمستند مضمن كمدخل له.

عادةً ما تحمل ملفات pod النقية الامتداد .pod .pod، ولكن يُستخدم pod بشكل أساسي مباشرةً في كود Perl، الذي يستخدم عادةً الامتدادين .pl.pod و .pod . (صُمم محلل مُفسِّر.pm Perl لتجاهل pod في كود Perl). في ملفات الكود المصدري، تُوضع الوثائق عمومًا بعد علامة pod (مما يُساعد أيضًا في تمييز بناء الجملة في بعض المحررات لعرضها كتعليقات).__END__

يمكن تحويل Pod بسهولة إلى تنسيقات أخرى، على سبيل المثال بعض تنسيقات Wiki المتنوعة مثل: WikiWikiWeb أو Kwiki أو TWiki أو UseModWiki أو TiddlyWiki أو Textile أو MediaWiki أو MoinMoin أو Confluence باستخدام Pod::Simple::Wiki.

هذه الوثيقة صحيحة نحوياً، وتحاول اتباع الاصطلاحات الرئيسية في تسمية الأقسام أيضاً. ^{[ 2 ]}

=الاسم الأول My::Module- نموذج نموذجي =head1 ملخص useMy::Module;my$object=My::Module->new();print$object->as_string; =head1 الوصف هذه الوحدة غير موجودة في الواقع، تم صنعه لغرض وحيد هو توضيح كيفية عمل نظام الطباعة عند الطلب. =head2 طرق = أكثر من 12 =العنصر ج<جديد> يُعيد كائنًا جديدًا .My::Module =item C<as_string> يُعيد تمثيلًا نصيًا لـ الكائن. هذا مخصص بشكل أساسي لتصحيح الأخطاء الأغراض. =رجوع =head1 رخصة تم إصدار هذا العمل بموجب الترخيص الفني . انظر L<perlartistic>. =المؤلف_الرئيسي Juerd - L< http://juerd.nl/ > =head1 انظر أيضًا L<perlpod>, L<perlpodspec> =ut

تُكتب ملفات Pod باستخدام ترميز متوافق مع ASCII ، مثل Latin-1 أو UTF-8 . يفترض محلل Pod دائمًا أن الملف الذي يحلله لا يبدأ بـ pod؛ ويتجاهل جميع الأسطر حتى يرى توجيه pod. يجب أن يكون هذا التوجيه في بداية السطر وأن تبدأ جميع الأسطر بعلامة يساوي (=). ثم يفترض محلل Pod أن جميع الأسطر التالية هي pod، حتى يصادف سطرًا يحتوي على التوجيه "=cut". يتم تجاهل أي محتوى يلي ذلك حتى يصادف المحلل توجيه pod آخر. وبالتالي، يمكن دمج ملفات Pod مع شفرة المصدر القابلة للتنفيذ إذا كان محلل اللغة يعرف كيفية التعرف على ملفات Pod وتجاهلها.

يُقسّم محتوى Pod إلى فقرات بواسطة أسطر فارغة. تُعتبر الفقرات التي تبدأ بمسافات بيضاء - علامات جدولة أو مسافات عادية - فقرات نصية، وتُترك بدون تنسيق؛ وتُستخدم هذه الفقرات لعرض نماذج التعليمات البرمجية، ورسومات ASCII ، وما إلى ذلك. أما الفقرات التي تبدأ بعلامة يساوي (=) فهي فقرات أوامر؛ حيث تُعامل سلسلة الأحرف والأرقام التي تلي علامة يساوي مباشرةً كأمر برمجي، ويتم تنسيق باقي الفقرة وفقًا لهذا الأمر. تؤثر بعض الأوامر البرمجية أيضًا على الفقرات التالية. إذا بدأت الفقرة بشيء آخر غير علامة يساوي أو مسافة بيضاء، تُعتبر فقرة عادية.

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

• حرف كبير واحد، متبوعًا بعلامة أصغر من (<)، ثم المحتوى المراد تنسيقه، ثم علامة أكبر من (>)، على سبيل المثال B<bolded text>، أو
• حرف كبير واحد، علامتا أصغر من أو أكثر (<<)، مسافة، المحتوى المراد تنسيقه، مسافة أخرى، ونفس عدد علامات أكبر من المستخدمة سابقًا، على سبيل المثال: B<< bolded text >>. يُستخدم هذا الشكل غالبًا لمقاطع التعليمات البرمجية التي تحتوي على علامة أكبر من، والتي ستنهي رمز التنسيق في حال عدم وجودها.

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

• مقارنة بين مولدات الوثائق

• وال، لاري؛ كريستيانسن، توم؛ وأوروانت، جون (2000). برمجة بيرل (الطبعة الثالثة). سيباستوبول: أورايلي وشركاؤه. ISBN 0-596-00027-8.
• الفصل الخامس عشر، "العمل مع بود"، في كتاب فوي، برايان د. (2007). إتقان بيرل . سيباستوبول: أورايلي ميديا . رقم ISBN 0-596-52724-1.
• القسم 5.2، "تضمين التوثيق في نصوص شل البرمجية"، في: ألبينغ، كارل؛ فوسن، جيه بي؛ وكاميرون نيوهام. (2007). كتاب طبخ باش: حلول وأمثلة لمستخدمي باش ؛ أورايلي وشركاؤه. ISBN 0-596-52678-4.

• perlpod (وثائق حول pod للأشخاص الذين يكتبون المستندات باستخدامها)
• perlpodspec (وثائق حول pod للأشخاص الذين يكتبون محللات لها)
• صفحات دليل بيرل بصيغة pod الخام
• (PseudoPOD)
• يحتوي الدليل على العديد من الوحدات النمطية ذات تنسيق pod المضمن
• تقوم وحدة Getopt::Euclid بتحليل المدخلات إلى برنامج Perl النصي تلقائيًا بناءً على علامات pod
• يقوم برنامج Pod::Simple::Wiki بتحويل ملفات pod إلى تنسيقات ويكي متنوعة.
• تقوم الدالة Pod::Markdown بتحويل pod إلى Markdown