SchOS/docs/Website/docs.js
Nexoniarz 020aa6113c Users and permissions: accounts, login, enforced file permissions, setuid, su, passwd, doas
The kernel now checks owner/group/other on open, create, unlink, rename, exec
and path search; honours set-user-id and set-group-id; restricts kill, mount,
reboot and mknod; keeps supplementary groups; and implements chown. devtmpfs
nodes carry owners and modes that chmod/chown keep. Terminals run login, the
image has root and schos, X starts as the ordinary user.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EVRhxi9zpdW2uDUN4FVcao
2026-10-26 13:16:07 +01:00

518 lines
21 KiB
JavaScript

/* SPDX-License-Identifier: GPL-2.0-or-later
*
* The documentation reader.
*
* Renders the project's Markdown in the site's own theme, so the docs can be
* read without leaving the page and without a build step. No dependency: the
* parser below handles exactly what docs/ actually uses -- headings, fenced
* code, tables, lists, quotes, and inline marks. Pulling in a 40 KB Markdown
* library to render 30 files would outweigh every other asset here combined.
*
* Everything is escaped before any tag is emitted. The only HTML that reaches
* the page is HTML this file wrote.
*/
(function () {
"use strict";
/* ---- the index ---------------------------------------------------- */
var DOCS = [
{ group: "Start here", items: [
["README.md", "Overview"],
["plan/1.0.md", "The 1.0 definition"],
["licensing.md", "Licensing"]
]},
{ group: "Architecture", items: [
["architecture/README.md", "The system, layer by layer"],
["architecture/boot.md", "Boot"],
["architecture/kernel.md", "Kernel"],
["architecture/scheduler.md", "Scheduler"],
["architecture/syscalls.md", "Syscalls"],
["architecture/filesystem.md", "The VFS"],
["architecture/schfs.md", "SchFS"],
["architecture/scff.md", "SCFF"],
["architecture/fat.md", "FAT"],
["architecture/terminals.md", "Virtual terminals"],
["architecture/devices.md", "Device model"],
["architecture/usb.md", "USB"],
["architecture/udev.md", "udev"],
["architecture/users.md", "Users and permissions"],
["architecture/graphics.md", "Graphics"],
["architecture/audio.md", "Audio"],
["architecture/networking.md", "Networking"],
["architecture/init.md", "init"],
["architecture/packages.md", "Packages (apk)"],
["architecture/desktop.md", "The desktop (Xorg)"],
["architecture/ldls.md", "Linux drivers (LDLS)"],
["architecture/debugging.md", "Debugging"]
]},
{ group: "Guides", items: [
["guides/building.md", "Building"],
["guides/testing.md", "Testing"],
["guides/layout.md", "Tree layout"],
["guides/adding-a-driver.md", "Adding a driver"],
["guides/hardware-report.md", "Reporting hardware"]
]},
{ group: "Plan", items: [
["plan/README.md", "What plan/ is for"],
["plan/roadmap.md", "Roadmap"],
["plan/gpu.md", "The GPU"],
["plan/finch.md", "Finch"],
["plan/schapi.md", "SchAPI"]
]},
{ group: "History", items: [
["history/README.md", "Why history/ exists"],
["history/kernel.md", "Kernel"],
["history/schfs.md", "SchFS"],
["history/moving-to-linux.md", "Moving to Linux"]
]},
{ group: "Branding", items: [
["branding/README.md", "Shift, and the wallpapers"]
]}
];
/* ---- helpers ------------------------------------------------------- */
function esc(s) {
return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
}
/* Resolve a doc-relative link against the doc it appeared in, so
"../history/schfs.md" inside architecture/ lands on history/schfs.md. */
function resolve(from, href) {
var base = from.split("/").slice(0, -1);
var parts = href.split("/");
for (var i = 0; i < parts.length; i++) {
if (parts[i] === "." || parts[i] === "") continue;
if (parts[i] === "..") base.pop();
else base.push(parts[i]);
}
return base.join("/");
}
/* encodeURIComponent turns every "/" into %2F, which works but makes a
shared link unreadable. Slashes are legal in a query value, so keep them. */
function docHref(p) {
return "?doc=" + encodeURIComponent(p).replace(/%2F/g, "/");
}
function slug(s) {
return s.toLowerCase().replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "-");
}
/* ---- inline marks --------------------------------------------------- */
/* U+0001 as the placeholder sentinel: it cannot occur in a Markdown source
file, so a code span lifted out here can never be confused with document
text when it is put back. */
var SENTINEL = "\u0001";
function inline(s, from) {
/* Code spans come out first and go back last, so nothing inside a backtick
pair is mistaken for emphasis or for a link. */
var spans = [];
s = s.replace(/`([^`]+)`/g, function (_, code) {
spans.push("<code>" + esc(code) + "</code>");
return SENTINEL + (spans.length - 1) + SENTINEL;
});
s = esc(s);
s = s.replace(/!\[([^\]]*)\]\(([^)\s]+)[^)]*\)/g, function (_, alt, src) {
return '<img src="' + encodeURI(src) + '" alt="' + alt + '">';
});
s = s.replace(/\[([^\]]+)\]\(([^)\s]+)[^)]*\)/g, function (_, text, href) {
if (/^https?:/.test(href))
return '<a href="' + encodeURI(href) + '" target="_blank" rel="noopener">' + text + "</a>";
if (href.charAt(0) === "#")
return '<a href="' + encodeURI(href) + '">' + text + "</a>";
if (/\.md($|#)/.test(href)) {
var cut = href.indexOf("#");
var hash = cut >= 0 ? href.slice(cut) : "";
var path = cut >= 0 ? href.slice(0, cut) : href;
return '<a href="' + docHref(resolve(from, path)) + hash + '">' + text + "</a>";
}
/* Anything else is a file in the repo rather than a document. Link at it
relative to docs/, which is where this page's ../ points. */
return '<a href="../' + encodeURI(resolve(from, href)) + '">' + text + "</a>";
});
s = s.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
s = s.replace(/(^|[^*])\*([^*\n]+)\*/g, "$1<em>$2</em>");
var restore = new RegExp(SENTINEL + "(\\d+)" + SENTINEL, "g");
return s.replace(restore, function (_, n) { return spans[+n]; });
}
/* ---- blocks --------------------------------------------------------- */
function render(md, from, headings) {
md = md.replace(/\r\n?/g, "\n").replace(/<!--[\s\S]*?-->/g, "");
var L = md.split("\n"), out = [], i = 0, m;
function listBlock(ordered) {
var tag = ordered ? "ol" : "ul", items = [];
while (i < L.length) {
var li = L[i].match(ordered ? /^\s*\d+\.\s+(.*)$/ : /^\s*[-*+]\s+(.*)$/);
if (!li) {
/* an indented continuation line belongs to the item above it */
if (items.length && /^\s+\S/.test(L[i])) {
items[items.length - 1] += " " + L[i].trim();
i++;
continue;
}
break;
}
items.push(li[1]);
i++;
}
out.push("<" + tag + ">");
items.forEach(function (t) { out.push("<li>" + inline(t, from) + "</li>"); });
out.push("</" + tag + ">");
}
function cells(row) {
return row.replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|")
.map(function (c) { return c.trim(); });
}
while (i < L.length) {
var line = L[i];
if (!line.trim()) { i++; continue; }
/* fenced code */
if (/^\s*```/.test(line)) {
var lang = line.replace(/^\s*```/, "").trim(), buf = [];
i++;
while (i < L.length && !/^\s*```/.test(L[i])) buf.push(L[i++]);
i++;
/* A frame rather than a bare block: a title strip naming the language,
and a button that copies it, because the thing a reader most often
wants from a code block in these docs is to paste it somewhere. */
out.push('<figure class="codeframe">' +
'<figcaption class="codeframe__bar">' +
'<span class="codeframe__lang">' + esc(lang || "text") + "</span>" +
'<button class="nv-button nv-button--ghost nv-button--sm" type="button" data-copy>Copy</button>' +
"</figcaption>" +
'<pre class="nv-code doc__pre"' +
(lang ? ' data-lang="' + esc(lang) + '"' : "") +
"><code>" + esc(buf.join("\n")) + "</code></pre></figure>");
continue;
}
/* table: a pipe row followed by a separator row */
if (/^\s*\|/.test(line) && /^\s*\|?[\s:|-]+$/.test(L[i + 1] || "") && /-/.test(L[i + 1] || "")) {
var head = cells(line);
i += 2;
out.push('<div class="nv-table-frame"><table class="nv-table"><thead><tr>');
head.forEach(function (c) { out.push("<th>" + inline(c, from) + "</th>"); });
out.push("</tr></thead><tbody>");
while (i < L.length && /^\s*\|/.test(L[i])) {
out.push("<tr>");
cells(L[i++]).forEach(function (c) { out.push("<td>" + inline(c, from) + "</td>"); });
out.push("</tr>");
}
out.push("</tbody></table></div>");
continue;
}
/* heading */
if ((m = line.match(/^(#{1,6})\s+(.*?)\s*#*$/))) {
var lvl = m[1].length, text = m[2], id = slug(text);
if (lvl <= 3) headings.push({ level: lvl, text: text, id: id });
out.push("<h" + lvl + ' id="' + id + '">' + inline(text, from) + "</h" + lvl + ">");
i++;
continue;
}
/* rule */
if (/^\s*(-{3,}|\*{3,}|_{3,})\s*$/.test(line)) { out.push("<hr>"); i++; continue; }
/* blockquote */
if (/^\s*>/.test(line)) {
var q = [];
while (i < L.length && /^\s*>/.test(L[i])) q.push(L[i++].replace(/^\s*>\s?/, ""));
out.push("<blockquote>" + render(q.join("\n"), from, []) + "</blockquote>");
continue;
}
if (/^\s*[-*+]\s+/.test(line)) { listBlock(false); continue; }
if (/^\s*\d+\.\s+/.test(line)) { listBlock(true); continue; }
/* paragraph: runs to the next blank line or block opener */
var para = [];
while (i < L.length && L[i].trim() &&
!/^\s*(```|>|#{1,6}\s|[-*+]\s|\d+\.\s|\|)/.test(L[i]) &&
!/^\s*(-{3,}|\*{3,}|_{3,})\s*$/.test(L[i])) {
para.push(L[i++]);
}
if (para.length) out.push("<p>" + inline(para.join(" "), from) + "</p>");
else i++; /* a block opener we do not handle: never spin on it */
}
return out.join("\n");
}
/* ---- the page ------------------------------------------------------- */
var nav = document.getElementById("docnav");
var article = document.getElementById("doc");
var tocEl = document.getElementById("toc");
function buildNav() {
DOCS.forEach(function (g) {
var h = document.createElement("p");
h.className = "nv-nav__section";
h.textContent = g.group;
nav.appendChild(h);
var ul = document.createElement("ul");
ul.className = "nv-nav__list";
g.items.forEach(function (it) {
var li = document.createElement("li");
var a = document.createElement("a");
a.className = "nv-nav__item";
a.href = docHref(it[0]);
a.textContent = it[1];
a.dataset.path = it[0];
li.appendChild(a);
ul.appendChild(li);
});
nav.appendChild(ul);
});
}
function markCurrent(path) {
Array.prototype.forEach.call(nav.querySelectorAll("a"), function (a) {
if (a.dataset.path === path) a.setAttribute("aria-current", "page");
else a.removeAttribute("aria-current");
});
}
/* A heading's own Markdown, as text. The contents panel is a list of
destinations, not a place to render code and emphasis -- a heading written
`proc_reincarnate()` should read as proc_reincarnate() there rather than
carrying its backticks across. Marks are stripped, not escaped: the result
goes through textContent. */
function plain(s) {
return s.replace(/`([^`]+)`/g, "$1")
.replace(/\*\*([^*]+)\*\*/g, "$1")
.replace(/\*([^*]+)\*/g, "$1")
.replace(/\[([^\]]+)\]\([^)]*\)/g, "$1");
}
function buildToc(headings) {
tocEl.innerHTML = "";
var real = headings.filter(function (h) { return h.level >= 2; });
if (real.length < 2) { tocEl.hidden = true; return; }
tocEl.hidden = false;
var t = document.createElement("p");
t.className = "nv-nav__section";
t.textContent = "On this page";
tocEl.appendChild(t);
var ul = document.createElement("ul");
ul.className = "nv-nav__list";
real.forEach(function (h) {
var li = document.createElement("li");
li.className = "toc-lvl" + h.level;
var a = document.createElement("a");
a.className = "nv-nav__item";
a.href = "#" + h.id;
a.textContent = plain(h.text);
li.appendChild(a);
ul.appendChild(li);
});
tocEl.appendChild(ul);
}
/* Every document in index order, with the group it belongs to. */
var FLAT = [];
DOCS.forEach(function (g) {
g.items.forEach(function (it) { FLAT.push({ path: it[0], title: it[1], group: g.group }); });
});
function indexOf(path) {
for (var k = 0; k < FLAT.length; k++) if (FLAT[k].path === path) return k;
return -1;
}
/* Where the reader is, how long it will take, and where the file lives --
above the document, because a page arrived at from a search has no other
way to say which part of the docs it belongs to. */
function header(path, text) {
var at = FLAT[indexOf(path)] || { group: "Docs", title: path };
var words = text.split(/\s+/).length;
var mins = Math.max(1, Math.round(words / 230));
return '<header class="dochead">' +
'<ol class="nv-breadcrumbs">' +
'<li><a href="?doc=README.md">Docs</a></li>' +
"<li>" + esc(at.group) + "</li>" +
'<li aria-current="page">' + esc(at.title) + "</li>" +
"</ol>" +
'<span class="dochead__meta nv-caption nv-text-tertiary">' +
mins + " min read · " +
'<a href="../' + esc(path) + '">' + esc(path) + "</a>" +
"</span>" +
"</header>";
}
/* The next and previous document, as two keys at the foot of the page. A
reader who reaches the end of one has nearly always come to read the
section, not the file. */
function pager(path) {
var k = indexOf(path), html = '<nav class="docpager" aria-label="More documents">';
function key(d, dir) {
return '<a class="nv-card nv-card--interactive docpager__key docpager__key--' + dir +
'" href="' + docHref(d.path) + '">' +
'<span class="nv-overline nv-text-tertiary">' + (dir === "prev" ? "← Previous" : "Next →") + "</span>" +
'<span class="nv-title">' + esc(d.title) + "</span>" +
'<span class="nv-caption nv-text-tertiary">' + esc(d.group) + "</span></a>";
}
if (k > 0) html += key(FLAT[k - 1], "prev");
else html += "<span></span>";
if (k >= 0 && k < FLAT.length - 1) html += key(FLAT[k + 1], "next");
return html + "</nav>";
}
/* Light the contents entry for the section being read. */
var spy;
function watchHeadings() {
if (spy) spy.disconnect();
if (!("IntersectionObserver" in window)) return;
var links = {};
Array.prototype.forEach.call(tocEl.querySelectorAll("a"), function (a) {
links[a.getAttribute("href").slice(1)] = a;
});
spy = new IntersectionObserver(function (entries) {
entries.forEach(function (e) {
if (!e.isIntersecting || !links[e.target.id]) return;
Array.prototype.forEach.call(tocEl.querySelectorAll("a"), function (a) {
a.removeAttribute("aria-current");
});
links[e.target.id].setAttribute("aria-current", "location");
});
}, { rootMargin: "0px 0px -70% 0px" });
Array.prototype.forEach.call(article.querySelectorAll("h2[id], h3[id]"), function (h) {
spy.observe(h);
});
}
function fail(title, body) {
article.innerHTML = "<h1>" + title + "</h1>" + body;
tocEl.hidden = true;
}
function load(path) {
markCurrent(path);
document.title = "Docs — SchOS";
article.setAttribute("aria-busy", "true");
fetch("../" + path).then(function (r) {
if (!r.ok) throw new Error(r.status + " " + r.statusText);
return r.text();
}).then(function (text) {
var headings = [];
article.innerHTML = header(path, text) + render(text, path, headings) + pager(path);
buildToc(headings);
watchHeadings();
article.removeAttribute("aria-busy");
if (headings.length) document.title = headings[0].text + " — SchOS docs";
var hash = location.hash.slice(1);
var target = hash && document.getElementById(hash);
if (target) target.scrollIntoView();
else window.scrollTo(0, 0);
}).catch(function (e) {
article.removeAttribute("aria-busy");
/* The common case, and worth naming precisely: browsers refuse fetch()
on file:// for the same reason they refuse it cross-origin, so this
one page needs a server even though nothing here is dynamic. */
if (location.protocol === "file:") {
fail("This page needs a local server",
"<p>Browsers block <code>fetch()</code> on <code>file://</code> URLs, so the " +
"reader cannot load the Markdown. The rest of the site works from a file; " +
"this page does not. Serve the repository root:</p>" +
'<pre class="nv-code doc__pre"><code>cd path/to/SchOS\n' +
"python3 -m http.server 8000</code></pre>" +
"<p>Then open <code>http://localhost:8000/docs/Website/docs.html</code>.</p>" +
'<p>Or read this one directly: <a href="../' + esc(path) + '">' + esc(path) + "</a></p>");
} else {
fail("Could not load that document",
"<p><code>" + esc(path) + "</code> — " + esc(e.message) + "</p>" +
'<p><a href="?doc=README.md">Back to the overview</a></p>');
}
});
}
function pathFromUrl() {
var m = /[?&]doc=([^&#]+)/.exec(location.search);
var p = m ? decodeURIComponent(m[1]) : "README.md";
/* Only ever load something that is in the index above. */
var known = DOCS.some(function (g) {
return g.items.some(function (it) { return it[0] === p; });
});
return known ? p : "README.md";
}
buildNav();
load(pathFromUrl());
/* Fold the index on a narrow screen, and fold it again after picking a
document there -- the choice is made, and the document is what was asked
for. */
var fold = document.getElementById("docindex");
var narrow = window.matchMedia && window.matchMedia("(max-width: 64rem)");
if (fold && narrow && narrow.matches) fold.open = false;
nav.addEventListener("click", function () {
if (fold && narrow && narrow.matches) fold.open = false;
});
/* Filter the index as you type. Groups with nothing left in them go too,
so the heading of an empty section does not sit there implying a match. */
var filter = document.getElementById("docfilter");
if (filter) filter.addEventListener("input", function () {
var q = filter.value.trim().toLowerCase();
Array.prototype.forEach.call(nav.querySelectorAll(".nv-nav__list"), function (ul) {
var any = false;
Array.prototype.forEach.call(ul.querySelectorAll("li"), function (li) {
var hit = !q || li.textContent.toLowerCase().indexOf(q) >= 0;
li.hidden = !hit;
any = any || hit;
});
ul.hidden = !any;
if (ul.previousElementSibling) ul.previousElementSibling.hidden = !any;
});
});
/* Copy a code block. The label says what happened, then goes back. */
article.addEventListener("click", function (ev) {
var b = ev.target.closest ? ev.target.closest("[data-copy]") : null;
if (!b) return;
var code = b.closest(".codeframe").querySelector("code").textContent;
var done = function (ok) {
b.textContent = ok ? "Copied" : "Select and copy";
setTimeout(function () { b.textContent = "Copy"; }, 1600);
};
if (navigator.clipboard) navigator.clipboard.writeText(code).then(function () { done(true); }, function () { done(false); });
else done(false);
});
/* How far down the document the reader is: a hairline under the bar. */
var bar = document.getElementById("readbar");
if (bar) window.addEventListener("scroll", function () {
var h = document.documentElement;
var f = h.scrollHeight > h.clientHeight ? h.scrollTop / (h.scrollHeight - h.clientHeight) : 0;
bar.style.transform = "scaleX(" + Math.min(1, Math.max(0, f)) + ")";
}, { passive: true });
/* Intercept in-page navigation so the reader does not reload its own shell. */
document.addEventListener("click", function (ev) {
var a = ev.target.closest ? ev.target.closest("a") : null;
if (!a || ev.metaKey || ev.ctrlKey || ev.shiftKey || a.target) return;
var href = a.getAttribute("href") || "";
if (href.indexOf("?doc=") !== 0) return;
ev.preventDefault();
history.pushState(null, "", href);
load(pathFromUrl());
});
window.addEventListener("popstate", function () { load(pathFromUrl()); });
})();