نام (NAME)

txt2man - تبدیل متن ساده ASCII به قالب صفحه راهنما (man page)

خلاصه دستور (SYNOPSIS)

txt2man [-hpTX] [-t mytitle] [-P pname] [-r rel] [-s sect]
        [-v vol] [-I txt] [-B txt] [-d date] [ifile]

توضیحات (DESCRIPTION)

دستور txt2man متن ورودی را به ماکروهای استاندارد man(7) در nroff/troff تبدیل می‌کند که برای قالب‌بندی صفحات راهنمای یونیکس استفاده می‌شوند. می‌توان صفحات مناسبی به‌ویژه برای دستورات (بخش ۱ یا ۸) یا مرجع توابع C (بخش‌های ۲ یا ۳) با توانایی شناسایی و قالب‌بندی نام دستورات و توابع، گزینه‌ها، انواع داده و آرگومان‌ها تولید کرد.

ابزار txt2man همچنین قادر به شناسایی و قالب‌بندی بخش‌ها، پاراگراف‌ها، فهرست‌ها (استاندارد، شماره‌دار، توصیفی، تودرتو)، ارجاعات متقابل و بلوک‌های نمایش متن دست‌نخورده (کد) است.

اگر فایل ورودی ifile مشخص نشود، ورودی استاندارد به کار می‌رود. نتیجه در خروجی استاندارد نمایش داده می‌شود.

نحوه شناسایی و پردازش الگوهای متنی به شرح زیر است:

بخش‌ها (Sections): این سرآیندها با خطی با حروف بزرگ انگلیسی تعریف می‌شوند که از ستون ۱ آغاز می‌شود. اگر یک یا چند فاصله در ابتدای خط وجود داشته باشد، به جای آن یک زیربخش ایجاد خواهد شد. به صورت اختیاری، قبل از نام بخش می‌تواند یک خط خالی قرار گیرد. این کار برای خوانایی و تجسم بهتر متن مبدأ مورد استفاده در تولید صفحه راهنما مفید است.
پاراگراف‌ها (Paragraphs): پاراگراف‌ها باید با یک خط خالی از هم جدا شده و چپ‌چین باشند. به عنوان روش جایگزین، می‌توان از دو فاصله خالی برای ایجاد همان نتیجه استفاده کرد. این گزینه خوانایی بهتری از متن مبدأ را جهت تولید صفحه راهنما فراهم می‌کند.
فهرست برچسب‌دار (Tag list): تعریف مورد با حداقل ۲ فاصله خالی از شرح آن جدا می‌شود، حتی قبل از رفتن به خط جدید اگر تعریف بیش از حد طولانی باشد. بخش تعریف به طور پیش‌فرض برجسته خواهد شد.
فهرست نشانه‌دار (Bullet list): موارد فهرست نشانه‌دار به گونه‌ای تعریف می‌شوند که کلمه اول آن‌ها "-" یا "*" یا "o" باشد.
فهرست شماره‌دار (Enumerated list): کلمه اول باید یک عدد و به دنبال آن یک نقطه باشد.
بلوک‌های نمایش کد (Literal display blocks): این نوع پاراگراف برای نمایش متن تغییرنیافته، برای نمونه کد مبدأ استفاده می‌شود. این بلوک باید با یک خط خالی جدا شده و با یک کلید TAB تورفتگی داشته باشد. این بخش عمدتاً برای قالب‌بندی کد مبدأ دست‌نخورده به کار می‌رود. این متن در صورت امکان (troff) با قلم عرض ثابت چاپ خواهد شد.
ارجاعات متقابل (Cross references): یک ارجاع متقابل (به صفحه راهنمای دیگر) با کلمه‌ای مشخص می‌شود که به دنبال آن یک عدد درون پرانتز آمده باشد.

بخش‌های ویژه:

