نام (NAME)

darkman — کنترل جابه‌جایی میان حالت تاریک و حالت روشن

خلاصه دستور (SYNOPSIS)

darkman [options] command

توضیحات (DESCRIPTION)

darkman در پس‌زمینه اجرا می‌شود و با غروب آفتاب حالت تاریک را فعال کرده و با طلوع دوبارهٔ آفتاب آن را خاموش می‌کند. darkman برای استفاده به‌صورت تعاملی طراحی نشده است: این برنامه طوری طراحی شده که یک‌بار پیکربندی شود و در پس‌زمینه اجرا گردد.

همچنین امکان اعمال دستی تغییر حالت‌ها و یا غیرفعال‌سازی کامل تغییرات خودکار وجود دارد.

دستورها (COMMANDS)

run [--ready-fd fd]: سرویس darkman را اجرا می‌کند. این دستور برای اجرا توسط یک مدیر سرویس (service manager)، اسکریپت init یا موارد مشابه در نظر گرفته شده است.
آرگومان اختیاری fd یک توصیف‌کنندهٔ فایل (file descriptor) است که darkman هنگام آماده شدن برای دریافت اتصال‌ها از سوی کلاینت‌ها، از طریق آن اطلاع‌رسانی می‌کند. پروتکل استفاده‌شده با اعلان‌های آمادگی در s6، dinit و systemd سازگار است.
set ⟨light | dark⟩: حالت فعلی را تنظیم می‌کند.
get: حالت فعلی را چاپ می‌کند.
toggle: حالت فعلی را تغییر وضعیت (toggle) می‌دهد.

گزینه‌ها (OPTIONS)

--verbose: گزارش‌های با جزئیات دقیق را چاپ می‌کند. پیش‌فرض برای دستور run برابر با true و برای تمام دستورهای دیگر برابر با false است.

پیکربندی (CONFIGURATION)

برای ساختار فایل پیکربندی به darkman.conf(5) و برای مکان‌های فایل پیکربندی به بخش FILES مراجعه کنید.

یکپارچه‌سازی‌ها (INTEGRATIONS)

زیست‌بوم میزکارهای متن‌باز بسیار ناهمگن است و تغییر حالت برنامه‌های مختلف بین تاریک و روشن به سازوکارهای متفاوتی نیاز دارد.

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

فایل‌های اجرایی سفارشی (Custom executables)

darkman می‌تواند فایل‌های اجرایی سفارشی (که می‌توانند اسکریپت‌های شل ساده باشند) را اجرا کند.

اسکریپت‌ها در پوشه‌ای با نام darkman درون مسیرهای تعریف‌شده در XDG_DATA_DIRS و همچنین XDG_DATA_HOME جستجو می‌شوند. هر اسکریپت حالت فعلی را (“dark یا “light””) به‌عنوان اولین آرگومان خود ($1) دریافت می‌کند. این قابلیت به یک اسکریپت واحد اجازه می‌دهد هر دو حالت را مدیریت کند:

#!/bin/sh
case "$1" in
dark) THEME=dark-theme ;;
light) THEME=light-theme ;;
esac
gsettings set org.example.app theme "$THEME"

به‌منظور سازگاری با نسخه‌های قبلی، darkman همچنین دایرکتوری‌های dark-mode.d و light-mode.d (قالب قدیمی) را جستجو می‌کند. اسکریپت‌های موجود در این دایرکتوری‌ها بدون آرگومان اجرا می‌شوند. اسکریپت‌های موجود در دایرکتوری darkman با نام مشابه، بر اسکریپت‌های قدیمی اولویت داشته و جایگزین آن‌ها خواهند شد.

هر دوی این متغیرها و مقادیر جایگزین (fallback) آن‌ها در مشخصات دایرکتوری پایهٔ XDG تعریف شده‌اند: https://specifications.freedesktop.org/basedir-spec/latest

این اسکریپت‌ها یا فایل‌های اجرایی می‌توانند هر اقدام لازم را انجام دهند؛ از جمله بازنویسی فایل‌های پیکربندی یک خوانندهٔ PDF، کنترل یک دیمن اعلان‌ها برای جابه‌جایی به پوسته‌ای دیگر، یا تغییر وضعیتی خاص در محیط میزکار (DE).

فایل‌ها باید دارای بیت اجرایی (executable bit) باشند تا به‌عنوان یک فایل اجرایی در نظر گرفته شوند. اسکریپت‌ها باید shebang مناسب داشته باشند تا سیستم‌عامل بتواند آن‌ها را به‌درستی اجرا کند.

