keyd(1)                     General Commands Manual                    keyd(1)

نام (NAME)
       keyd - دیمن نگاشت مجدد کلیدها.

خلاصه دستور (SYNOPSIS)
       keyd [دستور] [گزینه‌ها]

دستورات (COMMANDS)
       monitor [-t]
           چاپ رویدادهای کلید. در صورت ارائه -t، زمان سپری‌شده از آخرین رویداد
           بر حسب میلی‌ثانیه را نیز چاپ می‌کند. برای یافتن نام کلیدها/شناسه
           دستگاه‌ها و اشکال‌زدایی کاربرد دارد.

       listen
           چاپ تغییرات وضعیت لایه‌های دیمن در حال اجرای keyd در خروجی استاندارد
           (stdout). برای اسکریپت‌نویسی بسیار مفید است.

       bind reset|<binding> [<binding>...]
           اعمال نگاشت‌های ارائه‌شده. برای جزئیات بخش Bindings را ببینید.

       reload
           بارگذاری مجدد فایل‌های پیکربندی.

       list-keys
           فهرست کردن نام‌های معتبر کلیدها.

       input [-t <timeout>] <text> [<text>...]
           تایپ یا وارد کردن متن ارائه‌شده. اگر هیچ آرگومانی داده نشود، ورودی
           را از STDIN می‌خواند.  می‌توان یک مهلت زمانی (timeout) اختیاری بر حسب
           میکروثانیه مشخص کرد که متناظر با فاصله زمانی بین رویدادهای ارسالی
           است.

       do [-t <timeout>] [<exp>]
           اجرای عبارت مشخص‌شده. برای قالب <exp> بخش MACROS را ببینید. اگر هیچ
           آرگومانی داده نشود، عبارت از STDIN خوانده می‌شود. در صورت ارائه،
           <timeout> متناظر با macro_sequence_timeout خواهد بود.

       check [<config file>...]
           اعتبارسنجی فایل‌های پیکربندی ارائه‌شده. اگر فایلی داده نشود، تمام
           فایل‌های موجود در دایرکتوری پیکربندی بررسی می‌شوند.  این دستور تنها
           در صورتی با کد بازگشتی غیرصفر خارج می‌شود که اعتبارسنجی حداقل یکی از
           فایل‌ها با شکست مواجه شود.

گزینه‌ها (OPTIONS)
       -v, --version
           چاپ نسخه فعلی و خروج.

       -h, --help
           نمایش راهنما و خروج.

توضیحات (DESCRIPTION)
       برنامه keyd یک دیمن سراسری سیستمی برای نگاشت مجدد کلیدها است که از
       قابلیت‌هایی نظیر لایه‌بندی (layering)، کلیدهای تبدیل تک‌ضربه‌ای (oneshot
       modifiers) و ماکروها پشتیبانی می‌کند. در پایه‌ای‌ترین شکل خود، می‌توان از
       آن برای تعریف یک چیدمان کلید سفارشی استفاده کرد که در سراسر سرورهای
       نمایش مختلف (مانند wayland/X/tty) پایدار و یکپارچه باقی می‌ماند.

       این برنامه در پیش‌زمینه اجرا می‌شود، اطلاعات عیب‌یابی را در جریان‌های خروجی
       استاندارد چاپ می‌کند و هدف آن اجرا شدن به عنوان یک نمونه واحد مدیریت‌شده
       توسط سیستم init است.

       نکته:

       از آنجا که keyd دستگاه ورودی اصلی شما را دستکاری می‌کند، ممکن است با یک
       فایل پیکربندی نادرست سیستم شما غیرقابل استفاده شود. اگر در چنین وضعیتی
       قرار گرفتید، توالی اضطراری (panic sequence) کلیدهای
       <backspace>+<escape>+<enter> دیمن keyd را مجبور به خروج فوری خواهد کرد.

