نام (NAME)

troff - حروفچین و قالببندیکننده اسناد متنی GNU roff

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

troff [-abcCEiRSUz] [-d ctext] [-d string=text] [-f font-family] [-F font-directory] [-I inclusion-directory] [-m macro-package] [-M macro-directory] [-n page-number] [-o page-list] [-r cnumeric-expression] [-r register=numeric-expression] [-T output-device] [-w warning-category] [-W warning-category] [file ...]

troff --help

troff -v

troff --version

توضیحات (DESCRIPTION)

برنامه GNU troff ورودی زبان groff(7) را به زبان توصیف صفحه مستقل از دستگاه که جزئیات آن در groff_out(5) شرح داده شده است، تبدیل می‌کند؛ بنابراین troff قلب سامانه قالب‌بندی اسناد GNU roff است. اگر هیچ عملوند فایلی وجود نداشته باشد، یا اگر فایل برابر با “-” باشد، troff جریان ورودی استاندارد را می‌خواند.

برنامه GNU troff از نظر عملکردی با حروف‌چین AT&T troff سازگار است و از قابلیت‌های گسترش‌یافته فراوانی بهره می‌برد. بسیاری از افراد ترجیح می‌دهند از دستور groff(1) استفاده کنند؛ یک پیشخوان که پیش‌پردازنده‌ها و گرداننده‌های خروجی را به ترتیب مناسب و با گزینه‌های درست اجرا می‌کند.

گزینه‌ها (OPTIONS)

گزینه‌های -h و --help پیام راهنمای استفاده را نمایش می‌دهند، در حالی که -v و --version اطلاعات نگارش را نشان می‌دهند؛ همگی پس از آن خارج می‌شوند.

-a: یک تقریب متنی ساده از خروجی حروف‌چینی‌شده تولید می‌کند. ثبات فقط‌خواندنی .A بر روی 1 تنظیم می‌شود. این گزینه گونه‌ای پیش‌نمایش کلی از خروجی قالب‌بندی‌شده ارائه می‌دهد.

•: شکست‌های صفحه با عبارتی در میان قلاب‌های شکسته مشخص می‌شوند؛ برای مثال، “<beginning of page>”.
•: خطوط دقیقاً در همان‌جایی که در خروجی قالب‌بندی‌شده شکسته می‌شدند، شکسته می‌شوند.
•: حرکت عمودی، به‌جز آن‌چه از یک شکست خط ناشی می‌شود، نمایش داده نمی‌شود.
•: حرکت افقی با هر اندازه‌ای به صورت یک فاصله نمایش داده می‌شود. حرکت‌های افقی مجاور با یکدیگر ترکیب نمی‌شوند. فاصله تکمیلی بین جملات (که توسط آرگومان دوم درخواست .ss پیکربندی می‌شود) نمایش داده نمی‌شود.
•: یک نویسه ویژه به صورت شناسه آن در میان قلاب‌های شکسته نمایش داده می‌شود؛ برای مثال، یک خط تیره به شکل “<hy>” ظاهر می‌شود.

: توضیحات بالا نباید به عنوان یک مشخصات رسمی در نظر گرفته شود؛ جزئیات خروجی -a ممکن است تغییر یابند.

