.\" Copyright (c) 1987, 2025, Oracle and/or its affiliates.
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining a
.\" copy of this software and associated documentation files (the "Software"),
.\" to deal in the Software without restriction, including without limitation
.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
.\" and/or sell copies of the Software, and to permit persons to whom the
.\" Software is furnished to do so, subject to the following conditions:
.\"
.\" The above copyright notice and this permission notice (including the next
.\" paragraph) shall be included in all copies or substantial portions of the
.\" Software.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
.\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
.\" DEALINGS IN THE SOFTWARE.
.\"
.\" Copyright 1988, 1989, 1990, 1998  The Open Group
.\"
.\" Permission to use, copy, modify, distribute, and sell this software and its
.\" documentation for any purpose is hereby granted without fee, provided that
.\" the above copyright notice appear in all copies and that both that
.\" copyright notice and this permission notice appear in supporting
.\" documentation.
.\"
.\" The above copyright notice and this permission notice shall be included
.\" in all copies or substantial portions of the Software.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
.\" OTHER DEALINGS IN THE SOFTWARE.
.\"
.\" Except as contained in this notice, the name of The Open Group shall
.\" not be used in advertising or otherwise to promote the sale, use or
.\" other dealings in this Software without prior written authorization
.\" from The Open Group.
.\"
.de EX		\"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +.5i
..
.de EE
.fi
.in -.5i
.if n .sp 1
.if t .sp .5
..
.TH XMODMAP 1 "xmodmap 1.0.12" "X Version 11"
.SH "نام (NAME)"
xmodmap \- ابزاری برای تغییر نگاشت کلیدها و دکمه‌های اشاره‌گر در X
.SH "خلاصه دستور (SYNOPSIS)"
.B xmodmap
[\fI\-options\fP ...] [\fIfilename\fP]
.SH "توضیحات (DESCRIPTION)"
برنامهٔ \fBxmodmap\fP برای ویرایش و نمایش \fImodifier map\fP (نگاشت کلیدهای تغییردهنده) و \fIkeymap table\fP (جدول نگاشت کلید) صفحه‌کلید به کار می‌رود؛ سازوکارهایی که برنامه‌های کلاینت از آن‌ها برای تبدیل کدهای کلید (keycodes) ناشی از رویدادها به نمادهای کلید (keysyms) بهره می‌برند.
.PP
در نسخه‌های پیشین X11، این برنامه معمولاً از اسکریپت راه‌اندازی نشست (session) کاربر اجرا می‌شد تا صفحه‌کلید مطابق سلیقهٔ فردی پیکربندی شود. در نسخه‌های امروزی X11، بیشتر کاربردهای \fBxmodmap\fP برای اصلاح پیکربندی صفحه‌کلید، با استفاده از گزینه‌های XKB جایگزین شده است؛ چه از طریق گزینه‌های پیکربندی کارساز X، ترجیحات محیط رومیزی، یا استفاده از دستورهایی مانند
.BR setxkbmap (1).
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های زیر می‌توانند به همراه \fBxmodmap\fP استفاده شوند:
.TP 8
.B \-display \fIdisplay\fP
این گزینه میزبان و نمایشگر (display) مورد استفاده را مشخص می‌کند.
.TP 8
.B \-help
این گزینه مشخص می‌کند که توضیحی کوتاه دربارهٔ آرگومان‌های خط فرمان باید در خروجی خطای استاندارد چاپ شود. همچنین هر زمان که یک آرگومان پردازش‌نشده به
.B xmodmap
داده شود، این کار انجام خواهد شد.
.TP 8
.B \-grammar
این گزینه مشخص می‌کند که یک پیام راهنما در توصیف دستور زبان (grammar) عبارت‌های استفاده‌شده در فایل‌ها و عبارت‌های همراه با \-e باید در خطای استاندارد چاپ شود.
.TP 8
.B \-version
این گزینه مشخص می‌کند که
.B xmodmap
باید اطلاعات نسخهٔ خود را چاپ کرده و خارج شود.
.TP 8
.B \-verbose
این گزینه مشخص می‌کند که
.B xmodmap
باید اطلاعات گزارش‌گیری (logging) را هم‌زمان با تجزیهٔ ورودی خود چاپ کند.
.TP 8
.B \-quiet
این گزینه گزارش‌گیری پرحرف (verbose) را غیرفعال می‌کند. این حالت پیش‌فرض است.
.TP 8
.B \-n
این گزینه مشخص می‌کند که
.B xmodmap
نباید نگاشت‌ها را تغییر دهد، بلکه باید نمایش دهد چه کارهایی انجام خواهد داد؛ شبیه به کاری که دستور
.BR make (1)
هنگام دریافت این گزینه انجام می‌دهد.
.TP 8
.B \-e \fIexpression\fB
این گزینه عبارتی را برای اجرا تعیین می‌کند. می‌توان هر تعداد عبارت را از طریق خط فرمان مشخص کرد.
.TP 8
.B \-pm
این گزینه مشخص می‌کند که نگاشت کنونی کلیدهای تغییردهنده (modifier map) باید در خروجی استاندارد چاپ شود. اگر گزینهٔ حالت دیگری تعیین نشده باشد، این حالت پیش‌فرض اجرای برنامه است.
.TP 8
.B \-pk
این گزینه مشخص می‌کند که جدول کنونی نگاشت کلیدها (keymap table) باید در خروجی استاندارد چاپ شود.
.TP 8
.B \-pke
این گزینه مشخص می‌کند که جدول کنونی نگاشت کلیدها باید به شکل عبارت‌هایی که مجدداً قابلیت ارسال به
\fBxmodmap\fP
را دارند، در خروجی استاندارد چاپ شود.
.TP 8
.B \-pp
این گزینه مشخص می‌کند که نگاشت کنونی دکمه‌های اشاره‌گر (pointer map) باید در خروجی استاندارد چاپ شود.
.TP 8
.B \-
یک خط تیرهٔ تنها به این معناست که ورودی استاندارد باید به عنوان فایل ورودی استفاده شود.
.PP
آرگومان \fIfilename\fP فایلی حاوی عبارت‌های \fBxmodmap\fP را جهت اجرا تعیین می‌کند. این فایل معمولاً در دایرکتوری خانگی کاربر با نامی مانند
\fB.xmodmaprc\fP
نگهداری می‌شود..SH "دستور زبان عبارت‌ها (EXPRESSION GRAMMAR)"
برنامهٔ
.B xmodmap
فهرستی از عبارت‌ها را می‌خواند و پیش از اقدام به اجرای هر یک، تمامی آن‌ها را تجزیه می‌کند.
این ویژگی ارجاع به keysymهایی را که در حال بازتعریف هستند، به شکلی طبیعی و بدون نگرانی زیاد بابت تداخل نام‌ها ممکن می‌سازد.
.PP
فهرست نام‌های keysym را می‌توان در فایل سرآیند
\fB<X11/keysymdef.h>\fP
(بدون پیشوند \fBXK_\fP) یافت.
keysymهای منطبق با نویسه‌های یونیکد را می‌توان برای تمامی نویسه‌های ممکن یونیکد به‌صورت "U0020" تا "U007E" و "U00A0" تا "U10FFFF" مشخص کرد.
.TP 8
.B keycode \fINUMBER\fP = \fIKEYSYMNAME ...\fP
فهرست keysymها به keycode مشخص‌شده انتساب می‌یابد
(که می‌تواند در مبنای ده‌دهی، شانزده‌شانزدهی یا هشت‌هشتی مشخص شود و با اجرای برنامهٔ
.BR xev (1)
قابل تعیین است).
حداکثر تا هشت keysym را می‌توان به یک کلید متصل کرد،
با این حال چهار مورد آخر در هیچ پیاده‌سازی عمده‌ای از کارساز X استفاده نمی‌شوند.
نخستین keysym زمانی استفاده می‌شود که هیچ کلید تغییردهنده‌ای (modifier) هم‌زمان با این کلید فشرده نشود،
دومی همراه با Shift،
سومی زمانی که کلید Mode_switch به همراه این کلید استفاده شود،
و چهارمی زمانی که هر دو کلید Mode_switch و Shift به کار روند.
.TP 8
.B keycode any = \fIKEYSYMNAME ...\fP
اگر هیچ کلید موجودی فهرست keysymهای مشخص‌شده را به خود اختصاص نداده باشد،
یک کلید آزاد روی صفحه‌کلید انتخاب شده و keysymها به آن اختصاص داده می‌شوند.
فهرست keysymها را می‌توان در مبنای ده‌دهی، شانزده‌شانزدهی یا هشت‌هشتی مشخص کرد.
.TP 8
.B keysym \fIKEYSYMNAME\fP = \fIKEYSYMNAME ...\fP
عبارت \fIKEYSYMNAME\fP در سمت چپ به keycodeهای منطبق ترجمه می‌شود
تا برای اجرای مجموعه عبارت‌های متناظر \fBkeycode\fP به کار روند.
توجه داشته باشید که اگر یک keysym یکسان به چند کلید مقید شده باشد،
عبارت برای هر یک از keycodeهای منطبق اجرا خواهد شد.
.TP 8
.B clear \fIMODIFIERNAME\fP
تمام مدخل‌های موجود در نگاشت تغییردهنده (modifier map) را برای تغییردهندهٔ مشخص‌شده حذف می‌کند؛
نام‌های معتبر عبارتند از:
.BR Shift ،
.BR Lock ،
.BR Control ،
.BR Mod1 ،
.BR Mod2 ،
.BR Mod3 ،
.BR Mod4
و
.B Mod5
(بزرگی یا کوچکی حروف در نام‌های تغییردهنده اهمیتی ندارد،
اگرچه برای تمام نام‌های دیگر اهمیت دارد).
برای نمونه، «clear Lock» تمام کلیدهایی را که به تغییردهندهٔ shift lock مقید شده بودند، حذف خواهد کرد.
.TP 8
.B add \fIMODIFIERNAME\fP = \fIKEYSYMNAME ...\fP
تمام کلیدهای حاوی keysymهای مشخص‌شده را به نگاشت تغییردهندهٔ مورد نظر اضافه می‌کند.
نام‌های keysym پس از خوانده شدن تمام عبارت‌های ورودی ارزیابی می‌شوند
تا نوشتن عبارت‌ها برای جابه‌جایی کلیدها آسان گردد (بخش «مثال‌ها (EXAMPLES)» را ببینید).
.TP 8
.B remove \fIMODIFIERNAME\fP = \fIKEYSYMNAME ...\fP
تمام کلیدهای حاوی keysymهای مشخص‌شده را از نگاشت تغییردهندهٔ مورد نظر حذف می‌کند.
برخلاف
.BR add ،
نام‌های keysym به محض خوانده شدن خط ارزیابی می‌شوند.
این ویژگی به شما اجازه می‌دهد کلیدها را از یک تغییردهنده حذف کنید، بدون اینکه نگران بازتخصیص یافتن یا نیافتن آن‌ها باشید.
.TP 8
.B "pointer = default"
نگاشت اشاره‌گر (pointer map) را به تنظیمات پیش‌فرض آن بازمی‌گرداند (دکمهٔ ۱ کد ۱ تولید می‌کند، دکمهٔ ۲ کد ۲ و غیره).
.TP 8
.B pointer = \fINUMBER ...\fP
نگاشت اشاره‌گر را به گونه‌ای تنظیم می‌کند که شامل کدهای دکمهٔ مشخص‌شده باشد.
این فهرست همیشه با نخستین دکمهٔ فیزیکی آغاز می‌شود.
تنظیم کد یک دکمه روی 0، رویدادهای حاصل از آن دکمه را غیرفعال می‌کند.
.PP
خطوطی که با علامت تعجب (!) آغاز می‌شوند، به‌عنوان توضیح در نظر گرفته می‌شوند.
.PP
اگر می‌خواهید مقیدسازی (binding) یک کلید تغییردهنده را تغییر دهید، باید آن را از نگاشت تغییردهندهٔ مربوطه نیز حذف کنید..SH "مثال‌ها (EXAMPLES)"
بسیاری از اشاره‌گرها به‌گونه‌ای طراحی شده‌اند که دکمه اول با انگشت اشاره دست راست فشرده می‌شود.
افراد چپ‌دست معمولاً متوجه می‌شوند که معکوس کردن کدهای تولیدشده دکمه‌ها راحت‌تر است،
تا دکمه اصلی با انگشت اشاره دست چپ فشرده شود.
این کار را می‌توان در یک اشاره‌گر ۳ دکمه‌ای به شکل زیر انجام داد:
.EX
%  xmodmap \-e "pointer = 3 2 1"
.EE
.PP
بسیاری از برنامه‌ها از مفهوم کلیدهای Meta پشتیبانی می‌کنند
(مشابه کلیدهای Control، جز اینکه به‌جای Control، کلید Meta پایین نگه داشته می‌شود).
با این حال، برخی از سرورها فاقد یک keysym برای Meta در جدول نگاشت کلید پیش‌فرض هستند،
بنابراین باید یکی به‌صورت دستی اضافه شود.
دستور زیر Meta را به کلید Multi-language (که گاهی با برچسب Compose Character مشخص می‌شود) متصل می‌کند.
این دستور همچنین از این ویژگی بهره می‌برد که برنامه‌های نیازمند به کلید Meta
تنها باید keycode را دریافت کنند و نیازی ندارند که keysym در ستون اول جدول نگاشت کلید قرار داشته باشد.
این بدان معناست که برنامه‌هایی که به‌دنبال Multi_key هستند (از جمله نگاشت modifier پیش‌فرض)
متوجه هیچ تغییری نخواهند شد.
.EX
%  xmodmap \-e "keysym Multi_key = Multi_key Meta_L"
.EE
.PP
به‌طور مشابه، برخی صفحه‌کلیدها دارای کلید Alt هستند اما کلید Meta ندارند.
در این حالت، دستور زیر ممکن است مفید باشد:
.EX
%  xmodmap \-e "keysym Alt_L = Meta_L Alt_L"
.EE
.PP
یکی از کاربردهای ساده‌تر، و در عین حال کارآمد \fBxmodmap\fP، تنظیم کلید «rubout» (پاک‌کردن) صفحه‌کلید برای تولید یک keysym جایگزین است.
این عمل معمولاً شامل جابه‌جایی Backspace با Delete برای راحتی بیشتر کاربر است.
اگر منبع \fBttyModes\fP در
.BR xterm (1)
نیز تنظیم شده باشد،
تمام پنجره‌های شبیه‌ساز پایانه از همان کلید برای پاک کردن نویسه‌ها استفاده خواهند کرد:
.EX
%  xmodmap \-e "keysym BackSpace = Delete"
%  echo "XTerm*ttyModes:  erase ^?" | xrdb \-merge
.EE
.PP
برخی صفحه‌کلیدها هنگام فشرده شدن هم‌زمان Shift با کلیدهای ویرگول (comma) و نقطه (period)،
نویسه‌های کوچکتری و بزرگتری را به‌صورت خودکار تولید نمی‌کنند.
این مشکل را می‌توان در \fBxmodmap\fP با بازنشانی اتصالات ویرگول و نقطه با استفاده از اسکریپت‌های زیر برطرف کرد:
.EX
!
! make shift-, be < and shift-. be >
!
keysym comma = comma less
keysym period = period greater
.EE
.PP
یکی از تفاوت‌های آزاردهنده‌تر میان صفحه‌کلیدها، محل قرارگیری کلیدهای Control و CapsLock است.
یک کاربرد رایج \fBxmodmap\fP جابه‌جایی این دو کلید به‌صورت زیر است:
.EX
!
! Swap Caps_Lock and Control_L
!
remove Lock = Caps_Lock
remove Control = Control_L
keysym Control_L = Caps_Lock
keysym Caps_Lock = Control_L
add Lock = Caps_Lock
add Control = Control_L
.EE
.PP
این مثال را می‌توان مجدداً اجرا کرد تا کلیدها به وضعیت و تخصیص قبلی خود بازگردند.
.PP
دستور \fBkeycode\fP برای تخصیص یک keysym یکسان به چندین keycode مفید است.
اگرچه این دستور غیرقابل‌حمل (وابسته به سخت‌افزار) است، اما امکان نوشتن اسکریپت‌هایی را فراهم می‌کند
که می‌توانند وضعیت صفحه‌کلید را به یک حالت مشخص بازنشانی کنند.
اسکریپت زیر کلید Backspace را برای تولید Delete تنظیم می‌کند (همان‌طور که در بالا نشان داده شد)،
تمامی اتصالات فعلی Caps Lock را پاک می‌کند،
کلید CapsLock را به یک کلید Control تبدیل می‌کند،
کاری می‌کند که F5 نویسه Escape را تولید کند،
و Break/Reset را به یک Shift Lock تبدیل می‌نماید.
.EX
!
! On the HP, the following keycodes have key caps as listed:
!
!     101  Backspace
!      55  Caps
!      14  Ctrl
!      15  Break/Reset
!      86  Stop
!      89  F5
!
keycode 101 = Delete
keycode 55 = Control_R
clear Lock
add Control = Control_R
keycode 89 = Escape
keycode 15 = Caps_Lock
add Lock = Caps_Lock
.EE.SH "محیط (ENVIRONMENT)"
.TP 8
.B DISPLAY
برای دریافت نام میزبان پیش‌فرض و شماره نمایشگر.
.SH "همچنین ببینید (SEE ALSO)"
.BR X (7),
.BR xev (1),
.BR setxkbmap (1),
.BR XStringToKeysym (3),
مستندات \fIXlib\fP درباره رویدادهای کلید و نشانگر (pointer)
.SH "گزارش باگ‌ها (BUGS)"
هر بار که یک عبارت \fBkeycode\fP ارزیابی می‌شود،
کارساز یک رویداد \fBMappingNotify\fP برای تمام کلاینت‌ها تولید می‌کند.
این امر می‌تواند باعث کوبش (thrashing) شود.
تمام تغییرات باید به صورت دسته‌ای جمع‌آوری شده و یک‌باره اعمال شوند.
کلاینت‌هایی که ورودی صفحه‌کلید را دریافت کرده و رویدادهای \fBMappingNotify\fP را نادیده می‌گیرند،
متوجه هیچ‌یک از تغییرات اعمال‌شده در نگاشت‌های صفحه‌کلید نخواهند شد.
.PP
برنامه
.B Xmodmap
باید هر زمان که یک keycode که پیش‌تر به یک کلید تبدیلگر (modifier) مقید شده تغییر می‌کند،
عبارت‌های \fBadd\fP و \fBremove\fP را به صورت خودکار تولید کند.
.PP
باید راهی وجود داشته باشد تا عبارت
.B remove
بتواند علاوه بر keysymها، keycodeها را نیز برای مواقعی که نگاشت‌های خود را واقعاً
به‌هم می‌ریزید بپذیرد.
.SH "نویسندگان (AUTHORS)"
جیم فولتون (Jim Fulton)، MIT X Consortium، بازنویسی‌شده از یک نسخه قدیمی‌تر توسط
دیوید روزنتال (David Rosenthal) از Sun Microsystems.