mirror of
https://github.com/MintCN/linux-insides-zh.git
synced 2026-10-29 03:44:00 +08:00
docs: add agent guide and localize links
This commit is contained in:
Dongliang Mu
137
AGENTS.md
Normal file
137
AGENTS.md
Normal file
@@ -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.
|
||||
32
LINKS.md
32
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)
|
||||
|
||||
@@ -87,5 +87,5 @@
|
||||
* [内核中的数据结构]()
|
||||
* [内核数据结构](KernelStructures/README.md)
|
||||
* [中断描述符表](KernelStructures/linux-kernelstructure-1.md)
|
||||
* [有帮助的链接](LINKS.md)
|
||||
* [有用的链接](LINKS.md)
|
||||
* [贡献者](CONTRIBUTORS.md)
|
||||
|
||||
Reference in New Issue
Block a user