نام (NAME)

xman - برنامه نمایش صفحات راهنما برای سامانه پنجره X

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

xman [ -options ... ]

توضیحات (DESCRIPTION)

دستور Xman یک مرورگر صفحات راهنما است. اندازه پیش‌فرض پنجره اولیه xman کوچک است تا بتوانید آن را در تمام طول نشست ورود به سیستم باز نگه دارید. در پنجره اولیه سه دکمه وجود دارد: Help پنجره‌ای با راهنمای برخط باز می‌کند، Quit خارج می‌شود، و Manual Page پنجره‌ای باز می‌کند که یک مرورگر صفحات راهنما درون آن قرار دارد. فشردن Control-S پنجره‌ای باز می‌کند که صفحه راهنمای خاصی را برای نمایش درخواست می‌کند. می‌توانید هم‌زمان بیش از یک پنجره مرورگر صفحه راهنما را از یک بار اجرای xman نمایش دهید.

برای اطلاعات بیشتر در مورد استفاده از xman، لطفاً اطلاعات راهنمای برخط را مطالعه کنید. بیشتر این راهنما به شخصی‌سازی xman خواهد پرداخت.

گزینه‌ها (OPTIONS)

برنامه Xman از تمام آرگومان‌های استاندارد خط فرمان جعبه‌ابزار پشتیبانی می‌کند (نگاه کنید به X(7)). آرگومان‌های تکمیلی زیر نیز پشتیبانی می‌شوند.

-helpfile filename: یک فایل راهنما به غیر از فایل پیش‌فرض برای استفاده مشخص می‌کند.
-bothshown: امکان نمایش هم‌زمان صفحه راهنما و دایرکتوری راهنما روی صفحه را فراهم می‌کند.
-notopbox: برنامه را بدون منوی بالایی (Top Menu) شامل سه دکمه اجرا می‌کند.
-geometry WxH+X+Y: اندازه و مکان منوی بالایی حاوی سه دکمه را تنظیم می‌کند.
-pagesize WxH+X+Y: اندازه و مکان تمامی صفحات راهنما را تنظیم می‌کند.
-help: پیام راهنمای استفاده را چاپ کرده و خارج می‌شود.
-version: نسخه برنامه را چاپ کرده و خارج می‌شود.

شخصی‌سازی XMAN (CUSTOMIZING XMAN)

Xman امکان شخصی‌سازی دایرکتوری‌های مورد جستجو برای صفحات راهنما، و همچنین نامی که هر دایرکتوری در منوی Sections به آن نگاشت می‌شود را فراهم می‌کند. Xman با خواندن متغیر محیطی MANPATH مشخص می‌کند که چه دایرکتوری‌هایی را جستجو کند. اگر متغیر MANPATH یافت نشود، در سیستم‌های POSIX دایرکتوری /usr/man جستجو می‌شود. این متغیر محیطی باید فهرستی از دایرکتوری‌ها باشد که با دونقطه (:) از هم جدا شده‌اند تا xman آنها را جستجو کند.

setenv MANPATH /mit/kit/man:/usr/man

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

Directory	Section Name
-	-
man1	(1) User Commands
man2	(2) System Calls
man3	(3) Subroutines
man4	(4) Devices
man5	(5) File Formats
man6	(6) Games
man7	(7) Miscellaneous
man8	(8) Sys. Administration
manl	(l) Local
mann	(n) New
mano	(o) Old

برای نمونه، کاربری سه دایرکتوری در مسیر راهنمای خود دارد و هر یک حاوی دایرکتوری‌ای به نام man3 هستند. زمانی که کاربر آیتم منویی با عنوان (3) Subroutines را انتخاب می‌کند، تمامی این صفحات راهنما با مرتب‌سازی الفبایی ظاهر می‌شوند. اگر در هیچ‌کدام از دایرکتوری‌های موجود در MANPATH کاربر دایرکتوری‌ای به نام mano وجود نداشته باشد، یا هیچ صفحه راهنمایی در هیچ‌یک از دایرکتوری‌های mano نباشد، هیچ آیتم منویی برای بخش (o) Old نمایش داده نخواهد شد.

سیستم‌های BSD و لینوکس (BSD AND LINUX SYSTEMS)

