.\" Text automatically generated by txt2man
.TH txt2man 1 "14 July 2024" "txt2man-1.7.1" ""
.SH "نام (NAME)"
txt2man \- تبدیل متن ساده ASCII به قالب صفحه راهنما (man page)
.SH "خلاصه دستور (SYNOPSIS)"
.nf
.fam C
\fBtxt2man\fP [\fB-hpTX\fP] [\fB-t\fP \fImytitle\fP] [\fB-P\fP \fIpname\fP] [\fB-r\fP \fIrel\fP] [\fB-s\fP \fIsect\fP]
        [\fB-v\fP \fIvol\fP] [\fB-I\fP \fItxt\fP] [\fB-B\fP \fItxt\fP] [\fB-d\fP \fIdate\fP] [\fIifile\fP]
.fam T
.fi
.SH "توضیحات (DESCRIPTION)"
دستور
\fBtxt2man\fP
متن ورودی را به ماکروهای استاندارد
\fBman\fP(7)
در nroff/troff تبدیل می‌کند که برای قالب‌بندی صفحات راهنمای یونیکس استفاده می‌شوند. می‌توان صفحات مناسبی به‌ویژه برای دستورات (بخش ۱ یا ۸) یا مرجع توابع C (بخش‌های ۲ یا ۳) با توانایی شناسایی و قالب‌بندی نام دستورات و توابع، گزینه‌ها، انواع داده و آرگومان‌ها تولید کرد.
.PP
ابزار
\fBtxt2man\fP
همچنین قادر به شناسایی و قالب‌بندی بخش‌ها، پاراگراف‌ها، فهرست‌ها (استاندارد، شماره‌دار، توصیفی، تودرتو)، ارجاعات متقابل و بلوک‌های نمایش متن دست‌نخورده (کد) است.
.PP
اگر فایل ورودی
\fIifile\fP
مشخص نشود، ورودی استاندارد به کار می‌رود. نتیجه در خروجی استاندارد نمایش داده می‌شود.
.PP
نحوه شناسایی و پردازش الگوهای متنی به شرح زیر است:
.TP
.B
بخش‌ها (Sections)
این سرآیندها با خطی با حروف بزرگ انگلیسی تعریف می‌شوند که از ستون ۱ آغاز می‌شود. اگر یک یا چند فاصله در ابتدای خط وجود داشته باشد، به جای آن یک زیربخش ایجاد خواهد شد. به صورت اختیاری، قبل از نام بخش می‌تواند یک خط خالی قرار گیرد. این کار برای خوانایی و تجسم بهتر متن مبدأ مورد استفاده در تولید صفحه راهنما مفید است.
.TP
.B
پاراگراف‌ها (Paragraphs)
پاراگراف‌ها باید با یک خط خالی از هم جدا شده و چپ‌چین باشند. به عنوان روش جایگزین، می‌توان از دو فاصله خالی برای ایجاد همان نتیجه استفاده کرد. این گزینه خوانایی بهتری از متن مبدأ را جهت تولید صفحه راهنما فراهم می‌کند.
.TP
.B
فهرست برچسب‌دار (Tag list)
تعریف مورد با حداقل ۲ فاصله خالی از شرح آن جدا می‌شود، حتی قبل از رفتن به خط جدید اگر تعریف بیش از حد طولانی باشد. بخش تعریف به طور پیش‌فرض برجسته خواهد شد.
.TP
.B
فهرست نشانه‌دار (Bullet list)
موارد فهرست نشانه‌دار به گونه‌ای تعریف می‌شوند که کلمه اول آن‌ها "-" یا "*" یا "o" باشد.
.TP
.B
فهرست شماره‌دار (Enumerated list)
کلمه اول باید یک عدد و به دنبال آن یک نقطه باشد.
.TP
.B
بلوک‌های نمایش کد (Literal display blocks)
این نوع پاراگراف برای نمایش متن تغییرنیافته، برای نمونه کد مبدأ استفاده می‌شود. این بلوک باید با یک خط خالی جدا شده و با یک کلید TAB تورفتگی داشته باشد. این بخش عمدتاً برای قالب‌بندی کد مبدأ دست‌نخورده به کار می‌رود. این متن در صورت امکان (troff) با قلم عرض ثابت چاپ خواهد شد.
.TP
.B
ارجاعات متقابل (Cross references)
یک ارجاع متقابل (به صفحه راهنمای دیگر) با کلمه‌ای مشخص می‌شود که به دنبال آن یک عدد درون پرانتز آمده باشد.
.PP
بخش‌های ویژه:
.TP
.B
NAME
نام تابع یا دستور و توضیح کوتاه آن در این بخش قرار می‌گیرد.
.TP
.B
SYNOPSIS
این بخش تحت پردازش ویژه‌ای قرار می‌گیرد تا نام دستور، گزینه‌ها و آرگومان‌ها شناسایی شوند و ویژگی‌های متناظر آن‌ها در ادامه متن اعمال گردد. اگر تابعی شبیه به C تشخیص داده شود (کلمه‌ای که بلافاصله یک پرانتز باز به دنبال آن می‌آید)،
\fBtxt2man\fP
نام تابع را با قلم پررنگ (bold)، انواع داده را با قلم معمولی و متغیرها را با قلم کج (italic) چاپ می‌کند. کل بخش در صورت امکان (troff) با یک خانواده قلم با عرض ثابت (courier) چاپ خواهد شد.
.PP
گنجاندن مستندات درون کد مبدأ با استفاده از کامنت‌ها یا متغیرهای متنی ثابت، شیوه کاری مناسبی است.
\fBtxt2man\fP
اجازه می‌دهد تا این کار انجام شود و متن مبدأ سند، خوانا، قابل‌استفاده حتی بدون قالب‌بندی بیشتر (برای نمونه به عنوان راهنمای درون‌برنامه‌ای) و نوشتن آن ساده باقی بماند. نتیجه نهایی، سندی با کیفیت بالا و سازگار با استانداردها خواهد بود.
.SH "گزینه‌ها (OPTIONS)"
.TP
.B
\fB-h\fP
نمایش راهنما.
.TP
.B
\fB-d\fP \fIdate\fP
تنظیم \fIdate\fP در سرآیند. مقدار پیش‌فرض، \fIdate\fP جاری است.
.TP
.B
\fB-P\fP \fIpname\fP
تنظیم \fIpname\fP به عنوان نام پروژه در سرآیند. مقدار پیش‌فرض خروجی uname \fB-s\fP است.
.TP
.B
\fB-p\fP
شناسایی و تشخیص خودکار عنوان، نام بخش و نام جلد.
.TP
.B
\fB-t\fP \fImytitle\fP
تنظیم \fImytitle\fP به عنوان عنوان صفحه راهنمای تولیدشده.
.TP
.B
\fB-r\fP \fIrel\fP
تنظیم \fIrel\fP به عنوان نام و شماره انتشار پروژه.
.TP
.B
\fB-s\fP \fIsect\fP
تنظیم \fIsect\fP به عنوان شماره بخش در سرآیند، معمولاً مقداری از ۱ تا ۸.
.TP
.B
\fB-v\fP \fIvol\fP
تنظیم \fIvol\fP به عنوان نام جلد، مانند "Unix user 's manual".
.TP
.B
\fB-I\fP \fItxt\fP
کج (italic) کردن \fItxt\fP در خروجی. این گزینه می‌تواند بیش از یک بار مشخص شود.
.TP
.B
\fB-B\fP \fItxt\fP
برجسته (bold) کردن \fItxt\fP در خروجی. این گزینه می‌تواند بیش از یک بار مشخص شود.
.TP
.B
\fB-T\fP
پیش‌نمایش متنی نتیجه با استفاده از PAGER، معمولاً
\fBmore\fP(1).
.TP
.B
\fB-X\fP
پیش‌نمایش گرافیکی نتیجه در سامانه پنجره X11 با استفاده از
\fBgxditview\fP(1).
.SH "محیط (ENVIRONMENT)"
.TP
.B
PAGER
نام دستور صفحه‌بندی، معمولاً
\fBmore\fP(1)
یا
\fBless\fP(1).
در صورت عدم تنظیم، به
\fBmore\fP(1)
بازمی‌گردد.
.TP
.B
SOURCE_DATE_EPOCH
برچسب زمانی یونیکس (Unix timestamp) که به جای \fIdate\fP جاری برای درج در سرآیند استفاده می‌شود.
.SH "مثال‌ها (EXAMPLES)"
برای قالب‌بندی خود این متن، این دستور را امتحان کنید:
.PP
.nf
.fam C
    $ txt2man -h 2>&1 | txt2man -T
