251 lines
13 KiB
Bash
Executable File
251 lines
13 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
|
|
# The manual.
|
|
#
|
|
# docs/ in this repository is engineering artifacts: design specs, plans, an
|
|
# upstream ledger. None of it is written for the person using the desktop, and
|
|
# that person is the one with questions. The manual is the answer, and it is
|
|
# rendered inside Settings so a chapter can point at a settings page and have
|
|
# that mean something.
|
|
#
|
|
# What must hold:
|
|
#
|
|
# 1. Every chapter the page lists exists, and every chapter file is listed.
|
|
# A renamed file shows an error card in place of a chapter, which looks
|
|
# like the manual is broken rather than like somebody moved a file.
|
|
# 2. Chapters render one at a time. Text has an implicit texture size limit,
|
|
# and a document long enough to hit it goes blank rather than complaining.
|
|
# 3. Links leave the desktop rather than doing nothing.
|
|
# 4. The page is registered everywhere a settings page has to be, or it
|
|
# silently redirects to Home.
|
|
|
|
set -uo pipefail
|
|
|
|
repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
|
|
manual_dir="$repo_dir/config/dot/quickshell/manual"
|
|
page="$repo_dir/config/dot/quickshell/modules/settings/ManualPage.qml"
|
|
# The chapter list and the titles live in one place that both the reader and
|
|
# About's Manual card instantiate, so neither can drift from the other.
|
|
contents="$repo_dir/config/dot/quickshell/modules/settings/ManualChapters.qml"
|
|
routes="$repo_dir/config/dot/quickshell/services/SettingsRoutes.qml"
|
|
shell_ui="$repo_dir/config/dot/quickshell/modules/settings/SettingsShell.qml"
|
|
qmldir="$repo_dir/config/dot/quickshell/modules/settings/qmldir"
|
|
state="$repo_dir/config/dot/quickshell/services/ShellState.qml"
|
|
search="$repo_dir/config/dot/quickshell/services/SettingsSearch.qml"
|
|
|
|
findings=()
|
|
note() { findings+=("$1"); }
|
|
|
|
[[ -d "$manual_dir" ]] || { printf 'manual contract: %s is missing\n' "$manual_dir" >&2; exit 1; }
|
|
|
|
# ── 1. The chapters on disk and the chapters listed are the same set ─────────
|
|
|
|
mapfile -t on_disk < <(find "$manual_dir" -maxdepth 1 -name '*.md' -printf '%f\n' | sort)
|
|
(( ${#on_disk[@]} > 0 )) || note 'the manual has no chapters'
|
|
|
|
[[ -r "$contents" ]] \
|
|
|| note 'ManualChapters.qml is missing, so neither the reader nor About knows what the chapters are'
|
|
mapfile -t listed < <(grep -oE 'file: "[^"]+\.md"' "$contents" | sed 's/file: "//; s/"//' | sort)
|
|
(( ${#listed[@]} > 0 )) || note 'the chapter list names no chapters'
|
|
|
|
for file in "${on_disk[@]}"; do
|
|
printf '%s\n' "${listed[@]}" | grep -qx "$file" \
|
|
|| note "$file exists but the chapter list never names it"
|
|
done
|
|
for file in "${listed[@]}"; do
|
|
[[ -r "$manual_dir/$file" ]] \
|
|
|| note "the chapter list names $file, which does not exist, so that chapter renders an error"
|
|
done
|
|
|
|
# A chapter that is only a heading is a chapter somebody forgot to write.
|
|
for file in "${on_disk[@]}"; do
|
|
lines="$(grep -c . "$manual_dir/$file" || true)"
|
|
(( lines > 10 )) || note "$file has $lines lines; it reads as unfinished"
|
|
head -1 "$manual_dir/$file" | grep -q '^# ' \
|
|
|| note "$file does not begin with a heading, so it has no title of its own"
|
|
done
|
|
|
|
# ── 1b. The tab titles come from the files ───────────────────────────────────
|
|
#
|
|
# The page carried a comment saying the title shown is the first heading of
|
|
# each chapter, "so a chapter cannot be renamed in one place and not the
|
|
# other". It was not true: the titles were a second copy, written beside the
|
|
# filenames, and the two agreed only because nobody had renamed anything yet.
|
|
# A comment that describes a property the code does not have is worse than no
|
|
# comment, because it is the reason the next person does not check.
|
|
#
|
|
# So: no authored label beside a chapter file, and something that actually
|
|
# reads a leading heading out of one.
|
|
python3 - "$contents" <<'PY' || note 'the chapter list still carries hand-written titles beside the filenames, so a renamed heading and a tab label can disagree'
|
|
import re
|
|
import sys
|
|
|
|
text = open(sys.argv[1], encoding="utf-8").read()
|
|
block = re.search(r'chapters:\s*\[(.*?)\n \]', text, re.S)
|
|
if not block:
|
|
raise SystemExit(1)
|
|
raise SystemExit(1 if re.search(r'label:\s*"', block.group(1)) else 0)
|
|
PY
|
|
grep -qE '\^#' "$contents" \
|
|
|| note 'nothing reads a leading heading, so the chapter titles cannot be coming from the files'
|
|
grep -q 'Quickshell.shellDir + "/manual/"' "$contents" \
|
|
|| note 'the chapter titles are not read through the shell directory, so they would break on a clone elsewhere'
|
|
grep -q 'ManualChapters {' "$page" \
|
|
|| note 'the manual reader keeps its own idea of what the chapters are'
|
|
|
|
# And the titles the files offer have to be usable as tab labels: a first line
|
|
# that is a paragraph would render a tab strip nobody can read.
|
|
for file in "${on_disk[@]}"; do
|
|
heading="$(head -1 "$manual_dir/$file" | sed 's/^#\+[[:space:]]*//')"
|
|
[[ -n "$heading" ]] || note "$file has an empty first heading, so its tab would have no name"
|
|
(( ${#heading} <= 40 )) \
|
|
|| note "$file's first heading is ${#heading} characters; it is the tab label, so it has to be a title"
|
|
done
|
|
|
|
# ── 2 & 3. How it renders ────────────────────────────────────────────────────
|
|
|
|
grep -q 'textFormat: Text.MarkdownText' "$page" \
|
|
|| note 'chapters are not rendered as markdown, so the source appears verbatim'
|
|
grep -q 'root.chapters\[root.current\]' "$page" \
|
|
|| note 'the page does not render one chapter at a time; a single long Text goes blank rather than erroring'
|
|
grep -q 'onLinkActivated' "$page" \
|
|
|| note 'links in the manual do nothing when clicked'
|
|
|
|
# ── 3b. A link to a settings page opens the settings page ────────────────────
|
|
#
|
|
# The whole reason the manual is rendered inside Settings rather than in a
|
|
# browser is that a chapter can point at a page and have that mean something.
|
|
# Every link went to Qt.openUrlExternally, so "open Displays" handed a
|
|
# panama:// URL to xdg-open, which has no handler for it: the click did
|
|
# nothing, silently, which is the worst of the three possible outcomes.
|
|
grep -q 'panama://settings/' "$page" \
|
|
|| note 'the manual has no in-app link scheme, so a chapter cannot point at a settings page'
|
|
python3 - "$page" <<'PY' || note 'the manual link handler does not route in-app links through ShellState.openSettings while still sending everything else out of the desktop'
|
|
import re
|
|
import sys
|
|
|
|
text = open(sys.argv[1], encoding="utf-8").read()
|
|
|
|
|
|
def block_at(index: int) -> str:
|
|
"""The braced body starting at the first { on or after index."""
|
|
start = text.index("{", index)
|
|
depth = 0
|
|
for position in range(start, len(text)):
|
|
if text[position] == "{":
|
|
depth += 1
|
|
elif text[position] == "}":
|
|
depth -= 1
|
|
if depth == 0:
|
|
return text[start:position + 1]
|
|
raise SystemExit(1)
|
|
|
|
|
|
# Either shape is fine: the branch written inline, or delegated to a named
|
|
# function on the page. What matters is what is on the path, so the path is
|
|
# followed rather than one line being read and guessed at.
|
|
handler = re.search(r'onLinkActivated:\s*link\s*=>\s*(?P<tail>.)', text)
|
|
if not handler:
|
|
raise SystemExit(1)
|
|
if handler.group("tail") == "{":
|
|
body = block_at(handler.start("tail"))
|
|
else:
|
|
called = re.match(r'(?:root\.)?([A-Za-z][A-Za-z0-9]*)\(', text[handler.start("tail"):])
|
|
if not called:
|
|
raise SystemExit(1)
|
|
declaration = re.search(rf'function {called.group(1)}\s*\(', text)
|
|
if not declaration:
|
|
raise SystemExit(1)
|
|
body = block_at(declaration.end())
|
|
|
|
raise SystemExit(0 if "ShellState.openSettings" in body
|
|
and "Qt.openUrlExternally" in body
|
|
and ("panama://settings/" in body or "linkScheme" in body) else 1)
|
|
PY
|
|
|
|
# Every in-app link a chapter actually writes must name a page that exists.
|
|
# A typo here is invisible: the scheme matches, the handler fires, and
|
|
# openSettings resolves an unknown id to Home -- so the link works, just not
|
|
# the way the sentence around it promised.
|
|
leaves="$( {
|
|
grep -oE '\{ page: "[a-z-]+", label: "[^"]*", icon: "[^"]*", tabs: \[\] \}' "$routes"
|
|
grep -oE '\{ page: "[a-z-]+", label: "[^"]*" \}' "$routes"
|
|
sed -n '/property var hiddenLeaves:/,/\]/p' "$routes" | grep -oE 'page: "[a-z-]+"'
|
|
} | sed -E 's/.*page: "([a-z-]+)".*/\1/' | sort -u)"
|
|
[[ -n "$leaves" ]] || note 'no leaves could be read from SettingsRoutes, so in-app manual links prove nothing'
|
|
while read -r target; do
|
|
[[ -n "$target" ]] || continue
|
|
grep -qx "$target" <<<"$leaves" \
|
|
|| note "a chapter links to panama://settings/$target, which is not a page anyone can land on"
|
|
done < <(grep -rhoE 'panama://settings/[a-z-]+' "$manual_dir" \
|
|
| sed -E 's|panama://settings/||' | sort -u)
|
|
grep -q 'onLoadFailed' "$page" \
|
|
|| note 'a chapter that cannot be read fails silently instead of saying so'
|
|
|
|
# The chapters are reached through the shell directory, not by walking upward
|
|
# out of it: that path is only correct when the repository is where it usually
|
|
# is, and the shell directory is a symlink.
|
|
grep -q 'Quickshell.shellDir + "/manual/"' "$page" \
|
|
|| note 'the manual is not located through the shell directory, so it would break on a clone elsewhere'
|
|
grep -q '\.\./\.\./\.\.' "$page" \
|
|
&& note 'the manual path walks upward out of the shell directory, which is only correct by accident'
|
|
|
|
# ── 4. Registered everywhere a settings page has to be ───────────────────────
|
|
# The manual is a routable leaf with no tab of its own. It was a tab of System
|
|
# until the strip reached ten and had to come back down to eight, and it is the
|
|
# right one to lose: it is reference material rather than a control surface, so
|
|
# it is opened deliberately -- from About's Manual card, from a deep link, from
|
|
# a search result -- rather than found by scanning a row of tabs.
|
|
#
|
|
# That makes the taxonomy entry the only thing holding it up. A leaf missing
|
|
# from SettingsRoutes cannot be opened, searched, or linked to, and because it
|
|
# draws no tab anywhere, nothing on screen would show it had gone.
|
|
|
|
python3 - "$routes" <<'PY' || note 'the manual is not a hidden leaf in SettingsRoutes, so nothing can navigate to it'
|
|
import re
|
|
import sys
|
|
|
|
text = open(sys.argv[1], encoding="utf-8").read()
|
|
block = re.search(r'hiddenLeaves:\s*\[(.*?)\]', text, re.S)
|
|
raise SystemExit(0 if block and re.search(r'page: "manual"', block.group(1)) else 1)
|
|
PY
|
|
python3 - "$routes" <<'PY' || note 'the manual is a System tab again, taking back a slot the eight-tab strip does not have'
|
|
import re
|
|
import sys
|
|
|
|
text = open(sys.argv[1], encoding="utf-8").read()
|
|
block = re.search(r'\{ page: "system",.*?tabs: \[(.*?)\n \] \}', text, re.S)
|
|
raise SystemExit(1 if block and '{ page: "manual"' in block.group(1) else 0)
|
|
PY
|
|
grep -q 'case "manual": return manualPage;' "$shell_ui" || note 'SettingsShell does not route to the manual'
|
|
grep -q 'Component { id: manualPage; ManualPage {} }' "$shell_ui" || note 'SettingsShell never declares the manual component'
|
|
grep -q '^ManualPage 1.0 ManualPage.qml$' "$qmldir" || note 'ManualPage is not registered in the settings qmldir'
|
|
# ShellState keeps no page list of its own any more; it resolves whatever it is
|
|
# handed through SettingsRoutes. That is what makes the taxonomy check above
|
|
# sufficient, so it is worth pinning that it stays that way.
|
|
grep -q 'SettingsRoutes.resolve(' "$state" || note 'ShellState does not resolve pages through SettingsRoutes, so openSettings("manual") has no defined destination'
|
|
grep -q 'page: "manual"' "$search" || note 'the manual is not searchable from the settings search box'
|
|
|
|
# With no tab of its own, About's Manual card is the only place the manual is
|
|
# offered rather than looked up. If that card stops opening it, the page is
|
|
# still reachable in principle and undiscoverable in practice.
|
|
about="$repo_dir/config/dot/quickshell/modules/settings/AboutPage.qml"
|
|
if [[ -r "$about" ]]; then
|
|
grep -q 'openSettings("manual"' "$about" \
|
|
|| note 'About does not open the manual, which is now the only place it is offered rather than searched for'
|
|
grep -q 'ManualChapters {' "$about" \
|
|
|| note 'About keeps its own idea of what the chapters are, so its card and the reader can disagree'
|
|
grep -qE 'file: "[^"]+\.md"' "$about" \
|
|
&& note 'About names chapter files itself instead of reading the shared list'
|
|
else
|
|
note 'AboutPage.qml is missing, so the manual has nowhere to be opened from'
|
|
fi
|
|
|
|
if (( ${#findings[@]} > 0 )); then
|
|
printf 'manual contract: %d finding(s)\n' "${#findings[@]}" >&2
|
|
printf ' - %s\n' "${findings[@]}" >&2
|
|
exit 1
|
|
fi
|
|
|
|
printf 'manual contract: PASS (%d chapters)\n' "${#on_disk[@]}"
|