-b: به ازای هر پیام تشخیصی، یک گزارش ردگیری (backtrace) از وضعیت تجزیه‌کننده ورودی troff را در جریان خطای استاندارد می‌نویسد. شماره خطوط ارائه‌شده در گزارش ردگیری ممکن است همیشه درست نباشند، زیرا تصور troff از شماره خطوط می‌تواند به دلیل درخواست‌هایی که به ماکروها محتوا اضافه می‌کنند، دچار اشتباه شود.
-c: غیرفعال کردن خروجی چندرنگ و سلب توانایی درخواست “color” برای فعال‌سازی آن.
-C: فعال کردن حالت سازگاری با AT&T troff؛ متضمن گزینه -c است. رجوع کنید به groff_diff(7).
-d ctext
-d string=text: تعریف رشته roff با نام c یا string به عنوان text. شناسه c باید یک شناسه تک‌نویسه‌ای باشد؛ string می‌تواند دارای طول دلخواه باشد. چنین تخصیص‌هایی پیش از بارگذاری هر فایل ماکرو، از جمله فایل راه‌اندازی، انجام می‌شوند. به دلیل محدودیت‌های تابع getopt_long(3)، شناسه c نمی‌تواند علامت مساوی باشد، و string نیز نمی‌تواند حاوی علامت مساوی باشد، اگرچه مساوی یک نویسه معتبر در شناسه‌های roff است.
-E: جلوگیری از نمایش پیام‌های خطای troff؛ متضمن گزینه -Ww است. این گزینه پیام‌های ارسال‌شده به جریان خطای استاندارد توسط اسناد یا بسته‌های ماکرو با استفاده از tm یا درخواست‌های مرتبط را نادیده نمی‌گیرد (سرکوب نمی‌کند).
-f fam: استفاده از fam به عنوان خانواده قلم پیش‌فرض.
-F dir: جستجو در دایرکتوری dir برای یافتن دایرکتوری فایل‌های توصیف قلم و دستگاه خروجی انتخاب‌شده. برای آگاهی از مکان‌های جستجوی پیش‌فرض و اولویت آن‌ها، به توضیحات GROFF_FONT_PATH در بخش “محیط” در ادامه مراجعه کنید.
-i: خواندن جریان ورودی استاندارد پس از آن‌که تمامی فایل‌های ورودی نام‌برده پردازش شدند.
-I dir: جستجو در دایرکتوری dir برای یافتن فایل‌ها (فایل‌هایی که در خط فرمان نام برده شده‌اند؛ در درخواست‌های psbb، so و soquiet؛ و در توالی‌های گریز گسترش دستگاه “\X'ps: import'”، “\X'ps: file'” و “\X'pdf: pdfpic'”). گزینه -I می‌تواند بیش از یک بار مشخص شود؛ هر dir به ترتیب داده‌شده جستجو می‌شود. برای جستجوی دایرکتوری جاری کاری پیش از سایرین، “-I .” را در مکان مورد نظر بیفزایید؛ در غیر این صورت در انتهای جستجو بررسی می‌شود. گزینه -I مشابه گزینه “include” در کامپایلرهای سی یونیکس عمل کرده و نام آن نیز از همان گرفته شده است.
-m mac: جستجو برای بسته ماکروی mac.tmac و خواندن آن پیش از هرگونه ورودی. اگر یافت نشد، tmac.mac امتحان می‌شود. برای آگاهی از مکان‌های پیش‌فرض جستجو و ترتیب آن‌ها، به توضیحات GROFF_TMAC_PATH در بخش “محیط” در ادامه مراجعه کنید.
-M dir: جستجو در دایرکتوری dir برای فایل‌های ماکرو. برای آگاهی از مکان‌های پیش‌فرض جستجو و ترتیب آن‌ها، به توضیحات GROFF_TMAC_PATH در بخش “محیط” در ادامه مراجعه کنید.
-n num: آغاز شماره‌گذاری صفحات از num. مقدار پیش‌فرض برابر 1 است.
-o list: تنها خروجی دادن صفحات موجود در list، که فهرستی جداشده با کاما از بازه‌های فراگیر صفحات است؛ n به معنای صفحه n است، m-n به معنای تمامی صفحات بین m و n، -n به معنای تمامی صفحات تا n، و n- به معنای تمامی صفحات از n به بعد است. troff پس از قالب‌بندی آخرین صفحه فهرست‌شده در list پردازش را متوقف کرده و خارج می‌شود.
-r cnumeric-expression
-r register=numeric-expression: تعریف ثبات roff با نام c یا register برابر با numeric-expression. شناسه c باید یک شناسه تک‌نویسه‌ای باشد؛ register می‌تواند طول دلخواه داشته باشد. چنین تخصیص‌هایی پیش از بارگذاری هر فایل ماکرو، از جمله فایل راه‌اندازی، رخ می‌دهند. به دلیل محدودیت‌های تابع getopt_long(3)، شناسه c نمی‌تواند علامت مساوی باشد، و register نیز نمی‌تواند حاوی علامت مساوی باشد، اگرچه مساوی یک نویسه معتبر در شناسه‌های roff است.
-R: جلوگیری از بارگذاری troffrc و troffrc-end؛ این گزینه می‌تواند برای عیب‌یابی سودمند باشد.
-S: فعال کردن حالت امن‌تر و نادیده گرفتن هر گزینه بعدی -U.
-T dev: آماده‌سازی خروجی برای دستگاه dev. پیش‌فرض ps است؛ رجوع کنید به groff(1).
-U: کارکرد در حالت ناامن، که درخواست‌های cf، open، opena، pi، pso و sy را فعال می‌کند؛ این درخواست‌ها به طور پیش‌فرض غیرفعال هستند زیرا به یک سند ورودی غیرقابل اعتماد اجازه می‌دهند دستورات دلخواه را اجرا کند، محتوای دلخواه را در خروجی troff قرار دهد، یا در فایل‌هایی با نام دلخواه بنویسد. (با این حال، برنامه GNU troff نویسه خط جدید (line feed) را در نام فایل‌هایی که به عنوان آرگومان به درخواست‌ها داده می‌شوند نمی‌پذیرد.) این گزینه همچنین دایرکتوری جاری را به مسیر جستجوی بسته ماکرو می‌افزاید؛ گزینه‌های -m و -M در بالا را ببینید.
-w cat
-W cat: به ترتیب، فعال‌سازی و غیرفعال‌سازی هشدارها در رده cat. به بخش “هشدارها” در ادامه مراجعه کنید.
-z: جلوگیری از تولید خروجی قالب‌بندی‌شده.

