From 30dde7dee50a5e230600e99db61b5c53e9d3901e Mon Sep 17 00:00:00 2001 From: Dongliang Mu Date: Tue, 1 Sep 2026 10:00:41 +0800 Subject: [PATCH] docs: add agent guide and localize links --- AGENTS.md | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++++ LINKS.md | 32 ++++++------- SUMMARY.md | 2 +- 3 files changed, 154 insertions(+), 17 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cf0ed64 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,137 @@ +# 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](https://github.com/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: + +```bash +cargo install mdbook mdbook-pdf mdbook-epub --locked +``` + +Build all configured outputs: + +```bash +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: + +```bash +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): + +```bash +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: + +```bash +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: + +1. Read `TRANSLATION_NOTES.md`, `TRANSLATION_STATUS.md`, and + `CONTRIBUTING.md`. +2. Check that the article is not already claimed. Translation claims use an + issue plus a PR that marks the article as in progress. +3. Synchronize the latest relevant upstream source before translating it. +4. Prefer one translated file per PR so review remains focused. +5. 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. diff --git a/LINKS.md b/LINKS.md index 33d5e6f..42dd8d0 100644 --- a/LINKS.md +++ b/LINKS.md @@ -1,51 +1,51 @@ -有帮助的链接 +有用的链接 ======================== Linux 启动 ------------------------ -* [Linux/x86 boot protocol](https://www.kernel.org/doc/Documentation/x86/boot.txt) -* [Linux kernel parameters](https://github.com/torvalds/linux/blob/master/Documentation/kernel-parameters.txt) +* [Linux/x86 启动协议](https://www.kernel.org/doc/Documentation/x86/boot.txt) +* [Linux 内核参数](https://github.com/torvalds/linux/blob/master/Documentation/kernel-parameters.txt) 保护模式 ------------------------ -* [64-ia-32-architectures-software-developer-vol-3a-part-1-manual.pdf](http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html) +* [Intel 64 和 IA-32 架构软件开发者手册 卷 3A](http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html) Linux 内核内存管理 -------------------------------------- -* [Notes on the linux kernel VM subsystem by @lorenzo-stoakes](https://github.com/lorenzo-stoakes/linux-vm-notes) +* [@lorenzo-stoakes 的 Linux 内核虚拟内存子系统笔记](https://github.com/lorenzo-stoakes/linux-vm-notes) 串口编程 ------------------------ -* [8250 UART Programming](http://en.wikibooks.org/wiki/Serial_Programming/8250_UART_Programming#UART_Registers) -* [Serial ports on OSDEV](https://wiki.osdev.org/Serial_Ports) +* [8250 UART 编程](http://en.wikibooks.org/wiki/Serial_Programming/8250_UART_Programming#UART_Registers) +* [OSDEV 上的串口资料](https://wiki.osdev.org/Serial_Ports) VGA ------------------------ -* [Video Graphics Array (VGA)](http://en.wikipedia.org/wiki/Video_Graphics_Array) +* [视频图形阵列（VGA）](https://zh.wikipedia.org/wiki/%E8%A7%86%E9%A2%91%E5%9B%BE%E5%BD%A2%E9%98%B5%E5%88%97) IO ------------------------ -* [IO port programming](http://www.tldp.org/HOWTO/text/IO-Port-Programming) +* [IO 端口编程](http://www.tldp.org/HOWTO/text/IO-Port-Programming) -GCC and GAS +GCC 与 GAS ------------------------ -* [GCC type attributes](https://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html) -* [Assembler Directives](http://www.chemie.fu-berlin.de/chemnet/use/info/gas/gas_toc.html#TOC65) +* [GCC 类型属性](https://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html) +* [汇编伪指令](http://www.chemie.fu-berlin.de/chemnet/use/info/gas/gas_toc.html#TOC65) 重要的数据结构 -------------------------- -* [task_struct definition](http://lxr.free-electrons.com/source/include/linux/sched.h#L1274) +* [task_struct 定义](http://lxr.free-electrons.com/source/include/linux/sched.h#L1274) -有帮助的链接 +其他有用的链接 ------------------------ -* [Linux x86 Program Start Up](http://dbp-consulting.com/tutorials/debugging/linuxProgramStartup.html) -* [Memory Layout in Program Execution (32 bits)](http://fgiasson.com/articles/memorylayout.txt) +* [Linux x86 程序启动过程](http://dbp-consulting.com/tutorials/debugging/linuxProgramStartup.html) +* [程序执行中的内存布局（32 位）](http://fgiasson.com/articles/memorylayout.txt) diff --git a/SUMMARY.md b/SUMMARY.md index a54fc21..cf74e69 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -87,5 +87,5 @@ * [内核中的数据结构]() * [内核数据结构](KernelStructures/README.md) * [中断描述符表](KernelStructures/linux-kernelstructure-1.md) -* [有帮助的链接](LINKS.md) +* [有用的链接](LINKS.md) * [贡献者](CONTRIBUTORS.md)