.Dd November 29, 2016
.Dt VIS-MENU 1
.Os Vis v0.9-498-gad0f1deb-dirty
.Sh "نام (NAME)"
.Nm vis-menu
.Nd انتخاب تعاملی یک مورد از یک فهرست
.
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm vis-menu
.Op Fl i
.Op Fl t | Fl b
.Op Fl p Ar prompt
.Op Fl l Ar lines
.Op Ar initial
.Nm vis-menu
.Op Fl v
.
.Sh "توضیحات (DESCRIPTION)"
دستور
.Nm vis-menu
به کاربر اجازه می‌دهد تا به‌صورت تعاملی یک مورد را از فهرستی از گزینه‌ها انتخاب کند.
فهرستی از موارد که با خط جدید از یکدیگر جدا شده‌اند از ورودی استاندارد خوانده می‌شود،
سپس فهرست موارد مستقیماً روی ترمینال ترسیم می‌شود
تا کاربر بتواند یکی را انتخاب کند.
در نهایت،
مورد انتخاب‌شده در خروجی استاندارد چاپ می‌شود.
.Pp
برای اطلاعات بیشتر درباره نحوه پیمایش در منو،
بخش
.Sx "نحوه استفاده (USAGE)"
در ادامه را ببینید.
.Bl -tag -width flag
.It Fl i
استفاده از مقایسه غیرحساس به حروف کوچک و بزرگ هنگام فیلتر کردن موارد.
.It Fl t | Fl b
در حالت عادی،
منو در خط فعلی ترمینال نمایش داده می‌شود.
هنگامی که
.Fl t
داده شود، منو همیشه در بالاترین خط ترمینال ترسیم خواهد شد.
هنگامی که
.Fl b
داده شود، منو همیشه در پایین‌ترین خط ترسیم خواهد شد.
.It Fl p Ar prompt
نمایش
.Ar prompt
پیش از فهرست موارد.
.It Fl l Ar lines
در حالت عادی،
فهرست با قرارگیری تمام موارد در کنار یکدیگر در یک خط منفرد نمایش داده می‌شود
که از نظر اشغال فضا بهینه است
اما موارد زیادی را در یک لحظه نشان نمی‌دهد،
به‌ویژه اگر برخی از آن‌ها طولانی باشند.
هنگامی که
.Fl l
داده شود،
فهرست به گونه‌ای نمایش داده می‌شود که هر مورد در خط جداگانه خود قرار دارد
و ارتفاع آن
.Ar lines
خط خواهد بود.
اگر تعداد موارد موجود در فهرست بیشتر از
.Ar lines
باشد،
کاربر می‌تواند با کلیدهای جهت‌نما در میان آن‌ها پیمایش کند،
درست مانند حالت افقی معمولی.
.It Ar initial
کاربر می‌تواند علاوه بر پیمایش در میان موارد، در یک فیلد متنی تایپ کند
تا فهرست موارد را فیلتر کند.
در صورت مشخص شدن، از
.Ar initial
به‌عنوان محتوای اولیه فیلد متنی استفاده می‌شود.
.It Fl v
به جای نمایش یک منوی تعاملی،
.Nm vis-menu
شماره نسخه خود را در خروجی استاندارد چاپ کرده و خارج می‌شود.
.El
.
.Sh "نحوه استفاده (USAGE)"
دستور
.Nm vis-menu
اعلان یا prompt (در صورت وجود)،
یک فیلد متنی،
و فهرستی از موارد را نمایش می‌دهد.
به طور معمول این موارد در کنار یکدیگر در یک خط منفرد ارائه می‌شوند،
اما اگر پرچم
.Fl l
داده شود،
اعلان و ناحیه تایپ در خط اول،
و موارد فهرست در خطوط بعدی قرار خواهند گرفت.
.Pp
فرمان‌های زیر در دسترس هستند:
.Bl -tag -width ".Sy Control-A"
.It Sy Enter
موردِ هایلایت‌شده فعلی فهرست را انتخاب کرده و خارج می‌شود.
.It Xo Sy Control-\e
یا
.Sy Control-\&]
.Xc
محتوای فعلی فیلد متنی را
(حتی اگر در فهرست ظاهر نشده باشد)
انتخاب کرده و خارج می‌شود.
.It Xo Sy "ESC ESC"
یا
.Sy Control-C
.Xc
بدون انتخاب هیچ موردی خارج می‌شود.
.It Xo Sy Down
یا
.Sy Control-N
.Xc
پیمایش رو به جلو در میان موارد موجود فهرست.
.It Xo Sy Up
یا
.Sy Control-P
.Xc
پیمایش رو به عقب در میان موارد موجود فهرست.
.It Xo Sy Right
یا
.Sy Control-F
.Xc
حرکت مکان‌نما به جلو در متن تایپ‌شده،
و پیمایش در میان موارد موجود فهرست.
.It Xo Sy Left
یا
.Sy Control-B
.Xc
حرکت مکان‌نما به عقب در متن تایپ‌شده،
و پیمایش در میان موارد موجود فهرست.
.It Xo Sy PageUp
یا
.Sy Control-V
.Xc
برای نمایش صفحه قبلی موارد فهرست پیمایش می‌کند.
.It Xo Sy PageDown
یا
.Sy Meta-v
.Xc
برای نمایش صفحه بعدی موارد فهرست پیمایش می‌کند.
.It Xo Sy Home
یا
.Sy Control-A
.Xc
حرکت مکان‌نما به ابتدای فیلد متنی
یا پیمایش به اولین مورد در فهرست.
.It Xo Sy End
یا
.Sy Control-E
.Xc
حرکت مکان‌نما به انتهای فیلد متنی
یا پیمایش به آخرین مورد در فهرست.
.It Sy Meta-b
مکان‌نما را به ابتدای کلمه فعلی در فیلد متنی منتقل می‌کند.
.It Sy Meta-f
مکان‌نما را به بعد از انتهای کلمه فعلی در فیلد متنی منتقل می‌کند.
.It Sy Tab
محتوای مورد انتخاب‌شده فهرست را در فیلد متنی کپی می‌کند.
این قابلیت تقریباً مشابه با تکمیل با کلید Tab (tab completion) است، اما دقیقاً آن نیست.
.It Xo Sy Delete
یا
.Sy Control-D
.Xc
حذف نویسه زیر مکان‌نما در فیلد متنی.
.It Sy Backspace
نویسه سمت چپ مکان‌نما در فیلد متنی را حذف می‌کند.
.It Sy Meta-d
نویسه‌های موجود در فیلد متنی را
از نویسه زیر مکان‌نما
تا فاصله بعدی حذف می‌کند.
.It Sy Control-K
نویسه‌های موجود در فیلد متنی را
از نویسه زیر مکان‌نما تا انتها حذف می‌کند.
.It Sy Control-U
نویسه‌های موجود در فیلد متنی را
از ابتدا تا
(بدون احتساب)
نویسه زیر مکان‌نما حذف می‌کند.
.It Sy Control-W
نویسه‌های موجود در فیلد متنی را
از فاصله قبلی تا
(بدون احتساب)
نویسه زیر مکان‌نما حذف می‌کند.
.El
.Pp
همه نویسه‌های غیرکنترلی دیگر در موقعیت فعلی مکان‌نما در فیلد متنی درج خواهند شد.
.Pp
هنگامی که متنی در فیلد متنی وجود دارد،
تنها مواردی از فهرست نشان داده می‌شوند که شامل متن داده‌شده باشند.
اگر متن شامل یک یا چند فاصله باشد،
هر رشته جداشده با فاصله یک فیلتر جداگانه در نظر گرفته می‌شود
و تنها مواردی که با تمام فیلترها مطابقت داشته باشند نمایش داده خواهند شد.
.Pp
اگر کاربر تمام موارد را از فهرست فیلتر کند،
و سپس کلید Enter را برای انتخاب
.Dq موردِ هایلایت‌شده فعلی
بفشارد،
متنی که تایپ کرده است به جای آن بازگردانده می‌شود.
.
.Sh "مثال‌ها (EXAMPLES)"
در اینجا یک اسکریپت شل آورده شده است که به کاربر اجازه می‌دهد عددی از ۱ تا ۱۰ را انتخاب کند:
.Bd -literal -offset indent
NUMBER=$(seq 1 10 | vis-menu -p "Choose a number")
if [ $? -eq 0 ]; then
	echo "You chose: $NUMBER"
