KHAL(1) khal KHAL(1) نام (NAME) khal - برنامه تقویم متنی و خط فرمانی مبتنی بر استاندارد CalDAV/vCalendar برنامه khal یک نرم‌افزار تقویم برای محیط خط فرمان و ترمینال جهت مشاهده، افزودن و ویرایش رویدادها و تقویم‌ها است. khal بر پایه استانداردهای iCalendar و vdir (با امکان استفاده از vdirsyncer(1) برای سازگاری با CalDAV) ساخته شده است. نحوه استفاده (USAGE) برنامه khal مجموعه‌ای از دستورات را ارائه می‌دهد که مهم‌ترین آن‌ها عبارتند از: list، calendar، interactive، new، printcalendars، printformats و search. برای توضیحات عملکرد هر دستور به بخش‌های زیر مراجعه کنید. در حال حاضر khal از هیچ دستور پیش‌فرضی پشتیبانی نمی‌کند (یعنی در صورت مشخص نشدن دستور، دستوری اجرا نمی‌شود). این رفتار عمدی است. گزینه‌ها (OPTIONS) برنامه khal (بدون هیچ زیردستوری) گزینه‌هایی برای نمایش اطلاعاتی درباره khal دارد: --version نسخه khal را چاپ کرده و خارج می‌شود. -h, --help خلاصه‌ای از گزینه‌ها و دستورات khal را نمایش داده و سپس خارج می‌شود. چندین گزینه میان تقریباً تمام دستورات khal مشترک هستند (موارد استثنا در ادامه توضیح داده شده‌اند): -v, --verbosity LVL میزان پرگویی و جزئیات گزارش‌ها را تنظیم می‌کند (مثلاً چاپ اطلاعات اشکال‌زدایی)، LVL باید یکی از مقادیر CRITICAL، ERROR، WARNING، INFO یا DEBUG باشد. -l, --logfile LOFILE از فایل لاگ LOGFILE برای ثبت گزارش‌ها استفاده می‌کند؛ حالت پیش‌فرض ارسال گزارش به خروجی استاندارد (stdout) است. -c CONFIGFILE از یک فایل پیکربندی جایگزین استفاده می‌کند. -a CALENDAR تقویم مورد استفاده را مشخص می‌کند (که باید در فایل پیکربندی تعریف شده باشد)؛ می‌تواند چندین بار استفاده شود. تقویم‌هایی که مشخص نشده باشند در این اجرا نادیده گرفته می‌شوند. -d CALENDAR تقویمی را مشخص می‌کند که در این اجرا نادیده گرفته می‌شود؛ می‌تواند چندین بار استفاده شود. --color/--no-color برنامه khal تشخیص می‌دهد که آیا خروجی استاندارد یک tty نیست (برای نمونه هنگامی که خروجی khal را به یک فایل هدایت می‌کنید) و در این صورت تمام رنگ‌آمیزی‌ها و برجسته‌سازی‌ها را از خروجی حذف می‌کند. اگر می‌خواهید رنگ‌آمیزی را اجباری کنید از --color و اگر می‌خواهید رنگ‌ها همیشه حذف شوند از --no-color استفاده کنید. --format FORMAT برای تمام دستورات khal که رویدادها را چاپ می‌کنند، قالب‌بندی نمایش رویداد را می‌توان با این گزینه مشخص کرد. FORMAT یک رشته الگویی است که در آن شناسه‌های محصور میان آکولاد ({}) به ویژگی‌های رویداد گسترش می‌یابند. FORMAT از تمام قابلیت‌های قالب‌بندی ارائه‌شده توسط str.format() پایتون پشتیبانی می‌کند (زیرا در ساختار داخلی آن استفاده می‌شود). گزینه‌های الگوی موجود عبارتند از: title عنوان رویداد. description توضیحات رویداد. description-separator جداکننده: " :: " که هنگام وجود توضیحات نمایش داده می‌شود. uid شناسه یکتای (UID) رویداد. start تاریخ و زمان شروع در قالب datetimeformat. start-long تاریخ و زمان شروع در قالب longdatetimeformat. start-date تاریخ شروع در قالب dateformat. start-date-long تاریخ شروع در قالب longdateformat. start-time زمان شروع در قالب timeformat. end تاریخ و زمان پایان در قالب datetimeformat. end-long تاریخ و زمان پایان در قالب longdatetimeformat. end-date تاریخ پایان در قالب dateformat. end-date-long تاریخ پایان در قالب longdateformat. end-time زمان پایان در قالب timeformat. repeat-symbol نماد تکرار (فلش حلقه) در صورتی که رویداد تکرارشونده باشد. alarm-symbol نماد هشدار (ساعت زنگ‌دار) در صورتی که رویداد حداقل یک هشدار داشته باشد. alarms-list فهرستی جداشده با کاما از هشدارهای رویداد (مثلاً alarm1@-15m, getready@-1h). location مکان رویداد. calendar نام تقویم. calendar-color رنگ خروجی را به رنگ تقویم تغییر می‌دهد. start-style زمان شروع در قالب timeformat یا یک نماد مناسب. to-style یک خط تیره "-" یا هیچ چیز، به گونه‌ای که به شکل مناسب میان start-style و end-style قرار گیرد. end-style زمان پایان در قالب timeformat یا یک نماد مناسب. start-end-time-style ترکیبی متصل از start-style، to-style و end-style یا یک نماد مناسب. end-necessary برای رویداد تمام‌روز یک رشته خالی است مگر اینکه تاریخ شروع و پایان متفاوت باشند. برای رویداد غیر تمام‌روز، در صورت متفاوت بودن تاریخ شروع و پایان، زمان یا تاریخ‌وزمان را نشان می‌دهد. end-necessary-long همانند end-necessary ولی از datelong و datetimelong استفاده می‌کند. status وضعیت رویداد (اگر این رویداد وضعیتی داشته باشد)، مقداری مانند CONFIRMED یا CANCELLED. status-symbol وضعیت رویداد به عنوان یک نماد، ✓ یا ✗ یا ?. partstat-symbol وضعیت مشارکت در رویداد به عنوان یک نماد، ✓ یا ✗ یا ?. cancelled رشته CANCELLED (به همراه یک فاصله) در صورتی که وضعیت رویداد لغو شده باشد، در غیر این صورت خالی. organizer برگزارکننده رویداد. اگر قالب دارای CN باشد، مقدار "CN (email)" بازگردانده می‌شود؛ اگر CN وجود نداشته باشد تنها رشته ایمیل بازگردانده می‌شود. مثال: ORGANIZER;CN=Name Surname:mailto:name@mail.com مقدار Name Surname (name@mail.com) را بازمی‌گرداند و اگر صفت CN نداشته باشد آخرین عنصر پس از دونقطه را بازمی‌گرداند: ORGANIZER;SENT-BY="mailto:toemail@mail.com":mailto:name@mail.com مقدار name@mail.com را بازمی‌گرداند. url نشانی اینترنتی (URL) جاسازی‌شده در رویداد، در غیر این صورت خالی. url-separator جداکننده: " :: " که هنگام وجود URL نمایش داده می‌شود. duration مدت زمان رویداد بر حسب روز، ساعت، دقیقه و ثانیه (به ترتیب با حروف اختصاری d، h، m و s). repeat-pattern قاعده خام تکرار iCal در صورتی که رویداد تکرارشونده باشد. all-day یک مقدار بولی که نشان می‌دهد رویداد تمام‌روز است یا خیر. categories دسته‌بندی‌های رویداد. به طور پیش‌فرض، رویدادهای تمام‌روز فاقد زمان هستند. برای مشاهده زمان شروع و پایان در هر حال، کافی است -full را به انتهای هر الگوی دارای start/end یا duration اضافه کنید؛ برای نمونه start-time تبدیل به start-time-full شده و همیشه زمان شروع و پایان را نشان می‌دهد (به جای اینکه برای رویدادهای تمام‌روز خالی باشد). علاوه بر این، رنگ‌ها وجود دارند: black، red، green، yellow، blue، magenta، cyan، white (و نسخه‌های پررنگ آن‌ها: red-bold و غیره). همچنین reset وجود دارد که استایل را پاک می‌کند و bold که بولد معمولی است. چند کد کنترلی نیز ارائه شده است. می‌توانید به خط جدید (nl)، 'tab' و 'bell' دسترسی داشته باشید. کدهای کنترلی مانند nl بهترین کاربرد را با حالت --list دارند. در زیر نمونه‌ای از دستوری آورده شده است که عنوان و توضیحات تمام رویدادهای امروز را چاپ می‌کند. khal list --format "{title} {description}" --json FIELD ... مشابه --format عمل می‌کند، اما به جای تعریف یک رشته قالب‌بندی، یک شیء JSON برای هر فیلد مشخص‌شده ایجاد می‌شود. رویدادهای منطبق در یک آرایه JSON جمع‌آوری می‌شوند. این گزینه زیرمجموعه زیر از گزینه‌های الگوی --format را می‌پذیرد: title, description, uid, start, start-long, start-date, start-date-long, start-time, end, end-long, end-date, end-date-long, end-time, start-full, start-long-full, start-date-full, start-date-long-full, start-time-full, end-full, end-long-full, end-date-full, end-date-long-full, end-time-full, repeat-symbol, alarms-list, location, calendar, calendar-color, start-style, to-style, end-style, start-end-time-style, end-necessary, end-necessary-long, status, cancelled, organizer, url, duration, duration-full, repeat-pattern, all-day, categories توجه داشته باشید که calendar-color نام واقعی رنگ خواهد بود نه کد رنگ ANSI، و فاصله‌های خالی ابتدا و انتهای مقادیر repeat-symbol، status و cancelled حذف خواهند شد. علاوه بر این، اگر فقط مقدار ویژه all مشخص شود، تمام فیلدها فعال خواهند شد. در زیر یک دستور نمونه آورده شده است که فهرستی از اشیاء JSON حاوی عنوان و توضیحات تمام رویدادهای امروز را چاپ می‌کند. khal list --json title --json description --day-format DAYFORMAT مشابه --format عمل می‌کند، اما برای سرصفحه روزها است. این گزینه تنها چند انتخاب دارد (علاوه بر تمامی گزینه‌های رنگ): date تاریخ در قالب dateformat. date-long تاریخ در قالب longdateformat. name نام روز (Monday، Tuesday، …) یا today یا tomorrow. اگر به --day-format یک رشته خالی داده شود، سرصفحه روزها را چاپ نخواهد کرد (برای یک خط خالی، یک کاراکتر فاصله ارسال کنید). تاریخ‌ها (DATES) تقریباً در هر جایی که khal تاریخ‌ها را می‌پذیرد، باید نام‌های نسبی تاریخ مانند today، tomorrow و نام روزهای هفته (همچنین به صورت مخفف سه حرفی) را تشخیص دهد. نام روزهای هفته به عنوان تاریخ وقوع بعدی آن روز تفسیر می‌شوند. نام روز جاری به عنوان آن تاریخ در هفته بعدی (یعنی هفت روز بعد از امروز) تفسیر می‌شود. اگر از قالب کوتاهِ تاریخ‌وزمان استفاده شود (سالی ذکر نشود)، khal تاریخ را در آینده تفسیر خواهد کرد. در صورتی که تاریخ داده‌شده در سال جاری گذشته باشد، احتمالاً به عنوان سال بعد در نظر گرفته می‌شود. دستورات (COMMANDS) list تمام رویدادهای زمان‌بندی‌شده برای یک محدوده تاریخ (یا تاریخ‌وزمان) مشخص را با قالب‌بندی سفارشی نمایش می‌دهد: khal list [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT] [--json FIELD ...] [--day-format DAYFORMAT] [--once] [--notstarted] [START [END | DELTA] ] مقادیر START و END هر دو می‌توانند به صورت تاریخ، تاریخ‌وزمان یا زمان (در صورت ارائه فقط زمان، فرض می‌شود امروز مد نظر است) در قالب‌های پیکربندی‌شده در فایل پیکربندی داده شوند. اگر END داده نشود، نیمه‌شب تاریخ شروع فرض می‌شود. اگر START به صراحت مشخص نشود، امروز در نظر گرفته می‌شود. اگر DELTA، یعنی یک محدوده (تاریخ و) زمان در قالب I{m,h,d} (که در آن I یک عدد صحیح است و m به معنای دقیقه، h به معنای ساعت و d به معنای روز است) داده شود، END به صورت START + DELTA در نظر گرفته می‌شود. مقدار eod نیز به عنوان DELTA پذیرفته می‌شود و به معنای پایان روز تاریخ شروع است. علاوه بر این، مقدار DELTA برابر با week را می‌توان برای مشخص کردن این که محدوده تاریخ باید هفته شامل START باشد به کار برد. گزینه --once باعث می‌شود رویدادها حتی در صورت قرار داشتن در چند روز، فقط یک بار نمایش داده شوند. با گزینه --notstarted فقط رویدادهایی نمایش داده می‌شوند که پس از START شروع می‌شوند. چندین مثال شامل کردن یا استثنا کردن تقویم‌های مشخص: • دستور khal list -d soccer رویدادها را به صورت فهرست از تمام تقویم‌ها به جز "soccer." نمایش می‌دهد. • دستور khal list -a soccer رویدادها را به صورت فهرست تنها از تقویم "soccer" نمایش می‌دهد. کار با محدوده‌های تاریخی: • دستور khal list -a soccer today 30d تمام رویدادهای ۳۰ روز آینده را (از تقویم "soccer") نمایش می‌دهد. • دستور khal list 2019-12-01 31d تمام رویدادهای مربوط به ۳۱ روز پس از ۱ دسامبر ۲۰۱۹ را نمایش می‌دهد. at تمام رویدادهای زمان‌بندی‌شده برای یک تاریخ‌وزمان مشخص را نمایش می‌دهد. به khal at باید یک تاریخ و زمان، فقط یک زمان (که در این صورت تاریخ امروز فرض می‌شود) یا رشته now داده شود. مقدار پیش‌فرض at برابر now است. دستور at دقیقاً مانند دستور list عمل می‌کند، با این تفاوت که زمان پایان ضمنی آن صفر دقیقه پس از شروع است. khal at [-a CALENDAR ... | -d CALENDAR ...] [--format FORMAT] [--json FIELD ...] [--notstarted] [[START DATE] TIME | now] calendar یک تقویم (مشابه cal(1)) و یک فهرست را نمایش می‌دهد. دستور khal calendar سینتکس زیر را می‌پذیرد: khal calendar [-a CALENDAR ... | -d CALENDAR ...] [START DATETIME] [END DATETIME] انتخاب تاریخ دقیقاً مانند khal list عمل می‌کند. تقویم نمایش‌داده‌شده شامل سه ماه متوالی است که در آن ماه نخست همان ماهِ شامل اولین تاریخ مشخص‌شده است. اگر امروز در این بازه باشد، برجسته می‌شود. برای توضیحات گزینه‌ها به khal list مراجعه کنید. configure به کاربران در ایجاد یک فایل پیکربندی اولیه کمک می‌کند. اگر از قبل یک فایل پیکربندی وجود داشته باشد، configure از اجرا خودداری می‌کند. import به کاربر امکان می‌دهد فایل‌های .ics را با ساختار زیر وارد کند: khal import [-a CALENDAR] [--batch] [--random-uid|-r] ICSFILE اگر رویدادی با همان UID از قبل در تقویم انتخاب‌شده (ضمنی) وجود داشته باشد، khal import پیش از به‌روزرسانی (یعنی بازنویسی) آن رویداد قدیمی با رویداد واردشده سوال می‌پرسد، مگر اینکه --batch داده شده باشد که در این صورت همیشه به‌روزرسانی می‌کند. اگر این رفتار مورد نظر نیست، از فلگ --random-uid برای تولید یک UID جدید و تصادفی استفاده کنید. اگر تقویمی مشخص نشده باشد (و --batch نباشد)، از شما خواسته می‌شود یک تقویم انتخاب کنید. می‌توانید شماره چاپ‌شده در کنار نام هر تقویم یا هر پیشوند یکتا از نام تقویم را وارد کنید. interactive نسخه تعاملی khal را فراخوانی می‌کند؛ همچنین با اجرای ikhal نیز قابل فراخوانی است. گرچه ikhal را می‌توان کاملاً با صفحه‌کلید استفاده کرد، برخی عناصر در صورت کلیک با ماوس واکنش نشان می‌دهند (عمدتاً با انتخاب شدن). هنگامی که تقویم سمت چپ در فوکوس است، می‌توانید: • در تقویم پیمایش کنید (کلیدهای میانبر پیش‌فرض کلیدهای جهت‌نما، space و backspace هستند؛ این کلیدهای میانبر در فایل پیکربندی قابل تنظیم می‌باشند) • با فشردن tab یا enter روی ستون سمت راست فوکوس کنید • فوکوس را به تاریخ جاری برگردانید؛ کلید میانبر پیش‌فرض t مانند today • یک محدوده تاریخی را نشانه‌گذاری کنید؛ کلید میانبر پیش‌فرض v مانند visual (مشابه حالت دیداری در Vim)؛ فشردن esc از این حالت دیداری خارج می‌شود • اگر در حالت دیداری هستید، می‌توانید سر دیگر محدوده نشانه‌گذاری‌شده را انتخاب کنید؛ کلید میانبر پیش‌فرض o مانند other (باز هم مشابه Vim) • یک رویداد جدید در روز فوکوس‌شده فعلی (یا محدوده تاریخ در صورت انتخاب یک محدوده) ایجاد کنید؛ کلید میانبر پیش‌فرض n مانند new • رویدادها را جستجو کنید؛ کلید میانبر پیش‌فرض /؛ یک پنجره بازشو عبارت جستجوی شما را درخواست می‌کند هنگامی که فهرست رویدادها در فوکوس است، می‌توانید: • جزئیات یک رویداد را با فشردن enter (یا tab) مشاهده کرده و با فشردن دوباره enter (یا tab) آن را ویرایش کنید (اگر گزینه [default] event_view_always_visible روی True تنظیم شده باشد، رویداد دارای فوکوس همیشه با جزئیات نمایش داده می‌شود) • وضعیت حذف رویداد را تغییر دهید؛ کلید میانبر پیش‌فرض d مانند delete؛ رویدادهای نشانه‌گذاری‌شده برای حذف با یک حرف D در ابتدا نمایش داده می‌شوند و هنگام خروج از khal حذف خواهند شد. • رویداد انتخاب‌شده را تکثیر کنید؛ کلید میانبر پیش‌فرض p مانند duplicate (حرف d قبلاً استفاده شده بود) • رویداد انتخاب‌شده را صادر کنید؛ کلید میانبر پیش‌فرض e در ویرایشگر رویداد، می‌توانید: • با فشردن tab (shift+tab) به عنصر قابل‌انتخاب بعدی (قبلی) بروید • ذخیره سریع؛ کلید میانبر پیش‌فرض meta+enter (meta احتمالاً همان alt خواهد بود) • از برخی میانبرهای متداول ویرایش در اکثر فیلدهای متنی استفاده کنید (ctrl+w کلمه قبل از مکان‌نما را حذف می‌کند، ctrl+u (ctrl+k) تا ابتدای (انتهای) خط را حذف می‌کند، ctrl+a (ctrl+e) به ابتدای (انتهای) خط می‌پرد) • در فیلدهای تاریخ و زمان می‌توانید عدد زیر مکان‌نما را با ctrl+a و ctrl+x افزایش یا کاهش دهید (زمان در گام‌های ۱۵ دقیقه‌ای) • در فیلدهای تاریخ می‌توانید با فشردن enter به یک تقویم مینیاتوری دسترسی پیدا کنید • با فشردن enter روی متن محصور در علامت‌های کوچکتر/بزرگتر، عملیات‌ها را فعال کنید، مانند < Save > (گاهی اوقات ممکن است یک پنجره بازشو باز شود) فشردن esc عملیات جاری را لغو می‌کند و/یا شما را به قاب نمایش داده‌شده قبلی برمی‌گرداند (یعنی آنچه هنگام باز کردن ikhal می‌بینید)؛ اگر در قاب اولیه باشید، با فشردن مجدد esc برنامه ikhal بسته می‌شود. new امکان افزودن رویدادهای جدید را فراهم می‌کند. دستور khal new ساختار زیر را می‌پذیرد: khal new [-a CALENDAR] [OPTIONS] [START [END | DELTA] [TIMEZONE] SUMMARY [:: DESCRIPTION]] که در آن start- و enddatetime می‌توانند تاریخ‌وزمان، زمان یا کلمات کلیدی و زمان در قالب‌های تعریف‌شده در فایل پیکربندی باشند. اگر هیچ تقویمی از طریق -a مشخص نشود، از تقویم پیش‌فرض استفاده می‌شود. دستور new از -d پشتیبانی نمی‌کند و همچنین -a فقط یک بار می‌تواند استفاده شود. دستور new این ترکیب‌ها را برای زمان‌های شروع و پایان می‌پذیرد (مشخص کردن پایان همیشه اختیاری است): • datetime [datetime|time] [timezone] • time [time] [timezone] • date [date] که قالب‌های datetime و time در آن به صورت زیر است: • datetime = (longdatetimeformat|datetimeformat|keyword-date timeformat) • time = timeformat • date = (longdateformat|dateformat) و timezone که منطقه زمانی محل شروع و پایان رویداد را مشخص می‌کند، باید یک شناسه معتبر پایگاه‌داده اولسون (مانند Europe/Berlin یا America/New_York) باشد. اگر هیچ منطقه زمانی داده نشود، به جای آن از defaulttimezone تعریف‌شده در فایل پیکربندی استفاده می‌شود. قالب دقیق longdatetimeformat، datetimeformat، timeformat، longdateformat و dateformat در فایل پیکربندی قابل تنظیم است. کلمات کلیدی معتبر برای تاریخ‌ها عبارتند از today، tomorrow، نام انگلیسی هر هفت روز هفته و مخفف سه حرفی آن‌ها (وقوع بعدی آن‌ها استفاده می‌شود). اگر پایانی مشخص نشود، طول پیش‌فرض یک ساعت یا یک روز (برای رویدادهای تمام‌روز) استفاده می‌شود. اگر فقط زمان شروع مشخص شده باشد، فرض می‌شود رویداد جدید امروز شروع می‌شود. اگر فقط یک زمان برای پایان رویداد داده شود، رویداد در همان روز شروع پایان می‌یابد، مگر اینکه باعث شود رویداد قبل از شروع پایان یابد که در این صورت روز بعد به عنوان تاریخ پایان استفاده می‌شود. اگر زمان 24:00 پیکربندی شده باشد (timeformat = %H:%M)، زمان پایان 24:00 به عنوان پایان تاریخ داده‌شده پذیرفته می‌شود. اگر summary شامل رشته :: باشد، هر آنچه بعد از :: قرار دارد به عنوان description رویداد جدید، یعنی «بدنه» رویداد در نظر گرفته می‌شود (و :: حذف خواهد شد). ارسال گزینه --interactive (-i ) تمام آرگومان‌ها را اختیاری می‌کند و فیلدهای لازم را به صورت تعاملی درخواست می‌نماید؛ سپس می‌توان رویداد را همانند دستور edit ویرایش کرد. گزینه‌ها (OPTIONS) • -l, --location=LOCATION محل برگزاری این رویداد را مشخص می‌کند. • -g, --categories=CATEGORIES مشخص می‌کند این رویداد متعلق به کدام دسته‌بندی‌ها است. فهرست دسته‌بندی‌ها جداشده با کاما. توجه: برخی سرورها (مانند SOGo) از چند دسته‌بندی پشتیبانی نمی‌کنند. • -r, --repeat=RRULE مشخص می‌کند آیا این رویداد تکرارشونده باشد و چگونه تکرار شود. مقادیر معتبر برای RRULE عبارتند از daily، weekly، monthly و yearly • -u, --until=UNTIL مشخص می‌کند یک رویداد تکرارشونده تا چه زمانی باید ادامه یابد. • --url عنصر نشانی اینترنتی (URL) رویداد را مشخص می‌کند. • --alarms DURATION,... زمان‌های هشدار را به صورت مقادیر DELTA جداشده با کاما برای این رویداد اضافه می‌کند؛ DURATION باید شکلی مانند 1day 10minutes یا 1d3H10m داشته باشد؛ مقادیر منفی DURATION هشدار را بعد از شروع رویداد تنظیم می‌کنند. مثال‌ها (EXAMPLES) این مثال‌ها ممکن است نیاز به تطبیق با پیکربندی و/یا محلی‌سازی (locale) شما داشته باشند (START و END باید با قالب پیکربندی‌شده مطابقت داشته باشند). به printformats مراجعه کنید. khal new 18:00 Awesome Event یک رویداد جدید از امروز ساعت 18:00 با عنوان 'awesome event' (به مدت زمان پیش‌فرض یک ساعت) به تقویم پیش‌فرض اضافه می‌کند. khal new tomorrow 16:30 Coffee Break یک رویداد جدید فردا ساعت 16:30 اضافه می‌کند. khal new 25.10. 18:00 24:00 Another Event :: with Alice and Bob یک رویداد جدید در ۲۵ اکتبر از ساعت 18:00 تا 24:00 به همراه توضیحات اضافی اضافه می‌کند. khal new -a work 26.07. Great Event -g meeting -r weekly یک رویداد تمام‌روز جدید در ۲۶ ژوئیه در تقویم work و در دسته‌بندی meeting اضافه می‌کند که هر هفته تکرار می‌شود. edit یک دستور تعاملی برای ویرایش و حذف رویدادها با استفاده از یک رشته جستجو است. khal edit [--show-past] event_search_string این دستور تمام رویدادهای منطبق با رشته جستجو را پیمایش کرده و برای حذف یا تغییر ویژگی‌ها از کاربر تایید می‌گیرد. printcalendars فهرستی از تمام تقویم‌های پیکربندی‌شده را چاپ می‌کند. printformats یک تاریخ ثابت (2013-12-21 21:45) را در تمام قالب‌های تاریخ (و زمان) پیکربندی‌شده چاپ می‌کند. این قابلیت برای کمک به بررسی صحت پیکربندی قالب‌ها در نظر گرفته شده است. search رویدادهای منطبق با یک رشته جستجو را جستجو کرده و چاپ می‌کند. در حال حاضر، جستجو برای هر رویداد متفاوت در یک مجموعه تکرار یک خط چاپ می‌کند؛ یعنی یک خط برای رویداد اصلی و یک خط برای هر رویداد بازنویسی‌شده متفاوت. در حال حاضر هیچ ویژگی جستجوی پیشرفته‌ای پشتیبانی نمی‌شود. دستور khal search party تمام رویدادهای منطبق با party را چاپ می‌کند. پیکربندی (CONFIGURATION) دستور khal فایل‌های پیکربندی را با نحو ini می‌خواند، بدین معنا که کلیدها با علامت = از مقادیر جدا می‌شوند، در حالی که نام بخش‌ها و زیربخش‌ها درون براکت‌های مربع تکی یا دوتایی قرار می‌گیرند (مانند [sectionname] و [[subsectionname]]). هر خطی که با # شروع شود به عنوان کامنت در نظر گرفته خواهد شد. راهنمایی برای پیکربندی اولیه اگر هنوز فایل پیکربندی ندارید، اجرای khal configure یک ابزار تعاملی کوچک را راه‌اندازی می‌کند که به شما در پیکربندی اولیه khal کمک خواهد کرد. محل قرارگیری فایل پیکربندی دستور khal در مکان‌ها و به ترتیب زیر به دنبال فایل‌های پیکربندی می‌گردد: $XDG_CONFIG_HOME/khal/config (در اکثر سیستم‌ها ~/.config/khal/config است)، ~/.khal/khal.conf (منسوخ‌شده) و فایلی به نام khal.conf در دایرکتوری جاری (منسوخ‌شده). همچنین می‌توانید در زمان اجرا با -c path/to/config مشخص کنید که از کدام فایل پیکربندی استفاده شود. بخش [calendars] بخش [calendars] الزامی است و باید حداقل شامل یک زیربخش باشد. هر زیربخش باید یک نام یکتا داشته باشد (که درون دو براکت مربع قرار می‌گیرد). هر زیربخش دقیقاً به یک تنظیم path نیاز دارد و بقیه موارد اختیاری هستند. در اینجا یک مثال کوچک آورده شده است: [calendars] [[home]] path = ~/.calendars/home/ color = dark green priority = 20 [[work]] path = ~/.calendars/work/ readonly = True addresses = user@example.com addresses تمام نشانی‌های ایمیل مرتبط با این حساب کاربری، جدا شده با کاما. در حال حاضر این مورد فقط برای بررسی اینکه چه وضعیت مشارکتی ("PARTSTAT") به کاربر تعلق دارد استفاده می‌شود. type list default color دستور khal از این رنگ برای رنگ‌آمیزی رویدادهای این تقویم استفاده خواهد کرد. نام‌های رنگ زیر پشتیبانی می‌شوند: black، white، brown، yellow، dark gray، dark green، dark blue، light gray، light green، light blue، dark magenta، dark cyan، dark red، light magenta، light cyan، light red. بسته به تنظیمات شبیه‌ساز ترمینال شما، ممکن است ظاهر آن‌ها با نامشان متفاوت باشد. علاوه بر ۱۶ رنگ نام‌گذاری‌شده، در صورت پشتیبانی ترمینال شما، می‌توان از شاخص پالت ۲۵۶ رنگی یا کد رنگ ۲۴ بیتی استفاده کرد. شاخص پالت ۲۵۶ رنگی صرفاً عددی بین 0 تا 255 است. رنگ ۲۴ بیتی باید به صورت #RRGGBB مشخص شود که در آن RR، GG و BB به ترتیب مقدار هگزادسیمال مؤلفه‌های قرمز، سبز و آبی هستند. هنگام استفاده از رنگ ۲۴ بیتی، حتماً مقدار رنگ را در ' یا " قرار دهید! اگر color روی auto (پیش‌فرض) تنظیم شده باشد، khal به دنبال مقدار رنگ در فایل color درون vdir این تقویم می‌گردد. اگر فایل color وجود نداشته باشد، از default_color (به زیر مراجعه کنید) استفاده می‌شود. اگر color روی '' تنظیم شده باشد، همیشه از default_color استفاده می‌شود. توجه داشته باشید که می‌توانید از vdirsyncer metasync برای همگام‌سازی رنگ‌ها با سرور caldav خود استفاده کنید. type color default auto path مسیر دایرکتوری موجود که این تقویم به عنوان یک vdir در آن ذخیره شده است. این دایرکتوری برای رویدادها یا روزهای تولد جستجو می‌شود (گزینه type را ببینید). اگر نوع روی discover تنظیم شده باشد، مسیر از بسط الگو (glob) با استفاده از * یا ? نیز پشتیبانی می‌کند. ** به معنای عمق دلخواه از دایرکتوری‌ها است. این امکان مسیرهایی مانند ~/accounts/*/calendars/* را فراهم می‌کند، جایی که دایرکتوری calendars شامل دایرکتوری‌های vdir است. علاوه بر این، اگر یک vdir در دایرکتوری default وجود داشته باشد، مسیرهای ~/calendars/* و ~/calendars/default معتبر هستند. (رفتار قبلی جستجوی بازگشتی در دایرکتوری‌ها با تطبیق الگو (globbing) جایگزین شده است). type string default None priority هنگام رنگ‌آمیزی روزها، رنگ بر اساس تقویم با بالاترین اولویت تعیین می‌شود. اگر اولویت‌ها برابر باشند، از رنگ "multiple" استفاده خواهد شد. type integer default 10 readonly تنظیم این مقدار روی True، مانع از اعمال هرگونه تغییر توسط khal روی این تقویم می‌شود type boolean default False type تنظیم نوع این مجموعه (پیش‌فرض calendar). اگر روی calendar (پیش‌فرض) تنظیم شود، این مجموعه به عنوان یک تقویم استاندارد استفاده خواهد شد، یعنی فقط فایل‌های با پسوند .ics در نظر گرفته می‌شوند و سایر فایل‌ها نادیده گرفته می‌شوند (به جز یک فایل احتمالی color). اگر روی birthdays تنظیم شود، khal انتظار یک مجموعه VCARD را دارد و روزهای تولد را از آن VCARDها استخراج می‌کند، یعنی فقط فایل‌های با پسوند .vcf در نظر گرفته خواهند شد و سایر فایل‌ها نادیده گرفته می‌شوند. مقدار birthdays همچنین به معنای readonly=True است. اگر روی discover تنظیم شود، khal از تطبیق الگو (globbing) برای بسط path این تقویم به (احتمالاً) چندین مسیر استفاده کرده و از آن‌ها به عنوان تقویم‌های جداگانه استفاده می‌کند (این مورد را نمی‌توان همراه با مجموعه‌های birthday به کار برد). برای مشاهده مثال، به بخش نمونه استفاده از discover مراجعه کنید. اگر vdir یک تقویم منفرد دارای فایل color باشد، رنگ تقویم روی مقدار مشخص‌شده در فایل color تنظیم می‌شود، در غیر این صورت از رنگ زیربخش calendars استفاده خواهد شد. type option, allowed values are calendar, birthdays and discover default calendar بخش [default] برخی مقادیر و رفتارهای پیش‌فرض در اینجا تنظیم می‌شوند. default_calendar تقویمی که در صورت مشخص نشدن تقویم برای یک عملیات (مثلاً هنگام افزودن یک رویداد جدید) استفاده می‌شود. اگر این مقدار تنظیم نشود، چنین عملیاتی نیاز به یک مقدار صریح دارند. type string default None default_dayevent_alarm تعریف هشدار پیش‌فرض برای رویدادهای تمام‌روز جدید، مثلاً '12h' type timedelta default default_dayevent_duration تعریف مدت‌زمان پیش‌فرض برای یک رویداد یک‌روزه (فقط در 'khal new') type timedelta default 1d default_event_alarm تعریف هشدار پیش‌فرض برای رویدادهای جدید، مثلاً '15m' type timedelta default default_event_duration تعریف مدت‌زمان پیش‌فرض برای یک رویداد (فقط در 'khal new') type timedelta default 1h enable_mouse فعال بودن یا نبودن ماوس در حالت تعاملی (فقط در 'khal interactive' و 'ikhal') type boolean default True highlight_event_days در صورت تنظیم روی true، دستور khal روزهای دارای رویداد را متمایز (برجسته) می‌کند. گزینه‌های مربوط به برجسته‌سازی در بخش [highlight_days] قرار دارند. type boolean default False print_new پس از افزودن یک رویداد جدید، چه چیزی باید در خروجی استاندارد چاپ شود؟ کل رویداد در قالب متنی، مسیر ذخیره‌سازی فعلی رویداد یا هیچ چیز؟ type option, allowed values are event, path and False default False show_all_days به‌طور پیش‌فرض، khal فقط تاریخ‌های دارای رویداد را در نمای list یا calendar نمایش می‌دهد. تنظیم این گزینه روی True همه روزها را نشان خواهد داد، حتی زمانی که هیچ رویدادی برای آن روز زمان‌بندی نشده باشد. type boolean default False timedelta کنترل می‌کند که به‌طور پیش‌فرض رویدادها تا چند روز در آینده (مثلاً در khal list) نمایش داده شوند. type timedelta default 2d بخش [highlight_days] هنگامی که highlight_event_days فعال باشد، این بخش نحوه برجسته‌سازی/رنگ‌آمیزی روزها را مشخص می‌کند. color رنگ مورد استفاده برای برجسته‌سازی -- رنگ صریح، یا استفاده از رنگ تقویم در صورت تنظیم روی '' type color default default_color رنگ پیش‌فرض برای تقویم‌های بدون رنگ -- هنگام تنظیم روی ''، برجسته‌سازی را برای رویدادهایی که باید از رنگ پیش‌فرض استفاده کنند غیرفعال می‌کند. type color default method روش برجسته‌سازی مورد استفاده -- پیش‌زمینه یا پس‌زمینه type option, allowed values are foreground, fg, background and bg default fg multiple نحوه رنگ‌آمیزی روزهای دارای رویداد از چندین تقویم -- رنگ صریح یا استفاده از رنگ‌های تقویم‌ها هنگام تنظیم روی '' type color default multiple_on_overflow هنگامی که multiple روی رنگ خاصی تنظیم شده باشد، تنظیم این مقدار روی True باعث می‌شود khal از آن رنگ فقط برای روزهای دارای رویداد از ۳ تقویم یا بیشتر استفاده کند (در نتیجه تمایز دو رنگی برای روزهایی که می‌توان همه رنگ‌های تقویم را نمایش داد حفظ می‌شود) type boolean default False بخش [keybindings] کلیدهای میانبر برای ikhal در اینجا تنظیم می‌شوند. می‌توانید با ارائه یک فهرست از کلیدها که با کاما جدا شده‌اند، بیش از یک کلید (ترکیب) را به یک دستور اختصاص دهید. برای اتصال کلیدهای ترکیبی، آن‌ها را با فاصله به هم متصل کنید، مثلاً ctrl n. delete حذف رویداد انتخاب‌شده فعلی type list default d down انتقال مکان‌نما به پایین (در مرورگر تقویم) type list default down, j duplicate تکثیر رویداد انتخاب‌شده فعلی type list default p export برون‌بری رویداد به عنوان فایل .ics type list default e external_edit ویرایش فایل خام .ics مربوط به رویدادهای انتخاب‌شده فعلی با $EDITOR فقط در صورتی از این گزینه استفاده کنید که می‌دانید چه کاری انجام می‌دهید؛ کتابخانه icalendar مورد استفاده اعتبارسنجی زیادی انجام نمی‌دهد و بیشتر داده‌های نامعتبر را بی‌صدا نادیده می‌گیرد. type list default meta E left انتقال مکان‌نما به چپ (در مرورگر تقویم) type list default left, h, backspace log نمایش پیام‌های ثبت‌شده type list default L mark رفتن به حالت برجسته‌سازی (بصری) برای انتخاب یک بازه زمانی type list default v new ایجاد یک رویداد جدید در تاریخ انتخاب‌شده type list default n other در حالت برجسته‌سازی، رفتن به انتهای دیگر بازه تاریخی برجسته‌شده type list default o quit خروج type list default q, Q right انتقال مکان‌نما به راست (در مرورگر تقویم) type list default right, l, space save ذخیره رویداد در حال ویرایش و خروج از ویرایشگر رویداد type list default meta enter search باز کردن یک فیلد متنی برای شروع جستجوی رویدادها type list default / today تمرکز مرورگر تقویم بر روی امروز type list default t up انتقال مکان‌نما به بالا (در مرورگر تقویم) type list default up, k view نمایش جزئیات یا ویرایش (اگر جزئیات از قبل نمایش داده شده باشند) رویداد انتخاب‌شده فعلی type list default enter بخش [locale] تنظیم گزینه‌های (long)date-، time- و datetimeformat اجباری است؛ تمامی گزینه‌های دیگر در بخش [locale] اختیاری بوده و مقادیر پیش‌فرض (معقول) دارند. dateformat khal تمام تاریخ‌ها را در این قالب نمایش داده و پردازش می‌کند؛ برای ساختار قالب به timeformat مراجعه کنید. type string default %x datetimeformat khal تمام تاریخ-زمان‌ها را در این قالب نمایش داده و پردازش می‌کند؛ برای ساختار قالب به timeformat مراجعه کنید. type string default %c default_timezone این منطقه زمانی برای رویدادهای جدید (زمانی که هیچ منطقه‌ای مشخص نشده باشد) و همچنین زمانی که khal منطقه زمانی مشخص‌شده در فایل icalendar را تشخیص ندهد، استفاده خواهد شد. اگر هیچ منطقه زمانی تنظیم نشده باشد، از منطقه زمانی تنظیم‌شده روی رایانه شما استفاده می‌شود. type timezone default None firstweekday نخستین روز هفته، که در آن دوشنبه 0 و یکشنبه 6 است. type integer, مقادیر مجاز بین 0 و 6 است default 0 local_timezone khal تمام زمان‌ها را در این منطقه زمانی نمایش خواهد داد. اگر هیچ منطقه زمانی تنظیم نشده باشد، از منطقه زمانی تنظیم‌شده روی رایانه شما استفاده می‌شود. type timezone default None longdateformat khal تمام تاریخ‌ها را در این قالب نمایش داده و پردازش می‌کند؛ این قالب باید شامل سال (مانند %Y) باشد؛ برای ساختار قالب به timeformat مراجعه کنید. type string default %x longdatetimeformat khal تمام تاریخ-زمان‌ها را در این قالب نمایش داده و پردازش می‌کند؛ این قالب باید شامل سال (مانند %Y) باشد؛ برای ساختار قالب به timeformat مراجعه کنید. type string default %c timeformat khal تمام زمان‌ها را در این قالب نمایش داده و پردازش می‌کند. رشته قالب‌بندی مطابق با تعریف strftime در پایتون تفسیر می‌شود که مشابه با قالب مشخص‌شده در man strftime است. در فایل پیکربندی ممکن است لازم باشد قالب را درون علامت نقل‌قول قرار دهید تا بارگذاری آن به صورت رشته اجباری شود. type string default %X unicode_symbols به‌طور پیش‌فرض khal از برخی نمادهای یونیکد (غیر اسکی) به عنوان نشانگر مواردی مانند رویدادهای تکرارشونده استفاده می‌کند؛ اگر قلم، کدگذاری و... شما از این نمادها پشتیبانی نمی‌کند، این مقدار را روی False قرار دهید (این کار جایگزین‌های مبتنی بر اسکی را فعال می‌کند). type boolean default True weeknumbers فعال‌سازی شماره هفته‌ها در حالت‌های calendar و interactive (ikhal) با مشخص کردن اینکه آیا باید در سمت راست ('right') یا چپ ('left') نمایش داده شوند. این شماره‌ها مطابق با استاندارد ISO هستند، بنابراین تنها در صورتی به‌درستی کار می‌کنند که firstweekday روی 0 تنظیم شده باشد. type weeknumbers default off بخش [palette] بازنویسی تم رنگی ikhal با یک پالت سفارشی. این گزینه برای استایل‌دهی مجزا به برخی عناصر خاص ikhal مفید است. درایه‌های پالت به شکل key = foreground, background, mono, foreground_high, background_high تعریف می‌شوند که در آن foreground و background در «حالت رنگ اندک (low color mode)»، foreground_high و background_high در «حالت رنگ بالا (high color mode)» و mono در صورتی که فقط حالت تک‌رنگ پشتیبانی شود استفاده می‌شوند. اگر نمی‌خواهید مقداری برای یک رنگ خاص تعیین کنید، از یک رشته خالی ('') استفاده کنید. درایه‌های معتبر برای حالت رنگ اندک در وب‌سایت urwid فهرست شده‌اند. برای حالت رنگ بالا می‌توانید از هر مقدار رنگ معتبر ۲۴ بیتی، مانند '#ff0000' استفاده کنید. نکته: رنگ‌های ۲۴ بیتی باید درون نقل‌قول تکی (single quotes) قرار گیرند تا به‌درستی تجزیه شوند، در غیر این صورت علامت # به عنوان کامنت تفسیر خواهد شد. اکثر ترمینال‌های مدرن باید از حالت رنگ بالا پشتیبانی کنند. نمونه درایه (به‌ویژه نازیبا): [palette] header = light red, default, default, '#ff0000', default edit = '', '', 'bold', '#FF00FF', '#12FF14' footer = '', '', '', '#121233', '#656599' برای مشاهده تمام کلیدهای موجود، پالت‌های پیش‌فرض را در khal/ui/colors.py بررسی کنید. اگر نمی‌توانید عنصری را در ikhal تم‌بندی کنید، لطفاً یک گزارش در گیت‌هاب باز کنید. بخش [sqlite] path khal پایگاه‌داده حافظه پنهان (کش) داخلی خود را در اینجا ذخیره می‌کند؛ به‌طور پیش‌فرض این مسیر در $XDG_CACHE_HOME/khal/khal.db خواهد بود (که به احتمال زیاد ~/.cache/khal/khal.db است). type string default None بخش [view] بخش view شامل گزینه‌های پیکربندی است که بر ظاهر بصری هنگام استفاده از khal و ikhal اثر می‌گذارند. agenda_day_format نحوه قالب‌بندی سربرگ هر روز (day header) را مشخص می‌کند. type string default {bold}{name}, {date-long}{reset} agenda_event_format قالب‌بندی پیش‌فرض رویدادها که هنگام درخواست کاربر برای تمام رویدادها در یک محدوده زمانی مشخص استفاده می‌شود؛ برای list، calendar و در interactive (ikhal) کاربرد دارد. لطفاً توجه داشته باشید که هرگونه استایل‌دهی رنگی در ikhal نادیده گرفته می‌شود، زیرا رویدادها همیشه با رنگ تقویمی که به آن تعلق دارند نمایش داده خواهند شد. دستور زبان آن همانند --format <#cmdoption-format> است. type string default {calendar-color}{cancelled}{start-end-time-style} {title}{repeat-symbol}{alarm-symbol}{description-separator}{description}{reset} blank_line_before_day افزودن یک خط خالی پیش از نام روز (فقط در khal) type boolean default False bold_for_light_color استفاده یا عدم استفاده از متن بولد (توپر) برای رنگ‌های روشن. رنگ‌های روشن غیر بولد ممکن است در همه ترمینال‌ها کار نکنند اما امکان استفاده از رنگ‌های پس‌زمینه روشن را فراهم می‌کنند. type boolean default True dynamic_days رفتار ستون سمت راست ikhal را تعیین می‌کند. اگر روی True تنظیم شود، ستون سمت راست رویدادها را برای هر تعداد روزی که جا شود نمایش می‌دهد و جابجایی مکان‌نما در فهرست، روز مربوطه را در ستون تقویم سمت چپ نیز انتخاب می‌کند. اگر روی False باشد، تنها رویدادهای تعداد ثابتی از روزها (فاصله زمانی [پیش‌فرض]) نمایش داده می‌شوند و جابجایی میان رویدادها، فوکوس ستون سمت چپ را تغییر نخواهد داد. type boolean default True event_format قالب‌بندی پیش‌فرض رویدادها در مواردی که تاریخ شروع و پایان بر اساس زمینه مشخص نیستند، مثلاً برای search؛ تقریباً در همه‌جا به جز list و calendar استفاده می‌شود. بنابراین گنجاندن تاریخ شروع و پایان در آن انتخابی معقول است. دستور زبان آن همانند --format <#cmdoption-format> است. type string default {calendar-color}{cancelled}{start}-{end} {title}{repeat-symbol}{alarm-symbol}{description-separator}{description}{reset} event_view_always_visible برای نمایش همیشگی پنجره نمای رویداد هنگام مشاهده فهرست رویدادها، این گزینه را روی true قرار دهید. type boolean default False event_view_weighting وزن و اولویتی که به پنجره نمای رویداد اعمال می‌شود type integer default 1 frame نمایش یا عدم نمایش کادری قابل مشاهده (با نویسه‌های رسم کادر / box drawing) پیرامون برخی از عناصر (یا گروه‌هایی از آن‌ها). در حال حاضر چندین گزینه مختلف برای کادر در دسترس است که باید از نظر بصری وضعیت فوکوس داشتن یا نداشتن یک عنصر را متمایز کنند. احتمالاً برخی از آن‌ها در نسخه‌های آینده khal حذف خواهند شد، بنابراین لطفاً آن‌ها را آزمایش کرده و درباره سبک مورد علاقه خود بازخورد دهید (رنگ تمام انواع آن در تم‌های رنگی قابل تعریف است). type option, مقادیر مجاز عبارتند از False، width، color و top default False min_calendar_display حداقل تعداد ماه‌های نمایش داده شده توسط دستور calendar پیش‌فرض ۳ ماه است type integer default 3 monthdisplay نمایش نام ماه در سطری که هفته شامل نخستین روز ماه است ('firstday') یا زمانی که نخستین روز هفته در آن ماه قرار دارد ('firstfullweek') type monthdisplay default firstday theme انتخاب تم رنگی برای khal. برنامه khal همراه با دو تم رنگی dark و light عرضه می‌شود. علاوه بر این، افزونه‌ها نیز ممکن است طرح‌های رنگی متفاوتی ارائه دهند. شما همچنین می‌توانید تم رنگی اختصاصی خود را در بخش [palette] تعریف کنید. type string default dark یک نمونه پیکربندی کمینه می‌تواند به این شکل باشد: مثال (Example) [calendars] [[home]] path = ~/.calendars/home/ [[work]] path = ~/.calendars/work/ [locale] local_timezone= Europe/Berlin default_timezone= Europe/Berlin timeformat= %H:%M dateformat= %d.%m. longdateformat= %d.%m.%Y datetimeformat= %d.%m. %H:%M longdatetimeformat= %d.%m.%Y %H:%M نمونه استفاده از discover اگر ساختار دایرکتوری زیر را داشته باشید: ~/calendars ├- work/ ├- home/ └─ family/ که در آن work، home و family همگی vdirهای متفاوتی هستند که هر کدام شامل یک تقویم است، بخش تقویم متناظر می‌تواند به این شکل باشد: [[calendars]] path = ~/calendars/* type = discover color = dark green همگام‌سازی (Syncing) برای راه‌اندازی و استفاده از khal همراه با CalDAV، ابتدا باید vdirsyncer را راه‌اندازی و تنظیم کنید. پس از هر بار اجرا، khal به‌طور خودکار تغییرات را بررسی کرده و پایگاه‌داده حافظه پنهان خود را به‌روزرسانی می‌کند (این کار پس از نخستین همگام‌سازی، به‌ویژه برای مجموعه‌های بزرگ تقویم، ممکن است کمی زمان ببرد). بنابراین، ممکن است بخواهید پس از همگام‌سازی با vdirsyncer، برنامه khal را به‌طور خودکار (مثلاً از طریق cron) اجرا کنید. استانداردها (STANDARDS) برنامه khal تلاش می‌کند تا جای ممکن از استانداردها و RFCها (مهم‌تر از همه RFC 5545 iCalendar) پیروی کند. انحراف‌های شناخته‌شده عمدی و غیرعمدی در زیر فهرست شده‌اند. RDATE;VALUE=PERIOD مقادیر RDATE دارای مقادیر PERIOD در حال حاضر پشتیبانی نمی‌شوند، زیرا icalendar هنوز از آن پشتیبانی نمی‌کند. لطفاً در صورت مواجهه با هر نمونه واقعی از رویدادهای دارای RDATE;VALUE=PERIOD آن را ارسال کنید (در صورت وجود چنین مواردی در تقویم‌های شما، khal هشدارهایی را چاپ خواهد کرد). RANGE=THISANDPRIOR رویدادهای تکرارشونده با RANGE=THISANDPRIOR توسط khal پشتیبانی نمی‌شوند و نخواهند شد [1]، زیرا برنامه‌هایی که از جدیدترین استاندارد پشتیبانی می‌کنند نباید (MUST NOT) آن‌ها را ایجاد کنند. در صورت مواجهه با رویدادی حاوی RANGE=THISANDPRIOR برنامه khal یک هشدار چاپ خواهد کرد. [1] مگر اینکه کاربران زیادی این قابلیت را درخواست کنند رویدادهای بدون END و DURATION در حالی که RFC بیان می‌کند: یک مدخل تقویم با مشخصه "DTSTART" اما بدون مشخصه "DTEND" هیچ زمانی را اشغال نمی‌کند. این مدخل برای نشان دادن رویدادی در نظر گرفته شده که با تاریخ و ساعت مشخصی از روز مرتبط است، مانند سالگرد. از آنجا که این رویداد هیچ زمانی را اشغال نمی‌کند، صرف‌نظر از مقدار مشخصه "TRANSP"، نباید (MUST NOT) برای ثبت زمان مشغول بودن (busy time) استفاده شود. برنامه khal این رویدادها را به رویدادهای تمام‌روز با مدت یک روز (تاریخ شروع) تبدیل می‌کند. تا زمانی که این رویدادها ویرایش نشوند، این تغییرات در vdir (و متعاقباً در سرور CalDAV) نوشته نخواهند شد. هرگونه اطلاعات منطقه زمانی مرتبط با تاریخ شروع نادیده گرفته می‌شود. نکته: اگرچه دلیل اصلی این رفتار کم‌حوصلگی از سوی نویسنده اصلی khal بوده است، سایر نرم‌افزارهای تقویم نیز رفتار مشابهی نشان می‌دهند (مانند تقویم گوگل و Evolution). مناطق زمانی (Timezones) به نظر می‌رسد تنظیم درست زمان محلی، دشوارترین بخش کار با تقویم باشد (و خراب کردن آن منجر به از دست دادن یک جلسه مهم در طول هفته می‌شود). بنابراین در اینجا به طور خلاصه شرح داده می‌شود که khal چگونه با اطلاعات منطقه زمانی برخورد می‌کند، چه اطلاعاتی را می‌تواند پردازش کند و از عهده چه مواردی برنمی‌آید. به طور کلی دو نوع رویداد مختلف وجود دارد: رویدادهای محلی‌شده (Localized events) (با تاریخ و ساعت شروع و پایان محلی‌شده) که اطلاعات منطقه زمانی به تاریخ و ساعت شروع و پایان آن‌ها پیوست شده است، و رویدادهای شناور (Floating events) (با تاریخ و ساعت شروع و پایان شناور) که هیچ اطلاعات منطقه زمانی به آن‌ها پیوست نشده است (رویدادهای تمام‌روز و رویدادهایی که چند روز کامل طول می‌کشند نیز شناور هستند). رویدادهای محلی‌شده همواره در زمان UTC یکسانی دیده می‌شوند (صرف‌نظر از اینکه مشاهده‌کننده در چه منطقه زمانی قرار دارد)، اما ساعت‌های محلی متفاوتی دارند. از سوی دیگر، رویدادهای شناور همواره در همان ساعت محلی مشاهده می‌شوند، که ممکن است در UTC متفاوت باشد. در khal تمام تاریخ و ساعت‌های محلی‌شده به عنوان UTC در پایگاه داده محلی ذخیره می‌شوند. تاریخ و ساعت‌هایی که از قبل UTC هستند، مانند 19980119T070000Z، به همان صورت ذخیره می‌شوند و سایر موارد به UTC تبدیل می‌شوند (اما نگران نباشید، اطلاعات منطقه زمانی از بین نمی‌رود). رویدادهای شناور به صورت زمان شناور و مستقل از رویدادهای محلی‌شده ذخیره می‌شوند. اگر بخواهید بررسی کنید چه رویدادهایی در یک تاریخ و ساعت مشخص رخ می‌دهند، khal همواره انتظار دارد که شما می‌خواهید بدانید چه رویدادهایی در آن تاریخ و ساعت محلی اتفاق می‌افتند. بنابراین، تاریخ و ساعت (محلی) درخواستی شما به UTC تبدیل شده، رویدادهای محلی‌شده مناسب انتخاب می‌شوند و تاریخ و ساعت شروع و پایان آن‌ها پس از تبدیل شدن به تاریخ و ساعت محلی شما نمایش داده می‌شوند. برای رویدادهای شناور نیازی به هیچ تبدیل نیست. برنامه Khal (به طور دقیق‌تر icalendar ) می‌تواند تمام شناسه‌های منطقه زمانی استفاده‌شده در پایگاه داده Olson و تعاریف سفارشی منطقه زمانی را درک کند، به شرطی که آن مؤلفه‌های VTIMEZONE پیش از VEVENTهایی قرار گیرند که از آن‌ها استفاده می‌کنند (همان‌طور که به نظر می‌رسد اکثر برنامه‌های تقویم این کار را انجام می‌دهند). در صورتی که یک منطقه زمانی ناشناخته (یا پشتیبانی‌نشده) پیدا شود، khal فرض می‌کند که می‌خواهید آن رویداد در منطقه زمانی پیش‌فرض قرار گیرد (که در فایل پیکربندی نیز قابل تنظیم است). برنامه khal انتظار دارد شما همواره بخواهید تمام تاریخ و ساعت‌های شروع و پایان در زمان محلی نمایش داده شوند (که در فایل پیکربندی نیز قابل تنظیم است، در غیر این صورت از منطقه زمانی رایانه شما استفاده می‌شود). پرسش‌های متداول (FAQ) پرسش‌های پرتکرار: • نصب با خطا متوقف می‌شود: source/str_util.c:25:20: fatal error: Python.h: No such file or directory هدرهای توسعه پایتون روی سیستم شما نصب نیست. در توزیع‌های مبتنی بر دبیان می‌توانید آن‌ها را از طریق aptitude install python-dev نصب کنید. • کلید ناشناخته "default_command" این کلید در کامیت f8d9135 منسوخ شد. برای آگاهی از دلیل حذف آن، را ببینید. مجوز (LICENSE) برنامه khal تحت مجوز Expat/MIT منتشر شده است: Copyright (c) 2013-2022 khal contributors 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 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. نویسنده (AUTHOR) Christan Geier و دیگران. حق نشر (COPYRIGHT) Copyright (c) 2013-2022 khal contributors 0.14.1 August 21, 2026 KHAL(1)