.Dd $Mdocdate: January 10 2024$
.Dt J4-DMENU-DESKTOP 1
.Os
.Sh "نام (NAME)"
.Nm j4-dmenu-desktop
.Nd منوی سریع دسکتاپ
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op OPTIONS
.Sh "توضیحات (DESCRIPTION)"
.Nm
یک جایگزین سریع‌تر برای i3-dmenu-desktop است.
.Pp
هدف آن یافتن فایل‌های .desktop و ارائه یک منو برای راه‌اندازی برنامه‌ها با استفاده از dmenu است.
.Pp
آرگومان‌ها به شرح زیر هستند:
.Bl -tag -width Ds
.It Fl b , Fl Fl display-binary
نمایش نام باینری پس از هر ورودی (به‌طور پیش‌فرض غیرفعال است).
.It Fl f , Fl Fl display-binary-base
نمایش نام پایه (basename) باینری پس از هر ورودی (به‌طور پیش‌فرض غیرفعال است).
.It Fl d , Fl Fl dmenu Ar command
دستور مورد استفاده برای فراخوانی dmenu را تعیین می‌کند.
توسط پوسته شما
.Pq Ev $SHELL
یا
.Pa /bin/sh
اجرا می‌شود.
.It Fl Fl no-exec
دستور انتخاب‌شده را اجرا نکن، به‌جای آن به stdout بفرست.
.It Fl Fl no-generic
نام عمومی (generic name) ورودی‌های دسکتاپ را شامل نکن.
.It Fl t , Fl Fl term Ar command
شبیه‌ساز ترمینال مورد استفاده برای اجرای برنامه‌های ترمینالی را تعیین می‌کند.
.It Fl Fl term-mode Ar mode
به
.Nm
دستور می‌دهد که چگونه شبیه‌ساز ترمینال را اجرا کند.
این فلگ مقدار پیش‌فرض فلگ
.Fl Fl term
را نیز تغییر می‌دهد.
.Pp
مقادیر ممکن عبارتند از:
.Cm default | xterm | alacritty | kitty | terminator | gnome-terminal | custom
.Pp
برای اطلاعات بیشتر
.Sx TERM MODE
را ببینید.
.It Fl Fl usage-log Ar file
باید به یک فایل با قابلیت خواندن و نوشتن اشاره کند (در صورت عدم وجود ایجاد خواهد شد). در این حالت، ورودی‌ها بر اساس بسامد و تعداد استفاده مرتب می‌شوند.
.It Fl Fl prune-bad-usage-log-entries
حذف نام‌های ثبت‌شده در گزارش استفاده که
.Nm
قادر به یافتن فایل دسکتاپ برای آن‌ها نبوده است.
این مورد زمانی رخ می‌دهد که برنامه‌ای که در لاگ استفاده ثبت شده دیگر وجود ندارد زیرا حذف نصب شده است.
.It Fl x , Fl Fl use-xdg-de
خواندن
.Ev $XDG_CURRENT_DESKTOP
را برای تعیین محیط رومیزی فعال می‌کند.
.It Fl Fl wait-on Ar path
باید به مسیری اشاره کند که بتوان در آن فایلی ایجاد کرد.
در این حالت هیچ منویی نمایش داده نخواهد شد.
در عوض برنامه منتظر می‌ماند تا در
.Ar path
نوشته شود
.Po
از
.Ql echo > path
استفاده کنید
.Pc .
هر بار که این اتفاق بیفتد، منو نمایش داده خواهد شد.
فایل‌های دسکتاپ از قبل تجزیه (parse) می‌شوند.
اجرای
.Ql echo -n q > path
باعث خروج از برنامه می‌شود.
.It Fl Fl wrapper Ar wrapper
یک باینری پوشش‌دهنده (wrapper).
استفاده از
.Ql --wrapper Qq i3 exec
و
.Ql --wrapper Qq sway exec
منسوخ شده است، به‌جای آن از
.Fl Fl i3-ipc
استفاده کنید.
.It Fl I , Fl Fl i3-ipc
اجرای ورودی‌های دسکتاپ از طریق i3 IPC یا Sway IPC.
نیازمند این است که یا i3 یا Sway در حال اجرا باشند.
.It Fl Fl skip-i3-exec-check
غیرفعال کردن بررسی برای
.Fl Fl wrapper Qq i3 exec
یا
.Fl Fl wrapper Qq sway exec .
برنامه j4-dmenu-desktop پشتیبانی مستقیم از i3/Sway از طریق فلگ
.Fl I
دارد که باید به‌جای گزینه
.Fl Fl wrapper
استفاده شود. j4-dmenu-desktop این مورد را تشخیص داده و خارج می‌شود.
این فلگ این رفتار را نادیده می‌گیرد.
.It Fl i , Fl Fl case-insensitive
مرتب‌سازی برنامه‌ها بدون حساسیت به حروف بزرگ و کوچک (case-insensitive)
.It Fl v
پرگویی بیشتر (verbose).
هنگامی که یک بار مشخص شود، سطح
.Cm INFO
استفاده می‌شود، و هنگامی که دو بار مشخص شود، سطح
.Cm DEBUG
استفاده می‌شود.
بخش
.Sx LOG LEVELS
را ببینید.
.It Fl Fl log-level Ar ERROR | WARNING | INFO | DEBUG
یک نسخه صریح‌تر از
.Fl v .
این فلگ بر
.Fl v
اولویت دارد.
.It Fl Fl log-file Ar file
یک فایل لاگ را مشخص می‌کند.
محتوای
.Ar file
کوتاه (truncate) خواهد شد.
به‌طور پیش‌فرض، سطح لاگ
.Cm INFO
استفاده می‌شود.
.It Fl Fl log-file-level Ar ERROR | WARNING | INFO | DEBUG
تنظیم سطح لاگ فایل.
.It Fl Fl desktop-file-quirks Ar ARGS
سازوکار تجزیه فایل دسکتاپ در
.Nm j4-dmenu-desktop
را تغییر می‌دهد تا فایل‌های دسکتاپی که با مشخصات Desktop Entry Specification سازگار نیستند پذیرفته شوند.
چندین حالت را می‌توان مشخص کرد.
آن‌ها باید با کاما (,) از هم جدا شوند.
هر
.Cm mode
دارای یک همتای
.Cm nomode
است که حالت مربوطه را غیرفعال می‌کند.
برای غیرفعال کردن تمام حالت‌ها، از
.Fl Fl strict-parsing
استفاده کنید.
هنگامی که یک فایل دسکتاپ از یک قلق (quirk) فعال استفاده کند، یک هشدار چاپ می‌شود.
.Ar ARGS
می‌تواند شامل حالت‌های زیر باشد:
.Bl -tag -width Ds
.It Ar wine
تحمل کدهای گریز (escape codes) نامعتبر
.Pq مانند اسکیپ کردن یک فاصله برای جلوگیری از تفکیک آرگومان‌ها
در کلید
.Cm Exec
فایل‌های دسکتاپ.
به‌طور پیش‌فرض فعال است.
.It Ar multispace
تحمل استفاده از چندین فاصله برای تفکیک آرگومان‌ها در کلید
.Cm Exec
فایل‌های دسکتاپ.
برای فایل‌های دسکتاپ ایجاد شده توسط distrobox مفید است.
به‌طور پیش‌فرض فعال است.
.El
.Pp
اگر این فلگ چندین بار مشخص شود، فقط آخرین مقدار اعمال می‌شود.
آن‌ها به هیچ وجه ادغام یا ترکیب نمی‌شوند.
.Pp
این فلگ با
.Fl Fl strict-parsing
ناسازگار و مانعة‌الجمع است.
.It Fl Fl strict-parsing
پایبندی دقیق به مشخصات Desktop Entry Specification هنگام تجزیه فایل‌های دسکتاپ.
به‌طور پیش‌فرض فعال نیست.
.Pp
این فلگ با
.Fl Fl desktop-file-quirks
ناسازگار و مانعة‌الجمع است.
.It Fl Fl version
نمایش نسخه برنامه.
.It Fl h , Fl Fl help
نمایش پیام راهنما.
.El
.Ss LOG LEVELS
برخی آرگومان‌ها از تنظیم سطح لاگ پشتیبانی می‌کنند.
.Nm
از سطوح لاگ زیر استفاده می‌کند:
.Cm ERROR , WARNING , INFO
و
.Cm DEBUG .
سطوح لاگ
.Cm WARNING
(و
.Cm ERROR )
به‌طور پیش‌فرض نمایش داده می‌شوند.
سطوح لاگ پایین‌تر به‌طور خودکار سطوح بالاتر را فعال می‌کنند.
.Ss TERM MODE
چندین حالت برای فلگ
.Fl Fl term-mode
در دسترس است:
.Bl -tag -width Ds
.It Cm default
حالت پیش‌فرض.
یک اسکریپت شل موقت حاوی دستور انتخاب‌شده ایجاد می‌شود.
اسکریپت پس از اجرا خود را حذف می‌کند،
.Nm
هرگز خودش آن را حذف نمی‌کند.
این حالت عنوان شبیه‌ساز ترمینال را با استفاده از توالی‌های گریز OSC تنظیم می‌کند
.Pq Xr console_codes 4 را ببینید .
شبیه‌ساز ترمینال به شرح زیر اجرا می‌شود:
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl e Bo Cm generated\ temporary\ script Bc
.Pp
سایر حالت‌ها ترجیح داده می‌شوند.
این رویکرد عمومی اما شکننده است.
.Pp
مقدار پیش‌فرض
.Fl Fl term
برابر است با
.Ic i3-sensible-terminal .
.It Cm xterm
استفاده از قرارداد فراخوانی
.Ic xterm :
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl title Bo Cm desktop\ app\ Name Bc Fl e \
Bo Cm command\ line Bc
.Pp
مقدار پیش‌فرض
.Fl Fl term
برابر است با
.Ic xterm .
سایر شبیه‌سازهای ترمینال سازگار عبارتند از:
.Ic rxvt-unicode .
.It Cm alacritty
استفاده از قرارداد فراخوانی
.Ic alacritty :
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl T Bo Cm desktop\ app\ Name Bc Fl e \
Bo Cm command\ line Bc
.Pp
مقدار پیش‌فرض
.Fl Fl term
برابر است با
.Ic alacritty .
سایر شبیه‌سازهای ترمینال سازگار عبارتند از:
.Ic st , foot .
.It Cm kitty
استفاده از قرارداد فراخوانی
.Ic kitty :
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl T Bo Cm desktop\ app\ Name Bc\
 Bo Cm command\ line Bc
