گزینه‌های عمومی

-C file, --config-file=file

استفاده از این فایل پیکربندی کاربر به‌جای پیشفرض ~/.manpath.

-d, --debug

چاپ اطلاعات اشکال‌زدایی.

-D, --default

این گزینه معمولاً به‌عنوان اولین گزینه داده می‌شود و رفتار man را به حالت پیشفرض بازمی‌گرداند. کاربرد آن، بازنشانی گزینه‌هایی است که ممکن است در $MANOPT تنظیم شده باشند. هر گزینه‌ای که پس از -D بیاید، تأثیر معمول خود را خواهد داشت.

--warnings[=warnings]

فعال‌سازی هشدارهای groff. از این گزینه می‌توان برای بررسی صحت متن مبدأ صفحات راهنما استفاده کرد. warnings فهرستی از نام‌های هشدار است که با کاما از هم جدا شده‌اند؛ اگر ارائه نشود، مقدار پیشفرض "mac" است. برای غیرفعال کردن یک هشدار groff علامت "!" را به ابتدای آن بیفزایید: برای نمونه، --warnings=mac,!break هشدارهای دستهٔ "mac" را فعال و هشدارهای دستهٔ "break" را غیرفعال می‌کند. برای مشاهدهٔ فهرستی از نام‌های هشدار موجود، به گره “Warnings” در info groff مراجعه کنید.

حالت‌های اصلی عملیات

-f, --whatis

تقریباً معادل با whatis. نمایش توضیحی کوتاه از صفحهٔ راهنما، در صورت وجود. برای جزئیات، به whatis(1) مراجعه کنید.

-k, --apropos

تقریباً معادل apropos است. توضیحات کوتاه صفحات راهنما را برای کلیدواژه‌ها جست‌وجو کرده و موارد منطبق را نمایش می‌دهد. برای جزئیات بیشتر به apropos(1) مراجعه کنید.

-K, --global-apropos

جست‌وجوی متن در تمامی صفحات راهنما. این یک جست‌وجوی جامع و سنگین (brute-force) است و احتمالاً مدتی زمان می‌برد؛ در صورت امکان، بهتر است یک بخش را مشخص کنید تا تعداد صفحاتی که باید جست‌وجو شوند کاهش یابد. عبارات جست‌وجو می‌توانند رشته‌های متنی ساده (حالت پیش‌فرض) باشند، یا در صورتی که از گزینهٔ --regex استفاده شود، عبارت باقاعده باشند.

توجه داشته باشید که این گزینه پرونده‌های منبع صفحات راهنما را جست‌وجو می‌کند، نه متن رندرشده را؛ بنابراین ممکن است شامل موارد مثبت کاذب به دلیل مواردی چون کامنت‌ها در پرونده‌های منبع، یا منفی کاذب به دلیل مواردی مانند نوشته‌شدن خط تیره به‌صورت "\-" در پرونده‌های منبع باشد. جست‌وجوی متن رندرشده بسیار کندتر خواهد بود.

-l, --local-file

فعال‌سازی حالت «محلی» (local). قالب‌بندی و نمایش پرونده‌های راهنمای محلی به‌جای جست‌وجو در مجموعه راهنماهای سیستم. هر آرگومان صفحهٔ راهنما به‌صورت یک پروندهٔ منبع nroff با ساختار صحیح تفسیر خواهد شد. هیچ پروندهٔ cat تولید نمی‌شود. اگر '-' به‌عنوان یکی از آرگومان‌ها داده شود، ورودی از stdin خوانده خواهد شد.

اگر از این گزینه استفاده نشود، در صورتی که آرگومان حاوی نویسهٔ "/" باشد، man همچنین به تفسیر آرگومان‌های صفحهٔ راهنما به‌عنوان نام پرونده‌های محلی بازمی‌گردد، چرا که این نشانهٔ خوبی از اشارهٔ آرگومان به مسیری در سیستم پرونده است.

-w, --where, --path, --location

صفحهٔ راهنما را عملاً نمایش نمی‌دهد، بلکه مکان پروندهٔ منبع nroff را که قالب‌بندی می‌شد چاپ می‌کند. اگر گزینهٔ -a نیز استفاده شود، مکان تمام پرونده‌های منبعی را که با معیارهای جست‌وجو مطابقت دارند چاپ می‌کند.

-W, --where-cat, --location-cat

صفحهٔ راهنما را واقعاً نمایش نده، بلکه مکان پروندهٔ cat از پیش قالب‌بندی‌شده‌ای را که نمایش داده می‌شد چاپ کن. اگر گزینهٔ -a نیز استفاده شود، مکان تمام پرونده‌های cat از پیش قالب‌بندی‌شده‌ای که با معیارهای جستجو مطابقت دارند را چاپ کن.