معمولاً متغیرهای XDG_DATA_* که در بالا ذکر شدند به مجموعه دایرکتوری‌های زیر منتهی می‌شوند:

~/.local/share/
/usr/local/share/
/usr/share/

اسکریپت‌های نمونه (و گفتگو دربارهٔ نحوهٔ یکپارچه‌سازی برنامه‌های مختلف) در مخزن پروژه در دسترس هستند: https://gitlab.com/WhyNotHugo/darkman

بسته‌ها نیز می‌توانند اسکریپت‌های خود را در هر یک از این مسیرها قرار دهند، اگرچه توسعه‌دهندگان برنامه‌ها تشویق می‌شوند تا برای تشخیص حالت فعلی و شنود تغییرات، از رابط سوکت (socket API) استفاده کنند (برای جزئیات به بخش‌های بعدی مراجعه کنید)..Ss درگاه تنظیمات XDG (XDG Settings portal) darkman رابط حالت تاریک درگاه میزکار XDG را پیاده‌سازی می‌کند. برنامه‌هایی که از این API استفاده می‌کنند باید بر اساس اولویت فعلی darkman به حالت تاریک/روشن تغییر وضعیت دهند. این رابط در ابتدا توسط تیم‌های GNOME و Elementary ارائه شد و در حال حاضر توسط KDE، Firefox و بسیاری از پروژه‌های دیگر پشتیبانی می‌شود. انتظار می‌رود برنامه‌های این محیط‌ها، علاوه بر نرم‌افزارهای دیگر، از آن پشتیبانی کنند.

برای جزئیات بیشتر دربارهٔ این پروتکل، ببینید: https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Settings.html

از نسخهٔ ۱.۱۷.۰ برنامهٔ xdg-desktop-portal(1) به بعد، درگاه‌ها حتماً باید با پیکربندی مختص هر کاربر در portals.conf(5) پیکربندی شوند. برای اجبار به استفاده از darkman جهت تنظیم حالت تاریک/روشن، از تنظیمی شبیه به مورد زیر استفاده کنید:

[preferred]
org.freedesktop.impl.portal.Settings=darkman

هنگام استفاده از پیکربندی مختص یک میزکار (مانند: swaywm-portals.conf) ، لطفاً به یاد داشته باشید که متغیر محیطی XDG_CURRENT_DESKTOP باید برای xdg-desktop-portal(1) تنظیم شده باشد.

سرویس xdg-desktop-portal(1) باید پس از اجرا و آماده‌به‌کار شدن darkman شروع به کار کند. از --ready-fd برای اعلان آمادگی استفاده کنید. این موضوع احتمالاً در سیستم‌های مبتنی بر systemd، جایی که مدیر سرویس در تصاحب گذرگاه نام‌گذاری‌شده واسطه می‌شود، صدق نمی‌کند.

برای توضیحات دقیق‌تر، این مقاله را ببینید: https://whynothugo.nl/journal/2024/04/09/darkman-portal-configuration

رابط سوکت (Socket API)

darkman برای دریافت دستورات پرس‌وجو و کنترل، به یک سوکت یونیکس گوش می‌دهد. این سوکت یک API سادهٔ متنی ارائه می‌دهد که در آن پس از دستورات یک نویسهٔ خط جدید قرار می‌گیرد و darkman پاسخی را برمی‌گرداند که آن هم با یک خط جدید همراه است.

دستورهای get, set و toggle از این API استفاده می‌کنند. این شیوه همچنین روش توصیه‌شده هنگام نوشتن ابزارهای سفارشی است (مانند: تغییر حالت فعلی بر اساس ورودی یک حسگر نور).

دستورهای زیر در دسترس هستند:

get: چاپ حالت فعلی.
set mode: تنظیم حالت فعلی. mode باید یکی از مقادیر light یا dark باشد.
toggle: تغییر وضعیت به حالت مخالف. حالت جدید به عنوان پاسخ چاپ می‌شود.
watch: چاپ تغییرات حالت به محض وقوع. حالت فعلی بلافاصله چاپ می‌شود و به دنبال آن هر تغییر بعدی گزارش خواهد شد.

برای برقراری ارتباط دستی با سوکت:

socat UNIX-CONNECT:${XDG_RUNTIME_DIR}/darkman/control.sock STDIO

