docs: The Dictionary of v4 -- every live word, alphabetical, its stack notation and description; built and published with every release (#157) [skip ci]
make dictionary -> build/docs/Dictionary.pdf (20 pages): mkdictionary.py checks docs/reference/v4-dictionary.tsv against the booted system's words first, so a stale dictionary fails the build; then Markdown, pandoc, docs/book/dictionary.tex (the books' preamble, its own title page: version and commit). Quoted FORTH tokens set as code, so their quotes print straight. The nightly's docs stage builds it; publish sends classifier dictionary; the Gitea release attaches it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE3SDvQn5EoxdGufk84zz2
This commit is contained in:
@@ -78,7 +78,7 @@ BOARD_DIR := $(if $(TARGET),$(BOARD_DIR_$(TARGET)))
|
|||||||
SUBMAKE := $(MAKE) --no-print-directory
|
SUBMAKE := $(MAKE) --no-print-directory
|
||||||
|
|
||||||
.DEFAULT_GOAL := all
|
.DEFAULT_GOAL := all
|
||||||
.PHONY: all boot_image boot_images write_stick docs fabric clean clean-docs kernel boards help help-hosted sbom sbom-board \
|
.PHONY: all boot_image boot_images write_stick docs fabric dictionary clean clean-docs kernel boards help help-hosted sbom sbom-board \
|
||||||
qemu qemu-esp qemu-gdb init
|
qemu qemu-esp qemu-gdb init
|
||||||
|
|
||||||
# ARCH given on the command line and no TARGET: `clean` is the kernel's for that
|
# ARCH given on the command line and no TARGET: `clean` is the kernel's for that
|
||||||
@@ -207,6 +207,10 @@ docs:
|
|||||||
fabric:
|
fabric:
|
||||||
@$(SUBMAKE) -f docs/book/Makefile fabric
|
@$(SUBMAKE) -f docs/book/Makefile fabric
|
||||||
|
|
||||||
|
# dictionary -- The Dictionary of v4 (#157): build/docs/Dictionary.pdf
|
||||||
|
dictionary:
|
||||||
|
@$(SUBMAKE) -f docs/book/Makefile dictionary
|
||||||
|
|
||||||
clean-docs:
|
clean-docs:
|
||||||
rm -rf build/docs
|
rm -rf build/docs
|
||||||
|
|
||||||
|
|||||||
+35
-1
@@ -63,9 +63,18 @@ FABRIC_DIR := $(OUT)/fabric
|
|||||||
FABRIC_PDF := $(OUT)/BookOfFabric.pdf
|
FABRIC_PDF := $(OUT)/BookOfFabric.pdf
|
||||||
FABRIC_FRAGS := $(foreach n,fabric-0 fabric-1 fabric-2 fabric-3 fabric-3-5 fabric-3-6 fabric-3-7 fabric-4,$(GEN)/$(n).tex)
|
FABRIC_FRAGS := $(foreach n,fabric-0 fabric-1 fabric-2 fabric-3 fabric-3-5 fabric-3-6 fabric-3-7 fabric-4,$(GEN)/$(n).tex)
|
||||||
|
|
||||||
.PHONY: all fabric tools FORCE
|
# The Dictionary of v4 (#157): every live word, alphabetical, with its stack
|
||||||
|
# notation and description -- `make dictionary` -> build/docs/Dictionary.pdf.
|
||||||
|
# Its names are the booted system's (v4/tools/mkdictionary.py); the check
|
||||||
|
# refuses a table that has fallen behind them.
|
||||||
|
DICT_DIR := $(OUT)/dictionary
|
||||||
|
DICT_PDF := $(OUT)/Dictionary.pdf
|
||||||
|
DICT_TSV := docs/reference/v4-dictionary.tsv
|
||||||
|
|
||||||
|
.PHONY: all fabric dictionary tools FORCE
|
||||||
all: $(PDF)
|
all: $(PDF)
|
||||||
fabric: $(FABRIC_PDF)
|
fabric: $(FABRIC_PDF)
|
||||||
|
dictionary: $(DICT_PDF)
|
||||||
|
|
||||||
tools:
|
tools:
|
||||||
@missing=""; \
|
@missing=""; \
|
||||||
@@ -113,6 +122,8 @@ $(VAR_DIR)/meta.tex: FORCE
|
|||||||
$(meta_cmds)
|
$(meta_cmds)
|
||||||
$(FABRIC_DIR)/meta.tex: FORCE
|
$(FABRIC_DIR)/meta.tex: FORCE
|
||||||
$(meta_cmds)
|
$(meta_cmds)
|
||||||
|
$(DICT_DIR)/meta.tex: FORCE
|
||||||
|
$(meta_cmds)
|
||||||
|
|
||||||
FORCE:
|
FORCE:
|
||||||
|
|
||||||
@@ -137,3 +148,26 @@ $(FABRIC_PDF): $(BOOK_DIR)/fabric.tex $(BOOK_DIR)/preamble.tex $(FABRIC_FRAGS) $
|
|||||||
echo "Error: LaTeX failed; full log: $(FABRIC_DIR)/fabric.log"; exit 1; }
|
echo "Error: LaTeX failed; full log: $(FABRIC_DIR)/fabric.log"; exit 1; }
|
||||||
@cp $(FABRIC_DIR)/fabric.pdf $@
|
@cp $(FABRIC_DIR)/fabric.pdf $@
|
||||||
@echo " PDF $@"
|
@echo " PDF $@"
|
||||||
|
|
||||||
|
# the live word list needs the hosted v4; the check fails the build on a word with no entry, an
|
||||||
|
# unfinished entry, or an entry for a word the system no longer has
|
||||||
|
$(GEN)/dictionary-words.md: $(DICT_TSV) v4/tools/mkdictionary.py FORCE | tools
|
||||||
|
@mkdir -p $(GEN)
|
||||||
|
@$(MAKE) --no-print-directory -C v4 hosted >/dev/null
|
||||||
|
@python3 v4/tools/mkdictionary.py check $(DICT_TSV)
|
||||||
|
@python3 v4/tools/mkdictionary.py md $(DICT_TSV) $@
|
||||||
|
|
||||||
|
$(GEN)/dictionary-words.tex: $(GEN)/dictionary-words.md $(PANDOC_FILTERS) | tools
|
||||||
|
@echo " PANDOC $< -> $@"
|
||||||
|
@$(PANDOC) $(PANDOC_FLAGS) --id-prefix=dictionary- $< -o $@
|
||||||
|
|
||||||
|
TEXINPUTS_DICT := $(abspath $(DICT_DIR)):$(abspath $(GEN)):$(abspath $(BOOK_DIR)):
|
||||||
|
|
||||||
|
$(DICT_PDF): $(BOOK_DIR)/dictionary.tex $(BOOK_DIR)/preamble.tex $(GEN)/dictionary-words.tex $(GEN)/pandoc-highlighting.tex $(DICT_DIR)/meta.tex | tools
|
||||||
|
@echo " LATEXMK $(BOOK_DIR)/dictionary.tex -> $@"
|
||||||
|
@TEXINPUTS=$(TEXINPUTS_DICT) $(LATEXMK) -xelatex -interaction=nonstopmode -halt-on-error \
|
||||||
|
-file-line-error -outdir=$(DICT_DIR) $(BOOK_DIR)/dictionary.tex > $(DICT_DIR)/latexmk.log 2>&1 || { \
|
||||||
|
grep -A4 -E '^(.*:[0-9]+:|!)' $(DICT_DIR)/dictionary.log | head -40; \
|
||||||
|
echo "Error: LaTeX failed; full log: $(DICT_DIR)/dictionary.log"; exit 1; }
|
||||||
|
@cp $(DICT_DIR)/dictionary.pdf $@
|
||||||
|
@echo " PDF $@"
|
||||||
|
|||||||
@@ -0,0 +1,42 @@
|
|||||||
|
% docs/book/dictionary.tex -- master file of The Dictionary of v4 (#157):
|
||||||
|
% every word StarForth v4 boots with, alphabetical, with its stack notation,
|
||||||
|
% a description and where it is defined (Captain Bob, 2026-11-08: "a
|
||||||
|
% 'dictionary' document with the word, stack notations and descriptions.
|
||||||
|
% Alphabetical."; v4's words only).
|
||||||
|
%
|
||||||
|
% Built by `make dictionary` (docs/book/Makefile): v4/tools/mkdictionary.py
|
||||||
|
% checks docs/reference/v4-dictionary.tsv against the live system and writes
|
||||||
|
% the Markdown that pandoc turns into the fragment input below.
|
||||||
|
\documentclass[11pt,openany]{book}
|
||||||
|
|
||||||
|
\input{preamble}
|
||||||
|
|
||||||
|
\title{The Dictionary of StarForth v4\\[0.5em]\large Every word, its stack notation, and what it does}
|
||||||
|
\author{Robert A. James (Captain Bob)}
|
||||||
|
\date{Version \texttt{\bookversion}\\Built \bookdate{} from commit \texttt{\bookcommit}}
|
||||||
|
|
||||||
|
\begin{document}
|
||||||
|
\frontmatter
|
||||||
|
\maketitle
|
||||||
|
|
||||||
|
\chapter{How to read it}
|
||||||
|
Every word of the dictionary StarForth v4 boots with is here, in
|
||||||
|
alphabetical order. The names are not typed by hand: they are the booted
|
||||||
|
system's own list (\texttt{WORDS}, and the kernel's words of the node), and
|
||||||
|
the build refuses a dictionary that has fallen behind it.
|
||||||
|
|
||||||
|
\textbf{Stack notation.} \texttt{( before -{}- after )}: the values a word
|
||||||
|
takes from the stack, the top on the right, and what it leaves there.
|
||||||
|
\texttt{( R: ... )} is the return stack. \texttt{n} a signed number,
|
||||||
|
\texttt{u} an unsigned one, \texttt{d} and \texttt{ud} double-cell numbers,
|
||||||
|
\texttt{q} a Q48.16 fixed-point number, \texttt{x} any cell, \texttt{flag}
|
||||||
|
a truth value (0 false, -1 true), \texttt{c} a character, \texttt{addr} a
|
||||||
|
cell address, \texttt{baddr} a byte address, \texttt{xt} an execution token.
|
||||||
|
|
||||||
|
\textbf{xxx.} Where a word reads a name or text from the input stream, the
|
||||||
|
description shows it, as \texttt{' xxx} or \texttt{.\textquotedbl{} text\textquotedbl}.
|
||||||
|
|
||||||
|
\mainmatter
|
||||||
|
\input{dictionary-words}
|
||||||
|
|
||||||
|
\end{document}
|
||||||
@@ -15,9 +15,9 @@ Captain Bob, 2026-11-10: "Do it" -- the rest of alpha.4 that lives in the tree,
|
|||||||
|
|
||||||
## #157 -- the dictionary of v4, and the .com's Documents page
|
## #157 -- the dictionary of v4, and the .com's Documents page
|
||||||
- [x] the live word list of the built system (318 words): `v4/tools/mkdictionary.py words` -- the hosted v4's `WORDS` (317) plus the kernel's `sk_v4_words[]` (`MINT-ZUSE`)
|
- [x] the live word list of the built system (318 words): `v4/tools/mkdictionary.py words` -- the hosted v4's `WORDS` (317) plus the kernel's `sk_v4_words[]` (`MINT-ZUSE`)
|
||||||
- [~] the table in the tree, `docs/reference/v4-dictionary.tsv`: drafted for all 318 (`mkdictionary.py draft`; the source gave a stack comment for 54, a description for 105); the rest written by hand in batches, alphabetical -- next: batch 1
|
- [x] the table in the tree, `docs/reference/v4-dictionary.tsv`: all 318 entries, written in three alphabetical batches against v4's own definitions (the source gave 54 stacks and 105 descriptions to start from); `check` passes
|
||||||
- [x] the check: `mkdictionary.py check` -- every live word has a finished entry, every entry a live word (fails on all 318 drafts today, as it should); not yet in the build
|
- [x] the check: `mkdictionary.py check` -- every live word has a finished entry, every entry a live word; run by `make dictionary`, so a stale table fails the build and the nightly
|
||||||
- [ ] the PDF, alphabetical; `make dictionary`; the nightly's docs stage, classifier `dictionary`
|
- [x] the PDF, alphabetical: `make dictionary` -> `build/docs/Dictionary.pdf` (20 pages; `docs/book/dictionary.tex`); the nightly's docs stage builds it, `publish` sends classifier `dictionary`, the release attaches it
|
||||||
- [ ] the Documents page: canvas artboard, then `site/com`
|
- [ ] the Documents page: canvas artboard, then `site/com`
|
||||||
|
|
||||||
## #126 -- the Downloads page live
|
## #126 -- the Downloads page live
|
||||||
|
|||||||
+5
-1
@@ -43,6 +43,7 @@
|
|||||||
# (make -C docs/formal doxygen), into build/nightly-docs/.
|
# (make -C docs/formal doxygen), into build/nightly-docs/.
|
||||||
# scripts/nightly.sh publish-docs <URL>
|
# scripts/nightly.sh publish-docs <URL>
|
||||||
# org.starship:documentation:<VERSION>: classifier book, fabric (The Book of Fabric, #138),
|
# org.starship:documentation:<VERSION>: classifier book, fabric (The Book of Fabric, #138),
|
||||||
|
# dictionary (The Dictionary of v4, #157 -- it fails the stage if a live word has no entry),
|
||||||
# vol1, vol2, vol3, api (pdf).
|
# vol1, vol2, vol3, api (pdf).
|
||||||
#
|
#
|
||||||
# VERSION is <LITHOS_VERSION>-SNAPSHOT, or NIGHTLY_VERSION when set (a release sets it from its
|
# VERSION is <LITHOS_VERSION>-SNAPSHOT, or NIGHTLY_VERSION when set (a release sets it from its
|
||||||
@@ -175,9 +176,11 @@ docs)
|
|||||||
rm -rf "$DOCS"; mkdir -p "$DOCS"
|
rm -rf "$DOCS"; mkdir -p "$DOCS"
|
||||||
make --no-print-directory docs
|
make --no-print-directory docs
|
||||||
make --no-print-directory fabric
|
make --no-print-directory fabric
|
||||||
|
make --no-print-directory dictionary
|
||||||
make --no-print-directory -C docs/formal vols doxygen
|
make --no-print-directory -C docs/formal vols doxygen
|
||||||
cp build/docs/LithosAnanke.pdf "$DOCS/book.pdf"
|
cp build/docs/LithosAnanke.pdf "$DOCS/book.pdf"
|
||||||
cp build/docs/BookOfFabric.pdf "$DOCS/fabric.pdf"
|
cp build/docs/BookOfFabric.pdf "$DOCS/fabric.pdf"
|
||||||
|
cp build/docs/Dictionary.pdf "$DOCS/dictionary.pdf"
|
||||||
for v in 1 2 3; do cp "docs/formal/build/vol$v/main.pdf" "$DOCS/vol$v.pdf"; done
|
for v in 1 2 3; do cp "docs/formal/build/vol$v/main.pdf" "$DOCS/vol$v.pdf"; done
|
||||||
cp docs/formal/build/doxygen/StarForth-API-Reference.pdf "$DOCS/api.pdf"
|
cp docs/formal/build/doxygen/StarForth-API-Reference.pdf "$DOCS/api.pdf"
|
||||||
(cd "$DOCS" && sha256sum ./*.pdf | tee SHA256SUMS)
|
(cd "$DOCS" && sha256sum ./*.pdf | tee SHA256SUMS)
|
||||||
@@ -220,8 +223,9 @@ print(json.dumps(notes.strip() + "\n\n## Checksums (SHA-256)\n\n```\n" + sums.st
|
|||||||
;;
|
;;
|
||||||
publish-docs)
|
publish-docs)
|
||||||
url=${2:-}; [ -n "$url" ] || usage
|
url=${2:-}; [ -n "$url" ] || usage
|
||||||
need "$DOCS/book.pdf" "$DOCS/fabric.pdf" "$DOCS/vol1.pdf" "$DOCS/vol2.pdf" "$DOCS/vol3.pdf" "$DOCS/api.pdf"
|
need "$DOCS/book.pdf" "$DOCS/fabric.pdf" "$DOCS/dictionary.pdf" "$DOCS/vol1.pdf" "$DOCS/vol2.pdf" "$DOCS/vol3.pdf" "$DOCS/api.pdf"
|
||||||
deploy "$url" documentation "$DOCS/book.pdf" pdf book "$DOCS/fabric.pdf" pdf fabric \
|
deploy "$url" documentation "$DOCS/book.pdf" pdf book "$DOCS/fabric.pdf" pdf fabric \
|
||||||
|
"$DOCS/dictionary.pdf" pdf dictionary \
|
||||||
"$DOCS/vol1.pdf" pdf vol1 "$DOCS/vol2.pdf" pdf vol2 "$DOCS/vol3.pdf" pdf vol3 \
|
"$DOCS/vol1.pdf" pdf vol1 "$DOCS/vol2.pdf" pdf vol2 "$DOCS/vol3.pdf" pdf vol3 \
|
||||||
"$DOCS/api.pdf" pdf api
|
"$DOCS/api.pdf" pdf api
|
||||||
;;
|
;;
|
||||||
|
|||||||
@@ -160,6 +160,9 @@ def main():
|
|||||||
stack, desc = table.get(w, ("", ""))
|
stack, desc = table.get(w, ("", ""))
|
||||||
rel = defs.get(w, ("", "", ""))[0]
|
rel = defs.get(w, ("", "", ""))[0]
|
||||||
cell = lambda x: x.replace("|", "\\|")
|
cell = lambda x: x.replace("|", "\\|")
|
||||||
|
# a token with a quote in it is FORTH (." text" S" ABORT"): set as code, so its
|
||||||
|
# quotes print straight, not as typographic ones
|
||||||
|
desc = re.sub(r'(\S*"\S*)', lambda mm: "`" + mm.group(1) + "`", desc)
|
||||||
f.write(f"| `{cell(w)}` | `{cell(stack)}` | {cell(desc)} | `{rel}` |\n")
|
f.write(f"| `{cell(w)}` | `{cell(stack)}` | {cell(desc)} | `{rel}` |\n")
|
||||||
print(f"mkdictionary: {out}, {len(words)} words")
|
print(f"mkdictionary: {out}, {len(words)} words")
|
||||||
return
|
return
|
||||||
|
|||||||
Reference in New Issue
Block a user