اگر هر دو گزینهٔ -w و -W استفاده شوند، هم پروندهٔ مبدأ و هم پروندهٔ cat را که با یک فاصله از هم جدا شده‌اند چاپ کن. اگر همهٔ گزینه‌های -w، -W و -a استفاده شوند، این کار را برای هر تطابق ممکن انجام بده.

-c, --catman

این گزینه برای استفادهٔ عمومی نیست و فقط باید توسط برنامهٔ catman استفاده شود.

-R encoding, --recode=encoding

به‌جای قالب‌بندی صفحهٔ راهنما به روش معمول، منبع آن را پس از تبدیل به encoding مشخص‌شده خروجی بده. اگر از قبل کدگذاری پروندهٔ مبدأ را می‌دانید، می‌توانید مستقیماً از manconv(1) نیز استفاده کنید. با این حال، این گزینه به شما امکان می‌دهد چندین صفحهٔ راهنما را به یک کدگذاری واحد تبدیل کنید، بدون اینکه نیاز باشد کدگذاری هر یک را به‌طور صریح مشخص کنید؛ به شرطی که آن‌ها از قبل در ساختاری مشابه با سلسله‌مراتب صفحات راهنما نصب شده باشند.

برای تبدیل چندین صفحهٔ راهنما، استفاده از man-recode(1) را در نظر داشته باشید، چرا که رابط کاربری آن برای تبدیل گروهی طراحی شده است و می‌تواند بسیار سریع‌تر باشد.

یافتن صفحات راهنما

-L locale, --locale=locale

man به‌طور معمول تنظیمات محلی فعلی شما را با فراخوانی تابع C setlocale(3) تعیین می‌کند که متغیرهای محیطی گوناگونی را بررسی می‌نماید، از جمله احتمالاً $LC_MESSAGES و $LANG. برای جایگزینی موقت مقدار تعیین‌شده، از این گزینه استفاده کنید تا یک رشتهٔ locale را مستقیماً به man ارائه دهید. توجه داشته باشید که این گزینه تا زمانی که جستجو برای صفحات واقعاً آغاز نشود، اعمال نخواهد شد. خروجی‌هایی مانند پیام راهنما همواره در تنظیمات محلی اولیهٔ تعیین‌شده نمایش داده خواهند شد.

-m system[,...], --systems=system[,...]

اگر این سیستم به صفحات راهنمای سایر سیستم‌عامل‌ها دسترسی دارد، می‌توان با استفاده از این گزینه به آن‌ها دسترسی پیدا کرد. برای جستجوی یک صفحه راهنما از مجموعه صفحات راهنمای NewOS، از گزینهٔ زیر استفاده کنید: -m NewOS.

مقدار system مشخص‌شده می‌تواند ترکیبی از نام‌های سیستم‌عامل جداشده با کاما باشد. برای گنجاندن جستجو در صفحات راهنمای سیستم‌عامل بومی، نام سیستم man را در رشته آرگومان قرار دهید. این گزینه بر متغیر محیطی $SYSTEM اولویت خواهد داشت.

-M path, --manpath=path

یک manpath جایگزین را برای استفاده مشخص می‌کند. به‌طور پیش‌فرض، man از کد مشتق‌شده از manpath برای تعیین مسیر جستجو استفاده می‌کند. این گزینه بر متغیر محیطی $MANPATH اولویت دارد و باعث می‌شود گزینهٔ -m نادیده گرفته شود.

مسیری که به‌عنوان manpath مشخص می‌شود، باید ریشهٔ سلسله‌مراتبی از صفحات راهنما باشد که طبق توضیحات راهنمای man-db (در بخش "The manual page system")، در بخش‌های مختلف ساختار یافته است. برای مشاهدهٔ صفحات راهنما در خارج از چنین سلسله‌مراتب‌هایی، گزینهٔ -l را ببینید.

-S list, -s list, --sections=list

فهرست list داده‌شده، فهرستی از بخش‌ها است که با دونقطه یا کاما از هم جدا شده‌اند و برای تعیین این‌که کدام بخش‌های راهنما و با چه ترتیبی جستجو شوند، به کار می‌رود. این گزینه بر متغیر محیطی $MANSECT اولویت دارد. (نگارش -s برای سازگاری با System V است.)

-e sub-extension, --extension=sub-extension