هشدارها (WARNINGS)

برنامه GNU troff پیام‌های تشخیصی هشدار خود را به رده‌های نام‌گذاری‌شده و شماره‌دار تقسیم می‌کند. گزینه‌های -w و -W از نام‌های مرتبط استفاده می‌کنند. یک توان از ۲ شناسه هر رده را مشخص می‌سازد؛ درخواست warn و ثبات .warn به ترتیب مجموع کدهای رده‌های فعال‌شده را تنظیم و گزارش می‌کنند. هشدارهای هر رده در شرایط زیر تولید می‌شوند.

Bit	Code	Category	Bit	Code	Category
0	1	char	10	1024	reg
1	2	unused	11	2048	tab
2	4	break	12	4096	unused
3	8	delim	13	8192	missing
4	16	unused	14	16384	input
5	32	scale	15	32768	escape
6	64	range	16	65536	space
7	128	syntax	17	131072	font
8	256	di	18	262144	ig
9	512	mac	19	524288	color
			20	1048576	file

break	4	یک خط خروجی پرشده (filled) نتوانست به گونه‌ای شکسته شود که طول آن کمتر یا مساوی با طول خط خروجی “ \n[.l] ” باشد، یا به گونه‌ای تراز شود که طول آن دقیقاً برابر با آن گردد. . برنامه GNU troff میزان سرریز (overset) یا کمبود (underset) را بر حسب واحد مقیاسی که توسط درخواست warnscale پیکربندی شده است در حالت troff و بر حسب en (‘ n ’؛ سلول‌های نویسه) در حالت nroff گزارش می‌دهد. . این رده به طور پیش‌فرض فعال است.
char	1	هیچ نویسه تعریف‌شده توسط کاربر با نام یا نمایه درخواستی وجود ندارد و هیچ قلم نصب‌شده‌ای گلیفی برای آن تعریف نکرده است، یا این‌که ورودی نتوانست برای خروجی مستقل از دستگاه کدگذاری شود. . این رده به طور پیش‌فرض فعال است.
color	524288	یک نام رنگ تعریف‌نشده انتخاب شده است، تلاشی برای تعریف یک رنگ با استفاده از یک فضای رنگ ناشناخته انجام شده است، یک مقدار کانال نامعتبر در یک تعریف رنگ مشاهده شده است، یا تلاشی برای تعریف مجدد یک رنگ پیش‌فرض صورت گرفته است.
delim	8	نویسه جداکننده انتخاب‌شده مبهم بوده است زیرا هنگام شروع یک عبارت عددی نیز معنادار است، یا جداکننده پایانی در یک توالی گریز جا افتاده یا ناهماهنگ بوده است. . . انتشارهای آینده groff ممکن است جداکننده‌های مبهم را رد کنند. . در حالت سازگاری، جداکننده‌های مبهم بدون هشدار پذیرفته می‌شوند.
di	256	یک درخواست di ، da ، box یا boxa بدون آرگومان فراخوانی شده است در حالی که هیچ انحراف (diversion) جاری وجود نداشته است.
escape	32768	یک توالی گریز پشتیبانی‌نشده مشاهده شده است.
file	1048576	تلاشی برای خواندن فایلی که وجود ندارد صورت گرفته است، یا یک جریان در هنگام خروج قالب‌بند باز باقی مانده است. . این رده به طور پیش‌فرض فعال است.
font	131072	یک قلم ناموجود انتخاب شده است. . این رده به طور پیش‌فرض فعال است.
ig	262144	یک توالی گریز نامعتبر در ورودی نادیده‌گرفته‌شده با استفاده از درخواست ig رخ داده است. . این رده هشدار وضعیتی را تشخیص می‌دهد که در ورودی عادی یک خطا محسوب می‌شود.
input	16384	یک نویسه نامعتبر در جریان ورودی رخ داده است.
mac	512	یک رشته، ماکرو، یا انحراف (diversion) تعریف‌نشده استفاده شده است. . هنگامی که به چنین شیئی ارجاع داده می‌شود، یک نمونه خالی از آن نام به طور خودکار ایجاد می‌گردد. . بنابراین، مگر این‌که بعداً حذف شود، troff برای هر کدام حداکثر یک هشدار صادر می‌کند. . . برنامه troff همچنین از این رده برای هشدار در مورد تلاش جهت جابجایی یک ماکروی تله (trap macro) کارگذاشته‌نشده استفاده می‌کند. . در چنین مواردی، به ماکروی کارگذاشته‌نشده ارجاعی داده نمی‌شود، بنابراین در صورت عدم وجود، ایجاد نخواهد شد.
missing	8192	یک درخواست با غیبت آرگومان اجباری فراخوانی شده است.
range	64	یک عبارت عددی خارج از محدوده مجاز برای زمینه کاربرد خود بوده است.
reg	1024	یک ثبات تعریف‌نشده استفاده شده است. . هنگامی که به یک ثبات تعریف‌نشده ارجاع داده می‌شود، قالب‌بند به طور خودکار آن را با مقدار 0 تعریف می‌کند. . بنابراین، مگر این‌که بعداً حذف شود، برنامه GNU troff برای هر کدام حداکثر یک هشدار صادر می‌کند.
scale	32	یک واحد مقیاس نامناسب برای زمینه کاربرد آن در یک عبارت عددی استفاده شده است.
space	65536	یک فاصله بین یک درخواست یا ماکرو و آرگومان آن جا افتاده است. . این هشدار هنگامی تولید می‌شود که یک نام تعریف‌نشده طولانی‌تر از دو نویسه مشاهده شود و دو نویسه نخست آن نام تشکیل‌دهنده یک نام تعریف‌شده باشند. . هیچ درخواستی اجرا نمی‌شود، هیچ ماکرویی فراخوانی نمی‌گردد، و ماکروی خالی نیز تعریف نمی‌شود. . این رده به طور پیش‌فرض فعال است. . این مورد هرگز در حالت سازگاری رخ نمی‌دهد.
syntax	128	یک حالت خط‌فاصله‌گذاری (hyphenation) خودمتناقض یا پرچم‌های نویسه متعارض درخواست شده است؛ یک عبارت عددی خالی یا ناقص مشاهده شده است؛ یک عملوند برای عملگر عددی جا افتاده است؛ تلاشی برای قالب‌بندی نویسه‌ها یا فاصله‌ها در یک خط ورودی پس از توالی گریز ادامه‌دهنده خط خروجی صورت گرفته است؛ یک توالی گریز شناخته‌شده اما نامناسب یا کد نویسه غیرقابل‌چاپ در یک دستور گسترش دستگاه استفاده شده است؛ تلاشی برای تعریف یک رده نویسه بازگشتی، خالی، یا بی‌معنی انجام شده است؛ یا یک توالی گریز افزوده groff یا عملگر عبارات شرطی در هنگام فعال بودن حالت سازگاری به کار رفته است.
tab	2048	یک نویسه تب (tab) در یک توالی گریز پارامتریک، در یک آرگومان ماکروی درون گیومه قرار نگرفته، یا در جایی که یک درخواست انتظار یک آرگومان عبارت عددی را داشته، ظاهر شده است.

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

