mirror of
https://github.com/openmlsys/openmlsys-zh.git
synced 2026-04-13 10:29:45 +08:00
9c289782cc
Split each bilingual CONTRIBUTING file into _en.md and _zh.md variants: - CONTRIBUTING.md → CONTRIBUTING_en.md + CONTRIBUTING_zh.md - style.md → style_en.md + style_zh.md - info.md → info_en.md + info_zh.md - issue.md → issue_en.md + issue_zh.md - reference_guide.md → reference_guide_en.md + reference_guide_zh.md terminology.md kept as-is (bilingual lookup table by nature). Update README.md to link to _zh.md files, README_EN.md to _en.md files. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
181 lines
4.4 KiB
Markdown
181 lines
4.4 KiB
Markdown
# Writing Style Guide
|
||
|
||
This document defines the formatting and style requirements for v2 chapter content. All contributors must follow these guidelines when writing or modifying content.
|
||
|
||
> **Note:** The LaTeX-to-Markdown conversion workflow has been **deprecated**. All v2 content is written directly in Markdown — no Pandoc or similar tools are needed.
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
- [File Structure](#file-structure)
|
||
- [Custom Syntax](#custom-syntax)
|
||
- [Figure Guidelines](#figure-guidelines)
|
||
- [Table Guidelines](#table-guidelines)
|
||
- [Code Block Guidelines](#code-block-guidelines)
|
||
- [References](#references)
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
- Each chapter corresponds to a `v2/en_chapters/<nn>_chapter_<name>/` directory (e.g., `02_chapter_programming_and_graph/`)
|
||
- The chapter entry file is `index.md`; section content goes in separate `.md` files in the same directory
|
||
- Declare the section structure in `index.md` using a `toc` block (used to auto-generate `SUMMARY.md`):
|
||
|
||
```markdown
|
||
```toc
|
||
:maxdepth: 2
|
||
|
||
section_one
|
||
section_two
|
||
```
|
||
```
|
||
|
||
---
|
||
|
||
## Custom Syntax
|
||
|
||
The project preprocessor supports the following extended Markdown syntax. **Follow it strictly** to ensure a correct build.
|
||
|
||
### Inline Math
|
||
|
||
```markdown
|
||
The model learns the mapping $f: \mathcal{X} \rightarrow \mathcal{Y}$.
|
||
```
|
||
|
||
### Display Math with Label
|
||
|
||
Label names should include a language suffix (e.g., `-en`) to avoid conflicts with Chinese labels:
|
||
|
||
```markdown
|
||
$$
|
||
\mathcal{L}_{CE} = -\sum_{i=1}^{N} y_i \log(\hat{y}_i)
|
||
$$
|
||
:eqlabel:`eq-cross-entropy-en`
|
||
```
|
||
|
||
Reference an equation: `:eqref:`eq-cross-entropy-en``
|
||
|
||
### Figures with Labels
|
||
|
||
```markdown
|
||
|
||
:width:`600px`
|
||
:label:`figure-label-en`
|
||
```
|
||
|
||
Reference a figure: `:numref:`figure-label-en``
|
||
|
||
### Section References
|
||
|
||
Add a label after a section heading:
|
||
|
||
```markdown
|
||
### Section Title
|
||
:label:`my-section-en`
|
||
```
|
||
|
||
Reference the section: `:ref:`my-section-en``
|
||
|
||
### Citations
|
||
|
||
```markdown
|
||
The perceptron :cite:`rosenblatt1958perceptron` is one of the earliest neural network models.
|
||
```
|
||
|
||
Multiple citations separated by commas: `:cite:`paper1,paper2``
|
||
|
||
All bibliography entries are maintained in `mlsys.bib` (see [References](#references)).
|
||
|
||
---
|
||
|
||
## Figure Guidelines
|
||
|
||
### Storage Location
|
||
|
||
Store figures under `img/ch<chapter-number>/`, e.g., `img/ch01/`. Image files must be committed together with the PR.
|
||
|
||
### Naming
|
||
|
||
Use lowercase English with hyphens, e.g., `framework-architecture.png`.
|
||
|
||
### Format
|
||
|
||
| Format | Use case |
|
||
|--------|---------|
|
||
| SVG | Hand-drawn diagrams and flowcharts (vector, lossless scaling); remove white background |
|
||
| PNG | Screenshots, photos, or images with complex gradients |
|
||
|
||
Recommended tools:
|
||
|
||
- **[Excalidraw MCP](https://github.com/excalidraw/excalidraw-mcp)** — Official Excalidraw MCP server for AI-assisted diagram creation (remote: `https://mcp.excalidraw.com`)
|
||
- **[interactive-drawer](https://github.com/anyin233/interactive-drawer)** — Self-hosted Excalidraw MCP with session management
|
||
- **PPT** — PowerPoint, see [Pic-Instruction/](Pic-Instruction/) for templates
|
||
- **draw.io** — Free online diagramming tool
|
||
|
||
**Do not use images from the internet** (copyright risk).
|
||
|
||
### Resolution and Size
|
||
|
||
- Recommended resolution: ≥ 150 dpi
|
||
- Maximum width: 1200 px
|
||
- Set display width in Markdown via `:width:` (600–800 px recommended)
|
||
|
||
### Layout
|
||
|
||
Include sufficient explanatory text between adjacent figures. Do not place figures immediately next to each other.
|
||
|
||
---
|
||
|
||
## Table Guidelines
|
||
|
||
Use standard Markdown table syntax. Add a label to any table that needs to be referenced:
|
||
|
||
```markdown
|
||
| Column 1 | Column 2 | Column 3 |
|
||
|----------|----------|----------|
|
||
| Value 1 | Value 2 | Value 3 |
|
||
:label:`table-label-en`
|
||
```
|
||
|
||
Reference a table: `:numref:`table-label-en``
|
||
|
||
---
|
||
|
||
## Code Block Guidelines
|
||
|
||
Use standard Markdown fenced code blocks and always specify the language:
|
||
|
||
````markdown
|
||
```python
|
||
import torch
|
||
import torch.nn as nn
|
||
```
|
||
````
|
||
|
||
Common language identifiers: `python`, `bash`, `cpp`, `markdown`, `text`.
|
||
|
||
---
|
||
|
||
## References
|
||
|
||
Add BibTeX entries to `mlsys.bib`:
|
||
|
||
```bibtex
|
||
@inproceedings{key2015,
|
||
title = {Title of the Paper},
|
||
author = {Author, A. and Author, B.},
|
||
year = {2015}
|
||
}
|
||
```
|
||
|
||
**Note:** Duplicate keys in `mlsys.bib` are not allowed. Search for existing entries before adding a new one.
|
||
|
||
Example citations in body text:
|
||
|
||
```markdown
|
||
This chapter references the paper :cite:`cnn2015`.
|
||
Multiple citations: :cite:`cnn2015,rnn2015`.
|
||
```
|