GROFF_TMAC(5) فایلهای پیکربندی GROFF_TMAC(5)

groff_tmac - فایلهای ماکرو در سامانه حروفچینی GNU roff

بستههای ماکرو در groff مجموعهای از تعاریف و دستورالعملها را برای قالببندی اسناد (مانند man، mdoc، me، ms، mm) فراهم میآورند. تعاریف ماکروها، رشته‌ها و ثبات‌ها برای استفاده در یک سند roff(7) می‌توانند در فایل‌های ماکرو گردآوری شوند؛ فایل‌های ورودی roff که طراحی شده‌اند تا خودشان هیچ خروجی مستقیمی تولید نکنند، بلکه در عوض آماده‌سازی سایر اسناد roff را آسان سازند. از نظر نحوی هیچ تفاوتی میان یک فایل ماکرو و هر سند دیگر roff وجود ندارد؛ تنها هدف و کاربرد آن است که آن را متمایز می‌سازد. هنگامی که یک فایل ماکرو در مکانی استاندارد نصب شود، بر اساس قراردادی مشخص نام‌گذاری گردد و برای استفاده همگانی مناسب باشد، به آن یک بسته ماکرو گفته می‌شود. بسته‌های ماکرو را می‌توان با ارسال گزینه -m به troff(1) یا یک پیش‌رابط groff بارگذاری کرد.

هر بسته ماکرو، تعاریف ماکرو، رشته و ثبات‌های خود را در یک یا چند فایل tmac ذخیره می‌کند. این نام در فرهنگ اولیه یونیکس به عنوان مخفف “ماکروهای troff” پدید آمد.

یک فایل ماکرو باید نامی به شکل name.tmac (یا tmac.name) داشته باشد و در یک “دایرکتوری tmac” قرار گیرد تا با استفاده از گزینه -mname قابل بارگذاری باشد. بخش “Environment” از troff(1) این دایرکتوری‌ها را فهرست کرده است. همچنین، یک سند groff که به یک فایل ماکرو نیاز دارد می‌تواند آن را با درخواست mso (“macro source”) بارگذاری کند.

همانند هر سند دیگر roff، یک فایل ماکرو می‌تواند از درخواست “so” (“source”) برای بارگذاری فایل‌های بیشتر نسبت به مکان خودش استفاده نماید.

فایل‌های ماکرو بر اساس برجسته‌ترین کاربردشان نام‌گذاری می‌شوند، اما یک فایل ماکرو نیازی به تعریف حتمی هیچ ماکرویی ندارد. می‌تواند صرفاً به تعریف ثبات‌ها و رشته‌ها یا فراخوانی سایر درخواست‌های groff محدود شود. حتی می‌تواند کاملاً خالی باشد.

بسته‌های ماکرو در دو دسته عرضه می‌شوند؛ آن‌هایی که مسئولیت صفحه‌آرایی و سایر عملکردهای حیاتی را بر عهده می‌گیرند (“اصلی” یا “خدمات کامل”) و آن‌هایی که چنین نقشی ندارند (“مکمل” یا “کمکی”). سامانه GNU roff بیشتر بسته‌های ماکروی اصلی موجود در سامانه‌های یونیکس AT&T و BSD، یک بسته خدمات کامل اضافی و بسیاری از بسته‌های مکمل را ارائه می‌دهد. چندین بسته ماکروی خدمات کامل نمی‌توانند به‌طور هم‌زمان توسط یک سند استفاده شوند. بسته‌های کمکی عموماً می‌توانند آزادانه با یکدیگر ترکیب شوند، هرچند باید به نحوه استفاده آن‌ها از فضاهای نام شناسه در زبان groff (به‌ویژه ثبات‌ها، ماکروها، رشته‌ها و انحراف‌ها) توجه شود. مدیریت فضای نام چالشی بزرگ در troff متعلق به AT&T بود؛ پشتیبانی groff از شناسه‌های با طول دلخواه، بهانه‌ای برای تداخل نام‌ها باقی نمی‌گذارد، مگر در مواردی که برای سازگاری با نیازهای اسناد تاریخی باشد.

