perlpodstyle - آنلاین در ابر

برنامه:

نام

perlpodstyle - راهنمای سبک Perl POD

شرح

اینها دستورالعمل های کلی برای نحوه نوشتن اسناد POD برای اسکریپت های Perl و
ماژول ها، بر اساس دستورالعمل های کلی برای نوشتن صفحات خوب یونیکس. همه اینها
دستورالعمل ها البته اختیاری هستند، اما پیروی از آنها اسناد شما را بیشتر می کند
مطابق با سایر اسناد موجود در سیستم

نام برنامه‌ای که مستند می‌شود معمولاً به صورت پررنگ نوشته می‌شود (با استفاده از B<>)
هر جا رخ دهد، مانند همه گزینه های برنامه. آرگومان ها باید به صورت مورب نوشته شوند
(من<>). نام توابع به طور سنتی به صورت مورب نوشته می شود. اگر تابعی را به عنوان بنویسید
عملکرد(), Pod::مرد این کار را برای شما انجام خواهد داد. کد یا دستورات تحت اللفظی باید باشد
در C<>. ارجاع به سایر صفحات man باید به شکل "manpage(section)" یا باشد
"L "، و Pod::Man به طور خودکار آنها را به طور مناسب قالب بندی می کند
فرم دوم، با L<>، برای درخواست از فرمت‌کننده POD استفاده می‌شود که پیوندی به صفحه مرد ایجاد کند
در صورت امکان. به عنوان یک استثنا، معمولاً هنگام مراجعه به ماژول، بخش را حذف می کند
مستندات، زیرا مشخص نیست که مستندات ماژول در کدام بخش قرار خواهد گرفت. استفاده کنید
"L در عوض برای مراجع ماژول.

ارجاع به سایر برنامه ها یا توابع معمولاً به صورت ارجاعات صفحه شخصی است
به طوری که ابزارهای ارجاع متقابل می توانند لینک ها و موارد مشابه را در اختیار کاربر قرار دهند. این است
با این حال، ممکن است بیش از حد در این مورد زیاده روی کنید، بنابراین مراقب باشید که اسناد خود را نیز درهم نریزید
نشانه گذاری زیاد ارجاع به برنامه های دیگری که به عنوان مرجع صفحه مرد ارائه نمی شوند
باید در B<> محصور شود.

سرصفحه های اصلی باید با استفاده از دستورالعمل "=head1" تنظیم شوند و از نظر تاریخی هستند
با فرمت نسبتاً شگفت انگیز ALL UPPER CASE نوشته شده است. این اجباری نیست، اما این است
اکیداً توصیه می‌شود تا بخش‌ها نام‌گذاری ثابتی در نرم‌افزارهای مختلف داشته باشند
بسته ها هدرهای جزئی ممکن است با استفاده از "=head2" درج شوند و معمولاً در حروف مختلط هستند.

بخش های استاندارد یک صفحه دستی عبارتند از:

نام
بخش اجباری؛ باید لیستی از برنامه ها یا توابع جدا شده با کاما باشد
مستند شده توسط این صفحه POD، مانند:

foo, bar - برنامه هایی برای انجام کاری

نمایه سازهای صفحه دستی اغلب در مورد قالب این بخش بسیار حساس هستند، بنابراین
جز این خط چیزی در آن قرار ندهید. هر برنامه یا عملکرد مستند شده توسط
این صفحه POD باید با کاما و فاصله از هم جدا شود. برای یک ماژول پرل،
فقط نام ماژول را بدهید. یک خط تیره و فقط یک خط تیره باید از هم جدا شوند
لیست برنامه ها یا توابع از توضیحات. از هیچ نشانه گذاری مانند C<> استفاده نکنید
یا B<> در هر جایی از این خط. توابع نباید با "()" یا صلاحیت شوند
پسندیدن. توضیحات باید به طور ایده آل در یک خط قرار گیرد، حتی اگر یک برنامه مرد باشد
خط تیره را با چند زبانه جایگزین می کند.

