WIP: Documentation #1512

jay · 2026-10-15T06:57:44Z

jay commented

2026-10-15 06:57:44 +00:00

very much still WIP, not ready for review
preview hosted at https://gerbil.tungo.org/

{.gerbil} inline and gerbil fences link documented identifiers
{module=":std/foo"} declares the documented module
{.def} generates checked signatures; macros use handwritten grammar
gerbil-repl for repl, with outputs in committed _freeze/ files

very much still WIP, not ready for review preview hosted at https://gerbil.tungo.org/ - `{.gerbil}` inline and `gerbil` fences link documented identifiers - `{module=":std/foo"}` declares the documented module - `{.def}` generates checked signatures; macros use handwritten grammar - `gerbil-repl` for repl, with outputs in committed `_freeze/` files

jay added 112 commits

2026-10-15 06:57:45 +00:00

Add a built-in Djot documentation tool 8649093c13

Relocate reference documentation beside source 95e35a075a

Convert documentation with minimal Djot edits 46873ba49a

Publish the documentation site with native Gerbil 2928f4ca68

README.md now publishes as index.html. Historical VuePress URLs
and heading identifiers are not compatibility targets.

merge build scripts into gxdoc.ss 11185f3443

Report generated documentation files bf0fe505dd

Add live documentation preview ded47d66ca

docs: Organize documentation into numbered manuals b3414e0c90

Each manual's root page lists its chapters in a ::: contents block, and doc/readme.md lists the four manuals in a ::: manuals block. The Guide's installation chapter moves from README.md to installation.md so the README can be the Guide's title page.

gxdoc: Publish numbered manuals with bundled fonts 28d75e31f2

Manuals come from ::: contents blocks and start pages from ::: manuals; every page must appear in exactly one contents block. Generated directory indexes, the header bar and breadcrumbs are replaced by a manual rail with numbered contents and prev/up/next links. The default stylesheet moves to gxdoc/gxdoc.css and ships with subset Piazzolla and Fira Mono fonts under the SIL Open Font License.

gxdoc: Cache bundled fonts in the live preview c6b973e647

gxdoc: Polish navigation states and contents layout 800b510159

gxdoc: Link Gerbil code to documented definitions ac68a9d99f

Heading {module=...} attributes declare the module a section documents,
and {.def} signature blocks define the names it must export.  Scheme code
on every page links each identifier to the definition documenting its
binding, found by following re-exports through compiled module interfaces.
Documentation never loads module source or instantiates a module.

docs: Declare modules and definitions in reference 2cef4b4352

Each reference page beside a compiled module declares it in place of an
import tip, and each heading whose signature names exported bindings
becomes a {.def} block.  Headings for bindings the module does not
export are left unchanged.  Links to removed headings use the new
definition anchors, and an unclosed tip in the JSON page is closed.

gxdoc: Link inline code and module-path references 4cebd7e665

Inline code in prose links like code blocks, and shows a definition's
metavariables within its description.  Links to :MODULE or :MODULE#NAME
refer to documentation by module path and must resolve.

gxdoc: Add an index page and search for definitions 7906a83f70

Sites that document definitions get doc-index.html, an alphabetical
index, and a search form ranking definitions, modules, pages and
sections.  A small script makes search live and loads its data on first
use; without JavaScript the form opens the index.

gxdoc: Let the prelude document core forms a02439437b

Core forms such as if and define-values are bound in the expander's root
context and exported by no module, so :gerbil/core accounts for them.
The prelude's expander page now defines its core forms.

gxdoc: Address review of binding links a79663b6e5

Preludes must be compiled too: the expander imports a module's prelude
without the import hook, so it is now imported first under the same
rule.  Each build refreshes interfaces that changed, so the preview
sees rebuilt packages.  Import filters narrow code context; vector
literals stay unlinked; := inside forms is not grammar; each name's
kind comes from its own signature line.  Duplicate definitions are
reported per module and name, and misplaced attributes on code blocks
and repeated module declarations are reported instead of crashing.

gxdoc: Test that rendered code reproduces its source def2811c5c

gxdoc: Link to other sites through published inventories 5cdfc27ecc