NAME: نام تابع یا دستور و توضیح کوتاه آن در این بخش قرار می‌گیرد.
SYNOPSIS: این بخش تحت پردازش ویژه‌ای قرار می‌گیرد تا نام دستور، گزینه‌ها و آرگومان‌ها شناسایی شوند و ویژگی‌های متناظر آن‌ها در ادامه متن اعمال گردد. اگر تابعی شبیه به C تشخیص داده شود (کلمه‌ای که بلافاصله یک پرانتز باز به دنبال آن می‌آید)، txt2man نام تابع را با قلم پررنگ (bold)، انواع داده را با قلم معمولی و متغیرها را با قلم کج (italic) چاپ می‌کند. کل بخش در صورت امکان (troff) با یک خانواده قلم با عرض ثابت (courier) چاپ خواهد شد.

گنجاندن مستندات درون کد مبدأ با استفاده از کامنت‌ها یا متغیرهای متنی ثابت، شیوه کاری مناسبی است. txt2man اجازه می‌دهد تا این کار انجام شود و متن مبدأ سند، خوانا، قابل‌استفاده حتی بدون قالب‌بندی بیشتر (برای نمونه به عنوان راهنمای درون‌برنامه‌ای) و نوشتن آن ساده باقی بماند. نتیجه نهایی، سندی با کیفیت بالا و سازگار با استانداردها خواهد بود.

گزینه‌ها (OPTIONS)

-h: نمایش راهنما.
-d date: تنظیم date در سرآیند. مقدار پیش‌فرض، date جاری است.
-P pname: تنظیم pname به عنوان نام پروژه در سرآیند. مقدار پیش‌فرض خروجی uname -s است.
-p: شناسایی و تشخیص خودکار عنوان، نام بخش و نام جلد.
-t mytitle: تنظیم mytitle به عنوان عنوان صفحه راهنمای تولیدشده.
-r rel: تنظیم rel به عنوان نام و شماره انتشار پروژه.
-s sect: تنظیم sect به عنوان شماره بخش در سرآیند، معمولاً مقداری از ۱ تا ۸.
-v vol: تنظیم vol به عنوان نام جلد، مانند "Unix user 's manual".
-I txt: کج (italic) کردن txt در خروجی. این گزینه می‌تواند بیش از یک بار مشخص شود.
-B txt: برجسته (bold) کردن txt در خروجی. این گزینه می‌تواند بیش از یک بار مشخص شود.
-T: پیش‌نمایش متنی نتیجه با استفاده از PAGER، معمولاً more(1).
-X: پیش‌نمایش گرافیکی نتیجه در سامانه پنجره X11 با استفاده از gxditview(1).

محیط (ENVIRONMENT)

PAGER: نام دستور صفحه‌بندی، معمولاً more(1) یا less(1). در صورت عدم تنظیم، به more(1) بازمی‌گردد.
SOURCE_DATE_EPOCH: برچسب زمانی یونیکس (Unix timestamp) که به جای date جاری برای درج در سرآیند استفاده می‌شود.

مثال‌ها (EXAMPLES)

برای قالب‌بندی خود این متن، این دستور را امتحان کنید:

$ txt2man -h 2>&1 | txt2man -T

دستور زیر یک صفحه راهنمای بخش ۱ برای برنامه foo-1.1.0 از فایل foo.txt که به عنوان متن مبدأ صفحه راهنما استفاده شده تولید می‌کند:

$ txt2man -d "15 May 2016" -t foo -r foo-1.1.0 -s 1 -v "show stars on screen" foo.txt > foo.1

نکات (HINTS)

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

همچنین ببینید (SEE ALSO)

man(1), mandoc(7), rman(1), groff(1), more(1), gxditview(1), troff(1).

اشکالات (BUGS)

•: تشخیص خودکار (گزینه -p) تنها زمانی کار می‌کند که ورودی یک فایل معمولی باشد (یعنی نه stdin).

نویسنده (AUTHOR)

Marc Vertes <mvertes@free.fr>