خلاصه
خلاصه استفاده از برنامه ها و توابع. این بخش برای
بخش 3 صفحه برای مستندات ماژول پرل، معمولاً داشتن آن راحت است
محتویات این بخش یک بلوک کلمه به کلمه است که چند نمونه (کوتاه) معمولی را نشان می دهد
روش های استفاده از ماژول

شرح
شرح و بحث گسترده در مورد برنامه یا توابع، یا بدنه برنامه
اسنادی برای صفحات man که چیز دیگری را مستند می کنند. اگر به خصوص طولانی است، آن را
یک ایده خوب برای تقسیم این بخش به دستورالعمل های "=head2" مانند:

=head2 استفاده عادی

=head2 ویژگی های پیشرفته

=head2 نوشتن فایل های پیکربندی

یا هر آنچه که برای اسناد شما مناسب است.

برای یک ماژول، این به طور کلی جایی است که مستندات رابط های ارائه شده توسط
ماژول معمولاً به شکل یک لیست با یک "= آیتم" برای هر رابط می رود.
بسته به تعداد اینترفیس ها، ممکن است بخواهید آن اسناد را در آن قرار دهید
به جای آن بخش‌های METHODS، FUNCTIONS، CLASS METHODS یا INSTANCE METHODS را جدا کنید و
بخش DESCRIPTION را برای یک نمای کلی ذخیره کنید.

OPTIONS
شرح مفصل هر یک از گزینه های خط فرمان گرفته شده توسط برنامه. این
برای استفاده از تجزیه کننده هایی مانند Pod::Usage باید از توضیحات جدا باشد. این
معمولاً به عنوان یک لیست ارائه می شود و هر گزینه به عنوان یک "= آیتم" جداگانه ارائه می شود. خاص
رشته گزینه باید در B<> محصور شود. هر مقداری که گزینه می گیرد باید باشد
محصور در I<>. به عنوان مثال، بخش مربوط به گزینه --بخش=manext خواهد بود
معرفی شده با:

=item B<--section>=I

گزینه های مترادف (مانند هر دو شکل کوتاه و بلند) با یک کاما و یک از هم جدا می شوند
فاصله در همان خط "=item"، یا به صورت اختیاری به عنوان مورد خود با a فهرست شده است
اشاره به نام متعارف به عنوان مثال، از آنجایی که --بخش را نیز می توان به صورت نوشتاری کرد
-s، موارد فوق عبارتند از:

=item B<-s> I ، B<--section>=I

ابتدا نوشتن گزینه کوتاه توصیه می شود زیرا خواندن آن آسان تر است. دراز
گزینه به اندازه ای طولانی است که به هر حال چشم را به سمت خود جلب کند و گزینه کوتاه در غیر این صورت می تواند
در نویز بصری گم شوید

ارزش بازگشتی
در صورت موفقیت آمیز بودن، برنامه یا تابع چه چیزی را برمی گرداند. این بخش را می توان حذف کرد
برنامه‌هایی که کدهای خروج دقیق آن‌ها مهم نیست، به شرطی که در صورت موفقیت، 0 را برگردانند
و غیر صفر در خرابی به عنوان استاندارد است. همیشه باید برای توابع موجود باشد.
برای ماژول ها، خلاصه کردن مقادیر بازگشتی از رابط ماژول ممکن است مفید باشد
در اینجا، یا ممکن است مفیدتر باشد که مقادیر بازگشتی را به طور جداگانه در مورد بحث کنیم
مستندات هر تابع یا روشی که ماژول ارائه می دهد.

خطاها
استثناها، کدهای بازگشت خطا، وضعیت خروج و تنظیمات خطا. به طور معمول برای استفاده می شود
مستندات عملکرد یا ماژول؛ اسناد برنامه به جای آن از DIAGNOSTICS استفاده می کند. را
قانون کلی این است که خطاها به "STDOUT" یا "STDERR" چاپ شده و برای آنها در نظر گرفته شده است
کاربر نهایی در DIAGNOSTICS ثبت می شود در حالی که خطاها به داخل تماس منتقل می شوند
برنامه و در نظر گرفته شده برای برنامه نویسان دیگر در ERRORS مستند شده است. هنگام مستندسازی
تابعی که errno را تنظیم می کند، یک لیست کامل از مقادیر احتمالی errno باید داده شود
اینجا.

