Commit f41aa84fc9167bd72e92f1ae6114aa1d820bea92
Commits[COMMIT BEGIN]commit f41aa84fc9167bd72e92f1ae6114aa1d820bea92 Author: 0x4248 <[email protected]> Date: Thu Mar 19 00:04:50 2026 +0000 linux-ref: init diff --git a/doc/linux-ref/.gitignore b/doc/linux-ref/.gitignore new file mode 100644 index 0000000..567609b --- /dev/null +++ b/doc/linux-ref/.gitignore @@ -0,0 +1 @@ +build/ diff --git a/doc/linux-ref/Makefile b/doc/linux-ref/Makefile new file mode 100644 index 0000000..049d138 --- /dev/null +++ b/doc/linux-ref/Makefile @@ -0,0 +1,122 @@ +PANDOC ?= pandoc +SRC_DIR ?= docs +BUILD_DIR ?= build +TITLE ?= 4248's Linux Reference Manual +#PDF_ENGINE ?= $(shell for e in tectonic xelatex lualatex pdflatex weasyprint prince; do \ +# command -v $$e >/dev/null 2>&1 && { echo $$e; break; }; done) + +PDF_ENGINE = xelatex +CSS := $(SRC_DIR)/assets/style.css +FRONT_MATTER := $(SRC_DIR)/index.md +CHAPTERS := $(sort $(shell find $(SRC_DIR)/chapters -type f -name '*.md')) +BOOK_SOURCES := $(FRONT_MATTER) $(CHAPTERS) + +# Per-chapter HTML: docs/chapters/XX-name.md -> build/html/chapters/XX-name.html +CHAPTER_HTMLS := $(patsubst $(SRC_DIR)/chapters/%.md,$(BUILD_DIR)/html/chapters/%.html,$(CHAPTERS)) + +HTML_INDEX := $(BUILD_DIR)/html/index.html +PDF_OUT := $(BUILD_DIR)/pdf/manual.pdf + +.PHONY: help all docs htmldocs pdfdocs cleandocs clean check-pandoc check-pdf-engine listdocs + +# ── Help ───────────────────────────────────────────────────────────────────── +help: + @echo "Targets:" + @echo " make htmldocs - Build per-chapter HTML manual" + @echo " make pdfdocs - Build PDF manual (new page per chapter)" + @echo " override engine: make pdfdocs PDF_ENGINE=xelatex" + @echo " make docs - Build both" + @echo " make listdocs - Show input source files" + @echo " make cleandocs - Remove generated output" + +all: docs +docs: htmldocs pdfdocs + +# ── Dependency checks ───────────────────────────────────────────────────────── +check-pandoc: + @command -v $(PANDOC) >/dev/null 2>&1 || { \ + echo "error: pandoc is not installed"; exit 1; \ + } + +check-pdf-engine: + @test -n "$(PDF_ENGINE)" || { \ + echo "error: no PDF engine found"; \ + echo "install one of: tectonic, xelatex, lualatex, pdflatex, weasyprint, prince"; \ + echo "or specify: make pdfdocs PDF_ENGINE=xelatex"; \ + exit 1; \ + } + @command -v $(PDF_ENGINE) >/dev/null 2>&1 || { \ + echo "error: PDF engine '$(PDF_ENGINE)' is not installed"; \ + echo "specify another: make pdfdocs PDF_ENGINE=xelatex"; \ + exit 1; \ + } + +listdocs: + @printf '%s\n' $(BOOK_SOURCES) + +# ── HTML: one file per chapter ──────────────────────────────────────────────── +# +# Each chapter is built as a self-contained HTML file (CSS embedded inline) +# so the output in build/html/chapters/ is portable with no external deps. + +$(BUILD_DIR)/html/chapters/%.html: $(SRC_DIR)/chapters/%.md $(CSS) | check-pandoc + @mkdir -p $(dir $@) + $(PANDOC) $< \ + --standalone \ + --embed-resources \ + --toc \ + --number-sections \ + --metadata title="$(TITLE)" \ + --css=$(CSS) \ + -o $@ + +# Index page: intro content + auto-generated chapter listing +$(HTML_INDEX): $(FRONT_MATTER) $(CHAPTERS) $(CSS) | check-pandoc + @mkdir -p $(dir $@) + @{ \ + cat $(FRONT_MATTER); \ + echo ""; \ + echo "## Chapters"; \ + for f in $(CHAPTERS); do \ + rel=$${f#$(SRC_DIR)/chapters/}; \ + base=$${rel%.md}; \ + title=$$(grep -m1 '^# ' $$f | sed 's/^# //'); \ + echo "- [$$title](chapters/$$base.html)"; \ + done; \ + } | $(PANDOC) \ + --standalone \ + --embed-resources \ + --metadata title="$(TITLE)" \ + --css=$(CSS) \ + -o $@ + +htmldocs: $(HTML_INDEX) $(CHAPTER_HTMLS) + @echo "HTML built: $(BUILD_DIR)/html/" + +# ── PDF: new page per chapter ───────────────────────────────────────────────── +# +# --top-level-division=chapter maps each top-level # heading to a LaTeX +# \chapter{}, which starts a new page in the 'report' document class. + +$(PDF_OUT): $(BOOK_SOURCES) | check-pandoc check-pdf-engine + @mkdir -p $(dir $@) + $(PANDOC) $(BOOK_SOURCES) \ + --toc \ + --number-sections \ + --top-level-division=chapter \ + --metadata title="$(TITLE)" \ + -V documentclass=report \ + -V geometry:margin=1in \ + -V colorlinks=true \ + -V linkcolor=blue \ + --pdf-engine=$(PDF_ENGINE) \ + -o $@ + +pdfdocs: $(PDF_OUT) + @echo "PDF built: $(PDF_OUT)" + +# ── Cleanup ─────────────────────────────────────────────────────────────────── +cleandocs: + rm -rf $(BUILD_DIR)/html $(BUILD_DIR)/pdf + +clean: cleandocs diff --git a/doc/linux-ref/README.md b/doc/linux-ref/README.md new file mode 100644 index 0000000..66ee78a --- /dev/null +++ b/doc/linux-ref/README.md @@ -0,0 +1,41 @@ +# 4248's Linux Reference Manual + +Minimal Pandoc generator with Linux-kernel-style Make targets: + +- `make htmldocs` +- `make pdfdocs` + +## Prerequisites + +- `pandoc` +- For PDF output: Pandoc uses a PDF engine backend (auto-detected: `tectonic`, `xelatex`, `lualatex`, `pdflatex`, `wkhtmltopdf`, `weasyprint`, or `prince`) + +## Layout + +- `docs/index.md` front matter and introduction +- `docs/chapters/**/*.md` chapter files (recursively discovered, built in lexicographic order) +- `build/html/index.html` generated HTML +- `build/pdf/manual.pdf` generated PDF + +## Usage + +```bash +make htmldocs +make pdfdocs +make pdfdocs PDF_ENGINE=xelatex +make docs # both +make cleandocs +``` + +If your preferred engine is installed, you can force it via `PDF_ENGINE`. + +## Add new chapters + +Create files under `docs/chapters/` with numeric prefixes for stable ordering, for example: + +- `docs/chapters/02-processes-and-scheduling.md` +- `docs/chapters/03-memory-management.md` +- `docs/chapters/bash/10-bash-overview.md` +- `docs/chapters/bash/20-expansions.md` + +The `Makefile` auto-discovers these files recursively and preserves subfolders in HTML output, for example `build/html/chapters/bash/10-bash-overview.html`. diff --git a/doc/linux-ref/docs/assets/style.css b/doc/linux-ref/docs/assets/style.css new file mode 100644 index 0000000..003eee0 --- /dev/null +++ b/doc/linux-ref/docs/assets/style.css @@ -0,0 +1,23 @@ +body { + font-family: serif; + font-size: 11pt; + background: #fff; + color: #111; + max-width: 860px; + margin: 0 auto; + padding: 3rem 2rem; + line-height: 1.6; +} + +h1, h2, h3, h4, h5, h6 { + font-family: serif; + font-weight: bold; + color: #000; + margin-top: 2.2rem; + margin-bottom: 0.5rem; + line-height: 1.3; +} +h1 { font-size: 2rem; border-bottom: 2px solid #b9b9b9; padding-bottom: 0.3em; text-align: center; } +h2 { font-size: 1.35rem; border-bottom: 1px solid #999; padding-bottom: 0.2em; } +h3 { font-size: 1.1rem; } +h4, h5, h6 { font-size: 1rem; } diff --git a/doc/linux-ref/docs/index.md b/doc/linux-ref/docs/index.md new file mode 100644 index 0000000..90d629f --- /dev/null +++ b/doc/linux-ref/docs/index.md @@ -0,0 +1,24 @@ +--- +title: 4248's Linux Reference Manual +subtitle: Systems and Kernel-Oriented Linux Documentation +author: "0x4248" +date: 2026-03-18 +--- + +# About This Manual + +This manual is a technical Linux reference aimed at practitioners working close to the kernel, user space internals, and system interfaces. + +It is not a beginner tutorial. It is a reference-oriented corpus for answering questions such as: + +- What does this device file represent? +- Which syscall or procfs node backs this behavior? +- Which subsystem owns this interface? + +# Reading Strategy + +Use this document as: + +- a jump table for subsystem-specific deep dives, +- a glossary-backed source of Linux interface details, +- and a cross-reference between user space artifacts and kernel internals.[COMMIT END](C) 2025 0x4248 (C) 2025 4248 Media and 4248 Systems, All part of 0x4248 See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.