diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0d672eb --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ +# CLAUDE.md + +## Style + +- Use simple English: short sentences, common words. +- Avoid em dashes (—). Do not just swap them for "-" either. Rewrite the sentence instead, for + example with a comma, a colon, brackets or two sentences. diff --git a/Makefile b/Makefile index 6d1d542..408a4db 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -# cachy-auto-update - build and install +# cachy-auto-update: build and install # # Everything here is plain shell; "building" only means compiling the gettext # catalogs and rendering the man page. Both are optional in the sense that the @@ -43,14 +43,14 @@ po/%.mo: po/%.po ifdef MSGFMT $(MSGFMT) --check --output-file=$@ $< else - @echo "msgfmt not found - skipping $@" + @echo "msgfmt not found, skipping $@" endif $(MANPAGE): doc/cachy-auto-update.1.scd ifdef SCDOC $(SCDOC) < $< > $@ else - @echo "scdoc not found - skipping $@" + @echo "scdoc not found, skipping $@" endif # Syntax-check every shell file, and run shellcheck when it is available. @@ -62,14 +62,14 @@ check: shellcheck -x -e SC1090,SC1091 src/cachy-auto-update src/cachy-auto-update-run $(LIBS); \ echo "ok shellcheck"; \ else \ - echo "shellcheck not found - skipped"; \ + echo "shellcheck not found, skipped"; \ fi @if command -v python3 >/dev/null 2>&1; then \ python3 -m py_compile src/cachy-auto-update-progress \ && echo "ok src/cachy-auto-update-progress"; \ rm -rf src/__pycache__; \ else \ - echo "python3 not found - skipped"; \ + echo "python3 not found, skipped"; \ fi @if command -v visudo >/dev/null 2>&1; then \ visudo -cf res/sudoers/cachy-auto-update >/dev/null && echo "ok sudoers"; \ diff --git a/doc/cachy-auto-update.1.scd b/doc/cachy-auto-update.1.scd index 19d26c6..ad2171b 100644 --- a/doc/cachy-auto-update.1.scd +++ b/doc/cachy-auto-update.1.scd @@ -15,7 +15,7 @@ think about it: repository packages, AUR packages, Flatpaks and AppImages are updated in the background, with no password prompt and no terminal. Run without a command it opens a small interactive menu with the two switches -that matter - automatic updates on/off and notifications on/off - plus the +that matter (automatic updates on/off and notifications on/off), plus the current status, and a settings screen covering every remaining option so the configuration file never has to be edited by hand. In the settings screen the arrow keys select, Space or Right changes a value, and _q_ goes back; every @@ -23,8 +23,8 @@ change is written out immediately. The actual work is done by a systemd system service. The timer ticks hourly; whether a tick does anything is decided by _UpdateInterval_ (daily by default). -A run that is postponed - low battery, a game running, somebody else using -pacman - is simply retried at the next tick. +A run that is postponed (low battery, a game running, somebody else using +pacman) is simply retried at the next tick. # COMMANDS @@ -64,7 +64,7 @@ Before anything is installed, a run is postponed when: - the battery is below _MinBatteryPercent_ (ignored on mains power, and on machines without a battery); - _RequireAC_ is set and the machine is not plugged in; -- a game is running - detected via GameMode, a list of known game processes, or +- a game is running, detected via GameMode, a list of known game processes, or an application holding a blocking idle inhibitor; - pacman's database is locked, or pacman, yay, paru, pamac or a similar tool is running. @@ -84,13 +84,13 @@ A package that has to replace another one is handled silently. If pacman would stop to ask whether a conflicting package may be removed, the transaction is retried once with that question answered affirmatively, unless _AutoResolveConflicts_ is turned off. Files on disk that collide with a package -are *not* forced - that stays a human decision. A signature failure triggers one +are *not* forced. That stays a human decision. A signature failure triggers one keyring refresh and one retry. AUR packages are built and installed as the locked *cachy-auto-update* system account, because *makepkg*(8) refuses to run as root. That account has no -password and no shell, and is allowed - through _/etc/sudoers.d/cachy-auto-update_ -- to invoke *pacman* without one. No user password is ever stored anywhere. +password and no shell. Through _/etc/sudoers.d/cachy-auto-update_ it is allowed +to invoke *pacman* without one. No user password is ever stored anywhere. A failed AUR build is not reported the first time it happens; only a failure that repeats is worth waking somebody up for. @@ -113,7 +113,7 @@ For as long as a run is working, the notification area carries a live progress entry: the step being performed, how many items it has got through, an overall percentage, and the package currently being unpacked under "Details". This is a job in the sense of *org.kde.JobViewServer*, the same mechanism a file manager -uses while copying, rather than a notification - which is what makes it a bar +uses while copying, rather than a notification. That is what makes it a bar instead of a line of text. The desktop withdraws a job as soon as the D-Bus connection that requested it @@ -134,8 +134,8 @@ for minutes at a time looking stuck. Expanding "Details" shows the last five lines of the run log as they are written, alongside the package currently being worked on. The percentage says the update is alive; these lines say what it is alive doing, which matters most -during the stretches that have nothing countable to report - an AUR package -being compiled, above all. The job interface carries exactly two description +during the stretches that have nothing countable to report, above all an AUR +package being compiled. The job interface carries exactly two description fields, so those are the two things shown. A step that turns out to have no work is dropped from the bar instead of being @@ -147,17 +147,17 @@ with nothing pending, or a machine with no Flatpaks installed. Neither counted phase gets a counter from pacman on an unattended run, so both are counted here, a line at a time: "foo-1.2-1-x86_64 downloading..." for the first, "upgrading foo..." for the second. pacman's output is line-buffered -through *stdbuf*(1) so those lines arrive as they happen - writing to a log +through *stdbuf*(1) so those lines arrive as they happen. Writing to a log rather than a terminal, libc would otherwise release them in 4KB blocks, around -a hundred and sixty packages at a time. pacman's other (n/m) sequences - -checking keys, package integrity, loading package files - each count up to the +a hundred and sixty packages at a time. pacman's other (n/m) sequences +(checking keys, package integrity, loading package files) each count up to the same total and are deliberately ignored. # HOW LONG NOTIFICATIONS STAY -A message that reports the machine still needing a person - an update that -failed, a package database left locked, packages that had to be held back - -stays on screen until it is dismissed. A message like that is only worth +A message that reports the machine still needing a person stays on screen +until it is dismissed. For example: an update that failed, a package database +left locked, or packages that had to be held back. A message like that is only worth sending if it is still there when somebody comes back to the machine. Everything else times out by itself, an update that simply worked included. @@ -188,10 +188,10 @@ _org.freedesktop.login1.power-off-ignore-inhibit_, which is _auth_admin_keep_, so the desktop presents an administrator password prompt reading "Power off the system while an application is inhibiting this". That string is shipped untranslated by systemd and does not mention updates, and no KDE dialog -explains the situation either - only *systemctl*(1) names the inhibitor and its +explains the situation either. Only *systemctl*(1) names the inhibitor and its reason. Hence the notification. -A hard power-off - holding the power button, or losing mains power - is not +A hard power-off (holding the power button, or losing mains power) is not preventable. On the next run a leftover _/var/lib/pacman/db.lck_ is removed if it is older than the current boot, since no process able to hold it can still exist; the upgrade is then repeated and pacman reinstalls whatever was caught diff --git a/po/cachy-auto-update.pot b/po/cachy-auto-update.pot index 9049941..8376add 100644 --- a/po/cachy-auto-update.pot +++ b/po/cachy-auto-update.pot @@ -5,7 +5,8 @@ msgid "" msgstr "" "Project-Id-Version: cachy-auto-update 1.0.0\n" -"Report-Msgid-Bugs-To: https://github.com/LoonixTools/cachy-auto-update/issues\n" +"Report-Msgid-Bugs-To: https://github.com/LoonixTools/cachy-auto-update/" +"issues\n" "POT-Creation-Date: 2026-08-08 00:00+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" @@ -65,7 +66,7 @@ msgstr "" msgid "%d days ago" msgstr "" -msgid "The last run reported a problem - see 'cachy-auto-update log'." +msgid "The last run reported a problem. See 'cachy-auto-update log'." msgstr "" msgid "A restart is recommended to finish a kernel update." @@ -162,19 +163,23 @@ msgstr "" msgid "/etc/sudoers.d/cachy-auto-update is invalid; refusing to enable." msgstr "" -msgid "No AUR helper found - install paru or yay for AUR updates." +msgid "No AUR helper found. Install paru or yay for AUR updates." msgstr "" -msgid "base-devel is missing - AUR packages cannot be built without it." +msgid "base-devel is missing, so AUR packages cannot be built." msgstr "" -msgid "cachy-update also notifies about available updates. Turn its notifications off? [Y/n]" +msgid "" +"cachy-update also notifies about available updates. Turn its notifications " +"off? [Y/n]" msgstr "" msgid "cachy-update's update check has been disabled." msgstr "" -msgid "CachyOS shows a \"Reboot recommended\" notification while an update is still running. Turn it off? [Y/n]" +msgid "" +"CachyOS shows a \"Reboot recommended\" notification while an update is still " +"running. Turn it off? [Y/n]" msgstr "" #, c-format @@ -278,13 +283,16 @@ msgstr "" msgid "Update failed" msgstr "" -msgid "Something went wrong while updating. Run 'cachy-auto-update log' for details." +msgid "" +"Something went wrong while updating. Run 'cachy-auto-update log' for details." msgstr "" msgid "Package database locked" msgstr "" -msgid "pacman's lock file looks left over from an interrupted update. Updates are paused until it is cleared." +msgid "" +"pacman's lock file looks left over from an interrupted update. Updates are " +"paused until it is cleared." msgstr "" msgid "Some packages were held back" @@ -304,13 +312,17 @@ msgstr "" msgid "Finishing an interrupted update" msgstr "" -msgid "The last update was cut short, most likely because the machine was switched off. It is being finished now." +msgid "" +"The last update was cut short, most likely because the machine was switched " +"off. It is being finished now." msgstr "" msgid "Installing updates" msgstr "" -msgid "%d packages are being updated. Please leave the computer switched on until this is done." +msgid "" +"%d packages are being updated. Please leave the computer switched on until " +"this is done." msgstr "" msgid "Settings" @@ -319,7 +331,7 @@ msgstr "" msgid "(none)" msgstr "" -msgid "Up/Down select - Space or Right changes - q goes back" +msgid "Up/Down: select, Space or Right: change, q: back" msgstr "" msgid "Package names separated by spaces, empty to clear:" diff --git a/po/de.po b/po/de.po index ceae492..46d7b35 100644 --- a/po/de.po +++ b/po/de.po @@ -5,7 +5,8 @@ msgid "" msgstr "" "Project-Id-Version: cachy-auto-update 1.0.0\n" -"Report-Msgid-Bugs-To: https://github.com/LoonixTools/cachy-auto-update/issues\n" +"Report-Msgid-Bugs-To: https://github.com/LoonixTools/cachy-auto-update/" +"issues\n" "POT-Creation-Date: 2026-08-08 00:00+0200\n" "PO-Revision-Date: 2026-08-08 00:00+0200\n" "Last-Translator: Felitendo\n" @@ -66,8 +67,8 @@ msgstr "vor %d Stunden" msgid "%d days ago" msgstr "vor %d Tagen" -msgid "The last run reported a problem - see 'cachy-auto-update log'." -msgstr "Beim letzten Lauf gab es ein Problem – siehe „cachy-auto-update log“." +msgid "The last run reported a problem. See 'cachy-auto-update log'." +msgstr "Beim letzten Lauf gab es ein Problem. Siehe „cachy-auto-update log“." msgid "A restart is recommended to finish a kernel update." msgstr "Ein Neustart wird empfohlen, um ein Kernel-Update abzuschließen." @@ -161,26 +162,37 @@ msgid "Could not enable the systemd timer." msgstr "Der systemd-Timer konnte nicht aktiviert werden." msgid "/etc/sudoers.d/cachy-auto-update is invalid; refusing to enable." -msgstr "/etc/sudoers.d/cachy-auto-update ist fehlerhaft – wird nicht aktiviert." +msgstr "" +"/etc/sudoers.d/cachy-auto-update ist fehlerhaft und wird nicht aktiviert." -msgid "No AUR helper found - install paru or yay for AUR updates." -msgstr "Kein AUR-Helper gefunden – für AUR-Updates paru oder yay installieren." +msgid "No AUR helper found. Install paru or yay for AUR updates." +msgstr "Kein AUR-Helper gefunden. Für AUR-Updates paru oder yay installieren." -msgid "base-devel is missing - AUR packages cannot be built without it." -msgstr "base-devel fehlt – ohne das lassen sich AUR-Pakete nicht bauen." +msgid "base-devel is missing, so AUR packages cannot be built." +msgstr "base-devel fehlt, daher lassen sich keine AUR-Pakete bauen." -msgid "cachy-update also notifies about available updates. Turn its notifications off? [Y/n]" -msgstr "cachy-update benachrichtigt ebenfalls über verfügbare Updates. Dessen Benachrichtigungen abschalten? [J/n]" +msgid "" +"cachy-update also notifies about available updates. Turn its notifications " +"off? [Y/n]" +msgstr "" +"cachy-update benachrichtigt ebenfalls über verfügbare Updates. Dessen " +"Benachrichtigungen abschalten? [J/n]" msgid "cachy-update's update check has been disabled." msgstr "Die Update-Prüfung von cachy-update wurde abgeschaltet." -msgid "CachyOS shows a \"Reboot recommended\" notification while an update is still running. Turn it off? [Y/n]" -msgstr "CachyOS zeigt eine Benachrichtigung \"Neustart empfohlen\", während ein Update noch läuft. Abschalten? [J/n]" +msgid "" +"CachyOS shows a \"Reboot recommended\" notification while an update is still " +"running. Turn it off? [Y/n]" +msgstr "" +"CachyOS zeigt eine Benachrichtigung \"Neustart empfohlen\", während ein " +"Update noch läuft. Abschalten? [J/n]" #, c-format msgid "The reboot notification has been turned off. Undo it by deleting %s." -msgstr "Die Neustart-Benachrichtigung wurde abgeschaltet. Rückgängig durch Löschen von %s." +msgstr "" +"Die Neustart-Benachrichtigung wurde abgeschaltet. Rückgängig durch Löschen " +"von %s." #, c-format msgid "Could not write %s." @@ -279,21 +291,29 @@ msgstr "%d Updates wurden installiert." msgid "Update failed" msgstr "Update fehlgeschlagen" -msgid "Something went wrong while updating. Run 'cachy-auto-update log' for details." -msgstr "Beim Update ist etwas schiefgelaufen. Details mit „cachy-auto-update log“." +msgid "" +"Something went wrong while updating. Run 'cachy-auto-update log' for details." +msgstr "" +"Beim Update ist etwas schiefgelaufen. Details mit „cachy-auto-update log“." msgid "Package database locked" msgstr "Paketdatenbank gesperrt" -msgid "pacman's lock file looks left over from an interrupted update. Updates are paused until it is cleared." -msgstr "Die Sperrdatei von pacman scheint von einem abgebrochenen Update übrig zu sein. Bis sie entfernt ist, pausieren die Updates." +msgid "" +"pacman's lock file looks left over from an interrupted update. Updates are " +"paused until it is cleared." +msgstr "" +"Die Sperrdatei von pacman scheint von einem abgebrochenen Update übrig zu " +"sein. Bis sie entfernt ist, pausieren die Updates." msgid "Some packages were held back" msgstr "Einige Pakete wurden zurückgehalten" #, c-format msgid "%s could not be updated and was skipped. Everything else is up to date." -msgstr "%s konnte nicht aktualisiert werden und wurde übersprungen. Alles andere ist aktuell." +msgstr "" +"%s konnte nicht aktualisiert werden und wurde übersprungen. Alles andere ist " +"aktuell." #, c-format msgid "Held back: %s" @@ -305,15 +325,23 @@ msgstr "Der letzte Lauf wurde abgebrochen, bevor er fertig war." msgid "Finishing an interrupted update" msgstr "Abgebrochenes Update wird beendet" -msgid "The last update was cut short, most likely because the machine was switched off. It is being finished now." -msgstr "Das letzte Update wurde unterbrochen, vermutlich weil der Rechner ausgeschaltet wurde. Es wird jetzt zu Ende geführt." +msgid "" +"The last update was cut short, most likely because the machine was switched " +"off. It is being finished now." +msgstr "" +"Das letzte Update wurde unterbrochen, vermutlich weil der Rechner " +"ausgeschaltet wurde. Es wird jetzt zu Ende geführt." msgid "Installing updates" msgstr "Updates werden installiert" #, c-format -msgid "%d packages are being updated. Please leave the computer switched on until this is done." -msgstr "%d Pakete werden gerade aktualisiert. Bitte den Rechner so lange eingeschaltet lassen." +msgid "" +"%d packages are being updated. Please leave the computer switched on until " +"this is done." +msgstr "" +"%d Pakete werden gerade aktualisiert. Bitte den Rechner so lange " +"eingeschaltet lassen." msgid "Settings" msgstr "Einstellungen" @@ -321,8 +349,8 @@ msgstr "Einstellungen" msgid "(none)" msgstr "(keine)" -msgid "Up/Down select - Space or Right changes - q goes back" -msgstr "Hoch/Runter wählen – Leertaste oder Rechts ändert – q zurück" +msgid "Up/Down: select, Space or Right: change, q: back" +msgstr "Hoch/Runter: wählen, Leertaste oder Rechts: ändern, q: zurück" msgid "Package names separated by spaces, empty to clear:" msgstr "Paketnamen mit Leerzeichen getrennt, leer zum Löschen:" diff --git a/res/applications/cachy-auto-update.desktop b/res/applications/cachy-auto-update.desktop index 39b798c..48786b5 100644 --- a/res/applications/cachy-auto-update.desktop +++ b/res/applications/cachy-auto-update.desktop @@ -1,5 +1,5 @@ [Desktop Entry] -# Not here to put an entry in the application menu - hence NoDisplay. This is +# Not here to put an entry in the application menu, hence NoDisplay. This is # how the desktop learns what to call the update while it runs: the progress # bar in the notification area is labelled from the desktop entry named in the # job request, and without one the job is filed under whatever the helper diff --git a/res/config/cachy-auto-update.conf b/res/config/cachy-auto-update.conf index bd1977e..1e0b2ab 100644 --- a/res/config/cachy-auto-update.conf +++ b/res/config/cachy-auto-update.conf @@ -7,7 +7,7 @@ # Documentation: man cachy-auto-update # --------------------------------------------------------------------------- -# Main switches - normally set through `cachy-auto-update enable/disable` +# Main switches, normally set through `cachy-auto-update enable/disable` # --------------------------------------------------------------------------- # Apply updates automatically in the background. @@ -73,7 +73,7 @@ IgnorePkg= # installed packages, and every cached version of packages that are no longer # installed. Nothing that is currently installed is ever touched, so this only # costs the ability to downgrade further back than KeepOldPackages. -# Without it /var/cache/pacman/pkg grows forever - tens of gigabytes on a +# Without it /var/cache/pacman/pkg grows forever: tens of gigabytes on a # machine with a few large packages. CleanCache=yes @@ -97,8 +97,8 @@ RemoveOrphans=no # # How long a message stays on screen is not configurable, because it follows # from what the message is for: anything reporting that the machine still needs -# a person - a failed update, a paused package queue, a package that had to be -# skipped - waits until it is dismissed, since a message like that is only ever +# a person (a failed update, a paused package queue, a package that had to be +# skipped) waits until it is dismissed, since a message like that is only ever # useful if it is still there when somebody comes back. Everything else, an # update that simply worked included, times out on its own. diff --git a/res/systemd/cachy-auto-update.service b/res/systemd/cachy-auto-update.service index 432440a..32bc8bc 100644 --- a/res/systemd/cachy-auto-update.service +++ b/res/systemd/cachy-auto-update.service @@ -28,8 +28,8 @@ TimeoutStartSec=4h # Deliberately *not* sandboxed the way paccache.service is: this unit installs # packages across the whole filesystem and downloads them over the network, so # ProtectSystem=, PrivateNetwork= and friends would break it. NoNewPrivileges -# in particular has to stay off - the AUR step relies on the build account -# calling sudo. +# in particular has to stay off, because the AUR step relies on the build +# account calling sudo. NoNewPrivileges=no ProtectHostname=yes diff --git a/res/systemd/cachy-auto-update.timer b/res/systemd/cachy-auto-update.timer index 0702f62..937e46a 100644 --- a/res/systemd/cachy-auto-update.timer +++ b/res/systemd/cachy-auto-update.timer @@ -5,7 +5,7 @@ Documentation=man:cachy-auto-update(1) [Timer] # The tick is hourly, but an actual update only happens once per # UpdateInterval (default: daily). That combination is what makes a postponed -# run - low battery, a game running, somebody else using pacman - retry by +# run (low battery, a game running, somebody else using pacman) retry by # itself an hour later without any backoff bookkeeping. OnBootSec=15min OnCalendar=hourly diff --git a/src/cachy-auto-update b/src/cachy-auto-update index 030c1b4..a96e90b 100644 --- a/src/cachy-auto-update +++ b/src/cachy-auto-update @@ -1,6 +1,6 @@ #!/usr/bin/env bash # -# cachy-auto-update - unattended updates for CachyOS +# cachy-auto-update: unattended updates for CachyOS # # The command line front end. Everything it does is either flipping a switch in # /etc/cachy-auto-update/cachy-auto-update.conf, driving the systemd timer, or @@ -77,10 +77,10 @@ cau_do_enable() { cau_config_load if [[ $CFG_AUR == yes ]] && ! cau_aur_detect_quiet; then - cau_note "$(cau_msg "No AUR helper found - install paru or yay for AUR updates.")" + cau_note "$(cau_msg "No AUR helper found. Install paru or yay for AUR updates.")" fi if [[ $CFG_AUR == yes ]] && ! cau_have makepkg; then - cau_note "$(cau_msg "base-devel is missing - AUR packages cannot be built without it.")" + cau_note "$(cau_msg "base-devel is missing, so AUR packages cannot be built.")" fi cau_offer_disable_cachy_update @@ -89,7 +89,7 @@ cau_do_enable() { # CachyOS ships a pacman hook that pops up "Reboot recommended!" the moment a # kernel, driver or systemd package is unpacked. During a manual upgrade that -# is fine - the transaction is the last thing happening. During an unattended +# is fine, because the transaction is the last thing happening. During an unattended # one it lands in the middle: the run still has AUR packages to build and # Flatpaks to pull, and a notification asking for a restart right then is an # invitation to cut the update in half. @@ -141,7 +141,7 @@ cau_aur_detect_quiet() { # cachy-update ships an enabled user timer that only ever says "N updates # available". Once updates apply themselves that notification is pure noise, -# so offer to silence it - but only ask, never decide. +# so offer to silence it. But only ask, never decide. cau_offer_disable_cachy_update() { local user uid answer found=0 @@ -163,7 +163,7 @@ cau_offer_disable_cachy_update() { read -r answer || return 0 # Defaults to yes: once updates install themselves, cachy-update's "N - # updates available" is purely noise. "j" is accepted too - the prompt is + # updates available" is purely noise. "j" is accepted too: the prompt is # translated, so a German user types the German letter and used to have # that silently read as "no". case "${answer,,}" in diff --git a/src/cachy-auto-update-progress b/src/cachy-auto-update-progress index ead8cb9..df6e3b4 100644 --- a/src/cachy-auto-update-progress +++ b/src/cachy-auto-update-progress @@ -1,6 +1,6 @@ #!/usr/bin/env python3 # -# cachy-auto-update-progress - the update's progress bar on the desktop +# cachy-auto-update-progress: the update's progress bar on the desktop # # Started by the update runner, once per logged-in user, inside that user's # session. Reads one instruction per line on stdin and turns it into the same @@ -16,7 +16,7 @@ # # Why a separate process at all: the desktop ties the progress entry to the # D-Bus connection that asked for it and withdraws the entry the moment that -# connection goes away. One-shot callers - gdbus, busctl, dbus-send - therefore +# connection goes away. One-shot callers (gdbus, busctl, dbus-send) therefore # cannot drive one, because each invocation is its own connection that closes # again immediately. So something has to sit there and hold the connection open # for as long as the update takes, and read its orders from somewhere else. @@ -54,7 +54,7 @@ class Job: reply = self.bus.call_sync( JOB_SERVICE, JOB_PATH, "org.kde.JobViewServerV2", "requestView", # capabilities 0: no cancel and no pause button. Neither can be - # honoured - pacman's commit phase is not interruptible - and a + # honoured, because pacman's commit phase is not interruptible. A # button that does nothing is worse than no button. GLib.Variant("(sia{sv})", (DESKTOP_ENTRY, 0, {})), GLib.VariantType("(o)"), Gio.DBusCallFlags.NONE, -1, None) @@ -68,8 +68,8 @@ class Job: JOB_SERVICE, self.path, "org.kde.JobViewV2", method, variant, None, Gio.DBusCallFlags.NONE, -1, None) except GLib.Error: - # The desktop went away mid-update - a logout, or a plasmashell - # restart. The update carries on without a bar. + # The desktop went away mid-update (a logout, or a plasmashell + # restart). The update carries on without a bar. self.path = None def close(self, message=""): @@ -96,7 +96,7 @@ def main(): try: job.open() except GLib.Error: - # No job server on this desktop - anything that is not Plasma. Same + # No job server on this desktop (anything that is not Plasma). Same # deal as a missing binding: drain stdin, stay out of the way. for _ in sys.stdin: pass diff --git a/src/cachy-auto-update-run b/src/cachy-auto-update-run index 439f9d4..eb53249 100644 --- a/src/cachy-auto-update-run +++ b/src/cachy-auto-update-run @@ -1,6 +1,6 @@ #!/usr/bin/env bash # -# cachy-auto-update-run - one unattended update pass +# cachy-auto-update-run: one unattended update pass # # Started by cachy-auto-update.service as root. The timer fires hourly and this # decides whether anything should happen; that is what makes deferrals free. @@ -43,7 +43,7 @@ fi # Force a neutral locale here rather than relying on the unit's Environment=, # so a run started by hand behaves exactly like one started by the timer. # pacman failures are classified by matching its output, and on a German system -# that output is German. Text aimed at a person does not come through here - a +# that output is German. Text aimed at a person does not come through here: a # notification is rendered in the recipient's own locale by cau_msg_in. export LC_ALL=C LANGUAGE= @@ -65,7 +65,7 @@ cau_log_open # Record an interruption rather than leaving the previous run's verdict behind. # Without this, killing an interactive run leaves last_result at whatever it was -# before - so the menu can keep reporting a problem from hours ago while the +# before. Then the menu can keep reporting a problem from hours ago while the # machine is in fact fully up to date, which is worse than saying nothing. # pacman makes the commit phase itself uninterruptible, so the packages either # all landed or none did; only our own bookkeeping is at risk here. @@ -193,8 +193,8 @@ progress_steps+=(cleanup) cau_progress_begin "${progress_steps[@]}" # And carry the run log's last lines along with it, so "Details" shows what the -# update is doing during the stretches that have nothing to count - an AUR -# package building for a quarter of an hour, most of all. +# update is doing during the stretches that have nothing to count. Most of all +# an AUR package building for a quarter of an hour. cau_progress_tail_start "$CAU_RUNLOG" if ! cau_pacman_update; then @@ -273,7 +273,7 @@ fi # Recorded, deliberately not announced. The running kernel loses its module # tree the moment pacman unpacks the new one, so this turns true partway -# through a run that still has AUR builds and Flatpaks ahead of it - and a +# through a run that still has AUR builds and Flatpaks ahead of it. A # "restart recommended" bubble arriving then reads as an invitation to restart # while the update is still going. `cachy-auto-update status` and the menu say # so instead, where nobody is being interrupted mid-transaction. diff --git a/src/lib/common.sh b/src/lib/common.sh index 59244ba..20e685a 100644 --- a/src/lib/common.sh +++ b/src/lib/common.sh @@ -49,8 +49,8 @@ export TEXTDOMAINDIR="${CAU_LOCALEDIR}" # # Standard POSIX precedence, deliberately: LC_ALL wins outright, and LC_ALL=C # really does mean English. The service sets LC_ALL=C so that pacman and upower -# stay parseable, which makes the log English - correct, since the log is a -# technical artefact. Anything aimed at a person (a desktop notification) does +# stay parseable, which makes the log English. That is correct, since the log +# is a technical artefact. Anything aimed at a person (a desktop notification) does # not go through here at all; it names the recipient's own locale explicitly # via cau_msg_in and cau_user_locale. cau_ui_locale() { @@ -117,8 +117,8 @@ cau_msg_in() { fi # With no arguments the message is plain text, not a format string. Feeding - # it to printf anyway turns any literal percent sign in it - "Battery (%)", - # "100 % done" - into an invalid conversion, and that is a trap every + # it to printf anyway turns any literal percent sign in it (like + # "Battery (%)" or "100 % done") into an invalid conversion, and that is a trap every # translator would eventually walk into. if (( $# == 0 )); then printf '%s' "$translated" @@ -184,7 +184,7 @@ cau_log_open() { # Runs a command, capturing its combined output in the run log. Returns the # command's exit status. # -# When a person is watching - `cachy-auto-update run` from a terminal - the +# When a person is watching (`cachy-auto-update run` from a terminal), the # output is shown as well. Building an AUR package or pulling a few hundred # megabytes of Flatpak can take minutes, and silence for that long is # indistinguishable from a hang. @@ -207,8 +207,8 @@ cau_run_logged() { # Set by cau_bad and cau_note. The menu redraws immediately after an action, # which would wipe the screen; this marks that something was printed that the # user still has to read, so only those cases wait for a keypress. A plain -# success needs no acknowledgement - the status block at the top of the menu -# already shows the new state. +# success needs no acknowledgement, because the status block at the top of the +# menu already shows the new state. CAU_UI_NEEDS_ACK='' cau_say() { printf '%s\n' "$*"; } diff --git a/src/lib/conditions.sh b/src/lib/conditions.sh index 6580625..125898c 100644 --- a/src/lib/conditions.sh +++ b/src/lib/conditions.sh @@ -16,7 +16,7 @@ CAU_SKIP_REASON='' # cau_on_ac # True when running on mains power. systemd-ac-power also returns success when # the machine has neither a battery nor an adapter, which is exactly right for -# desktops - hand-rolled sysfs globbing gets that case wrong. +# desktops. Hand-rolled sysfs globbing gets that case wrong. cau_on_ac() { if cau_have systemd-ac-power; then systemd-ac-power > /dev/null 2>&1 @@ -41,8 +41,8 @@ cau_on_ac() { # cau_battery_percent # Average charge across the system batteries, or failure when the machine has # none. Peripheral batteries (mice, headsets) advertise type=Battery too and -# are filtered out via the scope attribute; when scope is missing entirely - -# as on many laptops - the device counts as a system battery. +# are filtered out via the scope attribute. When scope is missing entirely (as +# on many laptops), the device counts as a system battery. cau_battery_percent() { local ps sum=0 count=0 cap @@ -139,7 +139,7 @@ cau_gamemode_active() { while read -r user uid; do [[ -n $user ]] || continue # timeout runs inside the runuser call because it has to be a real - # binary there - it cannot wrap a shell function from out here. + # binary there. It cannot wrap a shell function from out here. out="$(cau_as_user "$user" "$uid" timeout 5 busctl --user --json=short \ get-property com.feralinteractive.GameMode \ /com/feralinteractive/GameMode \ diff --git a/src/lib/locks.sh b/src/lib/locks.sh index 4203a8f..ef36d86 100644 --- a/src/lib/locks.sh +++ b/src/lib/locks.sh @@ -4,8 +4,8 @@ # # The contract this file implements: the machine's owner may run any package # manager at any time and must never see a lock error caused by us. We can only -# guarantee that in one direction - by never *starting* while somebody else is -# mid-transaction - so the checks here run before anything is touched, and a +# guarantee that in one direction: by never *starting* while somebody else is +# mid-transaction. So the checks here run before anything is touched, and a # refusal simply defers the run to the next hourly tick. # Package managers that take /var/lib/pacman/db.lck. checkupdates is absent on @@ -65,7 +65,7 @@ cau_package_manager_busy() { # # The rigorous test is the boot time: no process that existed before the # current boot can still be running, so a db.lck older than boot is abandoned -# by definition - which is exactly what a power cut during an update leaves +# by definition. That is exactly what a power cut during an update leaves # behind. A lock that is merely unheld *within* this boot is not provable in # the same way, so it is only reported (see cau_track_stale_lock) and never # removed; guessing wrong there would corrupt a live transaction. @@ -90,12 +90,12 @@ cau_pacman_lock_is_stale() { # cau_recover_stale_lock # Clears a provably abandoned lock so an interrupted update can be finished on # the next run. Without this, one power cut during an update stops every future -# update permanently and silently - the worst possible outcome for a machine -# nobody is watching. +# update permanently and silently. That is the worst possible outcome for a +# machine nobody is watching. cau_recover_stale_lock() { cau_pacman_lock_is_stale || return 1 - cau_warn "Found a pacman lock older than this boot - an update was cut short" + cau_warn "Found a pacman lock older than this boot. An update was cut short" rm -f "$CAU_PACMAN_LOCK" 2>/dev/null || { cau_error "Could not remove the stale pacman lock" return 1 diff --git a/src/lib/menu.sh b/src/lib/menu.sh index 7c12bef..8c68739 100644 --- a/src/lib/menu.sh +++ b/src/lib/menu.sh @@ -32,7 +32,7 @@ cau_ui_term_restore() { } # Runs an action with the terminal handed back to normal line mode, so anything -# it prints - or prompts for - behaves the way a program expects. +# it prints or prompts for behaves the way a program expects. cau_ui_cooked() { cau_ui_term_restore "$@" @@ -213,8 +213,8 @@ _cau_setting_cycle() { # A cursor list rather than a numbered menu: there are eighteen settings, and # numbering them would run out of digits and force paging. # -# The frame is assembled in memory and written once. Everything constant - the -# specs, the translated labels, the clear sequence - is resolved before the +# The frame is assembled in memory and written once. Everything constant (the +# specs, the translated labels, the clear sequence) is resolved before the # loop, and the values are re-read only after something actually changes. # Drawing the naive way cost a command substitution per label per frame, which # measured 435 ms per keypress: arrow keys felt like the console was reloading, @@ -239,7 +239,7 @@ cau_ui_settings() { local title hint cau_msg_into "$locale" "Settings"; title="$CAU_MSG_RESULT" - cau_msg_into "$locale" "Up/Down select - Space or Right changes - q goes back" + cau_msg_into "$locale" "Up/Down: select, Space or Right: change, q: back" hint="$CAU_MSG_RESULT" # the terminfo clear string, fetched once instead of forking per frame @@ -320,8 +320,8 @@ cau_ui_edit_text() { # _cau_row