all: تمامی رده‌های هشدار به جز di، mac و reg. این گزینه اختصاری برای تولید تمامی هشدارهایی در نظر گرفته شده است که همراه با بسته‌های ماکرو و اسناد نوشته‌شده برای AT&T troff و نسل‌های بعدی آن سودمند هستند، که تشخیص‌های کم‌وسواس‌تری نسبت به GNU troffدارند.
w: تمامی رده‌های هشدار. به نویسندگان اسناد و بسته‌های ماکرو که groff را هدف قرار می‌دهند توصیه می‌شود از این تنظیم استفاده کنند.

وضعیت خروج (EXIT STATUS)

برنامه troff در صورت اجرای موفق با وضعیت 0، چنانچه نتواند آرگومان‌های خط فرمان خود را تفسیر کند با وضعیت 2، و در صورتی که در حین اجرا با خطایی مهلک مواجه شود یا ورودی دستور توقف به آن دهد با وضعیت 1 خارج می‌شود.

محیط (ENVIRONMENT)

متغیرهای GROFF_FONT_PATH و GROFF_TMAC_PATH هر کدام یک مسیر جستجو از دایرکتوری‌ها را می‌پذیرند؛ بدین معنا که، فهرستی از نام‌های دایرکتوری هستند که با نویسه جداکننده مؤلفه‌های مسیر در سیستم جدا شده‌اند. در سیستم‌های یونیکس، این نویسه دو‌نقطه (:) است؛ در سیستم‌های ویندوز، نقطه-ویرگول (;) است.