else
	echo "You refused to choose a number, or an error occurred."
fi
.Ed
.
.Sh "خطاها (DIAGNOSTICS)"
ابزار
.Nm vis-menu
در صورتی که کاربر با موفقیت موردی را از فهرست انتخاب کند با وضعیت 0 خارج می‌شود،
و در صورتی که کاربر عملیات را لغو کند با وضعیت 1 خاتمه می‌یابد.
.Pp
در صورت وقوع یک خطای داخلی،
ابزار
.Nm vis-menu
پیامی را در خروجی خطای استاندارد چاپ کرده و با وضعیت خروجی بزرگ‌تر از 1 خاتمه می‌یابد.
شرایط خطای احتمالی شامل
عدم توانایی در تخصیص حافظه،
عدم توانایی در خواندن از ورودی استاندارد،
یا اجرا شدن بدون یک ترمینال کنترلی است.
.
.Sh "همچنین ببینید (SEE ALSO)"
.Xr dmenu 1 ,
.Xr slmenu 1 ,
.Xr vis 1
.
.Sh "تاریخچه (HISTORY)"
الگوی اولیه برای یک منوی تک‌خطی که موارد را از ورودی استاندارد می‌خواند
.Xr dmenu 1
بود که این ایده را برای سامانه پنجره X11 پیاده‌سازی کرد.
ابزار
.Nm dmenu
از طریق نشانی زیر در دسترس است:
.Li http://tools.suckless.org/dmenu
.Pp
سپس کد منبع برای خروجی ترمینال ANSI بازنویسی شد و به شکل
.Xr slmenu 1
درآمد که از طریق نشانی زیر در دسترس است:
.Li https://bitbucket.org/rafaelgg/slmenu
.Pp
از آنجا که به نظر می‌رسید
.Nm slmenu
دیگر نگهداری نمی‌شود،
یک انشعاب (fork) از آن ایجاد شد تا به
.Nm vis-menu
تبدیل شود و همراه با
.Xr vis 1
توزیع گردد.