یک بستهٔ Go به نام libdarkman برای پرس‌وجو از این رابط توسط سایر برنامه‌های کارخواه در دسترس است. برای جزئیات بیشتر به مستندات آن مراجعه کنید: یکپارچه‌سازی‌های شخص ثالث (Third party integrations) برای کاربران Emacs، یک بسته شخص ثالث جهت یکپارچه‌سازی darkman با Emacs وجود دارد: https://github.com/grtcdr/darkman.el

همچنین یک پلاگین برای کاربران neovim در دسترس است: https://github.com/4e554c4c/darkman.nvim

موقعیت مکانی (LOCATION)

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

همچنین این امکان برای darkman وجود دارد که موقعیت مکانی سیستم را با استفاده از geoclue(1) به طور خودکار تعیین کند. میزان قابلیت اطمینان Geoclue بسته به توزیع و محیط میزکار متفاوت است، زیرا اغلب برای کارکرد صحیح نیاز به پیکربندی یک عامل (agent) دارد.

اگر هیچ موقعیت مکانی مشخص نباشد، جابه‌جایی‌های خودکار غیرفعال می‌شوند.

محیط (ENVIRONMENT)

متغیرهای محیطی زیر نیز خوانده می‌شوند و بر مقادیر فایل پیکربندی اولویت خواهند داشت:

DARKMAN_LAT: عرض جغرافیایی (latitude) را برای موقعیت مکانی فعلی بازنویسی می‌کند.
DARKMAN_LNG: طول جغرافیایی (longitude) را برای موقعیت مکانی فعلی بازنویسی می‌کند.
XDG_CURRENT_DESKTOP: darkman از این متغیر استفاده نمی‌کند؛ این متغیر در عوض باید برای xdg-desktop-portal(1) تعریف شود.

فایل‌ها (FILES)

darkman برای یافتن فایل پیکربندی در مکان‌های زیر جستجو می‌کند و از اولین مورد یافت‌شده استفاده خواهد کرد:

$XDG_CONFIG_HOME/darkman/config.yaml
هر دایرکتوری در XDG_CONFIG_DIRS که darkman/config.yaml به انتهای آن افزوده شده باشد.

اگر XDG_CONFIG_HOME تنظیم نشده باشد، مقدار پیش‌فرض آن ~/.config خواهد بود. اگر XDG_CONFIG_DIRS تنظیم نشده باشد، مقدار پیش‌فرض آن /etc/xdg خواهد بود.

برای آگاهی از قالب فایل پیکربندی به darkman.conf(5) مراجعه کنید.

حریم خصوصی (PRIVACY)

darkman در زمان غروب خورشید در موقعیت مکانی فعلی، انتقال به حالت تاریک/روشن را فعال می‌کند. هر برنامه‌ای که به صورت محلی در حال اجرا است می‌تواند زمان این تغییر حالت‌ها را ضبط یا مخابره کند و تلاش نماید اطلاعات مربوط به موقعیت مکانی فعلی را استنتاج کند.

هنگامی که یک مرورگر وب به طور هم‌زمان این تغییر حالت را اعمال می‌کند، وب‌سایت‌های باز نیز می‌توانند این اطلاعات را ثبت کنند.

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

نویسنده این ابزار برای دستیابی به تعادلی منطقی بین حریم خصوصی و راحتی، از یک موقعیت مکانی با تنظیم دستی و مقادیر عدد صحیح برای عرض و طول جغرافیایی استفاده می‌کند..Sh "توسعه (DEVELOPMENT)" برای گزارش مشکلات و پرسش‌های عمومی پیرامون توسعه، صفحه اصلی پروژه را که در حال حاضر در GitLab میزبانی می‌شود ببینید: https://gitlab.com/WhyNotHugo/darkman

اشکال‌زدایی (DEBUGGING)

برای بررسی و تأیید اینکه چه مقداری از طریق xdg-desktop-portal(1) منتقل می‌شود، از این دستور استفاده کنید:

gdbus call --session \
    --dest org.freedesktop.portal.Desktop \
    --object-path /org/freedesktop/portal/desktop \
    --method org.freedesktop.portal.Settings.ReadOne \
    org.freedesktop.appearance color-scheme

همچنین ببینید (SEE ALSO)

portals.conf(5), gammastep(1), sd-ready-fd(1)

نویسندگان (AUTHORS)

توسعه‌یافته توسط Hugo O. Barrera <hugo@whynothugo.nl>, همراه با مشارکت‌های ارزشمند جامعه کاربری.

darkman یک پروژه متن‌باز تحت مجوز ISC است و برای استفاده آزادانه همگان توسعه یافته است. اگر مایل به حمایت مالی از این پروژه هستید، این پیوند را ببینید: https://whynothugo.nl/sponsor