پیکربندی (CONFIGURATION)
       فایل‌های پیکربندی تا حدودی از قالب فرمت INI پیروی می‌کنند که شامل بخش‌هایی
       به صورت [section_name] و به دنبال آن مجموعه‌ای از نگاشت‌ها (bindings)
       است. خطوطی که با علامت هش (#) شروع می‌شوند نادیده گرفته خواهند شد.

       فایل‌های پیکربندی در مسیر /etc/keyd/ ذخیره شده و در زمان راه‌اندازی
       بارگذاری می‌شوند.  از دستور reload می‌توان برای به‌روزرسانی مجموعه فعال
       فایل‌های پیکربندی استفاده کرد (مثلاً sudo keyd reload).

       یک فایل پیکربندی معتبر دارای پسوند .conf است و باید با یک بخش [ids]
       آغاز شود که یکی از فرم‌های زیر را داراست:

                [ids]

                <id 1 (obtained via keyd monitor)>
                <id 2>
                ...

       یا

                [ids]

                *
                -<id 1>
                -<id 2>
                ...

       فرم اول فهرستی از شناسه‌ها را برای تطبیق صریح مشخص می‌کند، در حالی که فرم
       دوم با هر شناسه‌ای که صراحتاً مستثنی نشده باشد تطبیق می‌یابد.

       برای مثال:

                [ids]
                *
                -0123:4567

       با تمام صفحه‌کلیدهایی که شناسه 0123:4567 را ندارند تطبیق می‌یابد، در حالی
       که:

                [ids]

                0123:4567

       منحصراً با دستگاه‌هایی که این شناسه را دارند تطبیق خواهد یافت. شناسه‌های
       دستگاه را می‌توان از دستور monitor به دست آورد (بخش COMMANDS را ببینید).
       توجه داشته باشید که هر شناسه دستگاه تنها می‌تواند در یک فایل پیکربندی
       فهرست شود.

       هر بخش بعدی فایل متناظر با یک لایه (layer) است (به استثنای بخش
       [global]، بخش GLOBALS را ببینید).

       خطاهای پیکربندی در خروجی لاگ نمایش داده می‌شوند و می‌توان به شیوه معمول
       با استفاده از مدیر سرویس سیستم به آن‌ها دسترسی پیدا کرد (مثلاً sudo
       journalctl -eu keyd).

       اگر یک شناسه با بیش از یک نوع دستگاه مطابقت داشته باشد، می‌توان از
       پیشوند k: برای تطبیق انحصاری صفحه‌کلیدها و از پیشوند m: برای تطبیق
       انحصاری ماوس‌ها استفاده کرد (مثلاً m:046d:b01d)

       نکته: تمام صفحه‌کلیدهای تعریف‌شده در یک فایل پیکربندی مشخص، وضعیت مشترکی
       خواهند داشت این ویژگی برای پیوند دادن دستگاه‌های ورودی جداگانه به یکدیگر
       (مانند پدال‌های پایی) بسیار کاربردی است.

       نکته ۲: نویسه عام (*) تنها با دستگاه‌هایی تطبیق می‌یابد که keyd آن‌ها را
       به عنوان صفحه‌کلید شناسایی کند.  همچنین keyd قادر به مدیریت ماوس‌ها نیز
       می‌باشد (مثلاً برای پاک کردن کلیدهای تبدیل تک‌ضربه‌ای هنگام کلیک)، اما
       شناسه‌های آن‌ها باید صراحتاً در لیست آورده شوند.

       نکته ۳: پشتیبانی از ماوس در حال حاضر آزمایشی است و عمدتاً به ماوس‌های
       سنتی (مثلاً تاچ‌پدها) محدود می‌شود اضافه کردن برخی از ماوس‌ها به بخش ids
       ممکن است نشانگر ماوس شما را دچار اختلال کند همچنین ممکن است لازم باشد
       ماوس‌هایی که به اشتباه به عنوان صفحه‌کلید شناسایی شده‌اند را صراحتاً در
       لیست سیاه قرار دهید (مثلاً اگر متوجه شدید ماوس شما رفتار نادرستی دارد)

   لایه‌ها (Layers)
       یک لایه مجموعه‌ای از نگاشت‌ها (bindings) است که هر کدام رفتار یک کلید خاص
       را مشخص می‌کنند چندین لایه می‌توانند در هر لحظه فعال باشند و پشته‌ای از
       نگاشت‌های پوشاننده را تشکیل دهند که به ترتیب فعال‌سازی بررسی می‌شوند لایه
       پیش‌فرض main نام دارد و نگاشت‌های عمومی باید در آن تعریف شوند

       به عنوان مثال، قطعه پیکربندی زیر لایه‌ای به نام nav تعریف می‌کند و یک
       سوئیچ تغییر وضعیت برای آن در لایه main ایجاد می‌نماید:

                [main]

                capslock = layer(nav)

                [nav]

                h = left
                k = up
                j = down
                l = right

       هنگامی که capslock نگه داشته شود، لایه nav روی لایه main قرار می‌گیرد و
       باعث می‌شود کلیدهای hjkl به عنوان کلیدهای جهت‌نمای متناظر عمل کنند.

       برخلاف اغلب ابزارهای نگاشت مجدد، keyd پشتیبانی درجه‌یکی از کلیدهای تبدیل
       (modifiers) فراهم می‌کند نام یک لایه می‌تواند به صورت اختیاری با یک ':'
       همراه با مجموعه‌ای از کلیدهای تبدیل که در صورت نبود نگاشت صریح شبیه‌سازی
       می‌شوند خاتمه یابد نام لایه‌ها حداکثر می‌تواند شامل ۶۴ نویسه باشد (شامل
       تمام کلیدهای تبدیل).

       این لایه‌ها به خوبی با سایر کلیدهای تبدیل هماهنگ شده و معناشناسی
       پشته‌بندی موجود را حفظ می‌کنند

       برای مثال:

                [main]

                capslock = layer(capslock)

                [capslock:C]

                j = down

       باعث می‌شود کلید capslock مانند control رفتار کند، به جز در مورد ترکیب
       capslock+j که کلید down را ارسال می‌کند این امر تعریف کلیدهای تبدیل
       سفارشی را که با یکدیگر تداخل ندارند بسیار ساده می‌سازد.

       توجه داشته باشید که نگاشت‌ها تحت تأثیر کلیدهای تبدیل لایه‌ای که در آن
       تعریف شده‌اند قرار نمی‌گیرند بنابراین ترکیب capslock+j یک فشرده شدن کلید
       down بدون تغییر تولید می‌کند، در حالی که shift+capslock+j همان‌طور که
       انتظار می‌رود shift+down تولید خواهد کرد.

       به صورت رسمی، سربرگ هر لایه دارای فرم زیر است:

                "[" <layer name>[:<modifier set>] "]"

       که در آن <modifier_set> دارای فرم زیر است:

           <modifier1>[-<modifier2>]...

       و هر کلید تبدیل یکی از موارد زیر است:

           C - کلید Control
           M - کلید Meta/Super
           A - کلید Alt
           S - کلید Shift
           G - کلید AltGr

       در نهایت، هر سربرگ لایه با مجموعه‌ای از نگاشت‌ها دنبال می‌شود که ساختار
       زیر را دارند:

           <key> | <alias> = <key>|<macro>|<action>

       برای توضیح <action> و <macro> بخش‌های ACTIONS و MACROS را ببینید.

       به طور پیش‌فرض، هر کلید در لایه اصلی به خود متصل است استثنای این قاعده
       کلیدهای تبدیل هستند که به جای آن به لایه‌هایی هم‌نام با کلیدهای تبدیل
       متناظر متصل شده‌اند

       برای مثال، کلید meta در واقع به layer(meta) متصل است، جایی که meta در
       داخل برنامه به عنوان meta:M تعریف شده است.

       مجموعه کامل نگاشت‌های کلیدهای تبدیل به صورت زیر است:

                control = layer(control)
                meta = layer(meta)
                shift = layer(shift)
                leftalt = layer(alt)
                rightalt = layer(altgr)

       پیامد این امر این است که بازنویسی کلیدهای تبدیل صرفاً با اضافه کردن
       نگاشت‌های دلخواه به لایه از پیش تعریف‌شده مناسب به راحتی امکان‌پذیر است.

       بنابراین:

                [ids]
                *

                [control]
                j = down

       یک فایل پیکربندی کاملاً معتبر است و دقیقاً همان کاری را انجام می‌دهد که
       کاربر انتظار دارد در داخل سیستم، پیکربندی کامل در واقع شبیه به این است:

                [ids]
                *

                [main]
                leftcontrol = layer(control)
                rightcontrol = layer(control)

                [control:C]
                j = down

       اگر چندین نگاشت برای یک کلید یکسان وجود داشته باشد، نگاشتی که دیرتر
       آمده اولویت خواهد داشت.

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

       یعنی:

           [mylayer:A]
           a = b
           c = d

           [mylayer:C]
           a = x
           b = c

       معادل است با:

           [mylayer:A]
           a = x
           b = c
           c = d

   لایه‌های ترکیبی (Composite Layers)
       نوع خاصی از لایه با نام لایه ترکیبی (composite layer) را می‌توان با
       ایجاد لایه‌ای با نامی متشکل از لایه‌های موجود که با علامت + از هم جدا
       شده‌اند تعریف کرد لایه حاصل زمانی فعال شده و اولویت می‌یابد که تمام اجزای
       تشکیل‌دهنده آن فعال باشند لایه‌های ترکیبی مجاز به داشتن کلیدهای تبدیل
       متصل نیستند و نمی‌توان آن‌ها را به صورت صریح انتساب داد.

       برای مثال:

                [control+alt]
                h = left

       باعث می‌شود توالی control+alt+h کلید left را تولید کند (با نادیده گرفتن
       کلیدهای تبدیل control و alt متصل به لایه‌های فعال control و alt)، در
       حالی که فشردن control+alt+f1 آن کلیدهای تبدیل را حفظ کرده و دقیقاً همان
       چیزی را که فشرده شده ارسال می‌کند، زیرا نگاشت صریحی برای f1 در لایه
       ترکیبی وجود ندارد.

                [main]
                capslock = layer(capslock)

                [capslock:C]

                [capslock+shift]
                h = left

       باعث می‌شود توالی capslock+shift+h کلید left را تولید کند، در حالی که
       عملکرد مورد انتظار capslock و shift را در حالت مجزا حفظ می‌نماید.

       نکته: لایه‌های ترکیبی باید همیشه بعد از لایه‌هایی که از آن‌ها تشکیل شده‌اند
       تعریف شوند.

       یعنی:

           [layer1]
           [layer2]
           [layer1+layer2]

       و نه:

           [layer1+layer2]
           [layer1]
           [layer2]

   چیدمان‌ها (Layouts)
       چیدمان (layout) نوع خاصی از لایه است که برای اصلاح کلیدهای الفبایی در
       نظر گرفته شده است برخلاف لایه‌ها، چیدمان‌ها نمی‌توانند کلید تبدیل مرتبطی
       داشته باشند، و تنها یک چیدمان می‌تواند در هر لحظه فعال باشد چیدمان
       پیش‌فرض 'main' نام دارد و می‌توان آن را با استفاده از کنش setlayout()
       تغییر داد.

       جهت سهولت، keyd همراه با تعدادی از چیدمان‌های حروف پرکاربرد در مسیر
       /usr/share/keyd/layouts عرضه می‌شود قبل از اضافه کردن آن‌ها، بررسی
       محتوایشان آموزنده است چیدمان‌های غیرانگلیسی شامل یک لایه shift اختصاصی
       هستند (که ترتیب شمول را مهم می‌سازد) و نیاز به استفاده از تعاریف compose
       در keyd دارند (بخش پشتیبانی از یونیکد (Unicode Support) را ببینید)

       برای مثال:

           # Include the shipped colemak layout.
           include layouts/colemak

           [global]
           default_layout = mylayout

           [mylayout:layout]
           a = b
           b = c
           #etc...

           [control]
           1 = setlayout(customlayout)
           2 = setlayout(colemak)

   آکوردگذاری (Chording)
       آکوردها (Chords) گروه‌هایی از کلیدها هستند که هنگام فشرده شدن هم‌زمان به
       عنوان یک واحد تلقی می‌شوند یک آکورد را می‌توان با استفاده از گروهی از
       نام‌های کلید جداشده با + به عنوان مقدار سمت چپ تعریف کرد در صورتی که همه
       کلیدها در بازه زمانی آکورد (chord_timeout) فشرده شوند، کنش متناظر فعال
       خواهد شد.

       برای مثال:

           j+k = esc

       باعث می‌شود در صورت فشرده شدن هم‌زمان هر دوی j و k، کلید esc ارسال شود.

       نکته: ممکن است برای تطابق با ویژگی‌های فیزیکی صفحه‌کلید خود بخواهید بازه
       زمانی پیش‌فرض آکوردگذاری (50 میلی‌ثانیه) را تغییر دهید.

   پشتیبانی از یونیکد (Unicode Support)
       اگر keyd با یک توالی معتبر UTF8 به عنوان مقدار سمت راست مواجه شود، تلاش
       می‌کند آن توالی را به یک ماکرو که توالی XKB مخصوص keyd را ارسال می‌کند
       ترجمه کند.

       برای اینکه این قابلیت کار کند، توالی‌های تعریف‌شده در فایل compose
       ارائه‌شده همراه با keyd (/usr/share/keyd/keyd.compose) باید در دسترس
       باشند این کار را می‌توان به صورت سراسری با کپی کردن فایل در مکان مناسب
       در /usr/share/X11/locale یا برای هر کاربر به طور جداگانه با ایجاد یک
       پیوند نمادین به ~/.XCompose انجام داد.

       برای مثال:

           ln -s /usr/share/keyd/keyd.compose ~/.XCompose

       علاوه بر این، شما باید از چیدمان پیش‌فرض US در سرور نمایش خود استفاده
       کنید. به کاربران چیدمان‌های غیرانگلیسی توصیه می‌شود چیدمان خود را درون
       keyd تنظیم کنند (بخش Layouts را ببینید) تا از تداخل بین چیدمان سرور
       نمایش و قابلیت‌های یونیکد keyd جلوگیری شود.

       نکته: ممکن است برای اعمال تغییرات لازم باشد برنامه‌های خود را مجدداً
       راه‌اندازی کنید.

       نکته ۲: توالی‌های compose تولیدشده طبق معمول تحت تأثیر کلیدهای تبدیل
       قرار می‌گیرند اگر می‌خواهید shift نماد متفاوتی تولید کند، باید یک لایه
       shift سفارشی تعریف کنید (برای نمونه فایل‌های چیدمان همراه برنامه را
       ببینید).

       نکته ۳: کتابخانه GTK4 در حال حاضر دارای باگی است که باعث می‌شود در صورت
       وجود فایل‌های بزرگ XCompose (مانند /usr/share/keyd/keyd.compose) دچار
       کرش شود.

   نام‌های مستعار (Aliases)
       به هر کلید می‌توان به صورت اختیاری یک نام مستعار (alias) اختصاص داد این
       نام مستعار می‌تواند به جای کلید به عنوان یک مقدار معتبر در سمت چپ نگاشت
       استفاده شود چندین کلید را می‌توان به یک نام مستعار یکسان متصل کرد، اما
       در هر زمان تنها یک نام مستعار را می‌توان به یک کلید اختصاص داد.

       به عنوان مثال، کلیدهای 'leftmeta' و 'rightmeta' به صورت پیش‌فرض به نام
       مستعار meta متصل شده‌اند بنابراین نگاشت 'meta = a' معادل با نگاشت‌های
       'leftmeta = a' و 'rightmeta = a' است.

       نام‌های مستعار در بخش ویژه‌ای به نام 'aliases' تعریف می‌شوند که هر خط آن
       دارای ساختار زیر است:

           <key> = <name>

       که در آن <key> باید یک نام کلید معتبر باشد.

       توجه داشته باشید که <name> خود می‌تواند یک نام کلید معتبر باشد، که در
       این صورت تمام ارجاعات به آن کلید در فایل پیکربندی با کلید جدید جایگزین
       می‌شوند علاوه بر این، اگر نام مستعار اختصاص‌داده‌شده یک نام کلید معتبر
       باشد، کد کلید (keycode) متناظر به طور پیش‌فرض به آن کلید اختصاص می‌یابد
       این امر بازتعریف کلیدها را قبل از اعمال هرگونه نگاشت ممکن می‌سازد و به
       ویژه در ترکیب با سازوکار include برای هماهنگی با تفاوت‌های سخت‌افزاری
       بسیار کاربردی است.

       برای مثال:

           /etc/keyd/common:
                meta = oneshot(meta)
                alt = oneshot(alt)

                a = a
                s = o
                # etc..

           /etc/keyd/default.conf:
                [ids]
                *

                [main]
                include common

           /etc/keyd/magic_keyboard.conf:
                [ids]
                004c:0267

                [aliases]
                leftalt = meta
                rightalt = meta
                rightmeta = alt
                leftmeta = alt

                [main]
                include common

       به کاربر اجازه می‌دهد مجموعه‌ای از نگاشت‌های سراسری را در /etc/keyd/common
       تعریف کند بدون اینکه نیازی باشد جابه‌جایی کلیدهای meta و alt را صراحتاً
       درون قطعه پیکربندیِ شامل‌شده در نظر بگیرد.

   شامل‌سازی فایل (File Inclusion)
       فایل‌های پیکربندی می‌توانند فایل‌های دیگر واقع در دایرکتوری پیکربندی را با
       استفاده از کلمه کلیدی include شامل شوند خطی به فرم include <file>
       می‌تواند در هر نقطه‌ای پس از بخش [ids] ظاهر شود پیکربندی حاصل طوری عمل
       خواهد کرد که گویی محتوای فایل شامل‌شده به جای عبارت include قرار گرفته
       است.

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

       مسیرهای include نسبی هستند و باید در یکی از دایرکتوری‌های زیر قرار داشته
       باشند:

           •   /etc/keyd/
           •   /usr/share/keyd/

       برای مثال:

           /etc/keyd/default.conf:
                [ids]
                *

                # Add our shared custom bindings.
                include common

                # Appends bindings to the main layer
                # defined in /etc/keyd/common (order matters)
                [main]
                capslock = layer(capslock)

                [capslock]
                1 = setlayout(colemak)
                2 = setlayout(dvorak)

           /etc/keyd/common:
                [main]

                rightmeta = layer(nav)

                [nav]

                h = left
                j = down
                k = up
                l = right

           /usr/share/keyd/layouts/dvorak:
                a = a
                s = o
                ...


       محدودیت‌ها:

           •   تمام عبارات include باید بعد از بخش [ids] در فایل اصلی ظاهر
               شوند.
           •   فایل‌های شامل‌شده نباید حاوی بخش ids باشند.
           •   فایل‌های شامل‌شده نباید فایل‌های دیگر را شامل شوند (شامل‌سازی
               غیربازگشتی است).
           •   فایل‌های شامل‌شده نباید با پسوند .conf خاتمه یابند.


تنظیمات عمومی (GLOBALS)
       بخش ویژه‌ای به نام [global] می‌تواند در فایل تعریف شود و می‌تواند حاوی هر
       یک از گزینه‌های زیر باشد:

           macro_timeout: زمان (بر حسب میلی‌ثانیه) بین اجرای اولیه توالی ماکرو
           و اولین تکرار آن (پیش‌فرض: 600)

           macro_repeat_timeout: زمان بین اجراهای متوالی یک ماکرو (پیش‌فرض: 50)

           layer_indicator: در صورت فعال بودن، هر زمان که یک لایه فعال باشد
           چراغ capslock را روشن می‌کند نکته: برخی کامپوزیتورهای wayland وضعیت
           LED را به شدت تغییر می‌دهند که این گزینه را غیرقابل استفاده می‌کند

           (پیش‌فرض: 0)

           macro_sequence_timeout: در صورت تنظیم، یک وقفه زمانی (بر حسب
           میکروثانیه) بین هر کلید ارسالی در یک توالی ماکرو اضافه می‌کند این
           گزینه برای جلوگیری از سرریز شدن بافر ورودی در برخی سیستم‌ها کاربرد
           دارد

           chord_timeout: حداکثر زمان بین کلیدهای متوالی که به عنوان بخشی از
           یک آکورد تفسیر می‌شوند (پیش‌فرض: 50)

           chord_hold_timeout: مدت زمانی که یک آکورد باید نگه داشته شود تا
           فعال گردد (پیش‌فرض: 0)

           oneshot_timeout: در صورت غیرصفر بودن، فعال‌سازی لایه تک‌ضربه‌ای
           (oneshot) پس از تعداد میلی‌ثانیه مشخص‌شده منقضی می‌شود (پیش‌فرض: 0)

           disable_modifier_guard: به طور پیش‌فرض، keyd فشردن کلیدهای اضافی
           control را در صورت نیاز تزریق می‌کند تا از دیدن فشردن‌های کوتاه کلید
           تبدیل توسط برنامه‌ها جلوگیری کند (مثلاً alt در firefox) در صورت
           تنظیم، این گزینه آن رفتار را غیرفعال می‌کند (پیش‌فرض: 0)

           overload_tap_timeout: در صورت غیرصفر بودن، اگر کلید سربارگذاری‌شده
           به مدت تعداد میلی‌ثانیه مشخص‌شده نگه داشته شود، رفتار ضربه زدن (tap)
           آن نادیده گرفته می‌شود (پیش‌فرض: 0)

       نکته: نویسه‌های یونیکد و توالی‌های کلید به عنوان ماکرو تلقی می‌شوند و در
       نتیجه تحت تأثیر گزینه‌های وقفه زمانی متناظر قرار می‌گیرند.

ماکروها (MACROS)
       کنش‌های مختلف keyd عبارت‌های ماکرو را می‌پذیرند.

       یک عبارت ماکرو یکی از فرم‌های زیر را داراست:

           1.   macro(<exp>)
           2.   [<modifier 1>[-<modifier 2>...]-<key>
           3.   <char>


       که در آن <char> یک نویسه معتبر یونیکد است و <exp> دارای فرم <token1>
       [<token2>...] می‌باشد و هر نشانه (token) یکی از موارد زیر است:

           •   یک کد کلید معتبر.
           •   یک ماکرو از نوع ۲.
           •   یک گروه پیوسته از نویسه‌های یونیکد.
           •   گروهی از کدهای کلید جداشده با + که به عنوان یک واحد فشرده
               می‌شوند.
           •   یک وقفه زمانی به فرم <time>ms (که در آن <time> < 1024).


       موارد زیر همگی عبارت‌های ماکروی معتبر هستند:

           •   C-a
           •   macro(C-a)
           •   macro(leftcontrol+leftmeta) # هم‌زمان کلیدهای left meta و left
               control را فشار داده و رها می‌کند
           •   A-M-x
           •   macro(Hello space World)
           •   macro(h e l l o space w o r ld) (کاملاً یکسان با عبارت بالا)
           •   macro(C-t 100ms google.com enter)


       تقسیم به نشانه‌های کوچک‌تر به عنوان سازوکار گریز (escaping) عمل می‌کند:
       macro(space) یک فاصله خالی درج می‌کند اما macro(s pace) کلمه "space" را
       می‌نویسد. به همین ترتیب، macro(3+5) کلیدهای 3 و 5 را به عنوان یک واحد
       می‌فشارد در حالی که macro(3 + 5) عبارت "3+5" را می‌نویسد.

       برای کارکرد نویسه‌های غیر-ASCII پیش‌نیازهایی لازم است؛ بخش پشتیبانی از
       یونیکد (Unicode Support) را ببینید.

کنش‌ها (ACTIONS)
       یک کلید می‌تواند به صورت اختیاری به یک کنش (action) متصل شود که صفر یا
       چند آرگومان می‌پذیرد.

       layer(<layer>)
           فعال‌سازی لایه داده‌شده در مدت زمان فشرده بودن کلید.

       oneshot(<layer>)

           در صورت ضربه زدن (tap)، لایه ارائه‌شده را برای مدت فشرده شدن کلید
           بعدی فعال می‌کند.

       swap(<layer>)
           تعویض لایه فعال کنونی با لایه ارائه‌شده. اگر لایه فعلی سوئیچ‌شده
           (toggled) باشد، غیرفعال شده و لایه ارائه‌شده به جای آن سوئیچ می‌شود
           در غیر این صورت، لایه فعال غیرفعال شده و لایه ارائه‌شده برای مدت
           زمان فشرده بودن کلیدِ فعال‌کننده فعال باقی می‌ماند رفتار این کنش برای
           لایه‌های ترکیبی تعریف‌نشده است.

                [control]

                x = swap(xlayer)

                [xlayer]

                s = C-s
                b = S-insert

           نکته:

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

       setlayout(<layout>)
           تنظیم چیدمان فعلی.

       clear()
           پاک کردن تمام لایه‌های سوئیچ‌شده یا تک‌ضربه‌ای (oneshot).

       toggle(<layer>)
           تغییر وضعیت دائمی (toggle) لایه داده‌شده.

       layerm(<layer>, <macro>)
           کاملاً یکسان با layer، اما ماکروی ارائه‌شده را قبل از تغییر لایه اجرا
           می‌کند.

       oneshotm(<layer>, <macro>)
           کاملاً یکسان با oneshot، اما ماکروی ارائه‌شده را قبل از تغییر لایه
           اجرا می‌کند.

       oneshotk(<layer>, <key>)
           کاملاً یکسان با oneshot، اما در زمان نگه داشته شدن به عنوان کلید
           ارائه‌شده نیز عمل می‌کند این کنش عمدتاً برای تغییر موقت رفتار کلیدهای
           الفبایی بلافاصله متوالی کاربرد دارد.

       swapm(<layer>, <macro>)
           کاملاً یکسان با swap، اما ماکرویی را می‌پذیرد که بلافاصله پس از تغییر
           لایه اجرا شود.

       togglem(<layer>, <macro>)
           معادل با toggle، اما علاوه بر آن ماکروی ارائه‌شده را قبل از سوئیچ
           لایه اجرا می‌کند.

       clearm(<macro>)
           کاملاً یکسان با clear، اما ماکروی ارائه‌شده را قبل از پاک کردن لایه‌ها
           اجرا می‌کند.

       repeat()
           تکرار آخرین توالی کلید یا ماکرو.

   سربارگذاری کلید (Key overloading)
       overload(<layer>, <action>)
           لایه داده‌شده را هنگام نگه داشتن فعال می‌کند و در صورت ضربه زدن،
           <action> را اجرا می‌نماید.

       overloadt(<layer>, <action>, <timeout>)
           یکسان با overload، اما تنها در صورتی لایه را فعال می‌کند که کلید
           متصل به مدت <timeout> میلی‌ثانیه نگه داشته شود این قابلیت عمدتاً برای
           سربارگذاری کلیدهایی که معمولاً به صورت متوالی فشرده می‌شوند (مانند
           کلیدهای الفبا) کاربرد دارد.

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

       overloadt2(<layer>, <action>, <timeout>)
           یکسان با overloadt، اما علاوه بر آن در صورت فشرده شدن یک کلید دیگر
           در این فاصله، فوراً به عنوان حالت نگه‌داشتن (hold) تفسیر می‌شود.

       overloadi(<action 1>, <action 2>, <idle timeout>)
           در صورتی که آخرین کلید غیرکنش (یعنی نماد یا نویسه) کمتر از
           <timeout> میلی‌ثانیه پیش فشرده شده باشد، <action 1> را فعال می‌کند،
           در غیر این صورت <action 2> را فعال می‌نماید.

           این قابلیت را می‌توان در ترکیب با سایر مهلت‌های زمانی overload
           استفاده کرد و به ویژه برای سربارگذاری کلیدهای الفبا (که اغلب
           'homerow mods' نامیده می‌شوند) بسیار مفید است.

           برای مثال:

                a = overloadi(a, overloadt2(control, a, 200), 150)

           کلید a را تنها و تنها در صورتی تولید می‌کند که:

               •   کلید a در فاصله کمتر از ۱۵۰ میلی‌ثانیه پس از یک کلید غیرکنش
                   دیگر فشرده شود.
               •   کلید a بیش از ۱۵۰ میلی‌ثانیه پس از آخرین کلید غیرکنش فشرده
                   شود اما برای کمتر از ۲۰۰ میلی‌ثانیه نگه داشته شود و کلید
                   دیگری در این بین فشرده نشود.


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

           از آنجا که این یک مورد کاربردی بسیار رایج است، ماکرویی به نام
           lettermod (که در زیر تعریف شده) برای تسهیل چنین تعاریفی ایجاد شده
           است.

       lettermod(<layer>, <key>, <idle timeout>, <hold timeout>)
           یک نام مستعار برای:

               overloadi(<key>, overloadt2(<layer>, <key>, <hold timeout>),
               <idle timeout>)

       timeout(<action 1>, <timeout>, <action 2>)
           اگر هیچ رویداد کلیدی در بازه زمانی <timeout> ms رخ ندهد، <action1>
           را اجرا می‌کند، در غیر این صورت <action2> را اجرا می‌نماید.

           برای مثال:

           timeout(a, 500, layer(control))

           باعث می‌شود کلید اختصاص‌داده‌شده در صورتی که بیش از ۵۰۰ میلی‌ثانیه بدون
           فشرده شدن هیچ کلید دیگری در این بازه نگه داشته شود، مانند control
           رفتار کند.

           نکته: این یک گزینه قدیمی با پیامدهای ظریف متعدد است این گزینه عمدتاً
           برای استفاده در ترکیب با کنش‌های دیگر به منظور دستیابی به مواردی که
           به شیوه دیگر ممکن نیست در نظر گرفته شده است اغلب کاربران ترجیح
           می‌دهند از یکی از توابع overload برای رفتار ساده ضربه/نگه‌داشتن
           استفاده کنند.

       macro2(<timeout>, <repeat timeout>, <macro>)
           یک ماکرو با مهلت زمانی و زمان تکرار داده‌شده ایجاد می‌کند اگر مقدار
           مهلت زمانی 0 استفاده شود، تکرار ماکرو غیرفعال می‌شود.

           توجه داشته باشید که <macro> باید یک عبارت ماکروی معتبر باشد.

           برای مثال:
                macro2(400, 50, macro(Hello space World))
                macro2(120, 80, left)
       command(<shell command>)
           دستور شل داده‌شده را اجرا می‌کند.

           برای مثال:

           command(brightness down)

       نکته: دستورات توسط کاربری که فرآیند keyd را اجرا کرده است (احتمالاً
       root) اجرا می‌شوند، از این قابلیت با احتیاط فراوان استفاده کنید.

       noop
           هیچ کاری انجام نده.

ارتباط بین‌پردازشی (IPC)
       برای تسهیل قابلیت توسعه، keyd از یک مدل کلاینت-سرور قابل دسترسی از طریق
       گزینه -e استفاده می‌کند بنابراین نگاشت کلید را می‌توان به عنوان یک
       موجودیت زنده تصور کرد که در زمان اجرا قابل تغییر است.

       علاوه بر اینکه این امکان به کاربر داده می‌شود تا نگاشت‌های جدید را در
       لحظه امتحان کند، به کاربر اجازه می‌دهد تا بدون افت عملکرد، از قدرت
       بیانگری keyd در سایر برنامه‌ها به طور کامل بهره‌مند شود.

       به عنوان مثال، کاربر می‌تواند از این قابلیت برای نوشتن اسکریپتی استفاده
       کند که هنگام جابه‌جایی بین نشست‌های مختلف tmux، نگاشت کلید را تغییر دهد.

       ابزار نگاشت مجدد برنامه‌ها (keyd-application-mapper(1)) که همراه با keyd
       ارائه می‌شود، نمونه بارزی از این کاربرد است این ابزار یک اسکریپت پایتون
       کوچک است که تشخیص رویدادها را برای سرورهای نمایش مختلف (مانند
       X/sway/gnome و غیره) انجام می‌دهد و نگاشت‌های مورد نظر را با استفاده از
       -e به هسته دیمن ارسال می‌کند.

       نکته: کاربرانی که به سوکت keyd دسترسی دارند باید به عنوان کاربر ممتاز
       در نظر گرفته شوند (یعنی فرض می‌شود به کل سیستم دسترسی دارند).

   نگاشت‌ها (Bindings)
       دستور bind یک یا چند نگاشت (binding) را می‌پذیرد که هر یک باید ساختار
       زیر را داشته باشند:

           [<layer>.]<key> = <key>|<macro>|<action>

       که در آن <layer> نام یک لایه (موجود) است که کلید باید در آن نگاشت شود.

       به عنوان یک حالت خاص، رشته "reset" می‌تواند به جای یک نگاشت استفاده شود،
       که در این حالت نگاشت کلید فعلی به وضعیت اولیه خود بازمی‌گردد (تمام
       نگاشت‌های اعمال‌شده به صورت پویا لغو خواهند شد).

       مثال‌ها:

                $ keyd bind '- = C-c'
                $ keyd bind reset '+ = C-c' # Reset the keyboard before applying the '+' binding (drops the previous '-' binding)

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

مثال‌ها (EXAMPLES)
   مثال ۱
       تغییر وضعیت چیدمان حروف dvorak با فشردن ترکیب esc+q.

                [ids]
                *

                [main]
                esc = layer(esc)

                [dvorak]

                a = a
                s = o
                ...

                [esc]

                q = toggle(dvorak)

   مثال ۲
       معکوس کردن رفتار کلید shift بدون برهم زدن رفتار کلید تبدیل.

                [ids]
                *

                [main]
                1 = !
                2 = @
                3 = #
                4 = $
                5 = %
                6 = ^
                7 = &
                8 = *
                9 = (
                0 = )

                [shift]
                0 = 0
                1 = 1
                2 = 2
                3 = 3
                4 = 4
                5 = 5
                6 = 6
                7 = 7
                8 = 8
                9 = 9

   مثال ۳
       یک بار ضربه زدن به کلید control باعث اعمال آن روی کلید بعدی می‌شود، دو
       بار ضربه زدن آن را تا زمانی که دوباره فشرده شود فعال نگه می‌دارد، و نگه
       داشتن آن رفتار مورد انتظار را ایجاد می‌کند.

                [main]

                control = oneshot(control)

                [control]

                control = toggle(control)

   مثال ۴
       کلید Meta رفتار عادی دارد مگر زمانی که کلید ` فشرده شود، که پس از آن
       لایه alt_tab در طول مدت فشردن leftmeta فعال می‌شود بنابراین فشردن‌های
       بعدی به جای M-\ کلید A-tab را تولید خواهند کرد.

                [meta]

                ` = swap(alt_tab, A-tab)

                [alt_tab:A]

                tab = A-S-tab
                ` = A-tab

   مثال ۵
                # Uses the compose key functionality of the display server to generate
                # international glyphs.  # For this to work 'setxkbmap -option  compose:menu'
                # must be run after keyd has started (see NOTES).

                # A list of sequences can be found in /usr/share/X11/locale/en_US.UTF-8/Compose
                # on most systems.


                [main]

                rightalt = layer(dia)

                [dia]

                # Map o to ö
                o = macro(compose o ")

                # Map e to €
                e = macro(compose c =)

   مثال ۶
                # Tapping both shift keys will activate capslock.

                [shift]

                leftshift = capslock
                rightshift = capslock

   مثال ۷
       کلید Capslock در تمام حالات مانند control عمل می‌کند به جز زمانی که در
       ترکیب با 'h/j/k/l' استفاده شود که در این حالت کلیدهای جهت‌نما را تولید
       می‌کند در صورت ضربه زدن به آن، به عنوان escape عمل خواهد کرد.

                [main]
                capslock = overload(capslock, esc)
                esc = capslock

                [capslock:C]
                h = left
                k = up
                j = down
                l = right

   مثال ۸
       غیرفعال کردن کلیدهای esc و end.

                [main]
                esc = noop
                end = noop

نکات (NOTES)
       از آنجا که keyd یک دستگاه ورودی مجازی ایجاد می‌کند، تنظیمات اعمال‌شده با
       استفاده از ابزارهای ورودی سطح بالاتر مانند setxkbmap و xset ممکن است در
       زمان راه‌اندازی (مجدد) دیمن از دست بروند برای جزئیات به نشانی
       https://github.com/rvaiya/keyd/issues/183 مراجعه کنید.

متغیرهای محیطی (ENVIRONMENT VARIABLES)
       KEYD_DEBUG
           سطح لاگ اشکال‌زدایی مقادیر 0، 1 و 2 قابل تعیین هستند (پیش‌فرض: 0).

نویسنده (AUTHOR)
       نوشته‌شده توسط Raheman Vaiya (2017-).

اشکالات (BUGS)
       لطفاً هرگونه اشکال یا درخواست ویژگی جدید را در نشانی زیر ثبت کنید:

       <https://github.com/rvaiya/keyd/issues>

                                  2025-09-11                           keyd(1)