diff --git a/README.md b/README.md index a7c5a6a..7e327d4 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,7 @@ crate cannot infer: - [Errors and tolerances](docs/design/errors.md) - [Layer boundaries](docs/design/layers.md) - [Parallelism](docs/design/parallel.md) +- [Glossary and formula conventions](docs/design/glossary.md) - [The simulation layer](docs/design/sim.md) ## Licence diff --git a/README.zh.md b/README.zh.md index d329ba1..290fe23 100644 --- a/README.zh.md +++ b/README.zh.md @@ -110,3 +110,7 @@ cargo run --release -p apsis-rs --features full --example bench_parallel ## 许可 MIT OR Apache-2.0，见 `LICENSE-MIT` 与 `LICENSE-APACHE`。 + +## 术语 + +- [术语与公式约定](docs/design/glossary.zh.md) diff --git a/docs/design/README.md b/docs/design/README.md index 71a0e32..4b5be62 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -20,3 +20,4 @@ public standard. ## Per-layer design - [The simulation layer](sim.md) +- [Glossary and formula conventions](glossary.md) diff --git a/docs/design/README.zh.md b/docs/design/README.zh.md index 41c598d..60d896c 100644 --- a/docs/design/README.zh.md +++ b/docs/design/README.zh.md @@ -17,3 +17,4 @@ ## 各层设计 - [仿真层](sim.md) +- [术语与公式约定](glossary.zh.md) diff --git a/docs/design/glossary.md b/docs/design/glossary.md new file mode 100644 index 0000000..f0a2285 --- /dev/null +++ b/docs/design/glossary.md @@ -0,0 +1,141 @@ +# Glossary and formula conventions + +English | [简体中文](./glossary.zh.md) + +This file fixes how a technical term is rendered in a comment and how a +formula is written. Follow it when translating a comment. + +## The principle + +**A term with an established Chinese name uses that name in the Chinese +paragraph.** The vocabulary of the field already has one, so the Chinese +paragraph uses it directly and does not append the English each time. The +English paragraph is unchanged, and the two sit side by side, so a reader may +read either. + +**A proper name, an abbreviation, a person's name, a model or a method keeps +its English form.** Those appear in the original sources only, the ITU-R +recommendations, the NASA orbital mechanics literature and the Rust standard +library, and translating them would leave a reader unable to find the source. + +## Terms that keep their English form + +| English | Kind | Notes | +| --- | --- | --- | +| SGP4, SDP4 | model | the orbit propagators | +| Hermite | name | the interpolation polynomial | +| Walker | name | the constellation pattern | +| Newton | name | the iteration | +| Runge-Kutta | name | the integrator | +| Vandermonde | name | the interpolation matrix | +| Hohmann | name | the transfer orbit | +| TLE, BSTAR | format and field | the element set and one of its fields | +| ECI, ECEF, TEME, ITRF, GCRS, ERA, GAST | abbreviation | frames and Earth rotation quantities | +| Isp, TAI, UTC, UT1, MJD, JD | abbreviation | specific impulse and time scales | +| TUMIN, XKE, X2O3 | symbol | internal model quantities | +| EIRP, C/N0 | abbreviation | link figures | +| delta-v | idiomatic | velocity increment, also written Δv in Chinese | + +These stay as they are in the Chinese paragraph too. + +## Terms that use their standard Chinese name + +The Chinese paragraph uses the Chinese directly, with no English appended: + +| English | Chinese | +| --- | --- | +| semi-major axis | 半长轴 | +| semi-minor axis | 半短轴 | +| semi-latus rectum | 半通径 | +| eccentricity | 偏心率 | +| perigee | 近地点 | +| apogee | 远地点 | +| true anomaly | 真近点角 | +| mean anomaly | 平近点角 | +| eccentric anomaly | 偏近点角 | +| right ascension | 赤经 | +| argument of perigee | 近地点幅角 | +| inclination | 倾角 | +| ascending node | 升交点 | +| osculating | 密切 | +| element set | 根数集 | +| two-line element | 两线根数集 | +| epoch | 历元 | +| ephemeris | 星历 | +| drag term | 阻力项 | +| perturbation | 摄动 | +| deep space | 深空 | +| resonance | 共振 | +| nodal | 交点 | +| zenith | 天顶 | +| nadir | 天底 | +| sub-satellite point | 星下点 | +| footprint | 覆盖区 | +| mask | 遮蔽角 | +| elevation | 仰角 | +| azimuth | 方位角 | +| central angle | 地心角 | +| slant range | 斜距 | +| path loss | 路径损耗 | +| attenuation | 衰减 | +| specific attenuation | 比衰减 | +| rain rate | 降雨率 | +| cross-section | 截面 | +| noise temperature | 噪声温度 | +| noise figure | 噪声系数 | +| signal to noise ratio | 信噪比 | +| free space path loss | 自由空间路径损耗 | +| specific impulse | 比冲 | +| exhaust velocity | 喷气速度 | +| propellant | 推进剂 | +| precession | 岁差 | +| nutation | 章动 | +| equinox | 分点 | +| Earth rotation angle | 地球自转角 | +| Modified Julian Date | 修正儒略日 | +| leap second | 闰秒 | +| assumed decimal point | 隐含小数点 | +| two digit year | 两位数年份 | +| checksum | 校验和 | +| scenario | 场景 | +| precedence | 优先约束 | +| placement | 放置 | +| candidate | 候选 | +| boundary | 边界 | +| invariant | 不变量 | +| reachability | 可达性 | +| shortest path | 最短路 | +| mutual visibility | 互见 | +| blocking | 遮挡 | +| cross-check | 对拍 | +| capacity | 容量 | +| demand | 需求 | +| window | 窗口 | +| availability | 可用性 | +| precedence graph | 优先关系图 | + +## Formulas + +- A formula is kept as it stands: not rewritten, not simplified, not completed. +- A formula in a comment must agree with the code. Changing the code means + changing the comment in the same edit. +- A variable, function, field or module name keeps its English form. +- An inline formula is written as code, `` `a (1 - e^2)` ``. A formula that + needs several lines goes in a `/// ```text` block. +- A unit goes in parentheses after the quantity, as in `半长轴，单位为千米`. + +## The layout of a comment + +The English and the Chinese of one passage are separated by an empty `///` +line, English first: + +```rust +/// Returns the phase offset applied between adjacent planes, in radians. +/// +/// This is `f * 360 / t` degrees, where `f` is the phase factor and `t` +/// the total satellite count. +/// +/// 返回相邻轨道面之间施加的相位偏移，单位为弧度。 +/// +/// 即 `f * 360 / t` 度，其中 `f` 为相位因子，`t` 为卫星总数。 +``` diff --git a/docs/design/glossary.zh.md b/docs/design/glossary.zh.md new file mode 100644 index 0000000..993c249 --- /dev/null +++ b/docs/design/glossary.zh.md @@ -0,0 +1,134 @@ +# 术语与公式约定 / Glossary and formula conventions + +[English](./glossary.md) | [简体中文](./glossary.zh.md) + +本文件规定代码注释与文档中专业术语的译法，以及公式的写法。翻译注释时以此 +为准。 + +## 原则 + +**中文段落里，术语一律用标准中文名。** 领域内已有约定俗成译法的词，直接 +译，不逐次附英文。英文段落保持原文，两段并列，读者可任选一种阅读。 + +**专有名称、缩写、人名、模型名、方法名保留英文。** 这些词在原始资料 +（ITU-R 建议书、NASA 轨道力学文献、Rust 标准库）中只有英文形式，译成中文 +会让读者无法检索到出处。 + +## 保留英文的词 + +| 英文 | 类别 | 说明 | +| --- | --- | --- | +| SGP4、SDP4 | 模型名 | 轨道传播模型 | +| Hermite | 人名 | 插值多项式 | +| Walker | 人名 | 星座构型 | +| Newton | 人名 | 迭代方法 | +| Runge-Kutta | 人名 | 积分方法 | +| Vandermonde | 人名 | 插值矩阵 | +| Hohmann | 人名 | 转移轨道 | +| TLE、BSTAR | 格式与字段名 | 两线根数集及其字段 | +| ECI、ECEF、TEME、ITRF、GCRS、ERA、GAST | 缩写 | 坐标系与地球自转量 | +| Isp、TAI、UTC、UT1、MJD、JD | 缩写 | 比冲与时间尺度 | +| TUMIN、XKE、X2O3 | 符号 | 模型内部量 | +| EIRP、C/N0 | 缩写 | 链路指标 | +| delta-v | 惯用写法 | 速度增量，中文亦常写 Δv | + +以上在中文段落中同样原样保留。 + +## 采用标准中文名的词 + +以下在中文段落中直接使用中文，不附英文： + +| 英文 | 中文 | +| --- | --- | +| semi-major axis | 半长轴 | +| semi-minor axis | 半短轴 | +| semi-latus rectum | 半通径 | +| eccentricity | 偏心率 | +| perigee | 近地点 | +| apogee | 远地点 | +| true anomaly | 真近点角 | +| mean anomaly | 平近点角 | +| eccentric anomaly | 偏近点角 | +| right ascension | 赤经 | +| argument of perigee | 近地点幅角 | +| inclination | 倾角 | +| ascending node | 升交点 | +| osculating | 密切 | +| element set | 根数集 | +| two-line element | 两线根数集 | +| epoch | 历元 | +| ephemeris | 星历 | +| drag term | 阻力项 | +| perturbation | 摄动 | +| deep space | 深空 | +| resonance | 共振 | +| nodal | 交点 | +| zenith | 天顶 | +| nadir | 天底 | +| sub-satellite point | 星下点 | +| footprint | 覆盖区 | +| mask | 遮蔽角 | +| elevation | 仰角 | +| azimuth | 方位角 | +| central angle | 地心角 | +| slant range | 斜距 | +| path loss | 路径损耗 | +| attenuation | 衰减 | +| specific attenuation | 比衰减 | +| rain rate | 降雨率 | +| cross-section | 截面 | +| noise temperature | 噪声温度 | +| noise figure | 噪声系数 | +| signal to noise ratio | 信噪比 | +| free space path loss | 自由空间路径损耗 | +| specific impulse | 比冲 | +| exhaust velocity | 喷气速度 | +| propellant | 推进剂 | +| precession | 岁差 | +| nutation | 章动 | +| equinox | 分点 | +| Earth rotation angle | 地球自转角 | +| Modified Julian Date | 修正儒略日 | +| leap second | 闰秒 | +| assumed decimal point | 隐含小数点 | +| two digit year | 两位数年份 | +| checksum | 校验和 | +| scenario | 场景 | +| precedence | 优先约束 | +| placement | 放置 | +| candidate | 候选 | +| boundary | 边界 | +| invariant | 不变量 | +| reachability | 可达性 | +| shortest path | 最短路 | +| mutual visibility | 互见 | +| blocking | 遮挡 | +| cross-check | 对拍 | +| capacity | 容量 | +| demand | 需求 | +| window | 窗口 | +| availability | 可用性 | +| precedence graph | 优先关系图 | + +## 公式 + +- 公式原样保留，不改写、不化简、不补全。 +- 注释中出现的公式必须与实现一致。改动代码时同步改注释。 +- 变量名、函数名、字段名、模块名一律保持英文原样。 +- 行内公式写作 `` `a (1 - e^2)` `` 这样的代码样式；多行公式用 `/// ```text` 代码块。 +- 单位写在括号里，例如 `半长轴，单位为千米`。 + +## 注释的排版 + +同一段说明的英文与中文之间用一个空的 `///` 行分隔，英文在上： + +```rust +/// Returns the phase offset applied between adjacent planes, in radians. +/// +/// This is `f * 360 / t` degrees, where `f` is the phase factor and `t` +/// the total satellite count. +/// +/// 返回相邻轨道面之间施加的相位偏移，单位为弧度。 +/// +/// 即 `f * 360 / t` 度，其中 `f` 为相位因子，`t` 为卫星总数。 +```