grog(1) General Commands Manual grog(1)

grog - حدس زدن دستور groff مورد نیاز برای پردازش یک سند

grog [groff-option ...] [--] [file ...]
grog -h
grog --help
grog -v
grog --version

دستور grog ورودی خود را می‌خواند و حدس می‌زند که کدام گزینه‌های groff(1) برای رندر و پردازش آن مورد نیاز است. اگر هیچ عملوندی داده نشود، یا اگر file برابر با “-” باشد، grog جریان ورودی استاندارد را می‌خواند. دستور معادل groff به‌طور معمول در جریان خروجی استاندارد نوشته می‌شود.

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

تمام گزینه‌های کوتاه دیگر که مشخص می‌شوند (یعنی آرگومان‌هایی که با علامت خط تیره “-” و به دنبال آن یک حرف شروع می‌شوند) به‌عنوان گزینه‌ها یا دسته‌گزینه‌های groff با یا بدون آرگومان گزینه تفسیر می‌شوند. چنین گزینه‌هایی در خط فرمان ساخته‌شده برای groff گنجانده می‌شوند.

دستور grog هر عملوند file را می‌خواند و رشته‌هایی را که بر اساس احتمالات آماری از ویژگی‌های اسناد roff(7) به شمار می‌روند، تطبیق الگو می‌دهد. این برنامه تلاش می‌کند حدس بزند کدام‌یک از گزینه‌های groff زیر برای رندر و نمایش صحیح ورودی لازم هستند: -e، -g، -G، -j، -p، -R، -t (پیش‌پردازنده‌ها)؛ و -man، -mdoc، -mdoc-old، -me، -mm، -mom و -ms (بسته‌های ماکرو). دستور استنتاج‌شده groff شامل این گزینه‌ها و هرگونه پارامتر file در جریان خروجی استاندارد نوشته می‌شود.

امکان تعیین گزینه‌های دلخواه groff در خط فرمان وجود دارد. این گزینه‌ها بدون تغییر در دستور استنتاج‌شده گنجانده می‌شوند. از جمله گزینه‌های groff می‌توان به -C برای فعال‌سازی حالت سازگاری با troff شرکت AT&T و -T برای انتخاب یک دستگاه خروجی غیرپیش‌فرض اشاره کرد. اگر ورودی با کدگذاری ISO 646:1991 IRV (US-ASCII) یا ISO Latin-1 (8859-1) کدگذاری نشده باشد، توصیه می‌کنیم یکی از گزینه‌های groff را برای اجرای preconv(1) مشخص کنید؛ به گزینه‌های -D، -k و -K در groff(1) مراجعه کنید. برای ورودی‌های UTF-8، گزینه -k انتخاب مناسبی است.

دستور groff ممکن است هنگام مشخص شدن یک گزینه نامناسب -m، یا چندین گزینه متناقض، پیام‌های تشخیصی صادر کند. بنابراین، بهتر است هیچ گزینه -m به grog داده نشود مگر آنکه نتواند تمام آرگومان‌های -m مورد نیاز یک سند را به‌درستی استنتاج کند. یک سند roff می‌تواند بدون استفاده از هیچ بسته ماکرویی نیز نوشته شود. در چنین مواردی، grog دستور groff را بدون گزینه -m استنتاج می‌کند.

دستور grog فرض می‌کند که ورودی نویسه‌های گریز (escape)، کنترلی یا کنترلی بدون شکست (no-break) را تغییر نمی‌دهد. همچنین grog ساختارهای ادامه‌دهنده خطوط ورودی یا ساختارهای کنترلی roff (توالی‌های گریز آکولاد و درخواست‌های “if”، “ie” و “el”) و نیز درخواست “while” در groff را تجزیه نمی‌کند. بنابراین، ورودی مانند

.if \
t .NH 1
.if n .SH
Introduction
استفاده از ماکروهای NH و SH در بسته ms را از دید grog پنهان می‌سازد. توسعه‌دهندگان grog این ساختارها را آن‌قدر نامتداول در نظر گرفته‌اند که مشکلات استنتاجی چندانی ایجاد نمی‌کنند. پیش‌پردازنده‌ها هنگام تطبیق فراخوانی‌های ماکرویی که محدوده‌های جایگزین‌شونده یک فایل ورودی را در بر می‌گیرند، می‌توانند حتی سخت‌گیرانه‌تر باشند. به‌عنوان مثال، pic نیاز دارد که فراخوانی‌های PS، PE و PF دقیقاً بعد از نویسه کنترلی پیش‌فرض در ابتدای خط قرار گیرند.