بسته an برای نگارش صفحات راهنما در قالبی که از نسخه ۷ یونیکس (۱۹۷۹) سرچشمه گرفته است به کار می‌رود. این بسته رابط کاربری کوچکی از ماکروها دارد و کاربرد گسترده‌ای یافته است؛ نگاه کنید به groff_man(7).
بسته doc برای نگارش صفحات راهنما در قالبی که از 4.3BSD-Reno (۱۹۹۰) سرچشمه گرفته است به کار می‌رود. امکانات بسیار بیشتری نسبت به an فراهم می‌کند، اما همچنین حجیم‌تر و پیچیده‌تر است و به اندازه آن به طور گسترده به کار گرفته نشده است؛ نگاه کنید به groff_mdoc(7).

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

این فایل ماکرو، که مختص groff است، تشخیص می‌دهد که آیا یک سند از قالب man یا mdoc استفاده می‌کند و بسته ماکروی متناظر را بارگذاری می‌کند. چندین صفحه راهنما، در هر یک از این دو قالب، می‌توانند پردازش شوند؛ andoc هر بسته ماکرو را در صورت نیاز مجدداً بارگذاری می‌کند.

بسته‌های این بخش مجموعه‌ای کامل از ماکروها را برای نگارش اسناد از هر نوعی، تا کل یک کتاب، ارائه می‌دهند. عملکرد آن‌ها مشابه است؛ انتخاب این‌که از کدام‌یک استفاده شود وابسته به سلیقه است.

بسته ماکروی کلاسیک me؛ نگاه کنید به groff_me(7).
بسته ماکروی نیمه‌کلاسیک mm؛ نگاه کنید به groff_mm(7).
بسته ماکروی mom، که تنها در groff موجود است. از آن‌جا که این بسته بر پایه بسته‌های دیگر ساخته نشده است، به عنوان یک بسته ماکروی مدرن، آزاد و بسیار زیبا طراحی شده است. نگاه کنید به groff_mom(7).
بسته ماکروی کلاسیک ms؛ نگاه کنید به groff_ms(7).

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

رشته‌های بومی‌سازی‌شده مورد استفاده بسته‌های ماکروی گوناگون را پس از آماده‌سازی شکل محلی آن‌ها توسط یک فایل ماکروی بومی‌سازی، بارگذاری می‌کند.

سامانه groff فایل‌های بومی‌سازی زیر را فراهم می‌آورد:

چکی؛ بسته‌های man، me، mm، mom و ms را بومی‌سازی می‌کند. کدبندی ورودی را با بارگذاری latin2.tmac روی Latin-2 تنظیم می‌نماید.
آلمانی؛ بسته‌های man، me، mm، mom و ms را بومی‌سازی می‌کند. کدبندی ورودی را با بارگذاری latin1.tmac روی Latin-1 تنظیم می‌نماید.
فایل de.tmac الگوهای خط‌فاصله‌گذاری را برای رسم‌الخط سنتی انتخاب می‌کند و den.tmac همین کار را برای رسم‌الخط جدید (“Rechtschreibreform”) انجام می‌دهد.
انگلیسی.
فرانسوی؛ بسته‌های man، me، mm، mom و ms را بومی‌سازی می‌کند. کدبندی ورودی را با بارگذاری latin9.tmac روی Latin-9 تنظیم می‌نماید.
ایتالیایی؛ بسته‌های man، me، mm، mom و ms را بومی‌سازی می‌کند.
ژاپنی.
سوئدی؛ بسته‌های man، me، mm، mom و ms را بومی‌سازی می‌کند. کدبندی ورودی را با بارگذاری latin1.tmac روی Latin-1 تنظیم می‌نماید. بخشی از بومی‌سازی بسته mm به‌طور جداگانه مدیریت می‌شود؛ نگاه کنید به groff_mmse(7) (فقط در محلی‌های سوئدی).
چینی.

کدبندی‌های ورودی گوناگون ISO 8859 هستند که توسط groff پشتیبانی می‌شوند. در سامانه‌هایی که از کدبندی‌های نویسه‌ای ISO استفاده می‌کنند، groff به‌طور خودکار هنگام راه‌اندازی latin1.tmac را بارگذاری می‌کند. سندی که از Latin-2، Latin-5 یا Latin-9 استفاده می‌کند می‌تواند یکی از این کدبندی‌های جایگزین را مشخص نماید.
پشتیبانی از سامانه‌های مبتنی بر EBCDIC را فراهم می‌آورد. در آن بسترها، groff به‌طور خودکار در زمان راه‌اندازی cp1047.tmac را بارگذاری می‌کند.