برخی سیستم‌ها بسته‌های بزرگی از صفحات راهنما، مانند مواردی که همراه بستهٔ Tcl هستند را در سلسله‌مراتب اصلی صفحات راهنما ادغام می‌کنند. برای دور زدن مشکل وجود دو صفحهٔ راهنما با نام یکسان مانند exit(3), معمولاً تمام صفحات Tcl اختصاص داده می‌شدند به بخش l. از آنجا که این وضعیت نامطلوب است، اکنون می‌توان صفحات را در بخش صحیح قرار داد و یک «پسوند» خاص به آن‌ها اختصاص داد؛ در این مورد، exit(3tcl). در حالت عادی، man صفحهٔ exit(3) را نمایش می‌دهد با اولویت نسبت به exit(3tcl). برای مدیریت این وضعیت و بی‌نیازی از دانستن این‌که صفحهٔ مورد نظر در کدام بخش قرار دارد، اکنون می‌توان به man یک رشتهٔ sub-extension داد که مشخص می‌کند صفحه باید متعلق به کدام بسته باشد. با استفاده از مثال بالا، دادن گزینهٔ -e tcl به man جست‌وجو را محدود می‌کند به صفحاتی با پسوند *tcl.

-i, --ignore-case

نادیده گرفتن بزرگی و کوچکی حروف هنگام جست‌وجوی صفحات راهنما. این حالت پیش‌فرض است.

-I, --match-case

جست‌وجوی حساس به بزرگی و کوچکی حروف برای صفحات راهنما.

--regex

نمایش تمام صفحاتی که بخشی از نام یا توضیحات آن‌ها با هر آرگومان page به‌عنوان یک عبارت باقاعده مطابقت دارد، مشابه apropos(1). از آنجا که معمولاً هنگام جست‌وجو برای یک عبارت باقاعده راه معقولی برای انتخاب «بهترین» صفحه وجود ندارد، این گزینه دلالت دارد بر -a.

--wildcard

نمایش تمام صفحاتی که هر بخشی از نام یا توضیحات آن‌ها با هر آرگومان page با استفاده از نویسه‌های عمومی سبک پوسته مطابقت دارد، همانند apropos(1) --wildcard. آرگومان page باید با کل نام یا توضیحات مطابقت داشته باشد، یا با مرزهای کلمات در توضیحات مطابقت کند. از آن‌جا که معمولاً هنگام جستجو با یک نویسه عمومی راه معقولی برای انتخاب «بهترین» صفحه وجود ندارد، این گزینه به طور ضمنی شامل این گزینه است: -a.

--names-only

اگر از گزینهٔ --regex یا --wildcard استفاده شود، تنها نام صفحه‌ها مطابقت داده می‌شوند و نه توضیحات آن‌ها، همانند whatis(1). در غیر این صورت، اثری ندارد.

-a, --all

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

-u, --update

این گزینه باعث می‌شود man حافظه‌های نهان پایگاه‌دادهٔ صفحات راهنمای نصب‌شدهٔ خود را به‌روزرسانی کند. این کار تنها در شرایط نادری مورد نیاز است، و معمولاً بهتر است به جای آن mandb(8) اجرا شود.

--no-subpages

به‌صورت پیش‌فرض، man تلاش می‌کند جفت‌نام‌های صفحات راهنمای داده‌شده در خط فرمان را معادل یک نام صفحهٔ راهنمای منفردِ حاوی خط تیره یا زیرخط تفسیر کند. این قابلیت از الگوی رایج برنامه‌هایی پشتیبانی می‌کند که تعدادی زیردستور را پیاده‌سازی کرده‌اند، و به آن‌ها اجازه می‌دهد برای هر یک صفحات راهنمایی ارائه دهند که با استفاده از نحوی مشابه روش فراخوانی خودِ زیردستورها قابل دسترسی باشند. برای مثال:

$ man -aw git diff
/usr/share/man/man1/git-diff.1.gz

برای غیرفعال کردن این رفتار، از گزینهٔ --no-subpages استفاده کنید.

$ man -aw --no-subpages git diff
/usr/share/man/man1/git.1.gz
/usr/share/man/man3/Git.3pm.gz
/usr/share/man/man1/diff.1.gz

کنترل خروجی قالب‌بندی‌شده

-P pager, --pager=pager

صفحه‌بندی‌کنندهٔ خروجی مورد استفاده را مشخص می‌کند. به‌طور پیش‌فرض، man از less استفاده می‌کند، و در صورتی که less یافت نشود یا قابل اجرا نباشد، به cat رجوع می‌کند. این گزینه متغیر محیطی $MANPAGER را بازنویسی می‌کند، که آن نیز به‌نوبهٔ خود متغیر محیطی $PAGER را بازنویسی می‌نماید. این گزینه در کنار -f یا -k استفاده نمی‌شود.