تشخیص گزینه -s (پیش‌پردازنده soelim(1)) دشوار است؛ استنتاج صحیح ضرورت آن مستلزم آن است که grog تمام فایل‌های داده‌شده به‌عنوان آرگومان به درخواست .so را تحت همان شرایطی که خود soelim انجام می‌دهد، به‌صورت بازگشتی باز کند؛ به صفحه راهنمای آن مراجعه کنید. به یاد داشته باشید که soelim تنها زمانی لازم است که فایل‌های فراخوانی‌شده (source شده) نیاز به پیش‌پردازش داشته باشند. بنابراین، به‌عنوان یک راهکار، می‌توانید ورودی را به‌صورت دستی از طریق soelim اجرا کرده، خروجی آن را به grog لوله (pipe) کنید، و خروجی را با اجرای مستقیم grog روی ورودی مقایسه نمایید. اگر ورودی پردازش‌شده با soelim باعث شود grog گزینه‌های پیش‌پردازنده بیشتری را استنتاج کند، آنگاه گزینه -s احتمالاً ضروری است.

$ 
printf ".TS\nl.\nI'm a table.\n.TE\n" > 3.roff
$ 
printf ".so 3.roff\n" > 2.roff
$ 
printf ".XP\n.so 2.roff\n" > 1.roff
$ 
grog 1.roff
groff -ms 1.roff
$ 
soelim 1.roff | grog
groff -t -ms -

در مثال بالا، می‌بینیم که این روش به grog امکان داد تا ماکروهای tbl(1) را تشخیص دهد، بنابراین گزینه -s را به همراه گزینه شناسایی‌شده -t به یک دستور بازبینی‌شده grog یا groff اضافه می‌کنیم.

$ 
grog -st 1.roff
groff -st -ms 1.roff

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

اجرای دستور

grog /usr/share/doc/groff-1.24.1/meintro.me
در خط فرمان نتیجه زیر را در پی دارد: 
groff -me /usr/share/doc/groff-1.24.1/meintro.me
زیرا grog تشخیص می‌دهد که فایل meintro.me با استفاده از ماکروهای بسته me نوشته شده است. از سوی دیگر، دستور 
grog /usr/share/doc/groff-1.24.1/pic.ms
خروجی زیر را تولید می‌کند: 
groff -e -p -t -ms /usr/share/doc/groff-1.24.1/pic.ms
علاوه بر تشخیص بسته ماکروی ms، دستور grog تشخیص می‌دهد که فایل pic.ms همچنین به ترکیبی از گزینه -t برای tbl، گزینه -e برای eqn و گزینه -p برای pic نیاز دارد.

فایل doc/grnexampl.me را در نظر بگیرید که از پیش‌پردازنده grn برای درج یک فایل تصویری gremlin(1) در یک سند me استفاده می‌کند. فرض کنیم می‌خواهیم خروجی رنگی را غیرفعال کنیم، یک فایل DVI تولید کنیم، و در صورت بروز هرگونه خطا توسط troff ردیابی خطاها (backtraces) را دریافت نماییم. دستور

grog -bc -Idoc -Tdvi doc/grnexmpl.me
توسط grog به صورت زیر پردازش می‌شود: 
groff -bc -Idoc -Tdvi -e -g -me doc/grnexmpl.me
که در آن می‌توانیم ببینیم grog بسته ماکروی me را همراه با پیش‌پردازنده‌های eqn و grn استنتاج کرده است. (اگر مایلید این مثال را خودتان امتحان کنید، فایل ورودی در مسیر /usr/share/doc/groff-1.24.1 قرار دارد.)

دستور grog در ابتدا توسط James Clark با پوسته بورن (Bourne shell) نوشته شد. پیاده‌سازی فعلی در پرل توسط Bernd Warken نوشته شده و توسط G. Branden Robinson به‌طور اساسی بازبینی شده است.

groff(1)

2026-03-15 groff 1.24.1