از آن‌جا که کدهای نویسه‌ای ورودی متفاوتی ورودی معتبر GNU troff را در سامانه‌های ISO و EBCDIC تشکیل می‌دهند، فایل‌های ماکروی latin نمی‌توانند در سامانه‌های EBCDIC استفاده شوند و cp1047 نیز در سامانه‌های ISO قابل استفاده نیست.

بسته‌های ماکرو در این بخش برای استفاده مستقل در نظر گرفته نشده‌اند، اما می‌توانند قابلیت‌هایی را به هر بسته ماکروی دیگر یا به اسناد ساده (یا “خام”) groff اضافه کنند.

62bit
ماکروهایی را برای جمع، ضرب و تقسیم اعداد صحیح ۶۲ بیتی فراهم می‌آورد (برای مثال امکان ضرب ایمن اعداد صحیح علامت‌دار ۳۱ بیتی را میسر می‌سازد).
امکان تولید جدول‌ها را با استفاده از نحو مشابه با مدل جدول‌های HTML فراهم می‌آورد. این بسته ماکروی جدول Heidelberger یک پیش‌پردازنده نیست، که این ویژگی در صورتی که محتوای خانه‌های جدول توسط فراخوانی ماکروها یا درون‌یابی رشته‌ها تعیین شوند می‌تواند مفید باشد. مقایسه کنید با tbl(1). این بسته تنها با دستگاه‌های خروجی ps و pdf کار می‌کند. نگاه کنید به groff_hdtbl(7).
امکان تنظیم قالب کاغذ را در خط فرمان با ارائه گزینه “-d paper=format” به troff فراهم می‌کند. مقادیر ممکن برای format شامل قالب‌های ISO و DIN به صورت “A0–A6”، “B0–B6”، “C0–C6” و “D0–D6”؛ قالب‌های ایالات متحده شامل “letter”، “legal”، “tabloid”، “ledger”، “statement” و “executive”؛ و قالب‌های پاکت نامه “com10”، “monarch” و “DL” هستند. تمام قالب‌ها، حتی آن‌هایی که برای پاکت نامه هستند، در جهت عمودی (portrait) هستند: اندازه طول به‌صورت عمودی است. افزودن “l” به هر یک از این‌ها در عوض نشان‌دهنده جهت افقی (landscape) است. این فایل ماکرو حاشیه‌های افقی یک‌اینچی را فرض می‌کند و ثبات‌های شناخته‌شده توسط بسته‌های man، mdoc، mm، mom و ms در groff را تنظیم می‌کند تا آن‌ها را متناسب با آن پیکربندی نماید. اگر حاشیه‌های متفاوتی می‌خواهید، باید از امکانات همان بسته‌ها یا درخواست‌های ll و/یا po در troff برای تنظیم آن‌ها استفاده کنید. یک دستگاه خروجی معمولاً به گزینه‌های خط فرمان -p و -l نیاز دارد تا ابعاد کاغذ و جهت‌گیری تعریف‌شده در فایل DESC خود را به ترتیب بازنویسی کند؛ نگاه کنید به زیربخش “Paper format” از groff(1). این فایل ماکرو معمولاً هنگام راه‌اندازی توسط فایل troffrc هنگام قالب‌بندی برای یک دستگاه حروفچینی (و نه یک ترمینال) بارگذاری می‌شود.
یک ماکروی واحد به نام PDFPIC ارائه می‌دهد تا یک گرافیک PDF را با استفاده از ویژگی‌های راه‌انداز خروجی pdf در یک سند بگنجاند. برای سایر دستگاه‌های خروجی، PDFPIC ماکروی PSPIC را فراخوانی می‌کند که با آن یک رابط مشترک دارد (پایین را ببینید). این فایل ماکرو معمولاً در زمان راه‌اندازی توسط فایل troffrc بارگذاری می‌شود.
تعاریف ماکروهای PS، PE و PF را برای استفاده با پیش‌پردازنده pic(1) فراهم می‌کند. آن‌ها هر تصویر را در مرکز قرار می‌دهند. اگر سند شما از یک بسته ماکروی خدمات کامل استفاده نمی‌کند، یا اگر آن بسته تعاریف ماکروی کارآمد pic را ارائه نمی‌دهد، از این ماکروها استفاده کنید. به جز man و mdoc، بسته‌های ارائه‌شده همراه با groff پیشاپیش این کار را انجام می‌دهند (استثنا: بسته mm نام PF را برای هدف متفاوتی به کار می‌برد).
یک ماکرو به نام PSPIC ارائه می‌دهد که یک تصویر گرافیکی پست‌اسکریپت (PostScript) را در یک سند می‌گنجاند. دستگاه‌های خروجی ps، dvi، html و xhtml از این گنجاندن‌ها پشتیبانی می‌کنند؛ برای تمام راه‌اندازهای دیگر، تصویر با یک کادر مستطیلی به همان اندازه جایگزین می‌شود. فایل pspic.tmac در زمان راه‌اندازی توسط فایل troffrc بارگذاری می‌شود.
نحو آن به شرح زیر است:
.PSPIC [-L|-R|-C|-I n] file [width [height]]
پارامتر file نام فایل پست‌اسکریپت است؛ width و height عرض و ارتفاع دلخواه تصویر را مشخص می‌کنند. اگر هیچ‌کدام از آرگومان‌های width یا height تعیین نشوند، عرض طبیعی تصویر (طبق کادر محدودکننده یا bounding box فایل) یا طول خط فعلی به عنوان عرض استفاده می‌شود، هرکدام که کمتر باشد. آرگومان‌های width و height می‌توانند واحدهای مقیاس داشته باشند؛ واحد مقیاس پیش‌فرض برابر i (اینچ) است. ماکروی PSPIC تصویر را به‌طور یکنواخت در جهات افقی و عمودی مقیاس‌بندی می‌کند تا از width عریض‌تر و از height بلندتر نشود. گزینه -C تصویر را به‌صورت افقی وسط‌چین می‌کند؛ این حالت پیش‌فرض است. گزینه‌های -L و -R تصویر را به ترتیب چپ‌چین و راست‌چین می‌کنند. گزینه -I تصویر را به اندازه  n تورفتگی می‌دهد (با واحد مقیاس پیش‌فرض از m).
برای استفاده از PSPIC درون یک انحراف (diversion)، توصیه می‌کنیم آن را با کد زیر گسترش دهید تا مطمئن شوید پهنای انحراف به‌طور کامل پهنای تصویر را پوشش می‌دهد:
.am PSPIC
.  vpt 0
\h'(\\n[ps-offset]u + \\n[ps-deswid]u)'
.  sp -1
.  vpt 1
..
شکست در بارگذاری آرگومان تصویر PSPIC یک خطا محسوب نمی‌شود. (درخواست psbb یک پیام تشخیصی خطا صادر می‌کند.) برای تبدیل چنین خطایی به یک خطای مرگبار (fatal)، کد مورد نظر را به ماکروی pspic*error-hook ضمیمه کنید:
.am pspic*error-hook
.  ab
..
ماکرویی به نام xx را برای قالب‌بندی مدخل‌های نمایه جایگشت‌یافته (permuted index) همان‌گونه که توسط برنامه GNU ptx(1) تولید می‌شود، ارائه می‌دهد. اگر نیازهای قالب‌بندی شما متفاوت است، این ماکرو را در سند خود کپی کرده و آن را بر اساس نیازتان تطبیق دهید.
توالی‌های گریز نویسه‌های ویژه را بر اساس نمادهای تصویری مشخص‌شده در RFC 1345 و جدول دونگار (digraph) ویرایشگر متن Vim تعریف می‌کند. نگاه کنید به groff_rfc1345(7).
رابطی را برای دستور کنترل دستگاه “pdf: background” که توسط gropdf(1) پشتیبانی می‌شود، ارائه می‌دهد. با استفاده از این بسته، اسناد groff ms می‌توانند مستطیل‌های رنگی را در زیر هر خروجی رسم نمایند.
.BOXSTART SHADED color OUTLINED color INDENT size WEIGHT size
یک کادر را آغاز می‌کند، که در آن آرگومان بعد از SHADED رنگ پر کردن درون کادر و آرگومان بعد از OUTLINED رنگ حاشیه را مشخص می‌کند. مورد اول را برای داشتن کادر پرشده بدون حاشیه و مورد دوم را برای داشتن حاشیه بدون رنگ پرکننده حذف کنید. مقدار مشخص‌شده برای WEIGHT در صورتی استفاده می‌شود که کادر دارای OUTLINED باشد.
گزینه INDENT پیش از مقداری می‌آید که فاصله‌ای میان حاشیه و محتویات داخل کادر باقی می‌گذارد.
هر color باید یک نام رنگ تعریف‌شده در groff باشد و هر size یک عبارت عددی معتبر در groff. جفت‌های کلیدواژه/مقدار می‌توانند به هر ترتیبی مشخص شوند.
کادرها می‌توانند تودرتو (انباشته) شوند، بنابراین می‌توانید یک کادر را درون کادر دیگری آغاز کنید؛ معمولاً کادرهای بعدی کوچک‌تر از کادر دربرگیرنده خواهند بود، هرچند این موضوع اجباری نیست. هنگام استفاده از BOXSTART، موقعیت سمت چپ برابر است با تورفتگی فعلی منهای مقدار INDENT در دستور، و موقعیت سمت راست برابر است با موقعیت سمت چپ (محاسبه‌شده در بالا) به علاوه طول خط فعلی و دو برابر تورفتگی.
.BOXSTOP
هیچ پارامتری دریافت نمی‌کند. این ماکرو آخرین کادر شروع‌شده را در موقعیت عمودی فعلی پس از افزودن فاصله INDENT آن می‌بندد.
اسناد groff شما می‌توانند به‌صورت شرطی ماکروهای sboxes را اجرا کنند. ثبات GSBOX در صورتی که بسته بارگذاری شده باشد تعریف می‌شود و اگر دستگاه خروجی pdf در حال استفاده باشد، مقدار درستی (true) را درون‌یابی می‌کند.
بسته sboxes علاوه بر این به بسته groff_ms(7) قلاب می‌شود تا هنگام رشد پانویس‌ها اعلان‌هایی دریافت کند، به طوری که بتواند پیش از چاپ پانویس‌ها، کادرهای روی صفحه را ببندد. هنگامی که این وضعیت رخ می‌دهد، sboxes کادرهای باز را دو پوینت بالاتر از جداکننده پانویس می‌بندد و آن‌ها را در صفحه بعدی مجدداً باز می‌کند. (این مقدار احتمالاً با INDENT کادر مطابقت نخواهد داشت.)
نگاه کنید به “Using PDF boxes with groff and the ms macros” برای مشاهده یک نمونه نمایشی.
با ردگیری فراخوانی ماکروها به اشکال‌زدایی اسناد groff کمک می‌کند. نگاه کنید به groff_trace(7).
ماکروهایی متناظر با عناصر HTML تعریف می‌کند. نگاه کنید به groff_www(7).

