d3c37f82b6
The site and several documents still described the system as it was before virtual terminals, the new schinit, the hybrid work and descriptor passing. docs/architecture/init.md described the wrong program. It documented a single schinit that parses manifests and supervises jobs, which has not been true since PID 1 was split: PID 1 forks a supervisor, spawns jobs on its behalf and reaps; the job table lives in /proc/schinit; a heartbeat runs both ways; and proc_reincarnate() re-execs PID 1 in place rather than panicking. Rewritten around what exists, keeping the reasoning that is still load-bearing -- the five failures of the sibling-init scheme, the escalation ladder, and the three bugs in the reincarnation path that each had to happen before they were obvious. docs/plan/init.md is deleted, which is the tree's own rule for finished work and had not been applied. Fourteen source comments referenced it by part number, so they are repointed at the architecture doc by section name rather than left dangling -- a deleted document nobody notices is worse than a stale one. docs/architecture/devices.md gained the section it has been missing since /dev/pci existed: what a driver needs from a kernel, why mmap is checked against the caller's claims, why DMA is a call and not a mapping, and why the write back after an interrupt is not optional. Also that a released device does not come back by itself, which is true and was nowhere. docs/architecture/networking.md gained a descriptor-passing section, and docs/architecture/README.md's stack diagram gained the two layers and the third seam it was missing. "Two seams hold the whole thing together" has not been true since /dev/pci. docs/plan/README.md said the hybrid work was deliberately last, on the argument that an interface with no consumer is wrong in ways nobody can see. The argument was right; the conclusion was not, and the document now says why it changed -- the alternative to a driver compatibility layer is writing a driver for every device that exists, and the original objection is answered rather than ignored because SchOS's own drivers are the consumers. The site: a Hybrid section with the eviction transcript, cards for virtual terminals, schinit and drivers outside the kernel, and the numbers remeasured rather than estimated -- 46,961 lines, 207 syscalls. The boot log in app.js is from a boot taken today, and the lines are trimmed to what the console can show without clipping, each still a verbatim prefix of real output. Two small rendering fixes found by looking at the pages rather than assuming: .console pre's min-height is now scoped to the hero, so a static transcript sizes to its content instead of reserving eight lines it does not have; and the docs reader's contents panel strips inline marks from headings, so a heading written `proc_reincarnate()` no longer carries its backticks into the sidebar. Every intra-doc link checked; none broken. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VQ7Qx8E1q1M1bbCq8QLHS2
100 lines
4.3 KiB
Markdown
100 lines
4.3 KiB
Markdown
<!-- SPDX-License-Identifier: Apache-2.0 -->
|
|
# The website
|
|
|
|
Five files and a folder of marks. No build step, no dependencies, no
|
|
framework — open `index.html` and it works, including from a `file://` URL.
|
|
|
|
```
|
|
index.html the front page
|
|
docs.html the documentation reader
|
|
style.css the palette, transcribed from include/theme.h
|
|
app.js the front page: the boot log types, sections fade in
|
|
docs.js the Markdown renderer and the doc index
|
|
Assets/ shift.svg (logo), uberblock.svg (SchFS), guru.svg (PSOGM),
|
|
pride.svg
|
|
```
|
|
|
|
## The docs reader
|
|
|
|
`docs.html` renders the Markdown in `docs/` in the site's own theme, with the
|
|
index down the left and a table of contents down the right. Links between
|
|
documents are rewritten to stay inside the reader, so `../history/schfs.md`
|
|
in an architecture page navigates rather than downloads.
|
|
|
|
The parser is about 150 lines in `docs.js` and handles what `docs/` actually
|
|
uses: headings, fenced code, tables, lists, quotes, rules and inline marks.
|
|
A Markdown library would be larger than everything else here put together.
|
|
Every document is escaped before a single tag is emitted — the only HTML that
|
|
reaches the page is HTML `docs.js` wrote.
|
|
|
|
**This one page needs a server.** Browsers refuse `fetch()` on `file://` for
|
|
the same reason they refuse it cross-origin, so opening `docs.html` from a
|
|
file gives a panel explaining that instead of the docs. Everything else works
|
|
from a file. To read them locally:
|
|
|
|
```sh
|
|
cd /home/nexoniarz/Dokumenty/Projects/SchOS
|
|
python3 -m http.server 8000
|
|
# then http://localhost:8000/docs/Website/docs.html
|
|
```
|
|
|
|
Adding a document means adding one line to the `DOCS` array in `docs.js`. The
|
|
reader will only load a path that appears there.
|
|
|
|
## The two footer notes
|
|
|
|
Both pages carry two statements below the licence line, and both are meant to
|
|
be read rather than skimmed past.
|
|
|
|
The first is the flag, below. The second is about AI, and it says the thing
|
|
worth saying: the tool is not the measure. A project is good when the people
|
|
building it understand what was built. That claim is deliberately made next to
|
|
a link to `history/`, because that directory is where it can be checked — the
|
|
bugs are written up in full, including the wrong turns and the measurements
|
|
that disproved them. An explanation you can follow is the evidence; the byline
|
|
is not.
|
|
|
|
## The flag
|
|
|
|
`Assets/pride.svg` is in the top bar and in the footer, on both pages, and it
|
|
is not seasonal. Support with an end date is marketing; this is a project that
|
|
belongs to whoever writes it. It is also deliberately small — the site is
|
|
about an operating system, and the flag is a statement, not a subject.
|
|
|
|
## The rules it follows
|
|
|
|
**The palette is not a design decision.** It is `include/theme.h`, copied. A
|
|
site describing an operating system should look like the operating system, and
|
|
copying the header means the two cannot drift apart by accident.
|
|
|
|
**PSOGM purple appears exactly once.** `#4B1D9A` is on the crash-screen section
|
|
and nowhere else, because [../branding/README.md](../branding/README.md) says
|
|
it means *the machine stopped* and that a colour used everywhere means nothing.
|
|
If it shows up in a second place, that is a bug in the page.
|
|
|
|
**The typefaces are the ones the OS ships.** Roboto for text and JetBrains Mono
|
|
for the system voice — both already in `ports/`, both already in `NOTICE`. They
|
|
are requested from the system rather than downloaded: a font file would be
|
|
larger than the entire rest of the site.
|
|
|
|
**The script is optional.** If `app.js` fails to load the page is still
|
|
complete and still readable. Everything it does is decoration, and it honours
|
|
`prefers-reduced-motion` by doing none of it.
|
|
|
|
**The boot log is real.** The lines in `app.js` are from an actual boot, not
|
|
invented. The timer calibration line is there deliberately; see section 13 of
|
|
[../history/kernel.md](../history/kernel.md) for what it cost.
|
|
|
|
## Editing it
|
|
|
|
The numbers in the *Numbers* section are measured, not estimated, and they go
|
|
stale. To refresh them:
|
|
|
|
```sh
|
|
find kernel include -name '*.c' -o -name '*.h' | xargs wc -l | tail -1
|
|
grep -c '^SYSCALL' kernel/sys/table.inc
|
|
```
|
|
|
|
The feature cards carry a tag — `runs`, `in progress`, or `designed` — and the
|
|
tag is a promise. Anything marked `runs` is in the tree and works today. When
|
|
that stops being true, change the tag rather than the wording.
|