در سیستم‌های جدیدتر BSD و لینوکس، Xman به دنبال فایلی به نام /etc/man.conf می‌گردد که حاوی فهرست دایرکتوری‌های شامل صفحات راهنما است. برای شرح کامل قالب این فایل، به man.conf(5) مراجعه کنید.

فایل MANDESC (THE MANDESC FILE)

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

قالب فایل mandesc شامل یک نویسه است که به دنبال آن یک برچسب می‌آید. نویسه مشخص می‌کند که کدام یک از بخش‌ها زیر این برچسب افزوده خواهند شد. به عنوان مثال، فرض کنید می‌خواهید یک آیتم منوی اضافی ایجاد کنید که شامل تمام زیرروال‌های برنامه‌نویس باشد. این برچسب باید شامل تمام صفحات راهنما در هر دو بخش دو و سه باشد. فایل mandesc بدین صورت خواهد بود:

2Programmer Subroutines
3Programmer Subroutines

این کار یک آیتم منو به منوی Sections اضافه می‌کند که فهرستی از تمامی صفحات راهنما در بخش‌های دو و سه Programmers Manual را نمایش می‌دهد. از آنجا که نام‌های برچسب‌ها دقیقاً یکسان هستند، به همان بخش اضافه خواهند شد. با این حال توجه داشته باشید که بخش‌های اصلی همچنان پابرجا خواهند بود.

اگر می‌خواهید بخش‌های پیش‌فرض را در یک دایرکتوری راهنما به‌طور کامل نادیده بگیرید، خط زیر را:

no default sections

در هر کجای فایل mandesc خود اضافه کنید. این کار مانع از جستجوی بخش‌های پیش‌فرض راهنما توسط xman فقط در آن دایرکتوری می‌شود. به عنوان مثال، فرض کنید می‌خواهید همان کار بالا را انجام دهید، اما به نظر شما وجود بخش‌های System Calls یا Subroutines دیگر مفید نیست. باید ورودی‌های پیش‌فرض را تکرار کرده و ورودی جدید خود را نیز اضافه کنید:

no default sections
1(1) User Commands
2Programmer Subroutines
3Programmer Subroutines
4(4) Devices
5(5) File Formats
6(6) Games
7(7) Miscellaneous
8(8) Sys. Administration
l(l) Local
n(n) New
o(o) Old

برنامه Xman هر بخشی را که به صورت man<character> باشد می‌خواند، که در آن <character> یک حرف بزرگ یا کوچک انگلیسی (به‌طور متمایز در نظر گرفته می‌شوند) یا یک رقم (0-9) است. با این حال هشدار داده می‌شود که man(1) و catman(8) دایرکتوری‌هایی را که غیراستاندارد باشند جستجو نخواهند کرد..SH "ویجت‌ها (WIDGETS)" برای تعیین منابع (resources)، دانستن سلسله‌مراتب ویجت‌هایی که xman را تشکیل می‌دهند مفید است. در نمادگذاری زیر، تورفتگی نشان‌دهندهٔ ساختار سلسله‌مراتبی است. ابتدا نام کلاس ویجت و به دنبال آن نام نمونهٔ (instance) ویجت آمده است.

Xman xman       (این ویجت هرگز استفاده نمی‌شود)
        TopLevelShell  topBox
                Form  form
                        Label  topLabel
                        Command  helpButton
                        Command  quitButton
                        Command  manpageButton
                TransientShell  search
                        DialogWidgetClass  dialog
                                Label  label
                                Text  value
                                Command  manualPage
                                Command  apropos
                                Command  cancel
                TransientShell  pleaseStandBy
                        Label  label
        TopLevelShell  manualBrowser
                Paned  Manpage_Vpane
                        Paned  horizPane
                                MenuButton  options
                                MenuButton  sections
                                Label  manualBrowser
                        Viewport  directory
                                List  directory
                                List  directory
                                .
                                . (یکی برای هر بخش،
                                .  که در لحظه ایجاد می‌شود)
                                .
                        ScrollByLine  manualPage
                SimpleMenu  optionMenu
                        SmeBSB  displayDirectory
                        SmeBSB  displayManualPage
                        SmeBSB  help
                        SmeBSB  search
                        SmeBSB  showBothScreens
                        SmeBSB  removeThisManpage
                        SmeBSB  openNewManpage
                        SmeBSB  showVersion
                        SmeBSB  quit
                SimpleMenu  sectionMenu
                        SmeBSB  <نام بخش>
                                .
                                . (یکی برای هر بخش)
                                .
                TransientShell  search
                        DialogWidgetClass  dialog
                                Label  label
                                Text  value
                                Command  manualPage
                                Command  apropos
                                Command  cancel
                TransientShell  pleaseStandBy
                        Label  label
                TransientShell  likeToSave
                        Dialog  dialog
                                Label  label
                                Text  value
                                Command  yes
                                Command  no
        TopLevelShell  help
                Paned  Manpage_Vpane
                        Paned  horizPane
                                MenuButton  options
                                MenuButton  sections
                                Label  manualBrowser
                        ScrollByLine  manualPage
                SimpleMenu  optionMenu
                        SmeBSB  displayDirectory
                        SmeBSB  displayManualPage
                        SmeBSB  help
                        SmeBSB  search
                        SmeBSB  showBothScreens
                        SmeBSB  removeThisManpage
                        SmeBSB  openNewManpage
                        SmeBSB  showVersion
                        SmeBSB  quit

