.Dd 2025-12-25
.Dt DARKMAN 1
.Os
.Sh "نام (NAME)"
.Nm darkman
.Nd کنترل جابه‌جایی میان حالت تاریک و حالت روشن
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Ar options
.Ar command
.Sh "توضیحات (DESCRIPTION)"
.Nm
در پس‌زمینه اجرا می‌شود و با غروب آفتاب حالت تاریک را فعال کرده و با طلوع دوبارهٔ آفتاب آن را خاموش می‌کند.
.Nm
برای استفاده به‌صورت تعاملی طراحی نشده است: این برنامه طوری طراحی شده که یک‌بار پیکربندی شود و در پس‌زمینه اجرا گردد.
.Pp
همچنین امکان اعمال دستی تغییر حالت‌ها و یا غیرفعال‌سازی کامل تغییرات خودکار وجود دارد.
.Sh "دستورها (COMMANDS)"
.Bl -tag -width Ds
.It Cm run Op Fl -ready-fd Ar fd
سرویس
.Nm
را اجرا می‌کند.
این دستور برای اجرا توسط یک مدیر سرویس (service manager)، اسکریپت init یا موارد مشابه در نظر گرفته شده است.
.Pp
آرگومان اختیاری
.Ar fd
یک توصیف‌کنندهٔ فایل (file descriptor) است که
.Nm
هنگام آماده شدن برای دریافت اتصال‌ها از سوی کلاینت‌ها، از طریق آن اطلاع‌رسانی می‌کند.
پروتکل استفاده‌شده با اعلان‌های آمادگی در s6، dinit و systemd سازگار است.
.It Cm set Aq Cm light | dark
حالت فعلی را تنظیم می‌کند.
.It Cm get
حالت فعلی را چاپ می‌کند.
.It Cm toggle
حالت فعلی را تغییر وضعیت (toggle) می‌دهد.
.El
.Sh "گزینه‌ها (OPTIONS)"
.Bl -tag -width Ds
.It Fl -verbose
گزارش‌های با جزئیات دقیق را چاپ می‌کند.
پیش‌فرض برای دستور
.Cm run
برابر با
.Cm true
و برای تمام دستورهای دیگر برابر با
.Cm false
است.
.El
.Sh "پیکربندی (CONFIGURATION)"
برای ساختار فایل پیکربندی به
.Xr darkman.conf 5
و برای مکان‌های فایل پیکربندی به بخش
.Sx FILES
مراجعه کنید.
.Sh "یکپارچه‌سازی‌ها (INTEGRATIONS)"
زیست‌بوم میزکارهای متن‌باز بسیار ناهمگن است و تغییر حالت برنامه‌های مختلف بین تاریک و روشن به سازوکارهای متفاوتی نیاز دارد.
.Pp
.Nm
تلاش می‌کند استانداردهایی را که به‌طور گسترده‌تری پذیرفته شده‌اند پیاده‌سازی کند، در حالی که این امکان را نیز به کاربران می‌دهد تا برای برنامه‌های دیگر اسکریپت‌های سفارشی خود را متصل کنند.
.Ss "فایل‌های اجرایی سفارشی (Custom executables)"
.Nm
می‌تواند فایل‌های اجرایی سفارشی (که می‌توانند اسکریپت‌های شل ساده باشند) را اجرا کند.
.Pp
اسکریپت‌ها در پوشه‌ای با نام
.Pa darkman
درون مسیرهای تعریف‌شده در
.Ev XDG_DATA_DIRS
و همچنین
.Ev XDG_DATA_HOME
جستجو می‌شوند.
هر اسکریپت حالت فعلی را
.Pq Dq dark No یا Dq light
به‌عنوان اولین آرگومان خود ($1) دریافت می‌کند.
این قابلیت به یک اسکریپت واحد اجازه می‌دهد هر دو حالت را مدیریت کند:
.Bd -literal -offset indent
#!/bin/sh
case "$1" in
dark) THEME=dark-theme ;;
light) THEME=light-theme ;;
esac
gsettings set org.example.app theme "$THEME"
.Ed
.Pp
به‌منظور سازگاری با نسخه‌های قبلی،
.Nm
همچنین دایرکتوری‌های
.Pa dark-mode.d
و
.Pa light-mode.d
(قالب قدیمی) را جستجو می‌کند.
اسکریپت‌های موجود در این دایرکتوری‌ها بدون آرگومان اجرا می‌شوند.
اسکریپت‌های موجود در دایرکتوری
.Pa darkman
با نام مشابه، بر اسکریپت‌های قدیمی اولویت داشته و جایگزین آن‌ها خواهند شد.
.Pp
هر دوی این متغیرها و مقادیر جایگزین (fallback) آن‌ها در مشخصات دایرکتوری پایهٔ XDG تعریف شده‌اند:
.Lk https://specifications.freedesktop.org/basedir-spec/latest
.Pp
این اسکریپت‌ها یا فایل‌های اجرایی می‌توانند هر اقدام لازم را انجام دهند؛ از جمله بازنویسی فایل‌های پیکربندی یک خوانندهٔ PDF، کنترل یک دیمن اعلان‌ها برای جابه‌جایی به پوسته‌ای دیگر، یا تغییر وضعیتی خاص در محیط میزکار (DE).
.Pp
فایل‌ها باید دارای بیت اجرایی (executable bit) باشند تا به‌عنوان یک فایل اجرایی در نظر گرفته شوند.
اسکریپت‌ها باید shebang مناسب داشته باشند تا سیستم‌عامل بتواند آن‌ها را به‌درستی اجرا کند.
.Pp
معمولاً متغیرهای
.Ev XDG_DATA_*
که در بالا ذکر شدند به مجموعه دایرکتوری‌های زیر منتهی می‌شوند:
.Bl -bullet -compact
.It
.Pa ~/.local/share/
.It
.Pa /usr/local/share/
.It
.Pa /usr/share/
.El
.Pp
اسکریپت‌های نمونه (و گفتگو دربارهٔ نحوهٔ یکپارچه‌سازی برنامه‌های مختلف) در مخزن پروژه در دسترس هستند:
.Lk https://gitlab.com/WhyNotHugo/darkman
.Pp
بسته‌ها نیز می‌توانند اسکریپت‌های خود را در هر یک از این مسیرها قرار دهند، اگرچه توسعه‌دهندگان برنامه‌ها تشویق می‌شوند تا برای تشخیص حالت فعلی و شنود تغییرات، از رابط سوکت (socket API) استفاده کنند (برای جزئیات به بخش‌های بعدی مراجعه کنید)..Ss درگاه تنظیمات XDG (XDG Settings portal)
.Nm
رابط حالت تاریک درگاه میزکار XDG را پیاده‌سازی می‌کند.
برنامه‌هایی که از این API استفاده می‌کنند باید بر اساس اولویت فعلی
.Nm
به حالت تاریک/روشن تغییر وضعیت دهند.
این رابط در ابتدا توسط تیم‌های GNOME و Elementary ارائه شد و در حال حاضر توسط KDE، Firefox و بسیاری از پروژه‌های دیگر پشتیبانی می‌شود.
انتظار می‌رود برنامه‌های این محیط‌ها، علاوه بر نرم‌افزارهای دیگر، از آن پشتیبانی کنند.
.Pp
برای جزئیات بیشتر دربارهٔ این پروتکل، ببینید:
.Lk https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Settings.html
.Pp
از نسخهٔ ۱.۱۷.۰ برنامهٔ
.Xr xdg-desktop-portal 1
به بعد، درگاه‌ها حتماً باید با پیکربندی مختص هر کاربر در
.Xr portals.conf 5
پیکربندی شوند.
برای اجبار به استفاده از
.Nm
جهت تنظیم حالت تاریک/روشن، از تنظیمی شبیه به مورد زیر استفاده کنید:
.Bd -literal -offset indent
[preferred]
org.freedesktop.impl.portal.Settings=darkman
.Ed
.Pp
هنگام استفاده از پیکربندی مختص یک میزکار (مانند:
.Pa swaywm-portals.conf )
، لطفاً به یاد داشته باشید که متغیر محیطی
.Ev XDG_CURRENT_DESKTOP
باید برای
.Xr xdg-desktop-portal 1
تنظیم شده باشد.
.Pp
سرویس
.Xr xdg-desktop-portal 1
باید پس از اجرا و آماده‌به‌کار شدن
.Nm
شروع به کار کند.
از
.Fl -ready-fd
برای اعلان آمادگی استفاده کنید.
این موضوع احتمالاً در سیستم‌های مبتنی بر systemd، جایی که مدیر سرویس در تصاحب گذرگاه نام‌گذاری‌شده واسطه می‌شود، صدق نمی‌کند.
.Pp
برای توضیحات دقیق‌تر، این مقاله را ببینید:
.Lk https://whynothugo.nl/journal/2024/04/09/darkman-portal-configuration
.Ss رابط سوکت (Socket API)
.Nm
برای دریافت دستورات پرس‌وجو و کنترل، به یک سوکت یونیکس گوش می‌دهد.
این سوکت یک API سادهٔ متنی ارائه می‌دهد که در آن پس از دستورات یک نویسهٔ خط جدید قرار می‌گیرد و
.Nm
پاسخی را برمی‌گرداند که آن هم با یک خط جدید همراه است.
.Pp
دستورهای
.Cm get , set
و
.Cm toggle
از این API استفاده می‌کنند.
این شیوه همچنین روش توصیه‌شده هنگام نوشتن ابزارهای سفارشی است
(مانند: تغییر حالت فعلی بر اساس ورودی یک حسگر نور).
.Pp
دستورهای زیر در دسترس هستند:
.Bl -tag -width Ds
.It Cm get
چاپ حالت فعلی.
.It Cm set Ar mode
تنظیم حالت فعلی.
.Ar mode
باید یکی از مقادیر
.Cm light
یا
.Cm dark
باشد.
.It Cm toggle
تغییر وضعیت به حالت مخالف.
حالت جدید به عنوان پاسخ چاپ می‌شود.
.It Cm watch
چاپ تغییرات حالت به محض وقوع.
حالت فعلی بلافاصله چاپ می‌شود و به دنبال آن هر تغییر بعدی گزارش خواهد شد.
.El
.Pp
برای برقراری ارتباط دستی با سوکت:
.Bd -literal -offset indent
socat UNIX-CONNECT:${XDG_RUNTIME_DIR}/darkman/control.sock STDIO
.Ed
.Pp
یک بستهٔ Go به نام
.Nm libdarkman
برای پرس‌وجو از این رابط توسط سایر برنامه‌های کارخواه در دسترس است.
برای جزئیات بیشتر به مستندات آن مراجعه کنید:
.Lk https://godocs.io/gitlab.com/WhyNotHugo/darkman/libdarkman.Ss "یکپارچه‌سازی‌های شخص ثالث (Third party integrations)"
برای کاربران Emacs، یک بسته شخص ثالث جهت یکپارچه‌سازی
.Nm
با Emacs وجود دارد:
.Lk https://github.com/grtcdr/darkman.el
.Pp
همچنین یک پلاگین برای کاربران neovim در دسترس است:
.Lk https://github.com/4e554c4c/darkman.nvim
.Sh "موقعیت مکانی (LOCATION)"
موقعیت مکانی فعلی می‌تواند در فایل پیکربندی مشخص شود.
از موقعیت مکانی برای محاسبه زمان غروب و طلوع خورشید استفاده می‌شود.
.Pp
همچنین این امکان برای
.Nm
وجود دارد که موقعیت مکانی سیستم را با استفاده از
.Xr geoclue 1
به طور خودکار تعیین کند.
میزان قابلیت اطمینان Geoclue بسته به توزیع و محیط میزکار متفاوت است،
زیرا اغلب برای کارکرد صحیح نیاز به پیکربندی یک عامل (agent) دارد.
.Pp
اگر هیچ موقعیت مکانی مشخص نباشد، جابه‌جایی‌های خودکار غیرفعال می‌شوند.
.Sh "محیط (ENVIRONMENT)"
متغیرهای محیطی زیر نیز خوانده می‌شوند و بر مقادیر فایل
پیکربندی اولویت خواهند داشت:
.Bl -tag -width Ds
.It Ev DARKMAN_LAT
عرض جغرافیایی (latitude) را برای موقعیت مکانی فعلی بازنویسی می‌کند.
.It Ev DARKMAN_LNG
طول جغرافیایی (longitude) را برای موقعیت مکانی فعلی بازنویسی می‌کند.
.It Ev XDG_CURRENT_DESKTOP
.Nm
از این متغیر استفاده نمی‌کند؛ این متغیر در عوض باید برای
.Xr xdg-desktop-portal 1
تعریف شود.
.El
.Sh "فایل‌ها (FILES)"
.Nm
برای یافتن فایل پیکربندی در مکان‌های زیر جستجو می‌کند و از اولین
مورد یافت‌شده استفاده خواهد کرد:
.Bl -enum -compact
.It
.Pa $XDG_CONFIG_HOME/darkman/config.yaml
.It
هر دایرکتوری در
.Ev XDG_CONFIG_DIRS
که
.Pa darkman/config.yaml
به انتهای آن افزوده شده باشد.
.El
.Pp
اگر
.Ev XDG_CONFIG_HOME
تنظیم نشده باشد، مقدار پیش‌فرض آن
.Pa ~/.config
خواهد بود.
اگر
.Ev XDG_CONFIG_DIRS
تنظیم نشده باشد، مقدار پیش‌فرض آن
.Pa /etc/xdg
خواهد بود.
.Pp
برای آگاهی از قالب فایل پیکربندی به
.Xr darkman.conf 5
مراجعه کنید.
.Sh "حریم خصوصی (PRIVACY)"
.Nm
در زمان غروب خورشید در موقعیت مکانی فعلی، انتقال به حالت تاریک/روشن را فعال می‌کند.
هر برنامه‌ای که به صورت محلی در حال اجرا است می‌تواند زمان این تغییر حالت‌ها را ضبط
یا مخابره کند و تلاش نماید اطلاعات مربوط به موقعیت مکانی فعلی را استنتاج کند.
.Pp
هنگامی که یک مرورگر وب به طور هم‌زمان این تغییر حالت را اعمال می‌کند، وب‌سایت‌های
باز نیز می‌توانند این اطلاعات را ثبت کنند.
.Pp
یک تعقیب‌کننده یا ردیاب بالقوه می‌تواند از اطلاعات فوق برای استنتاج این نکته استفاده
کند که شما احتمالاً در منطقه‌ای از جهان هستید که غروب خورشید در زمان مشخصی رخ داده است.
این منطقه معمولاً محدوده وسیعی به وسعت ده‌ها هزار کیلومتر را در بر می‌گیرد، اما می‌تواند
برای برخی موقعیت‌های جغرافیایی خاص کوچک‌تر باشد.
.Pp
نویسنده این ابزار برای دستیابی به تعادلی منطقی بین حریم خصوصی و راحتی،
از یک موقعیت مکانی با تنظیم دستی و مقادیر عدد صحیح برای عرض و طول جغرافیایی استفاده می‌کند..Sh "توسعه (DEVELOPMENT)"
برای گزارش مشکلات و پرسش‌های عمومی پیرامون توسعه، صفحه اصلی پروژه را که در حال حاضر در GitLab میزبانی می‌شود ببینید:
.Lk https://gitlab.com/WhyNotHugo/darkman
.Sh "اشکال‌زدایی (DEBUGGING)"
برای بررسی و تأیید اینکه چه مقداری از طریق
.Xr xdg-desktop-portal 1
منتقل می‌شود، از این دستور استفاده کنید:
.Bd -literal -offset indent
gdbus call --session \e
    --dest org.freedesktop.portal.Desktop \e
    --object-path /org/freedesktop/portal/desktop \e
    --method org.freedesktop.portal.Settings.ReadOne \e
    org.freedesktop.appearance color-scheme
.Ed
.Sh "همچنین ببینید (SEE ALSO)"
.Xr portals.conf 5 ,
.Xr gammastep 1 ,
.Xr sd-ready-fd 1
.Sh "نویسندگان (AUTHORS)"
توسعه‌یافته توسط
.An Hugo O. Barrera Aq Mt hugo@whynothugo.nl ,
همراه با مشارکت‌های ارزشمند جامعه کاربری.
.Pp
.Nm
یک پروژه متن‌باز تحت مجوز ISC است و برای استفاده آزادانه همگان توسعه یافته است.
اگر مایل به حمایت مالی از این پروژه هستید، این پیوند را ببینید:
.Lk https://whynothugo.nl/sponsor