Sites with definitions publish gxdoc-inventory.ss, a data file of their
definitions.  A project's xrefs: configuration names other sites'
inventories and base URLs, so its code links to their definitions.

gxdoc: Add glossary terms and a coverage report 52510df3a7

[term]{.dfn} defines a glossary term and [terms]{.term} refers to it,
matching case and plural forms like Scribble's tech.  gerbil doc
--coverage lists each declared module's undocumented exports.

gxdoc: Add version notes and titles for empty links 9c7706da86

{.def added=... deprecated=...} notes versions beside a definition's
kind, and a link with empty text shows its target's title, as Scribble's
history and secref do.

gxdoc: Accept definitions written as definition forms 2d2642ba44

{.def name="x"} marks a block such as (define x (make-parameter #t))
as linked code defining x, like Scribble's defthing; the definer implies
its kind.

docs: Mark definition forms in reference as definitions 743a047c6c

Headings over a definition form of an exported binding, such as
(defclass Exception ...), become {.def name=...} blocks.

gxdoc: Address second review of links and search eaa4dd47f0

Interface refresh now stamps every loaded interface, imported modules
and preludes included, and full builds retry modules that failed.
Search lists definitions first as documented, filters by page path, and
keeps its live region announced.  Inventory and search URLs encode page
paths; xrefs: bases get a final slash and are validated.  Incremental
previews rewrite search data and re-read inventories.  References inside
links no longer nest links, and nested group-in imports resolve.

gxdoc: Clarify when the preview sees rebuilt modules 5c2a0b0aeb

gxdoc: Classify Gerbil code into typed tokens d126b03242

gxdoc: Render pages from a typed document model 99a0f7e1e4

Pages are interpreted from the Djot AST into gxdoc's model and rendered
by one HTML module instead of annotating djot->sxml output. Problems are
reported together as FILE:LINE:COLUMN: message: detail, without the
gxdoc: prefix.

gxdoc: Address phase-1 review e0bd2c6b18

The preview now publishes pages despite content problems and keeps the
last good site only for outline and configuration errors; the outline
is a tree even for cyclic contents blocks, so rendering cannot loop.

gxdoc: Link only code marked as Gerbil a3918d88dc

Code blocks are Gerbil when their language is gerbil and inline code when
it has the class gerbil; gxdoc's classes are errors where they do not
belong, and imports= may precede a Gerbil block.  The pages are converted
mechanically: readable ```scheme blocks and every {.def} block become
```gerbil, and inline code phase 1 linked is marked {.gerbil}.

gxdoc: Close remaining unshown-content gaps e8a5d15045

gxdoc: Generate signatures from source, as a report dd28caa8e1

`gerbil doc --signatures FILE` writes, for each definition, the signature
generated from its module's source and type information beside the one
the page writes, for reviewing before pages switch to generated ones.
Rendering is unchanged.  gxdoc.pkg gains sources:.

gxdoc: Make generated signatures exact and per-build a070d59a45

Slots show their contracts and defaults; a constructor method, type or
alias that cannot be found is an error instead of an invented signature;
the compiled-interface check covers keywords, values that became
procedures and missing optimizer files.  Caches belong to each build's
source index, unreadable sources are located errors, and the report
code moves to gxdoc/migrate.

std/string/uuid: Declare uuid-hash's fixnum result 05903b8071

std/values: Fix nth-value used as a procedure 6c4fd692c9

std/list/list: Keep append-map's results in order 283f8dc3ea

gxdoc: Render definitions from generated signatures 81b0be0035

Blocks list names for generated kinds; syntax keeps its grammar. Members of exported types are defined on their type's lines. Pages are rewritten to names-only definitions; the migration report is removed.

gxdoc: Find own constructor methods; check compiled info both ways be5c93cb5b

A type's own constructor method may be defined in another module, where gxc declares only NS#T::METHOD. Constructors, primitive predicates and t::t bindings no longer fail the consistency check; values, parameters and type options are checked too. Alias targets are classified by declaration, and their errors reported. Headers show final:/constructor: as compiled and transparent:/equal: as written.

std/io/tempfile: Return the procedure's result untyped 8044be4cd2

call-with-temporary-file-name, call-with-temporary-file and call-with-temporary-directory declared => :string but return what PROC returns; optimized callers trusted the declaration ((fixnum? (call-with-temporary-file-name "x" (lambda (f) 42))) gave #f).

gxdoc: Show every type member; render aliases' identity; tighten checks bbc3550bd9

Types show their descriptor, unchecked accessors and an interface's instance predicates and constructors; a member with no line is an error; members of unexported types name their role. Own methods are indexed by method and confirmed by type, so a renamed type is found. An alias of syntax shows (defalias A B) with B's kind, and an alias's kind comes first from its own declaration. name= is an error; per-name problems point at their line. The preview watches sources: and the source and optimizer files read; sources: problems are configuration errors. Results are returned as values, not encoded.

docs: Make prose agree with generated signatures 4667979082

Rewrite request.md's options and http-* entries, websocket-connect and websocket-request-handler, and lru-cache-flush! from the source; name keywords as callers write them; rename old parameter names inside code; fix stale defaults, grammar and descriptions; state call-with-temporary-file-name's result.

gxdoc: Leave unchecked accessors off member lines 229681aee6

Unchecked (&) accessors and mutators are implementation names, which
coverage already ignores, so a type's slot lines no longer show them;
listing one alone is the "shows no line for it" error.  A slot line
without its slot is an internal error instead of "slot ?".  The manual
says so, and its problems sentence keeps its parentheticals with the
attributes they qualify.

docs: Settle open content issues from source 6c272ee76c

- actor: ->> to an exited local actor times out (no actor error);
  remove set-default-reply-timeout!, which v0.19 does not define.
- uuid: remove make-uuid, uuid? and uuid=?, which the module does not
  export; UUID's definition covers make-UUID, UUID? and equal?.
- request: request-json and request-cookies are unimplemented stubs
  that always raise; list the default headers in the order sent.
- make-hash-table: describe lock: (a Locker) and check: from hash.ss.
- csv, decimal: name what the source/writer accept
  (with-buffered-reader/-writer).
- json: write-json with #f returns a string (json-test.ss).
- guide: describe read-json's results and write-json's inputs.
- c3: struct: is optional; name get-name: as callers write it.
- process, hash/misc: parameter and keyword names; rwlock: module name.

gxdoc: Document the identifier macro grammar NAME -> result 96bd2770dc

The owner decided that an identifier macro, used as a bare identifier, is written NAME -> result, as multicall-default -> symbol is; its name alone is not a grammar.

docs: Remove the page of the removed :std/ref 72d1e5c521

docs: Correct stale definitions in the prelude pages c15136f750

docs: Correct stale definitions in the runtime pages 8065b95d3c

docs: Correct stale definitions in std/actor b7f697ea4a

docs: Correct stale definitions in std/struct, std/sync and std/time 949a183796

docs: Correct stale definitions in std/encoding da82b3c56e

docs: Correct stale definitions in std/io f20a95f847

docs: Correct stale definitions in std/error, cli, ffi and interface e254733a3d

docs: Correct stale definitions in std/iter df77552062

gxdoc: Reject a member no line of its exported type shows fbd5a1cb36

docs: Correct stale definitions in std/os and std/net/sasl cfee769974

docs: Correct stale definitions in std/net/address e072cbf04f

docs: Correct stale definitions in std/net and std/string/misc 1670b4bb96

docs: Correct stale definitions in std/text/parser/ll1 4d1ed73730

docs: Point to Gambit for primitives the prelude re-exports 98fd2d496b

docs: Correct stale definitions in std/sync/threads fb071ee7e6

docs: Correct stale definitions in std/log 7d23baac5a

docs: Correct stale definitions in std/vector/u8vector and std/number/misc 7797490ff2

docs: Document length-delimited IO under std/encoding/protobuf/io 89a61c09f9

std/vector/extensible: List only elements before the fill pointer 28d5076d94

docs: Correct stale definitions in std/vector/extensible 396dd3d184

docs: Correct stale definitions in std/list/walist 7926270b41

docs: Correct stale definitions in std/make and the expander page 3406ae4adc

std/list/list: End take-while's list where the predicate fails 315c5960c1

std/log: Name a logger's source after its identifier by default e929da6598

std/list/list: Make take-while! return its list and accept [] 295fce00bd

docs: Document remq1 and remv1; correct keyword-dispatch's kwt 04e0e7b4d0

docs: Correct claims in edited actor, error, iter, io and json prose 49338a884f

docs: Correct socket, extensible, walist and atom successors 7bf340394f

docs: Restore the Gambit primitives' sections, corrected 57247176ed

std/io/bio: Store read-string-utf8's characters from start 42dc8b665d

docs: Correct filter, cons* and extensible-vector claims 56cccb28a3

gxdoc: Parse and render REPL transcripts 47942884ec

runtime: Display a syntax error's form on the port given ae1a23d5b9

gxdoc: Check REPL transcripts with gerbil doc --check-examples b6ddefdade

gxdoc: Rewrite differing example outputs with --update fafb72f7e2

gxdoc: Contain and bound each example session 11950e3480

gxdoc: Keep a page's permissions on --update f8482dd4bf

gxdoc: Cut example diffs short and tidy the checker e7226f6227

gxdoc: Report an input that reads as nothing, at its prompt b90bb689ed

gxdoc: Make --update keep serials and page structure 0325f4437a

gxdoc: Run what examples link, reject an empty --only, count all 29f7dce8dc

docs: Write REPL examples as gerbil-repl transcripts 1ec7db2e9c

docs: Split shell sessions from REPL transcripts 3616ef2cc7

gxdoc: Report a prompt outside a transcript 4110615fcf

gxdoc: Address the fix review of the example checker 409844c726

--update numbers objects as the session's matching outputs do; set-id
and sticky bits are masked; check=none partial imports are replayed;
an exited driver is never signalled; a late cleanup failure is the
run's problem; late output joins the last input, malformed output
between frames the next, and a hang after the last input reports its
timeout; --timeout and --jobs need --check-examples again.

std/list: Define unique, whose SRFI 1 target is gone 944fe30db3

std/sync/channel: Pass timeouts to mutex-unlock! as times 77a550c8e6

docs: Repair examples for this branch's library baad3321f6

docs: Give sieve examples their own sessions and elide long outputs 15bfc93dc1

gxdoc: Keep the terminal fixture's unbound variable unbound fc761fb4e4

std/list now defines unique, which the fixture used as its unbound name.

gxdoc: Lay out a result from column 1, as a terminal REPL does b8ba0ebbfd

A pipe's column counts the characters of a string written to it past its
newlines, so a result after output ending in a newline was indented as
if it continued that output.

docs: Repair examples the output refresh showed broken e0af854cd8

gxdoc: Print a result with its port's readtable b6bff402ad

Laying a result out apart from the port lost the port's readtable, and
with it the #0= labels the REPL prints for shared structure.

docs: Refresh example outputs cbb9f97d75

gxdoc: Add recorded-example files and the driver's error frame 81906af1dd

freeze.ss reads, writes and replays _freeze recordings; nothing uses it
yet.  The driver frames an entry's error text with !ID, so output and
error text are recorded apart.

docs: Keep only inputs in REPL transcripts 2f70b8b783

Outputs move to recordings; inputs that must raise are marked ; raises,
and blocks whose S5 wildcards hid random output are check=run.

gxdoc: Record examples with gerbil doc --run-examples fb9883d54a

Results go to _freeze/ (freeze-dir:), one file per page; --check
compares without writing, and --manual adds check=manual sessions.
Inputs that must raise are marked ; raises.

docs: Mark examples that need the reader's machine check=manual 05b3b4136b

Examples that read the reader's files get setups that write them in
the session's directory instead, and are recorded.

docs: Record the REPL examples in _freeze 327418dbae

gxdoc: Show recorded examples, and remove --check-examples b838e9307a

Builds replay each page's recording from _freeze and stop on a missing
or stale one; an output line in a transcript is an error.  Page outputs,
wildcards and --update are gone.

gxdoc: Refresh the preview when recordings change b843d6563d

The preview watches the freeze directory and renders again the pages
whose recordings changed; it marks an input without a current one.

gxdoc: Keep previews and recording checks in sync a7e5deaea9

docs: Compare deterministic example results 12f7e2ea80

docs: normalize published references and code markup 1659ab1668

docs: state the gxdoc authoring conventions b618725ef0

docs: leave data and notation outside Gerbil spans a1c2a3c988

docs: leave foreign names and placeholders in plain notation 6c03b82c14

docs: preserve alias identities and markup 8b526f0998

jay added 2 commits

2026-10-15 08:11:26 +00:00

gxdoc: document confirmed external bindings acb420aa6d

gxdoc: check external origins and delimiters 2b4cf5cf4b

jay added 6 commits

2026-10-15 23:11:33 +00:00

gxdoc: publish installed sets and shared local lookup 6b912270bb

(cherry picked from commit 6cc169664bc7b4f4558bdcc7329d6b911d459d6c)

gxpkg: install native package manuals after compilation e83015adc5

Preserve manuals with --no-docs and remove them on named cleanup. Validate documentation destinations and reuse gxdoc dependency discovery.

Correct the pre-existing path-normalize* argument bug as approved: uninstall must remove its target, not the caller directory. Isolated tests preserve caller and sibling sentinels.

(cherry picked from commit d497bd3811944fc847034de10364c627e6510d85)

build: install native manuals and support documentation-free builds 50d937663a

(cherry picked from commit d32f51531d0d64013a851272c250d24753fbaf85)

repl: resolve installed help by binding identity 9ee0da7390

(cherry picked from commit 363f73ac181409382f7ed0c702b099f4e7b5179b)

build: memoize completed library dependencies a43b39a2e5

Keep traversal-local completion separate from final module ordering. Repeated acyclic imports otherwise expand exponentially before the clean build can compile libgerbil. Preserve phase selection, exclusions and deterministic dependency order.

gxdoc: exclude generated Gambit bootstrap readmes 44e392eabe

jay added 8 commits

2026-10-16 02:26:48 +00:00

gxdoc: register preview watches before publication 7d5b61bd1d

Keep newly discovered source watches inside the publication lock. Releasing readers first lets an immediate source edit precede watch registration and lose its event. The unchanged installed preview suite now passes all 18 cases.

tests: retain libraries in isolated manual roots 59a42db2f1

Fixture GERBIL_HOME values must isolate manuals without hiding the actual installed core library. This lets the unchanged command assertions run with no GERBIL_LOADPATH overlay.

docs: clarify help imports after module entry de3756a704

fix(gxdoc): preserve active interfaces, alias identity and source layouts 4262dd9e85

test(gxdoc): configure the competing-library fixture 85031f7a1c

fix(gxdoc): accept escaped percent filenames in documentation lookup fc02acfcbc

test(gxdoc): assert the native missing-page exception cbd7d10efb

test(gxdoc): supply explicit percent-fixture input directories 2ad3f8d31b

This pull request has changes conflicting with the target branch.

src/build/build-libgerbil-test.ss
src/build/build-libgerbil.ss
src/std/list/list-test.ss
src/std/sync/channel-test.ss

View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Merge commit title

WIP: Documentation (#1512)

Merge commit body

Reviewed-on: https://git.cons.io/mighty-gerbils/gerbil/pulls/1512

WIP: Documentation (#1512)

Reviewed-on: https://git.cons.io/mighty-gerbils/gerbil/pulls/1512

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u v0.19-documentation:jay-v0.19-documentation

git switch jay-v0.19-documentation

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch v0.19-staging

git merge --no-ff jay-v0.19-documentation

git switch jay-v0.19-documentation

git rebase v0.19-staging

git switch v0.19-staging

git merge --ff-only jay-v0.19-documentation

git switch jay-v0.19-documentation

git rebase v0.19-staging

git switch v0.19-staging

git merge --no-ff jay-v0.19-documentation

git switch v0.19-staging

git merge --squash jay-v0.19-documentation