مقدار می‌تواند یک نام دستور ساده یا دستوری همراه با آرگومان‌ها باشد، و می‌تواند از نقل‌قول‌گذاری‌های پوسته (بک‌اسلش، نقل‌قول تکی یا دوگانه) استفاده کند. نمی‌توان از لوله‌ها (pipes) برای اتصال چندین دستور استفاده کرد؛ اگر به چنین چیزی نیاز دارید، از یک اسکریپت پوششی (wrapper script) استفاده کنید، که می‌تواند پرونده را جهت نمایش به عنوان آرگومان یا از طریق ورودی استاندارد دریافت کند.

-r prompt, --prompt=prompt

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

Manual page name(sec) line x

که در آن name نشان‌دهندهٔ نام صفحهٔ راهنما، sec نشان‌دهندهٔ بخشی که صفحه در آن یافت شده، و x شمارهٔ خط فعلی است. این کار با استفاده از متغیر محیطی $LESS انجام می‌شود.

دادن یک رشته به -r این مقدار پیش‌فرض را بازنویسی خواهد کرد. این رشته می‌تواند شامل متن $MAN_PN باشد که به نام صفحهٔ راهنمای جاری و نام بخش آن در میان «(» و «)» بسط می‌یابد. رشته‌ای که برای تولید مقدار پیش‌فرض استفاده می‌شود را می‌توان به این صورت بیان کرد:

\ Manual\ page\ \$MAN_PN\ ?ltline\ %lt?L/%L.:
byte\ %bB?s/%s..?\ (END):?pB\ %pB\\%..
(press h for help or q to quit)

این رشته در اینجا صرفاً برای خوانایی بیشتر به سه خط شکسته شده است. برای درک مفهوم آن، به صفحهٔ راهنمای less(1) مراجعه کنید. رشتهٔ اعلان ابتدا توسط پوسته ارزیابی می‌شود. تمام علامت‌های نقل‌قول دوتایی، نقل‌قول‌های وارون (back-quotes) و بک‌اسلش‌ها در اعلان باید با یک بک‌اسلشِ پیشین گریز داده شوند (escaped). رشتهٔ اعلان ممکن است به یک $ گریز داده شده ختم شود که می‌تواند با گزینه‌های بیشتری برای less دنبال شود. به‌طور پیش‌فرض، man گزینه‌های -ix8 را تنظیم می‌کند. متغیر محیطی $MANLESS که در ادامه توضیح داده شده است، می‌تواند برای تعیین یک رشته اعلان پیشفرض در صورت مشخص نشدن در خط فرمان به کار رود.

-7, --ascii

هنگام مشاهدهٔ یک صفحهٔ راهنمای صرفاً ascii(7) روی یک پایانهٔ ۷ بیتی یا شبیه‌ساز پایانه، ممکن است برخی نویسه‌ها هنگام استفاده از توصیف دستگاه latin1(7) همراه با GNU nroff، به‌درستی نمایش داده نشوند. این گزینه اجازه می‌دهد صفحات راهنمای صرفاً ascii با استفاده از دستگاه latin1 به صورت ascii نمایش داده شوند. این گزینه هیچ متن latin1 را تبدیل نخواهد کرد. جدول زیر تبدیل‌های انجام‌شده را نشان می‌دهد: ممکن است برخی از بخش‌های آن تنها هنگام استفاده از دستگاه latin1(7) در GNU nroff به‌درستی نمایش داده شوند.

توضیحات	اکتال	latin1	ascii
خط تیره ادامه	255	‐	-
گلوله (نقطه میانی)	267	•	o
اکسان اگو	264	´	'
علامت ضرب	327	×	x

اگر ستون latin1 به‌درستی نمایش داده می‌شود، ممکن است پایانهٔ شما برای نویسه‌های latin1 تنظیم شده باشد و این گزینه ضروری نیست. اگر ستون‌های latin1 و ascii یکسان هستند، شما در حال خواندن این صفحه با استفاده از این گزینه هستید یا man این صفحه را با استفاده از توصیف دستگاه latin1 قالب‌بندی نکرده است. اگر ستون latin1 وجود ندارد یا مخدوش است، ممکن است لازم باشد صفحات راهنما را با این گزینه مشاهده کنید.

این گزینه هنگام استفاده از گزینه‌های -t، -H، -T یا -Z نادیده گرفته می‌شود و ممکن است برای nroff به‌جز GNU بی‌استفاده باشد.

-E encoding, --encoding=encoding

تولید خروجی برای یک کدگذاری نویسه غیر از حالت پیش‌فرض. برای سازگاری با گذشته، encoding می‌تواند یک دستگاه nroff مانند ascii، latin1، یا utf8 و همچنین یک کدگذاری نویسه واقعی مانند UTF-8 باشد.