ابزارهای nroff و troff متعلق به AT&T پیش از تکامل قراردادهای فراخوانی مدرن تابع getopt(3) در زبان C پیاده‌سازی شده بودند و از روش نام‌گذاری برای بسته‌های ماکرو استفاده می‌کردند که از دیدگاه امروزی عجیب به نظر می‌رسد. بسته‌های ماکرو معمولاً با استفاده از گزینه -m در قالب‌بند بارگذاری می‌شدند؛ هنگامی که این گزینه بلافاصله و بدون فاصله با آرگومان خود همراه می‌شد، شبیه یک گزینه طولانی بود که پیش از آن یک خط تیره منفرد قرار داشت—پدیده‌ای نوظهور در عصر حجر رایانه! بنابراین بسته‌های ماکرو با نام‌هایی شناخته شدند که با حرف “m” آغاز می‌شدند، حرفی که از نام فایل ماکرو به هنگام ذخیره بر روی دیسک حذف شده بود. به عنوان مثال، بسته ماکروی دست‌نوشته (manuscript) با نام tmac.s ذخیره شده بود و با گزینه -ms بارگذاری می‌شد.

دستورات groff اجازه وجود فاصله میان یک گزینه و آرگومان آن را می‌دهند. نحو “groff -m s” نام فایل ماکرو را شفاف‌تر می‌سازد اما ممکن است کاربرانی را که با قرارداد اصلی آشنا هستند شگفت‌زده کند، کسانی که آگاه نبودند نام “واقعی” بسته از ابتدا همان “s” بوده است. برای چنین بسته‌هایی با پیشینه کهن، groff با ارائه فایل‌های ماکروی پوششی (wrapper) که فایل مورد نظر را با درخواست‌های mso بارگذاری می‌کنند، انتظارات کاربران گوناگون را برآورده می‌سازد. بنابراین، تمام دستورات “groff -m s”، “groff -m ms”، “groff -ms” و “groff -mms” همگی برای بارگذاری ماکروهای manuscript به کار می‌روند.