عیب یابی
تمام پیام‌های ممکن که برنامه می‌تواند چاپ کند و معنای آنها چیست. ممکن است بخواهید
از همان سبک مستندسازی مستندات پرل پیروی کنید. دیدن پرلدیاگ(1) برای
جزئیات بیشتر (و همچنین به منبع POD نگاه کنید).

در صورت امکان، لطفاً جزئیاتی در مورد کارهایی که کاربر برای تصحیح خطا باید انجام دهد را وارد کنید.
مستند کردن یک خطا به عنوان نشان دادن "بافر ورودی خیلی کوچک است" بدون اینکه به آن بگویید
کاربر چگونه اندازه بافر ورودی را افزایش دهد (یا حداقل به آنها بگوید که آن را دارد
امکان پذیر نیست) خیلی مفید نیستند.

مثال ها
چند نمونه از کاربردهای برنامه یا تابع را ذکر کنید. کم نگذارید؛ کاربران اغلب این را پیدا می کنند
مفیدترین بخش مستندات نمونه ها به طور کلی به عنوان آورده شده است
پاراگراف های کلمه به کلمه

فقط یک مثال را بدون توضیح اینکه چه کاری انجام می دهد، ارائه نکنید. اضافه کردن کوتاه
پاراگراف با بیان اینکه مثال چه کاری انجام می دهد می تواند ارزش مثال را افزایش دهد
به شدت

محیط زیست
متغیرهای محیطی که برنامه به آنها اهمیت می دهد، معمولاً به صورت فهرستی با استفاده از آنها ارائه می شود
"=over"، "=item"، و "=back". مثلا:

= بیش از 6

=مورد HOME

برای تعیین فهرست اصلی کاربر استفاده می شود. F<.forc> در این
دایرکتوری برای جزئیات پیکربندی خوانده می شود، در صورت وجود.

=بازگشت

از آنجایی که متغیرهای محیطی معمولاً با حروف بزرگ هستند، هیچ چیز خاصی وجود ندارد
قالب بندی به طور کلی مورد نیاز است. آنها به اندازه کافی خیره کننده هستند.

فایل ها
همه فایل‌هایی که توسط برنامه یا تابع استفاده می‌شوند، معمولاً به‌صورت فهرستی ارائه می‌شوند و چه مواردی در آن وجود دارد
از آنها استفاده می کند. نام فایل ها باید در F<> قرار گیرد. به خصوص مهم است
فایل های سندی که به طور بالقوه تغییر خواهند کرد.

هشدارها
چیزهایی که باید از آنها مراقبت ویژه کرد، که گاهی اوقات هشدار نامیده می شود.

اشکالات
چیزهایی که خراب هستند یا کاملاً درست کار نمی کنند.

محدودیت های
اشکالاتی که قصد رفع آنها را ندارید. :-)

NOTES
تفسیر متفرقه

نویسنده
چه کسی آن را نوشته است (از AUTHORS برای چند نفر استفاده کنید). این ایده خوبی است که شما را نیز شامل شود
آدرس ایمیل فعلی (یا برخی از آدرس های ایمیلی که گزارش های اشکال باید به آن ارسال شود) یا
برخی از اطلاعات تماس دیگر تا کاربران راهی برای تماس با شما داشته باشند. یاد آوردن
که اسناد برنامه تمایل دارد برای مدت طولانی تر از آنچه شما انتظار دارید در طبیعت پرسه بزند
روش تماسی را انتخاب کنید که احتمالاً ماندگار است.

تاریخچه
برنامه های مشتق شده از منابع دیگر گاهی اوقات این را دارند. برخی افراد یک را نگه می دارند
گزارش اصلاحات در اینجا، اما معمولا طولانی می شود و معمولاً در آن بهتر نگهداری می شود
یک فایل جداگانه

حق چاپ و مجوز
برای کپی رایت

