AGENTS.md

This file provides guidance for coding agents working in this repository.

Project overview

This repository is the Simplified Chinese translation of 0xAX/linux-insides, a book about Linux kernel internals. The Chinese translation is maintained by @mudongliang and @xinqiu under the hust-open-atom-club organization. The project is licensed under CC BY-NC-SA 4.0.

Most changes are documentation changes. Preserve the technical meaning of the upstream text, the translation history, and any unrelated work already present in the working tree.

Repository layout

SUMMARY.md is the mdBook table of contents and defines which pages are included in the rendered book.
book.toml sets the source root to the repository root and configures HTML, PDF, and EPUB output.
TRANSLATION_STATUS.md records each article's translation state, translator, and, where available, the upstream commit to which it was synchronized.
TRANSLATION_NOTES.md contains the authoritative translation and typography conventions.
CONTRIBUTING.md describes the contribution workflow.
CONTRIBUTORS.md lists translation contributors.
Scripts/validate_markdown_links.py extracts Markdown links and checks live HTTP(S) targets. It expects a directory path and requires Python 3 plus the markdown package.
Chapter content is stored in Booting/, Initialization/, Interrupts/, SysCall/, Timers/, SyncPrim/, MM/, Cgroups/, Concepts/, DataStructures/, Theory/, Misc/, and KernelStructures/.
Chapter-specific images belong in that chapter's images/ directory. Shared project assets belong in Assets/.
book/ is generated output and is ignored by Git; do not edit or commit it.

Build and validation

Install all renderers needed for a complete local build:

cargo install mdbook mdbook-pdf mdbook-epub --locked

Build all configured outputs:

mdbook build

The generated files are written to:

HTML: book/html/
PDF: book/pdf/output.pdf
EPUB: book/epub/Linux 内核揭秘.epub

Preview the book locally with:

mdbook serve --open

For Markdown link changes, install the script dependency if necessary and run the validator on the relevant directory (or . for the entire repository):

python3 -m pip install markdown
python3 Scripts/validate_markdown_links.py .

The link validator performs network requests, so distinguish unavailable or rate-limited services from malformed links. Also run:

git diff --check

After validation, confirm that generated files under book/ have not entered the Git diff and that unrelated working-tree changes remain untouched.

CI and deployment

.github/workflows/mdbook.yml runs on pushes to master and by manual dispatch. It installs mdbook, builds the project, uploads book/html, and deploys that HTML output to GitHub Pages. PDF and EPUB are configured as optional mdBook outputs and are not deployed by this workflow.

Translation workflow

Before translating or updating an article:

Read TRANSLATION_NOTES.md, TRANSLATION_STATUS.md, and CONTRIBUTING.md.
Check that the article is not already claimed. Translation claims use an issue plus a PR that marks the article as in progress.
Synchronize the latest relevant upstream source before translating it.
Prefer one translated file per PR so review remains focused.
After the translation PR is merged, close the claim issue, record the first 12 characters of the verified upstream commit in TRANSLATION_STATUS.md, and add the translator to CONTRIBUTORS.md when needed.

When adding, removing, moving, or renaming an article, keep SUMMARY.md and TRANSLATION_STATUS.md consistent. Do not change an upstream commit hash or an article's completion state without verifying it against the corresponding source and local translation.

Report problems in the English source to 0xAX/linux-insides; report Chinese translation problems in this repository.

Translation style

Follow TRANSLATION_NOTES.md as the source of truth. In particular:

Translate for accurate meaning and natural Chinese; do not submit raw machine translation output.
Keep recurring technical terms consistent across chapters.
Use full-width Chinese punctuation except for parentheses, ellipses, and dashes as specified by the project conventions. Remove the half-width space that follows English punctuation when converting it to Chinese punctuation.
Normally insert one half-width space between Chinese and English text, Chinese and Arabic numerals, and English text and Arabic numerals. Do not add a space next to punctuation.
Keep English personal names untranslated.
Chapter titles must contain Chinese text only. Introduce an original English term at its first occurrence in the body when useful, rather than repeating it in titles.
Translate English "you" as “你”. If repetition harms readability, use “我们” or omit the subject when the context stays clear.
Omit the upstream author's recurring statement that English is not his native language.

Preserve code blocks, identifiers, commands, URLs, image paths, and technical values unless the source update specifically requires changing them. Avoid unrelated reformatting or line-ending normalization in translation-only changes.

5.3 KiB Raw Permalink Blame History