برای بسته‌های با قدمت جدیدتر، مانند www.tmac، پوشش‌های جایگزین ارائه نشده است.

همان‌طور که در بالا اشاره شد، troff در AT&T فایل‌های ماکرو را به صورت tmac.name نام‌گذاری می‌کرد. از آن زمان در سیستم‌های عامل مرسوم شده است که از پسوند در نام فایل برای بیان نوع یا قالب فایل استفاده شود.

روش سنتی استفاده از یک بسته ماکرو، مشخص کردن گزینه -m package به قالب‌بند است، که در پی آن فایل ماکروی package پیش از هر فایل ورودی دیگر خوانده می‌شود. از نظر تاریخی، package در فایلی به نام tmac.package (یعنی با پیشوند “tmac.”) جستجو می‌شد. سامانه GNU troff به دنبال package.tmac در مسیر ماکرو می‌گردد؛ اگر یافت نشد، در عوض به دنبال tmac.package می‌گردد و برعکس.

به عنوان روشی دیگر، می‌توان با استفاده از درخواست “.so file-name” یک فایل ماکرو را در سند گنجاند؛ file-name به صورت نسبی بر اساس مکان سند ورودی مشخص می‌شود. سامانه GNU troff قابلیتی بهبودیافته را در درخواستی مشابه به نام “mso package-file-name” ارائه می‌دهد که مسیر ماکرو را برای یافتن package-file-name جستجو می‌کند. از آن‌جا که آرگومان آن نام یک فایل است، بخش “.tmac” آن باید آورده شود تا فایل پیدا شود؛ با این حال برای راحتی کار، اگر باز کردن آن ناموفق باشد، mso هرگونه پسوندی از این دست را حذف کرده و مجدداً با پیشوند “tmac.” تلاش می‌کند و برعکس.