حق نشر سال(های) نام(های) شما

(خیر، (C) مورد نیاز نیست. خیر، "همه حقوق محفوظ است" مورد نیاز نیست.)

برای صدور مجوز ساده ترین راه استفاده از همان مجوز پرل است:

این کتابخانه نرم افزار رایگان است. شما می توانید آن را دوباره توزیع کنید و/یا
آن را با همان شرایطی که خود پرل دارد تغییر دهید.

این کار استفاده از ماژول شما با Perl را برای افراد آسان می کند. توجه داشته باشید که این مجوز
مثال نه تاییدیه و نه الزامی است، البته شما در انتخاب آزاد هستید
هر گونه مجوز

همچنین ببینید
سایر صفحات مرد برای بررسی، مانند مرد(1) مرد(7) makewhatis(8) ، یا گربه(8).
معمولاً یک لیست ساده از صفحات مرد که با کاما از هم جدا شده اند، یا یک پاراگراف که این را نشان می دهد
نام یک اثر مرجع ارجاعات صفحه Man، اگر از استاندارد استفاده کنند
فرم "name(section)"، لازم نیست در L<> محصور شود (اگرچه توصیه می شود)،
اما موارد دیگر در این بخش احتمالاً باید در صورت لزوم باشد.

اگر بسته دارای یک لیست پستی است، یک URL یا دستورالعمل های اشتراک را در اینجا قرار دهید.

اگر بسته دارای یک وب سایت است، یک URL در اینجا قرار دهید.

مستندات کتابخانه ها یا ماژول های شی گرا ممکن است بخواهند از CONSTRUCTORS و
بخش‌های METHODS، یا بخش‌های CLASS METHODS و INSTANCE METHODS، برای جزئیات بیشتر
مستندسازی بخش‌های کتابخانه و ذخیره بخش DESCRIPTION برای یک
بررسی اجمالی. ممکن است ماژول‌های بزرگ با رابط عملکردی بخواهند از FUNCTIONS برای موارد مشابه استفاده کنند
دلایل برخی از افراد از OVERVIEW برای خلاصه کردن توضیحات در صورت طولانی بودن آن استفاده می کنند.

ترتیب بخش ها متفاوت است، اگرچه NAME باید همیشه اولین بخش باشد (شما برخی از آنها را شکسته اید
در غیر این صورت، سیستم های صفحه مرد)، و NAME، SYNOPSIS، DESCRIPTION، و OPTIONS معمولا همیشه
ابتدا و در صورت وجود به آن ترتیب رخ می دهد. به طور کلی، ALSO، AUTHOR و موارد مشابه را ببینید
مواد باید برای آخر باقی بماند. برخی از سیستم ها هشدارها و یادداشت ها را نیز برای ماندگاری جابجا می کنند. در
دستور داده شده در بالا باید برای اکثر اهداف معقول باشد.

برخی از سیستم ها از CONFORMING TO برای یادداشت انطباق با استانداردهای مربوطه و MT-LEVEL به
ایمنی را برای استفاده در برنامه های رشته ای یا کنترل کننده های سیگنال یادداشت کنید. این سرفصل ها هستند
در درجه اول هنگام مستندسازی بخش هایی از کتابخانه C مفید است.

در نهایت، به عنوان یک نکته کلی، سعی کنید از مقدار بیش از حد نشانه گذاری استفاده نکنید. همانطور که مستند شده است
در اینجا و در Pod::Man، می توانید با خیال راحت متغیرهای Perl، نام توابع، صفحه man را ترک کنید
ارجاعات، و موارد مشابه بدون علامت گذاری و مترجمان POD آن را کشف خواهند کرد
برای شما. این کار باعث می شود که بعداً اسناد را ویرایش کنید. توجه داشته باشید که بسیاری از
مترجم‌های موجود وقتی آدرس‌های ایمیل را در L<> پیچیده می‌کنند، اشتباه می‌کنند، بنابراین
این کار را نکن

با استفاده از خدمات onworks.net به صورت آنلاین از perlpodstyle استفاده کنید