GROFF_FONT_PATH: فهرستی از دایرکتوری‌ها که در آن‌ها دایرکتوری فایل‌های توصیف قلم و دستگاه خروجی انتخاب‌شده جستجو می‌شود. برنامه troff دایرکتوری‌های ارائه‌شده به عنوان آرگومان برای هر گزینه -F مشخص‌شده را پیش از این‌ها پیمایش می‌کند، و سپس یک دایرکتوری ویژه سایت (/usr/share/groff/site-font)، یک مکان استاندارد (/usr/share/groff/1.24.1/font) و یک دایرکتوری سازگاری (/usr/lib/font) را پس از آن‌ها بررسی می‌نماید.
GROFF_TMAC_PATH: فهرستی از دایرکتوری‌ها برای جستجوی فایل‌های ماکرو. برنامه troff دایرکتوری‌های ارائه‌شده به عنوان آرگومان برای هر گزینه -M مشخص‌شده را پیش از این‌ها پیمایش می‌کند، سپس دایرکتوری جاری (تنها در صورت فعال بودن حالت ناامن)، دایرکتوری خانگی کاربر، یک دایرکتوری ویژه سایت (/usr/share/groff/site-tmac) و یک مکان استاندارد (/usr/share/groff/1.24.1/tmac) را پس از آن‌ها جستجو می‌کند.
GROFF_TYPESETTER: تنظیم دستگاه خروجی پیش‌فرض. اگر خالی باشد یا تنظیم نشده باشد، از ps استفاده می‌شود. گزینه -T بر GROFF_TYPESETTER ارجحیت دارد.
SOURCE_DATE_EPOCH: برچسب زمانی (بیان‌شده به صورت ثانیه‌های سپری‌شده از مبدأ زمانی یونیکس) برای استفاده به عنوان برچسب زمان ایجاد خروجی به جای زمان جاری. این زمان در هنگام راه‌اندازی قالب‌بند با استفاده از gmtime(3) و asctime(3) به قالبی خوانا برای انسان تبدیل شده و در ثبات‌های قابل‌استفاده توسط اسناد و بسته‌های ماکرو ذخیره می‌شود.
TZ: منطقه زمانی مورد استفاده هنگام تبدیل زمان جاری به قالبی خوانا برای انسان؛ رجوع کنید به tzset(3). اگر از SOURCE_DATE_EPOCH استفاده شود، همواره با استفاده از UTC به قالبی خوانا برای انسان تبدیل می‌گردد.