.fam T
.fi
.PP
دستور زیر یک صفحه راهنمای بخش ۱ برای برنامه foo-1.1.0 از فایل foo.txt که به عنوان متن مبدأ صفحه راهنما استفاده شده تولید می‌کند:
.PP
.nf
.fam C
    $ txt2man -d "15 May 2016" -t foo -r foo-1.1.0 -s 1 -v "show stars on screen" foo.txt > foo.1
.fam T
.fi
.SH "نکات (HINTS)"
جهت دستیابی به قالب‌بندی کلی مناسب در سند خروجی، تورفتگی پاراگراف‌ها را به درستی حفظ کنید. در صورت مشاهده بخش‌های پررنگ ناخواسته، فاصله‌های خالی چندگانه میان کلمات را بررسی کنید که برای تشخیص فهرست برچسب‌دار (اصطلاح و به دنبال آن توضیحات) استفاده می‌شوند. همچنین نام گزینه‌های خط فرمان یا پارامترهای توابع را با دقت برگزینید، زیرا هر بار که در سند دیده شوند برجسته خواهند شد.
.SH "همچنین ببینید (SEE ALSO)"
\fBman\fP(1), \fBmandoc\fP(7), \fBrman\fP(1), \fBgroff\fP(1), \fBmore\fP(1), \fBgxditview\fP(1), \fBtroff\fP(1).
.SH "اشکالات (BUGS)"
.IP \(bu 3
تشخیص خودکار (گزینه
.BR \-p )
تنها زمانی کار می‌کند که ورودی یک فایل معمولی باشد (یعنی نه stdin).
.SH "نویسنده (AUTHOR)"
Marc Vertes <mvertes@free.fr>