KHAL(1) khal KHAL(1)

khal - برنامه تقویم متنی و خط فرمانی مبتنی بر استاندارد CalDAV/vCalendar

برنامه khal یک نرم‌افزار تقویم برای محیط خط فرمان و ترمینال جهت مشاهده، افزودن و ویرایش رویدادها و تقویم‌ها است. khal بر پایه استانداردهای iCalendar و vdir (با امکان استفاده از vdirsyncer(1) برای سازگاری با CalDAV) ساخته شده است.

برنامه khal مجموعه‌ای از دستورات را ارائه می‌دهد که مهم‌ترین آن‌ها عبارتند از: list، calendar، interactive، new، printcalendars، printformats و search. برای توضیحات عملکرد هر دستور به بخش‌های زیر مراجعه کنید. در حال حاضر khal از هیچ دستور پیش‌فرضی پشتیبانی نمی‌کند (یعنی در صورت مشخص نشدن دستور، دستوری اجرا نمی‌شود). این رفتار عمدی است.

برنامه khal (بدون هیچ زیردستوری) گزینه‌هایی برای نمایش اطلاعاتی درباره khal دارد:

نسخه khal را چاپ کرده و خارج می‌شود.
خلاصه‌ای از گزینه‌ها و دستورات khal را نمایش داده و سپس خارج می‌شود.

چندین گزینه میان تقریباً تمام دستورات khal مشترک هستند (موارد استثنا در ادامه توضیح داده شده‌اند):

میزان پرگویی و جزئیات گزارش‌ها را تنظیم می‌کند (مثلاً چاپ اطلاعات اشکال‌زدایی)، LVL باید یکی از مقادیر CRITICAL، ERROR، WARNING، INFO یا DEBUG باشد.
از فایل لاگ LOGFILE برای ثبت گزارش‌ها استفاده می‌کند؛ حالت پیش‌فرض ارسال گزارش به خروجی استاندارد (stdout) است.
از یک فایل پیکربندی جایگزین استفاده می‌کند.
تقویم مورد استفاده را مشخص می‌کند (که باید در فایل پیکربندی تعریف شده باشد)؛ می‌تواند چندین بار استفاده شود. تقویم‌هایی که مشخص نشده باشند در این اجرا نادیده گرفته می‌شوند.
تقویمی را مشخص می‌کند که در این اجرا نادیده گرفته می‌شود؛ می‌تواند چندین بار استفاده شود.
برنامه khal تشخیص می‌دهد که آیا خروجی استاندارد یک tty نیست (برای نمونه هنگامی که خروجی khal را به یک فایل هدایت می‌کنید) و در این صورت تمام رنگ‌آمیزی‌ها و برجسته‌سازی‌ها را از خروجی حذف می‌کند. اگر می‌خواهید رنگ‌آمیزی را اجباری کنید از --color و اگر می‌خواهید رنگ‌ها همیشه حذف شوند از --no-color استفاده کنید.
برای تمام دستورات khal که رویدادها را چاپ می‌کنند، قالب‌بندی نمایش رویداد را می‌توان با این گزینه مشخص کرد. FORMAT یک رشته الگویی است که در آن شناسه‌های محصور میان آکولاد ({}) به ویژگی‌های رویداد گسترش می‌یابند. FORMAT از تمام قابلیت‌های قالب‌بندی ارائه‌شده توسط str.format() پایتون https://docs.python.org/3/library/string.html#formatstrings پشتیبانی می‌کند (زیرا در ساختار داخلی آن استفاده می‌شود). گزینه‌های الگوی موجود عبارتند از:
عنوان رویداد.
توضیحات رویداد.
description-separator
جداکننده: " :: " که هنگام وجود توضیحات نمایش داده می‌شود.
شناسه یکتای (UID) رویداد.
تاریخ و زمان شروع در قالب datetimeformat.
start-long
تاریخ و زمان شروع در قالب longdatetimeformat.
start-date
تاریخ شروع در قالب dateformat.
start-date-long
تاریخ شروع در قالب longdateformat.
start-time
زمان شروع در قالب timeformat.
تاریخ و زمان پایان در قالب datetimeformat.
end-long
تاریخ و زمان پایان در قالب longdatetimeformat.
end-date
تاریخ پایان در قالب dateformat.
end-date-long
تاریخ پایان در قالب longdateformat.
end-time
زمان پایان در قالب timeformat.
نماد تکرار (فلش حلقه) در صورتی که رویداد تکرارشونده باشد.
نماد هشدار (ساعت زنگ‌دار) در صورتی که رویداد حداقل یک هشدار داشته باشد.
فهرستی جداشده با کاما از هشدارهای رویداد (مثلاً alarm1@-15m, getready@-1h).
مکان رویداد.
نام تقویم.
calendar-color
رنگ خروجی را به رنگ تقویم تغییر می‌دهد.
start-style
زمان شروع در قالب timeformat یا یک نماد مناسب.
یک خط تیره "-" یا هیچ چیز، به گونه‌ای که به شکل مناسب میان 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 استفاده می‌کند.
وضعیت رویداد (اگر این رویداد وضعیتی داشته باشد)، مقداری مانند CONFIRMED یا CANCELLED.
status-symbol
وضعیت رویداد به عنوان یک نماد، ✓ یا ✗ یا ?.
وضعیت مشارکت در رویداد به عنوان یک نماد، ✓ یا ✗ یا ?.
رشته CANCELLED (به همراه یک فاصله) در صورتی که وضعیت رویداد لغو شده باشد، در غیر این صورت خالی.
برگزارکننده رویداد. اگر قالب دارای 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-separator
جداکننده: " :: " که هنگام وجود URL نمایش داده می‌شود.
مدت زمان رویداد بر حسب روز، ساعت، دقیقه و ثانیه (به ترتیب با حروف اختصاری d، h، m و s).
قاعده خام تکرار iCal در صورتی که رویداد تکرارشونده باشد.
یک مقدار بولی که نشان می‌دهد رویداد تمام‌روز است یا خیر.
دسته‌بندی‌های رویداد.

