| src2man(1) | src2man(1) |
نام (NAME)
src2man - استخراج صفحات راهنما از فایل‌های منبع
خلاصه دستور (SYNOPSIS)
src2man [-n][-d date][-v volume][-r release] [srcfile ...]
توضیحات (DESCRIPTION)
دستور src2man فایل منبع srcfile را بررسی می‌کند. در حال حاضر تنها فایل‌های منبع C پشتیبانی می‌شوند. بلوک‌های توضیحات که با "/** num" شروع می‌شوند (که در آن num شمارهٔ بخش است)، با استفاده از txt2man(1) به یک فایل man تبدیل می‌شوند.
نخستین خط از بلوک توضیح باید شامل نام صفحهٔ راهنما (معمولاً نام تابع)، و به دنبال آن یک "-" و شرحی کوتاه باشد. خطوط بعدی محتوای بخش "DESCRIPTION" خواهند بود، مگر اینکه با حروف بزرگ نوشته شده باشند که در این صورت بخش جدیدی را تعریف می‌کنند.
اگر خطِ بعد از یک بلوک توضیح خالی باشد، هیچ بخش "SYNOPSIS" تولید نخواهد شد. در غیر این صورت، src2man در خطوط بعدی منبع به دنبال اعلان اولیهٔ تابع (prototype) یا تعریف نوع (مانند struct، union، typedef و ...) متناظر با نام صفحهٔ راهنما می‌گردد و آن را در بخش "SYNOPSIS" می‌گنجاند. این کار از تکرار تعریف نوع یا اعلان تابع در بلوک توضیح جلوگیری می‌کند.
بهترین مکان برای مستندسازی کد در همان فایل منبع است که بدنه در آن پیاده‌سازی شده است، نه فایل سرآیند (header) که فقط حاوی اعلان اولیه است. src2man به‌طور خودکار وجود اعلان اولیه را در فایل سرآیند مربوطه جستجو می‌کند و در صورت یافتن، یک عبارت "#include" را در خلاصه دستور (synopsis) درج می‌نماید.
گزینه‌ها (OPTIONS)
- -d date
- تنظیم تاریخ صفحات راهنما. پیش‌فرض تاریخ جاری است.
- -n
- هیچ صفحهٔ راهنمایی ایجاد نمی‌شود. نام صفحات راهنمایی که قرار بود ایجاد شوند چاپ می‌شود.
- -v volume
- مشخص کردن نام جلد (volume) برای چاپ در وسط سربرگ صفحات man تولیدشده.
- -r release
- مشخص کردن نام پروژه و شمارهٔ انتشار (release) برای صفحهٔ man تولیدشده.
محیط (ENVIRONMENT)
- SOURCE_DATE_EPOCH
- برچسب زمانی یونیکس (Unix timestamp) که به جای تاریخ جاری برای تاریخ در سربرگ استفاده می‌شود.
مثال‌ها (EXAMPLES)
مثال زیر کد C و توضیحات را برای تولید صفحهٔ راهنمای foobar.3 نمایش می‌دهد:
/** 3
- foobar - a sample dummy function
- This line is now the first of the description section.
- Note that function parameters parm1 and parm2 are highlighted
- in the generated man page.
*/
int foobar(char *parm1, int parm2)
{
...
return 0;
}
همچنین ببینید (SEE ALSO)
نویسندگان (AUTHORS)
Marc Vertes <mvertes@free.fr>
| 14 July 2024 | txt2man-1.7.1 |