.Pp
مقدار پیش‌فرض
.Fl Fl term
برابر است با
.Ic kitty .
سایر شبیه‌سازهای ترمینال سازگار عبارتند از:
.Ic foot .
.It Cm terminator
استفاده از قرارداد فراخوانی
.Ic terminator :
.Pp
.Dl Bo Cm terminator\ emulator Bc Fl T Bo Cm desktop\ app\ Name Bc\
 Fl x Bo Cm command\ line Bc
.Pp
مقدار پیش‌فرض
.Fl Fl term
برابر است با
.Ic terminator .
سایر شبیه‌سازهای ترمینال سازگار عبارتند از:
.Ic xfce4-terminal .
.It Cm gnome-terminal
استفاده از قرارداد فراخوانی
.Ic gnome-terminal :
.Pp
.Dl Bo Cm terminal\ emulator Bc Fl Fl title Bo Cm desktop\ app\ Name Bc Fl \- \
Bo Cm command\ line Bc
.Pp
مقدار پیش‌فرض
.Fl Fl term
برابر است با
.Ic gnome-terminal .
.It Cm custom
امکان مدیریت کاملاً سفارشی
.Fl Fl term .
هنگامی که
.Fl Fl term-mode Cm custom
داده شود، یک سیستم جایگزین برای مدیریت
.Fl Fl term
استفاده می‌شود.
این مورد به عنوان فهرستی از آرگومان‌ها که با فاصله
.Pq " "
از هم جدا شده‌اند مدیریت می‌شود.
هیچ نویسه فضای خالی دیگری به عنوان جداکننده آرگومان عمل نمی‌کند (این رفتار با پوسته متفاوت است).
.Pp
چندین نویسه فاصله متوالی به عنوان یک فاصله واحد در نظر گرفته می‌شوند (به جز فاصله‌های اسکیپ‌شده).
فاصله‌های ابتدا و انتهای
.Fl Fl term
نادیده گرفته می‌شوند.
این بدان معنی است که امکان ارسال آرگومان‌های با طول صفر به
.Fl Fl term
وجود
.Em ندارد .
.Pp
محتویات
.Fl Fl term
از طریق پوسته اجرا
.Em نمی‌شوند .
این بدان معنی است که ساختارهای پوسته مانند تغییر مسیر (redirection)، زنجیره‌سازی
.Ic &&
و
.Ic ||
و موارد دیگر کار نخواهند کرد.
اگر به این موارد نیاز دارید، می‌توانید یک اسکریپت پوششی پوسته بسازید و آن را از طریق
.Fl Fl term
فراخوانی کنید یا می‌توانید
.Cm /bin/sh -c
یا پوسته دیگری را مستقیماً از
.Fl Fl term
صدا بزنید (هرچند استفاده از یک اسکریپت پوششی باید ترجیح داده شود، زیرا واضح‌تر و استفاده از آن ساده‌تر است).
.Pp
متغیرهای جانشین (placeholders) زیر شناخته می‌شوند:
.Bl -tag -width indent-two
.It Brq Ic name
نام برنامه دسکتاپ.
برای تنظیم عنوان مفید است.
.It Brq Ic cmdline@
خط دستور جهت اجرا، که به صورت آرگومان‌های جداگانه باز می‌شود (expand).
این باید یک آرگومان مستقل باشد؛
.Ql Cm j4-dmenu-desktop Fl Fl term-mode Cm custom Fl Fl term Qq Fl e= Ns Brq cmdline@
نامعتبر است.
.It Brq Ic cmdline*
خط دستور جهت اجرا، که به صورت یک آرگومان واحد باز می‌شود.
.Brq Ic cmdline@
باید بر
.Brq Ic cmdline*
ترجیح داده شود.
آرگومان‌ها اسکیپ خواهند شد؛ محتویات
.Brq Ic cmdline*
را می‌توان با خیال راحت به
.Cm /bin/sh -c
ارسال کرد.
.It Brq Ic script
نام فایل اسکریپت تولید شده توسط
.Nm .
این همان اسکریپتی است که توسط
.Fl Fl term-mode Cm default
استفاده می‌شود.
اسکریپت تنها در صورتی ایجاد می‌شود که این جانشین حداقل یک بار در
.Fl Fl term
مشخص شده باشد.
اسکریپت عنوان ترمینال را خودش تنظیم می‌کند، نباید لازم باشد آن را به صورت دستی تنظیم کنید.
.Pp
.Brq Ic cmdline@
و
.Brq Ic cmdline*
باید بر
.Brq Ic script
ترجیح داده شوند.
.El
.Pp
توالی‌های گریز (escape sequences) زیر شناخته می‌شوند:
.Bl -tag -width indent-two
.It Sy \e\e
نویسه واقعی
.Sy \e .
.It Sy \e{
نویسه واقعی
.Sy { .
.It Sy \e\  Ns
.Pq بک‌اسلش به همراه فاصله
فاصله بعدی را به عنوان جداکننده آرگومان تلقی نکن.
.El
.Pp
توالی‌های گریز و جانشین‌های تعریف‌نشده منجر به پیام خطا و خاتمه برنامه می‌شوند.
.Pp
مقدار پیش‌فرض
.Fl Fl term
همانند حالت ترمینال
.Cm default
است.
.Pp
.\" The following list should be in sync with pytest testsuite!
.\" =========================================================
سایر حالت‌ها در صورت نوشتن با حالت
.Cm custom
به این شکل خواهند بود:
.Bl -hang -width indent-two
.It Cm default
.Ql j4-dmenu-desktop --term-mode custom --term Qq i3-sensible-terminal -e Brq\
 script
.It Cm xterm
.Ql j4-dmenu-desktop --term-mode custom --term Qq xterm -title Bro name Brc\
 -e Brq cmdline@
.It Cm alacritty
.Ql j4-dmenu-desktop --term-mode custom --term Qq alacritty -T Bro name Brc\
 -e Brq cmdline@
.It Cm kitty
.Ql j4-dmenu-desktop --term-mode custom --term Qq kitty -T Bro name Brc Brq\
 cmdline@
.It Cm terminator
.Ql j4-dmenu-desktop --term-mode custom --term Qq terminator -T Bro name Brc\
 -x Brq cmdline@
.It Cm gnome-terminal
.Ql j4-dmenu-desktop --term-mode custom --term Qq gnome-terminal --title Bro\
 name Brc -- Brq cmdline@
.El
.Pp
نحوه استفاده از فلگ منسوخ‌شده -e در gnome-terminal به این شکل است:
.Pp
.Dl j4-dmenu-desktop --term-mode custom --term Qq gnome-terminal --title Bro name Brc -e Brq cmdline*
.Pp
نحوه اسکیپ کردن جانشین‌ها به این صورت است:
.Pp
.Dl j4-dmenu-desktop --term-mode custom --term Qq echo \e Ns Bro name Brc Ns \e \e Ns Brq cmdline*
.Pp
.Fl Fl term
دو آرگومان دریافت می‌کند:
.Ql echo
و
.Ql Bro name Brc Brq cmdline* ,
هیچ جانشینی جایگزین نمی‌شود.
اگر
.Sy \e
دوم ارسال نمی‌شد،
.Nm
به‌جای دو آرگومان، سه آرگومان را می‌دید.
.El
.Sh "محیط (ENVIRONMENT)"
.Bl -tag -width Ds
.It Ev I3SOCK
این متغیر مسیر سوکت i3/Sway IPC را بازنویسی می‌کند.
.It Ev XDG_DATA_HOME
دایرکتوری اصلی حاوی فایل‌های دسکتاپ.
.It Ev XDG_DATA_DIRS
دایرکتوری‌های اضافی حاوی فایل‌های دسکتاپ.
.It Ev XDG_CURRENT_DESKTOP
محیط رومیزی فعلی که برای فعال/غیرفعال کردن فایل‌های دسکتاپ وابسته به محیط رومیزی استفاده می‌شود.
باید توسط
.Fl Fl use-xdg-de
فعال شود.
.El
.Pp
علاوه بر متغیرهای فهرست‌شده در بالا، متغیرهای محیطی استاندارد برای محلی‌سازی (locales) نیز شناسایی می‌شوند.
متغیرهای محیطی دقیق استفاده شده به پیاده‌سازی بستگی دارند، اما تنظیم
.Ev LC_MESSAGES , LC_ALL
یا
.Ev LANG
به‌طور کلی باید کار کند.
.Sh "همچنین ببینید (SEE ALSO)"
.Lk https://github.com/enkore/j4-dmenu-desktop
.Sh "حق نشر (COPYRIGHT)"
حق نشر (C) 2013 enkore
.Eo <
.Mt public+j4-dmenu-desktop@enkore.de
.Ec >
.Pp
این برنامه نرم‌افزار آزاد است: شما می‌توانید آن را تحت شرایط مجوز عمومی همگانی گنو (GNU GPL) که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است، چه نسخه ۳ مجوز یا (به انتخاب خودتان) هر نسخه بعدی، بازتوزیع کرده و/یا تغییر دهید.
.Pp
این برنامه با این امید توزیع شده است که مفید واقع شود، اما بدون هیچ‌گونه ضمانتی؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف خاص.
برای جزئیات بیشتر به مجوز عمومی همگانی گنو مراجعه کنید.
.Pp
شما باید همراه با این برنامه یک نسخه از مجوز عمومی همگانی گنو را دریافت کرده باشید.
در غیر این صورت، ببینید:
.Eo <
.Lk http://www.gnu.org/licenses
.Ec > .