اگر یک فایل فراخوانی‌شده نیازمند پیش‌پردازش باشد، برای مثال اگر شامل جدول‌های tbl یا معادلات eqn باشد، باید از پیش‌پردازنده soelim(1) استفاده شود. این کار می‌تواند از طریق یک خط لوله (pipeline) یا در groff، با مشخص کردن گزینه -s برای قالب‌بند (یا پیش‌رابط) انجام پذیرد. برنامه‌های مدیریت صفحات man(1) عموماً soelim را به‌صورت خودکار فراخوانی می‌کنند. (بسته‌های ماکرو خود عموماً نیازی به پیش‌پردازش ندارند.)

یک سند roff(7) فایلی متنی است که با ساختارهای قالب‌بندی از پیش تعریف‌شده غنی شده است؛ مواردی مانند درخواست‌ها، توالی‌های گریز، رشته‌ها، ثبات‌های عددی و ماکروهایی از یک بسته ماکرو. این عناصر در roff(7) شرح داده شده‌اند.

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

ماکروهای بدون آرگومان دقیقاً مانند رشته‌ها هستند. اما قدرت کامل ماکروها زمانی پدیدار می‌شود که آرگومان‌ها به همراه فراخوانی ماکرو ارسال شوند. درون تعریف ماکرو، آرگومان‌ها به عنوان توالی‌های گریز \$1، ...، \$9، \$[...]، \$* و \$@ در دسترس هستند، نامی که ماکرو تحت آن فراخوانی شده است در \$0 قرار دارد و تعداد آرگومان‌ها در ثبات \n[.$] است؛ نگاه کنید به groff(7).