به طور پیش‌فرض، رویدادهای تمام‌روز فاقد زمان هستند. برای مشاهده زمان شروع و پایان در هر حال، کافی است -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}"
مشابه --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
مشابه --format عمل می‌کند، اما برای سرصفحه روزها است. این گزینه تنها چند انتخاب دارد (علاوه بر تمامی گزینه‌های رنگ):
تاریخ در قالب dateformat.
date-long
تاریخ در قالب longdateformat.
نام روز (Monday، Tuesday، …) یا today یا tomorrow.

اگر به --day-format یک رشته خالی داده شود، سرصفحه روزها را چاپ نخواهد کرد (برای یک خط خالی، یک کاراکتر فاصله ارسال کنید).

تقریباً در هر جایی که khal تاریخ‌ها را می‌پذیرد، باید نام‌های نسبی تاریخ مانند today، tomorrow و نام روزهای هفته (همچنین به صورت مخفف سه حرفی) را تشخیص دهد. نام روزهای هفته به عنوان تاریخ وقوع بعدی آن روز تفسیر می‌شوند. نام روز جاری به عنوان آن تاریخ در هفته بعدی (یعنی هفت روز بعد از امروز) تفسیر می‌شود.

اگر از قالب کوتاهِ تاریخ‌وزمان استفاده شود (سالی ذکر نشود)، khal تاریخ را در آینده تفسیر خواهد کرد. در صورتی که تاریخ داده‌شده در سال جاری گذشته باشد، احتمالاً به عنوان سال بعد در نظر گرفته می‌شود.

تمام رویدادهای زمان‌بندی‌شده برای یک محدوده تاریخ (یا تاریخ‌وزمان) مشخص را با قالب‌بندی سفارشی نمایش می‌دهد:

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 تمام رویدادهای مربوط به ۳۱ روز پس از ۱ دسامبر ۲۰۱۹ را نمایش می‌دهد.

تمام رویدادهای زمان‌بندی‌شده برای یک تاریخ‌وزمان مشخص را نمایش می‌دهد. به khal at باید یک تاریخ و زمان، فقط یک زمان (که در این صورت تاریخ امروز فرض می‌شود) یا رشته now داده شود. مقدار پیش‌فرض at برابر now است. دستور at دقیقاً مانند دستور list عمل می‌کند، با این تفاوت که زمان پایان ضمنی آن صفر دقیقه پس از شروع است.

khal at [-a CALENDAR ... | -d CALENDAR ...]
[--format FORMAT] [--json FIELD ...]
[--notstarted] [[START DATE] TIME | now]

یک تقویم (مشابه cal(1)) و یک فهرست را نمایش می‌دهد. دستور khal calendar سینتکس زیر را می‌پذیرد:

khal calendar [-a CALENDAR ... | -d CALENDAR ...] [START DATETIME]
[END DATETIME]

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

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

به کاربر امکان می‌دهد فایل‌های .ics را با ساختار زیر وارد کند:

khal import [-a CALENDAR] [--batch] [--random-uid|-r] ICSFILE

اگر رویدادی با همان UID از قبل در تقویم انتخاب‌شده (ضمنی) وجود داشته باشد، khal import پیش از به‌روزرسانی (یعنی بازنویسی) آن رویداد قدیمی با رویداد واردشده سوال می‌پرسد، مگر اینکه --batch داده شده باشد که در این صورت همیشه به‌روزرسانی می‌کند. اگر این رفتار مورد نظر نیست، از فلگ --random-uid برای تولید یک UID جدید و تصادفی استفاده کنید. اگر تقویمی مشخص نشده باشد (و --batch نباشد)، از شما خواسته می‌شود یک تقویم انتخاب کنید. می‌توانید شماره چاپ‌شده در کنار نام هر تقویم یا هر پیشوند یکتا از نام تقویم را وارد کنید.