--no-hyphenation, --nh

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

اگر در حال نگارش یک صفحه راهنما هستید و صرفاً می‌خواهید از شکستن یک واژه با خط پیوند در نقطه‌ای نامناسب توسط nroff جلوگیری کنید، از این گزینه استفاده نکنید، بلکه در عوض به مستندات nroff مراجعه کنید؛ برای نمونه، می‌توانید "\%" را درون یک واژه قرار دهید تا نشان دهید می‌تواند در آن نقطه با خط پیوند شکسته شود، یا "\%" را در ابتدای یک واژه بگذارید تا از شکستن آن با خط پیوند جلوگیری شود.

--no-justification, --nj

به‌طور معمول، nroff متن را به‌طور خودکار از هر دو حاشیه تراز می‌کند. این گزینه تراز کامل را غیرفعال می‌کند و متن را تنها از حاشیه چپ تراز نگه می‌دارد، که گاهی متن «راست‌دندانه‌دار» (ragged-right) نامیده می‌شود.

اگر در حال نگارش یک صفحه راهنما هستید و صرفاً می‌خواهید از تراز کردن پاراگراف‌های خاصی توسط nroff جلوگیری کنید، از این گزینه استفاده نکنید، بلکه در عوض به مستندات nroff مراجعه کنید؛ برای نمونه، می‌توانید از درخواست‌های ".na"، ".nf"، ".fi" و ".ad" برای غیرفعال کردن موقت تراز و پر کردن استفاده کنید.

-p string, --preprocessor=string

مشخص کردن دنباله پیش‌پردازنده‌هایی که باید پیش از nroff یا troff/groff اجرا شوند. در همه سیستم‌ها مجموعه کاملی از پیش‌پردازنده‌ها وجود نخواهد داشت. برخی از پیش‌پردازنده‌ها و حروفی که برای تعیین آن‌ها استفاده می‌شوند عبارتند از: eqn (e)، grap (g)، pic (p)، tbl (t)، vgrind (v)، refer (r). این گزینه بر متغیر محیطی $MANROFFSEQ اولویت دارد. zsoelim همیشه به عنوان اولین پیش‌پردازنده اجرا می‌شود.

-t, --troff

از groff -mandoc برای قالب‌بندی صفحه راهنما در stdout استفاده می‌کند. این گزینه همراه با -H، -T یا -Z لازم نیست.

-T[device], --troff-device[=device]

این گزینه برای تغییر خروجی groff (یا احتمالاً troff) جهت سازگاری با دستگاهی غیر از پیشفرض استفاده می‌شود. این گزینه به‌طور ضمنی -t را فعال می‌کند. مثالها (تا نسخه 1.23.0 groff) شامل موارد زیر است: dvi، latin1، pdf، ps، utf8، X75 و X100.

-H[browser], --html[=browser]

این گزینه موجب می‌شود groff خروجی HTML تولید کرده و آن را در یک مرورگر وب نمایش دهد. انتخاب مرورگر با آرگومان اختیاری browser (در صورت ارائه)، متغیر محیطی $BROWSER یا در صورت تنظیم نبودن آن، با مقدار پیشفرض زمان کامپایل تعیین می‌شود (معمولاً lynx). این گزینه به‌طور ضمنی -t را فعال می‌کند و تنها با GNU troff کار خواهد کرد.

-X[dpi], --gxditview[=dpi]

این گزینه خروجی groff را با استفاده از برنامه gxditview در یک پنجره گرافیکی نمایش می‌دهد. مقدار dpi (نقطه در اینچ) می‌تواند 75، 75-12، 100 یا 100-12 باشد که پیشفرض آن 75 است؛ گونه‌های -12 از یک قلم پایه 12 پوینتی استفاده می‌کنند. این گزینه به‌طور ضمنی -T را به ترتیب با دستگاه‌های X75، X75-12، X100 یا X100-12 اعمال می‌کند.

-Z, --ditroff

groff دستور troff را اجرا کرده و سپس از یک پس‌پردازشگر مناسب برای تولید خروجی متناسب با دستگاه انتخاب‌شده استفاده می‌کند. اگر groff -mandoc برابر با groff باشد، این گزینه به groff ارسال می‌شود و از به‌کارگیری پس‌پردازشگر جلوگیری می‌کند. این گزینه مستلزم -t است.

دریافت راهنما

-?, --help

چاپ پیام راهنما و خروج.

--usage

چاپ پیام کوتاه نحوهٔ استفاده و خروج.

-V, --version

نمایش اطلاعات نسخه.