فایل‌ها (FILES)

/usr/share/groff/1.24.1/tmac/troffrc: یک فایل ماکروی مقداردهی اولیه است که پیش از هر بسته ماکروی مشخص‌شده با گزینه‌های -m بارگذاری می‌شود.
/usr/share/groff/1.24.1/tmac/troffrc-end: یک فایل ماکروی مقداردهی اولیه است که پس از تمامی بسته‌های ماکروی مشخص‌شده با گزینه‌های -m بارگذاری می‌شود.
/usr/share/groff/1.24.1/tmac/name.tmac: فایل‌های ماکروی عرضه‌شده به همراه groff هستند.
/usr/share/groff/1.24.1/font/devname/DESC: دستگاه خروجی name را توصیف می‌کند.
/usr/share/groff/1.24.1/font/devname/F: قلم F از دستگاه name را توصیف می‌کند.

به دلایل امنیتی، فایل‌های troffrc و troffrc-end به طور پیش‌فرض نه در دایرکتوری جاری و نه در دایرکتوری خانگی جستجو نمی‌شوند، حتی اگر گزینه -U مشخص شده باشد. در صورت لزوم، از گزینه خط فرمان -M یا متغیر محیطی GROFF_TMAC_PATH برای افزودن این دایرکتوری‌ها به مسیر جستجو استفاده کنید.

نویسندگان (AUTHORS)

نگارش گنوی troff در ابتدا توسط James Clark نوشته شد؛ او همچنین نگارش اصلی این سند را نوشت، که سپس توسط Werner Lemberg، Bernd Warken و G. Branden Robinson به‌روزرسانی شد.

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

کتاب Groff: The GNU Implementation of troff، اثر Trent A. Fisher و Werner Lemberg، راهنمای اصلی groff است. می‌توانید آن را به صورت تعاملی با دستور “info groff” مرور کنید.

groff(1): نمایی کلی از سامانه GNU roff ارائه داده و فایل اجرایی پیشخوان آن را شرح می‌دهد.
groff(7): جزئیات زبان groff را شامل مرجعی کوتاه اما کامل از تمامی درخواست‌ها، ثبات‌ها و توالی‌های گریز از پیش تعریف‌شده تشریح می‌کند.
groff_char(7): نحو توالی‌های گریز نویسه‌های ویژه groff را توضیح داده و تمامی نویسه‌های ویژه از پیش تعریف‌شده در این زبان را فهرست می‌نماید.
groff_diff(7): تفاوت‌های میان troff مستقل از دستگاه AT&T و groff را برمی‌شمارد.
groff_font(5): قالب فایل‌های توصیف دستگاه و قلم groff را پوشش می‌دهد.
groff_out(5): قالب خروجی troff را شرح می‌دهد.
groff_tmac(5): شامل اطلاعاتی درباره فایل‌های ماکروی عرضه‌شده همراه با groff است.
roff(7): اطلاعات زمینه‌ای درباره سامانه‌های roff به طور کلی ارائه می‌دهد، شامل اشاره‌گرهایی به مستندات مرتبط بیشتر.