نسخه تعاملی 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 بسته می‌شود.

امکان افزودن رویدادهای جدید را فراهم می‌کند. دستور 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 https://docs.python.org/3/using/cmdline.html#cmdoption-i) تمام آرگومان‌ها را اختیاری می‌کند و فیلدهای لازم را به صورت تعاملی درخواست می‌نماید؛ سپس می‌توان رویداد را همانند دستور edit ویرایش کرد.

  • -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 هشدار را بعد از شروع رویداد تنظیم می‌کنند.

این مثال‌ها ممکن است نیاز به تطبیق با پیکربندی و/یا محلی‌سازی (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 اضافه می‌کند که هر هفته تکرار می‌شود.

یک دستور تعاملی برای ویرایش و حذف رویدادها با استفاده از یک رشته جستجو است.

khal edit [--show-past] event_search_string

این دستور تمام رویدادهای منطبق با رشته جستجو را پیمایش کرده و برای حذف یا تغییر ویژگی‌ها از کاربر تایید می‌گیرد.

فهرستی از تمام تقویم‌های پیکربندی‌شده را چاپ می‌کند.

یک تاریخ ثابت (2013-12-21 21:45) را در تمام قالب‌های تاریخ (و زمان) پیکربندی‌شده چاپ می‌کند. این قابلیت برای کمک به بررسی صحت پیکربندی قالب‌ها در نظر گرفته شده است.

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

دستور

khal search party

تمام رویدادهای منطبق با party را چاپ می‌کند.

دستور 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] الزامی است و باید حداقل شامل یک زیربخش باشد. هر زیربخش باید یک نام یکتا داشته باشد (که درون دو براکت مربع قرار می‌گیرد). هر زیربخش دقیقاً به یک تنظیم path نیاز دارد و بقیه موارد اختیاری هستند. در اینجا یک مثال کوچک آورده شده است:

[calendars]
  [[home]]
    path = ~/.calendars/home/
    color = dark green
    priority = 20
  [[work]]
    path = ~/.calendars/work/
    readonly = True
    addresses = user@example.com