منابع برنامه (APPLICATION RESOURCES)

برنامهٔ xman دارای منابع اختصاصی زیر است که امکان سفارشی‌سازی‌های منحصربه‌فرد برای xman را فراهم می‌کنند.

manualFontNormal (کلاس Font): قلم مورد استفاده برای متن عادی در صفحات راهنما.
manualFontBold (کلاس Font): قلم مورد استفاده برای متن پررنگ (bold) در صفحات راهنما.
manualFontItalic (کلاس Font): قلم مورد استفاده برای متن کج (italic) در صفحات راهنما.
directoryFontNormal (کلاس Font): قلم مورد استفاده برای متن دایرکتوری.
bothShown (کلاس Boolean): مقدار `true' یا `false'، مشخص می‌کند که آیا می‌خواهید هر دو بخش دایرکتوری و صفحهٔ راهنما در هنگام راه‌اندازی نمایش داده شوند یا خیر.
directoryHeight (کلاس DirectoryHeight): ارتفاع دایرکتوری بر حسب پیکسل، هنگامی که دایرکتوری و صفحهٔ راهنما به‌طور هم‌زمان نمایش داده می‌شوند.
topCursor (کلاس Cursor): مکان‌نمای مورد استفاده در کادر بالا (top box).
helpCursor (کلاس Cursor): مکان‌نمای مورد استفاده در پنجرهٔ راهنما.
manpageCursor (کلاس Cursor): مکان‌نمای مورد استفاده در پنجرهٔ صفحهٔ راهنما.
searchEntryCursor (کلاس Cursor): مکان‌نمای مورد استفاده در ویجت متنی ورودی جستجو.
pointerColor (کلاس Foreground): رنگ تمام مکان‌نماها (اشاره‌گرها) که در بالا مشخص شده‌اند. این نام برای سازگاری با xterm انتخاب شده است.
helpFile (کلاس File): استفاده از این مورد به‌جای فایل راهنمای پیش‌فرض سیستم.
topBox (کلاس Boolean): مقدار `true' یا `false'، تعیین می‌کند که در هنگام راه‌اندازی، کادر بالا (شامل دکمه‌های راهنما، خروج و صفحهٔ راهنما) روی صفحه نمایش داده شود یا یک صفحهٔ راهنما. مقدار پیش‌فرض true است.
verticalList (کلاس Boolean): مقدار `true' یا `false'، تعیین می‌کند که فهرست دایرکتوری به‌صورت عمودی سازمان‌دهی شود یا افقی. مقدار پیش‌فرض افقی (false) است..SH "کنش‌های سراسری (GLOBAL ACTIONS)" Xman تمام تعاملات کاربر را از طریق کنش‌های سراسری تعریف می‌کند. این امر به کاربر اجازه می‌دهد تا جدول ترجمه (translation table) هر ویجت را تغییر داده و هر رویدادی را به کنش جدید کاربر متصل کند. فهرست کنش‌های پشتیبانی‌شده توسط xman عبارت‌اند از:
GotoPage(page): هنگامی که در یک پنجرهٔ نمایش صفحه راهنما استفاده شود، به کاربر امکان می‌دهد میان نمایش دایرکتوری و صفحه راهنما جابه‌جا شود. آرگومان page می‌تواند Directory یا ManualPage باشد.
Quit(): این کنش می‌تواند در هر جایی استفاده شود و از xman خارج خواهد شد.
Search(type, action): تنها هنگامی که در پنجرهٔ بازشوی جستجو استفاده شود مفید است؛ این کنش باعث می‌شود ویجت جستجو نوع جستجوی مشخص‌شده را بر روی رشتهٔ موجود در ویجت مقدارِ پنجرهٔ جستجو انجام دهد. این کنش همچنین پنجرهٔ بازشوی جستجو را می‌بندد. آرگومان type می‌تواند Apropos، Manpage یا Cancel باشد. اگر برای action مقدار Open مشخص شده باشد، xman یک صفحه راهنمای جدید برای نمایش نتایج جستجو باز خواهد کرد، در غیر این صورت xman تلاش می‌کند نتایج را در والدِ پنجرهٔ بازشوی جستجو نمایش دهد.
PopupHelp(): این کنش می‌تواند در هر جایی استفاده شود و ویجت راهنما را به صورت بازشو نمایش می‌دهد.
PopupSearch(): این کنش می‌تواند در هر جایی به‌جز پنجرهٔ راهنما استفاده شود. این کنش باعث می‌شود پنجرهٔ بازشوی جستجو بر روی صفحه فعال و نمایان شود و به کاربر امکان جستجوی یک صفحه راهنما را می‌دهد.
CreateNewManpage(): این کنش می‌تواند در هر جایی استفاده شود و یک پنجرهٔ نمایش صفحه راهنمای جدید ایجاد می‌کند.
RemoveThisManpage(): این کنش می‌تواند در هر پنجرهٔ نمایش صفحه راهنما یا پنجرهٔ راهنما استفاده شود. هنگام فراخوانی، پنجره را حذف کرده و تمام منابع مرتبط با آن را پاک‌سازی می‌کند.
SaveFormattedPage(action): این کنش تنها می‌تواند در ویجت بازشوی likeToSave استفاده شود و به xman اعلام می‌کند که ذخیره‌سازی صفحه راهنمای تازه قالب‌بندی‌شده را Save (ذخیره) یا Cancel (لغو) کند.
ShowVersion(): این کنش می‌تواند از هر پنجرهٔ نمایش صفحه راهنما یا پنجرهٔ راهنما فراخوانی شود و باعث می‌شود خط نمایش اطلاعات، نسخهٔ کنونی xman را نشان دهد.

