mirror of
https://github.com/MintCN/linux-insides-zh.git
synced 2026-11-01 21:34:38 +08:00
138 lines
5.3 KiB
Markdown
138 lines
5.3 KiB
Markdown
# 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.
|