نگارش ماکروهای groff زمانی که سازوکار اسکیپ کردن (escaping) موقتاً غیرفعال باشد آسان است. در groff، این کار با محصور کردن تعریف (تعاریف) ماکرو در میان یک جفت درخواست .eo و .ec انجام می‌شود. در این حالت، بدنه تعریف ماکرو درست مانند بخش معمولی سند خواهد بود—متنی که با فراخوانی درخواست‌ها، ماکروها، رشته‌ها، ثبات‌ها و غیره ارتقا یافته است. برای مثال، کد بالا را می‌توان به روشی ساده‌تر به این شکل نوشت:

.eo
.ds midpart was called with the following
.de print_args
\f[I]\$0\f[] \*[midpart] \n[.$] arguments:
\$*
..
.ec

متأسفانه، حالت پیش‌نویس نمی‌تواند به‌صورت همگانی استفاده شود. اگرچه برای تعریف ماکروهای معمولی به‌اندازه کافی خوب است، اما حالت پیش‌نویس در کاربردهای پیشرفته، مانند رشته‌ها یا ثبات‌های تعریف‌شده به‌صورت غیرمستقیم، شکست می‌خورد. یک روش بهینه این است که تمام ماکروها را در حالت پیش‌نویس تعریف و آزمایش کنید و سپس به عنوان مرحله نهایی، بک‌اسلش‌ها را دو برابر (backslash doubling) نمایید؛ فراموش نکنید که درخواست .eo را حذف کنید.

•
هر خط را با یک نقطه آغاز کنید؛ برای مثال با استفاده از درخواست .nop در groff برای خطوط متنی، یا نوشتن ماکروی اختصاصی خود که خطوط متن را نیز با یک نقطه آغازین پردازش کند.
.de Text
.  if (\\n[.$] == 0) \
.    return
.  nop \)\\$*\)
..
•
ماکرویی برای کامنت‌گذاری بنویسید که هم در حالت کپی (copy mode) و هم در حالت پیش‌نویس (draft mode) کار کند؛ از آن‌جا که نویسه گریز در حالت پیش‌نویس خاموش است، هنگام استفاده از توالی‌های گریز کامنت ممکن است مشکلاتی رخ دهد. برای مثال، ماکروی زیر صرفاً آرگومان‌های خود را نادیده می‌گیرد، بنابراین مانند یک خط کامنت عمل می‌کند:
.de c
..
.c This is like a comment line.
  • در تعاریف طولانی ماکرو، برای ساختاردهی بهتر استفاده فراوانی از خطوط کامنت یا خطوط تقریباً خالی (یعنی خطوطی که فقط یک نقطه در ابتدای آن‌هاست و هیچ چیز دیگری ندارند) به عمل آورید.
  • برای افزایش خوانایی، از قابلیت تورفتگی در groff برای درخواست‌ها و فراخوانی ماکروها استفاده کنید (فاصله‌های خالی دلخواه پس از نقطه آغازین).

انحراف‌ها (Diversions) می‌توانند برای پیاده‌سازی ساختارهای برنامه‌نویسی بسیار پیشرفته به کار روند. آن‌ها با اشاره‌گرها به ساختارهای داده بزرگ در زبان برنامه‌نویسی C قابل مقایسه‌اند، اما نحوه استفاده از آن‌ها کاملاً متفاوت است.

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

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

(اگر واقعاً به انحراف‌هایی نیاز دارید که باید خط ناقص فعلی را نادیده بگیرند، از محیط‌ها (environments) برای ذخیره خط ناقص فعلی استفاده کنید و/یا از درخواست .box بهره ببرید.)

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

این سند توسط Bernd Warken، Werner Lemberg و G. Branden Robinson نوشته شده است.

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

استاندارد سلسله‌مراتب فایل‌سیستم (Filesystem Hierarchy Standard) توسط بنیاد لینوکس نگهداری می‌شود.

groff(1)
مروری کلی بر سامانه groff است.
groff_man(7)،
groff_mdoc(7)،
groff_me(7)،
groff_mm(7)،
groff_mom(7)،
groff_ms(7)،
groff_rfc1345(7)،
groff_trace(7)
و
groff_www(7)
بسته‌های ماکروی groff هستند.
groff(7)
زبانی را که توسط GNU troff شناخته می‌شود خلاصه می‌کند.
troff(1)
مسیر پیش‌فرض جستجوی فایل‌های ماکرو را مستند می‌کند.
مه ۲۰۲۵ groff