فایل‌ها (FILES)

<manpath directory>/man<character>
<manpath directory>/cat<character>
<manpath directory>/mandesc
/usr/share/X11/app-defaults/Xman: منابع مورد نیاز را مشخص می‌کند.
/tmp: برنامهٔ Xman فایل‌های موقت را در /tmp برای تمام صفحات راهنمای قالب‌بندی‌نشده و تمام جستجوهای apropos ایجاد می‌کند.

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

X(7), man(1), apropos(1), catman(8), Athena Widget Set

محیط (ENVIRONMENT)

DISPLAY: میزبان و نمایشگر پیش‌فرض برای استفاده.
MANPATH: مسیر جستجو برای صفحات راهنما. دایرکتوری‌ها با دو‌نقطه از یکدیگر جدا می‌شوند (مانند /usr/man:/mit/kit/man:/foo/bar/man).
XENVIRONMENT: برای دریافت نام فایل منبعی که منابع سراسری ذخیره‌شده در ویژگی RESOURCE_MANAGER را بازنویسی می‌کند.
XAPPLRESDIR: رشته‌ای که «Xman» به انتهای آن افزوده خواهد شد. این رشته مسیر کامل فایل app-defaults کاربر خواهد بود تا پس از فایل app-defaults سیستم و پیش از منابع متصل به نمایشگر، در پایگاه‌داده منابع ادغام شود.

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

کریس پیترسون (Chris Peterson)، کنسرسیوم MIT X بر اساس نسخهٔ V10 نوشته‌شده توسط بری شین (Barry Shein) سابقاً از دانشگاه بوستون. رفع باگ‌ها و پشتیبانی از لینوکس توسط کارلوس ای. ام. دوس سانتوس (Carlos A M dos Santos)، برای پروژهٔ The XFree86 Project.