تمام نشانی‌های ایمیل مرتبط با این حساب کاربری، جدا شده با کاما. در حال حاضر این مورد فقط برای بررسی اینکه چه وضعیت مشارکتی ("PARTSTAT") به کاربر تعلق دارد استفاده می‌شود.
list
دستور 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 خود استفاده کنید.
color
auto
مسیر دایرکتوری موجود که این تقویم به عنوان یک vdir در آن ذخیره شده است. این دایرکتوری برای رویدادها یا روزهای تولد جستجو می‌شود (گزینه type را ببینید). اگر نوع روی discover تنظیم شده باشد، مسیر از بسط الگو (glob) با استفاده از * یا ? نیز پشتیبانی می‌کند. ** به معنای عمق دلخواه از دایرکتوری‌ها است. این امکان مسیرهایی مانند ~/accounts/*/calendars/* را فراهم می‌کند، جایی که دایرکتوری calendars شامل دایرکتوری‌های vdir است. علاوه بر این، اگر یک vdir در دایرکتوری default وجود داشته باشد، مسیرهای ~/calendars/* و ~/calendars/default معتبر هستند. (رفتار قبلی جستجوی بازگشتی در دایرکتوری‌ها با تطبیق الگو (globbing) جایگزین شده است).
string
None
هنگام رنگ‌آمیزی روزها، رنگ بر اساس تقویم با بالاترین اولویت تعیین می‌شود. اگر اولویت‌ها برابر باشند، از رنگ "multiple" استفاده خواهد شد.
integer
10
تنظیم این مقدار روی True، مانع از اعمال هرگونه تغییر توسط khal روی این تقویم می‌شود
boolean
False
تنظیم نوع این مجموعه (پیش‌فرض calendar).

اگر روی calendar (پیش‌فرض) تنظیم شود، این مجموعه به عنوان یک تقویم استاندارد استفاده خواهد شد، یعنی فقط فایل‌های با پسوند .ics در نظر گرفته می‌شوند و سایر فایل‌ها نادیده گرفته می‌شوند (به جز یک فایل احتمالی color).

اگر روی birthdays تنظیم شود، khal انتظار یک مجموعه VCARD را دارد و روزهای تولد را از آن VCARDها استخراج می‌کند، یعنی فقط فایل‌های با پسوند .vcf در نظر گرفته خواهند شد و سایر فایل‌ها نادیده گرفته می‌شوند. مقدار birthdays همچنین به معنای readonly=True است.

اگر روی discover تنظیم شود، khal از تطبیق الگو (globbing) <https://en.wikipedia.org/wiki/Glob_(programming)> برای بسط path این تقویم به (احتمالاً) چندین مسیر استفاده کرده و از آن‌ها به عنوان تقویم‌های جداگانه استفاده می‌کند (این مورد را نمی‌توان همراه با مجموعه‌های birthday به کار برد). برای مشاهده مثال، به بخش نمونه استفاده از discover مراجعه کنید.

اگر vdir یک تقویم منفرد دارای فایل color باشد، رنگ تقویم روی مقدار مشخص‌شده در فایل color تنظیم می‌شود، در غیر این صورت از رنگ زیربخش calendars استفاده خواهد شد.

option, allowed values are calendar, birthdays and discover
calendar

برخی مقادیر و رفتارهای پیش‌فرض در اینجا تنظیم می‌شوند.

تقویمی که در صورت مشخص نشدن تقویم برای یک عملیات (مثلاً هنگام افزودن یک رویداد جدید) استفاده می‌شود. اگر این مقدار تنظیم نشود، چنین عملیاتی نیاز به یک مقدار صریح دارند.
string
None
تعریف هشدار پیش‌فرض برای رویدادهای تمام‌روز جدید، مثلاً '12h'
timedelta
تعریف مدت‌زمان پیش‌فرض برای یک رویداد یک‌روزه (فقط در 'khal new')
timedelta
1d
تعریف هشدار پیش‌فرض برای رویدادهای جدید، مثلاً '15m'
timedelta
تعریف مدت‌زمان پیش‌فرض برای یک رویداد (فقط در 'khal new')
timedelta
1h
فعال بودن یا نبودن ماوس در حالت تعاملی (فقط در 'khal interactive' و 'ikhal')
boolean
True
در صورت تنظیم روی true، دستور khal روزهای دارای رویداد را متمایز (برجسته) می‌کند. گزینه‌های مربوط به برجسته‌سازی در بخش [highlight_days] قرار دارند.
boolean
False
پس از افزودن یک رویداد جدید، چه چیزی باید در خروجی استاندارد چاپ شود؟ کل رویداد در قالب متنی، مسیر ذخیره‌سازی فعلی رویداد یا هیچ چیز؟
option, allowed values are event, path and False
False
به‌طور پیش‌فرض، khal فقط تاریخ‌های دارای رویداد را در نمای list یا calendar نمایش می‌دهد. تنظیم این گزینه روی True همه روزها را نشان خواهد داد، حتی زمانی که هیچ رویدادی برای آن روز زمان‌بندی نشده باشد.
boolean
False
کنترل می‌کند که به‌طور پیش‌فرض رویدادها تا چند روز در آینده (مثلاً در khal list) نمایش داده شوند.
timedelta
2d

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

رنگ مورد استفاده برای برجسته‌سازی -- رنگ صریح، یا استفاده از رنگ تقویم در صورت تنظیم روی ''
color
رنگ پیش‌فرض برای تقویم‌های بدون رنگ -- هنگام تنظیم روی ''، برجسته‌سازی را برای رویدادهایی که باید از رنگ پیش‌فرض استفاده کنند غیرفعال می‌کند.
color
روش برجسته‌سازی مورد استفاده -- پیش‌زمینه یا پس‌زمینه
option, allowed values are foreground, fg, background and bg
fg
نحوه رنگ‌آمیزی روزهای دارای رویداد از چندین تقویم -- رنگ صریح یا استفاده از رنگ‌های تقویم‌ها هنگام تنظیم روی ''
color
هنگامی که multiple روی رنگ خاصی تنظیم شده باشد، تنظیم این مقدار روی True باعث می‌شود khal از آن رنگ فقط برای روزهای دارای رویداد از ۳ تقویم یا بیشتر استفاده کند (در نتیجه تمایز دو رنگی برای روزهایی که می‌توان همه رنگ‌های تقویم را نمایش داد حفظ می‌شود)
boolean
False

کلیدهای میانبر برای ikhal در اینجا تنظیم می‌شوند. می‌توانید با ارائه یک فهرست از کلیدها که با کاما جدا شده‌اند، بیش از یک کلید (ترکیب) را به یک دستور اختصاص دهید. برای اتصال کلیدهای ترکیبی، آن‌ها را با فاصله به هم متصل کنید، مثلاً ctrl n.

حذف رویداد انتخاب‌شده فعلی
list
d
انتقال مکان‌نما به پایین (در مرورگر تقویم)
list
down, j
تکثیر رویداد انتخاب‌شده فعلی
list
p
برون‌بری رویداد به عنوان فایل .ics
list
e
ویرایش فایل خام .ics مربوط به رویدادهای انتخاب‌شده فعلی با $EDITOR فقط در صورتی از این گزینه استفاده کنید که می‌دانید چه کاری انجام می‌دهید؛ کتابخانه icalendar مورد استفاده اعتبارسنجی زیادی انجام نمی‌دهد و بیشتر داده‌های نامعتبر را بی‌صدا نادیده می‌گیرد.
list
meta E
انتقال مکان‌نما به چپ (در مرورگر تقویم)
list
left, h, backspace
نمایش پیام‌های ثبت‌شده
list
L
رفتن به حالت برجسته‌سازی (بصری) برای انتخاب یک بازه زمانی
list
v
ایجاد یک رویداد جدید در تاریخ انتخاب‌شده
list
n
در حالت برجسته‌سازی، رفتن به انتهای دیگر بازه تاریخی برجسته‌شده
list
o
خروج
list
q, Q
انتقال مکان‌نما به راست (در مرورگر تقویم)
list
right, l, space
ذخیره رویداد در حال ویرایش و خروج از ویرایشگر رویداد
list
meta enter
باز کردن یک فیلد متنی برای شروع جستجوی رویدادها
list
/
تمرکز مرورگر تقویم بر روی امروز
list
t
انتقال مکان‌نما به بالا (در مرورگر تقویم)
list
up, k
نمایش جزئیات یا ویرایش (اگر جزئیات از قبل نمایش داده شده باشند) رویداد انتخاب‌شده فعلی
list
enter

تنظیم گزینه‌های (long)date-، time- و datetimeformat اجباری است؛ تمامی گزینه‌های دیگر در بخش [locale] اختیاری بوده و مقادیر پیش‌فرض (معقول) دارند.

khal تمام تاریخ‌ها را در این قالب نمایش داده و پردازش می‌کند؛ برای ساختار قالب به timeformat مراجعه کنید.
string
%x
khal تمام تاریخ-زمان‌ها را در این قالب نمایش داده و پردازش می‌کند؛ برای ساختار قالب به timeformat مراجعه کنید.
string
%c
این منطقه زمانی برای رویدادهای جدید (زمانی که هیچ منطقه‌ای مشخص نشده باشد) و همچنین زمانی که khal منطقه زمانی مشخص‌شده در فایل icalendar را تشخیص ندهد، استفاده خواهد شد. اگر هیچ منطقه زمانی تنظیم نشده باشد، از منطقه زمانی تنظیم‌شده روی رایانه شما استفاده می‌شود.
timezone
None
نخستین روز هفته، که در آن دوشنبه 0 و یکشنبه 6 است.
integer, مقادیر مجاز بین 0 و 6 است
0
khal تمام زمان‌ها را در این منطقه زمانی نمایش خواهد داد. اگر هیچ منطقه زمانی تنظیم نشده باشد، از منطقه زمانی تنظیم‌شده روی رایانه شما استفاده می‌شود.
timezone
None
khal تمام تاریخ‌ها را در این قالب نمایش داده و پردازش می‌کند؛ این قالب باید شامل سال (مانند %Y) باشد؛ برای ساختار قالب به timeformat مراجعه کنید.
string
%x
khal تمام تاریخ-زمان‌ها را در این قالب نمایش داده و پردازش می‌کند؛ این قالب باید شامل سال (مانند %Y) باشد؛ برای ساختار قالب به timeformat مراجعه کنید.
string
%c
khal تمام زمان‌ها را در این قالب نمایش داده و پردازش می‌کند.

رشته قالب‌بندی مطابق با تعریف strftime در پایتون https://docs.python.org/3/library/time.html#time.strftime تفسیر می‌شود که مشابه با قالب مشخص‌شده در man strftime است.

در فایل پیکربندی ممکن است لازم باشد قالب را درون علامت نقل‌قول قرار دهید تا بارگذاری آن به صورت رشته اجباری شود.

string
%X
به‌طور پیش‌فرض khal از برخی نمادهای یونیکد (غیر اسکی) به عنوان نشانگر مواردی مانند رویدادهای تکرارشونده استفاده می‌کند؛ اگر قلم، کدگذاری و... شما از این نمادها پشتیبانی نمی‌کند، این مقدار را روی False قرار دهید (این کار جایگزین‌های مبتنی بر اسکی را فعال می‌کند).
boolean
True
فعال‌سازی شماره هفته‌ها در حالت‌های calendar و interactive (ikhal) با مشخص کردن اینکه آیا باید در سمت راست ('right') یا چپ ('left') نمایش داده شوند. این شماره‌ها مطابق با استاندارد ISO هستند، بنابراین تنها در صورتی به‌درستی کار می‌کنند که firstweekday روی 0 تنظیم شده باشد.
weeknumbers
off

بازنویسی تم رنگی ikhal با یک پالت سفارشی. این گزینه برای استایل‌دهی مجزا به برخی عناصر خاص ikhal مفید است. درایه‌های پالت به شکل key = foreground, background, mono, foreground_high, background_high تعریف می‌شوند که در آن foreground و background در «حالت رنگ اندک (low color mode)»، foreground_high و background_high در «حالت رنگ بالا (high color mode)» و mono در صورتی که فقط حالت تک‌رنگ پشتیبانی شود استفاده می‌شوند. اگر نمی‌خواهید مقداری برای یک رنگ خاص تعیین کنید، از یک رشته خالی ('') استفاده کنید. درایه‌های معتبر برای حالت رنگ اندک در وب‌سایت urwid http://urwid.org/manual/displayattributes.html#standard-foreground-colors فهرست شده‌اند. برای حالت رنگ بالا می‌توانید از هر مقدار رنگ معتبر ۲۴ بیتی، مانند '#ff0000' استفاده کنید.

نکته:

رنگ‌های ۲۴ بیتی باید درون نقل‌قول تکی (single quotes) قرار گیرند تا به‌درستی تجزیه شوند، در غیر این صورت علامت # به عنوان کامنت تفسیر خواهد شد.

اکثر ترمینال‌های مدرن باید از حالت رنگ بالا پشتیبانی کنند.

نمونه درایه (به‌ویژه نازیبا):

[palette]
header = light red, default, default, '#ff0000', default
edit = '', '', 'bold', '#FF00FF', '#12FF14'
footer = '', '', '', '#121233', '#656599'

برای مشاهده تمام کلیدهای موجود، پالت‌های پیش‌فرض را در khal/ui/colors.py بررسی کنید. اگر نمی‌توانید عنصری را در ikhal تم‌بندی کنید، لطفاً یک گزارش در گیت‌هاب https://github.com/pimutils/khal/issues/new/choose باز کنید.

khal پایگاه‌داده حافظه پنهان (کش) داخلی خود را در اینجا ذخیره می‌کند؛ به‌طور پیش‌فرض این مسیر در $XDG_CACHE_HOME/khal/khal.db خواهد بود (که به احتمال زیاد ~/.cache/khal/khal.db است).
string
None

بخش view شامل گزینه‌های پیکربندی است که بر ظاهر بصری هنگام استفاده از khal و ikhal اثر می‌گذارند.

نحوه قالب‌بندی سربرگ هر روز (day header) را مشخص می‌کند.
string
{bold}{name}, {date-long}{reset}
قالب‌بندی پیش‌فرض رویدادها که هنگام درخواست کاربر برای تمام رویدادها در یک محدوده زمانی مشخص استفاده می‌شود؛ برای list، calendar و در interactive (ikhal) کاربرد دارد. لطفاً توجه داشته باشید که هرگونه استایل‌دهی رنگی در ikhal نادیده گرفته می‌شود، زیرا رویدادها همیشه با رنگ تقویمی که به آن تعلق دارند نمایش داده خواهند شد. دستور زبان آن همانند --format <#cmdoption-format> است.
string
{calendar-color}{cancelled}{start-end-time-style} {title}{repeat-symbol}{alarm-symbol}{description-separator}{description}{reset}
افزودن یک خط خالی پیش از نام روز (فقط در khal)
boolean
False
استفاده یا عدم استفاده از متن بولد (توپر) برای رنگ‌های روشن. رنگ‌های روشن غیر بولد ممکن است در همه ترمینال‌ها کار نکنند اما امکان استفاده از رنگ‌های پس‌زمینه روشن را فراهم می‌کنند.
boolean
True
رفتار ستون سمت راست ikhal را تعیین می‌کند. اگر روی True تنظیم شود، ستون سمت راست رویدادها را برای هر تعداد روزی که جا شود نمایش می‌دهد و جابجایی مکان‌نما در فهرست، روز مربوطه را در ستون تقویم سمت چپ نیز انتخاب می‌کند. اگر روی False باشد، تنها رویدادهای تعداد ثابتی از روزها (فاصله زمانی [پیش‌فرض]) نمایش داده می‌شوند و جابجایی میان رویدادها، فوکوس ستون سمت چپ را تغییر نخواهد داد.
boolean
True
قالب‌بندی پیش‌فرض رویدادها در مواردی که تاریخ شروع و پایان بر اساس زمینه مشخص نیستند، مثلاً برای search؛ تقریباً در همه‌جا به جز list و calendar استفاده می‌شود. بنابراین گنجاندن تاریخ شروع و پایان در آن انتخابی معقول است. دستور زبان آن همانند --format <#cmdoption-format> است.
string
{calendar-color}{cancelled}{start}-{end} {title}{repeat-symbol}{alarm-symbol}{description-separator}{description}{reset}
برای نمایش همیشگی پنجره نمای رویداد هنگام مشاهده فهرست رویدادها، این گزینه را روی true قرار دهید.
boolean
False
وزن و اولویتی که به پنجره نمای رویداد اعمال می‌شود
integer
1
نمایش یا عدم نمایش کادری قابل مشاهده (با نویسه‌های رسم کادر / box drawing) پیرامون برخی از عناصر (یا گروه‌هایی از آن‌ها). در حال حاضر چندین گزینه مختلف برای کادر در دسترس است که باید از نظر بصری وضعیت فوکوس داشتن یا نداشتن یک عنصر را متمایز کنند. احتمالاً برخی از آن‌ها در نسخه‌های آینده khal حذف خواهند شد، بنابراین لطفاً آن‌ها را آزمایش کرده و درباره سبک مورد علاقه خود بازخورد دهید (رنگ تمام انواع آن در تم‌های رنگی قابل تعریف است).
option, مقادیر مجاز عبارتند از False، width، color و top
False
حداقل تعداد ماه‌های نمایش داده شده توسط دستور calendar پیش‌فرض ۳ ماه است
integer
3
نمایش نام ماه در سطری که هفته شامل نخستین روز ماه است ('firstday') یا زمانی که نخستین روز هفته در آن ماه قرار دارد ('firstfullweek')
monthdisplay
firstday
انتخاب تم رنگی برای khal.

برنامه khal همراه با دو تم رنگی dark و light عرضه می‌شود. علاوه بر این، افزونه‌ها نیز ممکن است طرح‌های رنگی متفاوتی ارائه دهند. شما همچنین می‌توانید تم رنگی اختصاصی خود را در بخش [palette] تعریف کنید.

string
dark

یک نمونه پیکربندی کمینه می‌تواند به این شکل باشد:

[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

اگر ساختار دایرکتوری زیر را داشته باشید:

~/calendars
├- work/
├- home/
└─ family/

که در آن work، home و family همگی vdirهای متفاوتی هستند که هر کدام شامل یک تقویم است، بخش تقویم متناظر می‌تواند به این شکل باشد:

[[calendars]]
path = ~/calendars/*
type = discover
color = dark green

برای راه‌اندازی و استفاده از khal همراه با CalDAV، ابتدا باید vdirsyncer https://github.com/pimutils/vdirsyncer را راه‌اندازی و تنظیم کنید. پس از هر بار اجرا، khal به‌طور خودکار تغییرات را بررسی کرده و پایگاه‌داده حافظه پنهان خود را به‌روزرسانی می‌کند (این کار پس از نخستین همگام‌سازی، به‌ویژه برای مجموعه‌های بزرگ تقویم، ممکن است کمی زمان ببرد). بنابراین، ممکن است بخواهید پس از همگام‌سازی با vdirsyncer، برنامه khal را به‌طور خودکار (مثلاً از طریق cron) اجرا کنید.

برنامه khal تلاش می‌کند تا جای ممکن از استانداردها و RFCها (مهم‌تر از همه RFC 5545 https://datatracker.ietf.org/doc/html/rfc5545.html iCalendar) پیروی کند. انحراف‌های شناخته‌شده عمدی و غیرعمدی در زیر فهرست شده‌اند.

مقادیر RDATE دارای مقادیر PERIOD در حال حاضر پشتیبانی نمی‌شوند، زیرا icalendar https://github.com/collective/icalendar هنوز از آن پشتیبانی نمی‌کند. لطفاً در صورت مواجهه با هر نمونه واقعی از رویدادهای دارای RDATE;VALUE=PERIOD آن را ارسال کنید (در صورت وجود چنین مواردی در تقویم‌های شما، khal هشدارهایی را چاپ خواهد کرد).

رویدادهای تکرارشونده با RANGE=THISANDPRIOR توسط khal پشتیبانی نمی‌شوند و نخواهند شد [1]، زیرا برنامه‌هایی که از جدیدترین استاندارد http://tools.ietf.org/html/rfc5546 پشتیبانی می‌کنند نباید (MUST NOT) آن‌ها را ایجاد کنند. در صورت مواجهه با رویدادی حاوی RANGE=THISANDPRIOR برنامه khal یک هشدار چاپ خواهد کرد.

[1]
مگر اینکه کاربران زیادی این قابلیت را درخواست کنند

در حالی که RFC بیان می‌کند:

یک مدخل تقویم با مشخصه "DTSTART" اما بدون مشخصه
"DTEND" هیچ زمانی را اشغال نمی‌کند. این مدخل برای نشان دادن
رویدادی در نظر گرفته شده که با تاریخ و ساعت مشخصی از روز مرتبط است،
مانند سالگرد. از آنجا که این رویداد هیچ زمانی را اشغال نمی‌کند،
صرف‌نظر از مقدار مشخصه "TRANSP"، نباید (MUST NOT) برای
ثبت زمان مشغول بودن (busy time) استفاده شود.

برنامه khal این رویدادها را به رویدادهای تمام‌روز با مدت یک روز (تاریخ شروع) تبدیل می‌کند. تا زمانی که این رویدادها ویرایش نشوند، این تغییرات در vdir (و متعاقباً در سرور CalDAV) نوشته نخواهند شد. هرگونه اطلاعات منطقه زمانی مرتبط با تاریخ شروع نادیده گرفته می‌شود.

نکته:

اگرچه دلیل اصلی این رفتار کم‌حوصلگی از سوی نویسنده اصلی khal بوده است، سایر نرم‌افزارهای تقویم نیز رفتار مشابهی نشان می‌دهند (مانند تقویم گوگل و Evolution).

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

به طور کلی دو نوع رویداد مختلف وجود دارد: رویدادهای محلی‌شده (Localized events) (با تاریخ و ساعت شروع و پایان محلی‌شده) که اطلاعات منطقه زمانی به تاریخ و ساعت شروع و پایان آن‌ها پیوست شده است، و رویدادهای شناور (Floating events) (با تاریخ و ساعت شروع و پایان شناور) که هیچ اطلاعات منطقه زمانی به آن‌ها پیوست نشده است (رویدادهای تمام‌روز و رویدادهایی که چند روز کامل طول می‌کشند نیز شناور هستند). رویدادهای محلی‌شده همواره در زمان UTC یکسانی https://en.wikipedia.org/wiki/Coordinated_Universal_Time دیده می‌شوند (صرف‌نظر از اینکه مشاهده‌کننده در چه منطقه زمانی قرار دارد)، اما ساعت‌های محلی متفاوتی دارند. از سوی دیگر، رویدادهای شناور همواره در همان ساعت محلی مشاهده می‌شوند، که ممکن است در UTC متفاوت باشد.

در khal تمام تاریخ و ساعت‌های محلی‌شده به عنوان UTC در پایگاه داده محلی ذخیره می‌شوند. تاریخ و ساعت‌هایی که از قبل UTC هستند، مانند 19980119T070000Z، به همان صورت ذخیره می‌شوند و سایر موارد به UTC تبدیل می‌شوند (اما نگران نباشید، اطلاعات منطقه زمانی از بین نمی‌رود). رویدادهای شناور به صورت زمان شناور و مستقل از رویدادهای محلی‌شده ذخیره می‌شوند.

اگر بخواهید بررسی کنید چه رویدادهایی در یک تاریخ و ساعت مشخص رخ می‌دهند، khal همواره انتظار دارد که شما می‌خواهید بدانید چه رویدادهایی در آن تاریخ و ساعت محلی اتفاق می‌افتند. بنابراین، تاریخ و ساعت (محلی) درخواستی شما به UTC تبدیل شده، رویدادهای محلی‌شده مناسب انتخاب می‌شوند و تاریخ و ساعت شروع و پایان آن‌ها پس از تبدیل شدن به تاریخ و ساعت محلی شما نمایش داده می‌شوند. برای رویدادهای شناور نیازی به هیچ تبدیل نیست.

برنامه Khal (به طور دقیق‌تر icalendar https://github.com/collective/icalendar) می‌تواند تمام شناسه‌های منطقه زمانی استفاده‌شده در پایگاه داده Olson https://en.wikipedia.org/wiki/Tz_database و تعاریف سفارشی منطقه زمانی را درک کند، به شرطی که آن مؤلفه‌های VTIMEZONE پیش از VEVENTهایی قرار گیرند که از آن‌ها استفاده می‌کنند (همان‌طور که به نظر می‌رسد اکثر برنامه‌های تقویم این کار را انجام می‌دهند). در صورتی که یک منطقه زمانی ناشناخته (یا پشتیبانی‌نشده) پیدا شود، khal فرض می‌کند که می‌خواهید آن رویداد در منطقه زمانی پیش‌فرض قرار گیرد (که در فایل پیکربندی نیز قابل تنظیم است).

برنامه khal انتظار دارد شما همواره بخواهید تمام تاریخ و ساعت‌های شروع و پایان در زمان محلی نمایش داده شوند (که در فایل پیکربندی نیز قابل تنظیم است، در غیر این صورت از منطقه زمانی رایانه شما استفاده می‌شود).

پرسش‌های پرتکرار:

•
نصب با خطا متوقف می‌شود: source/str_util.c:25:20: fatal error: Python.h: No such file or directory
هدرهای توسعه پایتون روی سیستم شما نصب نیست. در توزیع‌های مبتنی بر دبیان می‌توانید آن‌ها را از طریق aptitude install python-dev نصب کنید.
•
کلید ناشناخته "default_command"
این کلید در کامیت f8d9135 منسوخ شد. برای آگاهی از دلیل حذف آن، https://github.com/pimutils/khal/issues/648 را ببینید.

برنامه 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.

Christan Geier و دیگران.

Copyright (c) 2013-2022 khal contributors

August 21, 2026 0.14.1