# Dagor 文档风格指南

## 关于本指南

本风格指南概述了为软件开发人员和其他技术专业人员创建清晰、一致和准确的技术文档的编辑准则。它旨在确保与 Dagor Engine 相关的所有文档的一致性。

本指南是创建 Dagor Engine 文档的主要参考。如果此处提供的指南未涵盖特定场景，请参阅以下编辑资源：

- **拼写:**	[Merriam-Webster](https://www.merriam-webster.com/).
- **非技术风格:** [*The Chicago Manual of Style Online*](https://www.chicagomanualofstyle.org/home.html).
- **技术风格:** [Google developer documentation style guide](https://developers.google.com/style).

## 语音和语气

采用专业但平易近人的声音和语气——清晰、尊重、没有俚语或过度非正式。目标是听起来像一个知识渊博的导游，他了解开发人员的需求，提供有用的见解，而不会过于正式或居高临下。

虽然鼓励使用对话语气，但请避免完全按照你所说的方式写作。
在清晰度和相关性之间取得平衡，以保持内容的吸引力和重点。

避免过度娱乐或过度干燥。文档的主要目的是将信息有效地传达给可能在时间限制下寻求答案的读者。

请记住，受众可能包括来自不同文化背景和不同英语熟练程度的读者。使用简单、一致的语言写作可以提高可读性，并有助于更轻松地翻译成其他语言。

## 单词表

**3ds Max**
: 始终将 *Max* 大写。

**add-on (noun or adjective), add on (verb)**
: 不是 *addon*.

**Asset Viewer**
: 将每个单词大写。

**assetViewer{}**

**Blender**
: 始终大写。

**BLK 格式**
: 当一般引用格式时。

**`.blk` 文件**
: 引用 BLK 格式的特定文件时。文件扩展名使用 [代码字体](#code-font) 进行格式设置.

**Building Resources**
: 在提到标题或标题时使用 *Building Resources*，在描述编译资源的行为时使用 *resource building process* （或类似）。

**button**
: 你 *点击* 屏幕上的按钮和鼠标按钮，然后 *按下* 键盘上的键。

**checkbox**
: 使用 *check*/*uncheck* 进行清除和特定的复选框作。

  {octicon}`check;1.4em` 选中 **Enable Ray Tracing（启用光线追踪）** 框以激活场景中的高级光照效果。

  {octicon}`check;1.4em` 取消选中 **Enable Shadows** 框以禁用阴影渲染并提高性能。

  通过阐明复选框的效果来避免歧义。

  {octicon}`check;1.4em` 选中 **动态光照** 框以在游戏过程中应用实时光照更改。

  {octicon}`x;1.4em` 启用动态照明的框。（不清楚：“启用盒子”是什么意思？它是打开该功能还是只是使复选框可切换？

**daBuild**

**daEditor**

**Dagor Engine**
: 将每个单词大写。

**daNetGame**

**daNetGame-based, daNetGame-like**

**dynmodel**
: 小写，句子、标题或列表项的开头除外。

**ECS**
: 全部大写。首次提及时展开缩写。

**FAR**
: 全部大写。

**gameobj**
: 小写，句子、标题或列表项的开头除外。

**ID**
: 不是 *Id* 或 *id*，字符串文字或枚举除外。

**Impostor Baker**
: 将每个单词大写。

**in-game (adjective)**
:不是 *in game*。

**internet**
: 小写，句子、标题或列表项的开头除外。

**LOD, LODs**
: 全部大写。首次提及时展开缩写。

**login (noun or adjective), log in (verb)**
: 不是 *登录*。

**microdetails**
: 不是 *micro-details*。小写，句子、标题或列表项的开头除外。

**parent-child or parent/child**
: 不是 *parent – child* 或 *parent—child*.

**per**
: 要表示速率，请使用 *per* 而不是除法斜杠 (`/`).

**please**
: 请勿在解释如何使用产品的正常过程中使用 *please*。

  仅在您请求许可或宽恕时使用 *please*。例如，当您要求的内容给读者带来不便，或暗示产品存在潜在问题时。

**plugin (noun), plug-in (adjective), plug in (verb)**

**pop-up window**, **pop-up menu**,
: 使用 *弹出窗口* 来描述出现在主界面上的窗口，以提供其他信息、请求输入或显示通知。

  使用 *pop-up menu* 来描述用户右键单击某个项目时出现的菜单。

**prebuilt**
: 不是 *pre-built*.

**prefab**
: 小写，句子、标题或列表项的开头除外。

**read-only**
: 不是 *read only*.

**rendinst**
: 小写，句子、标题或列表项的开头除外。

**screenshot**
: 不是 *screen shot*.

**sign-in (noun or adjective), sign in (verb)**

**sign-out (noun or adjective), sign out (verb)**

**subdirectory**
: 不是 *sub-directory*.

**toolkit**
: 不是 *tool-kit* 或 *tool kit*.

**utilize**
: 当你的意思是 *use* 时，不要使用 *utilize*。

  在引用正在使用的资源数量时使用 *utilize* 或 *utilization*。

**vromfs**
: 小写，句子、标题或列表项的开头除外。

**War Thunder**
: 将每个单词大写。

**War Thunder-based, War Thunder-like**
: 不是 *WarThunder-based* 或 *War-Thunder-based*.

## 产品名称

本节介绍如何使用产品名称。

- **将产品名称大写**。当您撰写有关任何产品的文章时，请遵循品牌、公司、软件、产品、服务、功能以及公司和开源社区定义的术语的官方大写。如果正式名称以小写字母开头，则即使在句子的开头也要用小写。但是，如果可能的话，最好修改句子以避免在开头放置小写单词。

- **功能名称**。当您撰写有关功能的内容时，除非名称正式大写，否则不要将其大写。如果您不确定，请遵循描述该功能的其他文档所设定的先例。

- **缩短产品名称**。使用完整的商标产品名称。不要缩写产品名称，除非你匹配 UI 标签。

- **将 *the* 与产品名称一起使用。** 在引用特定实例、角色或修改的版本时，将 *the* 与产品名称一起使用。当名称用作独立的专有名词或出现在品牌中时，请避免使用 *the*。

  ```{seealso}
  有关更多信息，请参阅 [使用 *The*](#use-the).
  ```

## 文本格式

文本格式摘要，了解样式指南中其他位置介绍的许多一般约定。

### 粗体

对于 UI 元素、插入标题，以及在特殊情况下，使用粗体格式来强调句子中的重要短语。

### 斜体

在引起对特定单词或短语的注意时（例如，在定义术语或将单词用作单词时），请使用斜体格式。

### 下划线

不要下划线。

### 代码字体

将代码字体用于：

- 文件名、文件扩展名和路径
- 文件夹和目录
- 参数名称和值
- 占位符变量
- 文本输入
- 控制台输出
- 键名称和鼠标按钮标签
- 文本中的代码、内联代码和代码示例

**要放入普通（非代码）字体的项目:**

- IP 地址
- 网址
- 域名
- 产品、服务和组织的名称

### 字体类型、大小和颜色

- 不要覆盖字体类型、大小或颜色的全局样式。
- 仅当它是阐明概念的最有效方法时，才在示例中使用不同的文本颜色。

### 其他标点符号约定

- 不要使用 & 符号 （`&`） 作为 *and* 的连词或简写。请改用 *and*。
- 在需要引用 UI 元素或使用 `&` 的名称时，请使用 `&`。
- 请勿使用感叹号。

### 计量单位

- 在数字和单位之间放置一个不间断的空格` `。

  {octicon}`check;1.4em` 120 GB

  {octicon}`x;1.4em` 120GB

  {octicon}`check;1.4em` 5 m

  {octicon}`x;1.4em` 5m

- 如果度量单位是 money 或 percent 或 degrees of an angle，请不要使用空格。

  {octicon}`check;1.4em` $20

  {octicon}`check;1.4em` 50%

  {octicon}`check;1.4em` 90°

- 在数字范围内，为每个数字重复该单位。在数字之间使用单词 *to*，而不是连字符。

  {octicon}`check;1.4em` 0° to 90°

  {octicon}`x;1.4em` 0-90°

  {octicon}`check;1.4em` 5 m to 10 m

  {octicon}`x;1.4em` 5-10 m

### 标题

- 每个文件应包含一个主题文章。
- 文章可以有一个顶级标题，后续标题应遵循顺序，不要跳过任何级别。
- 如果文章的主标题是使用其他工具定义的，则文件中的章节标题应从第二级开始。

### 大写

遵循美式英语的标准大小写规则。此外，请执行以下作：

- 不要使用不必要的大写。
- 请勿使用全大写，除非在以下上下文中：在官方名称中，在始终以全大写形式编写的缩写中，或者引用使用全大写的代码时。
- 请勿使用 Camel Case，除非在官方名称中或引用使用 Camel Case 的代码。

  ```{seealso}
  有关如何将特定单词大写的信息，请参阅 [单词列表](#word-list).
  ```

#### 将商品名称大写

```{seealso}
有关如何将产品名称大写的更多信息，请参阅 [产品名称](#product-names)。
```

#### 标题和标题的大小写

- 在文档标题和标题中，使用 **title case**。也就是说，将标题的第一个和最后一个单词以及所有主要单词（如名词、代词、动词、形容词、副词和专有名词）大写。
- 少于四个字母的冠词（*a*、*an*、*the*）、连词（*and*、*but*、*or*）和介词不大写，除非它们作为标题的第一个或最后一个单词出现。

#### 引用标题和标题时的大小写

- 在引用遵循本指南的文档中的任何标题或标题时，请使用 **title case**。
- 对于未遵循本指南的作品或来源的标题或标题，请保留原始大小写。

#### 数字和表格的大小写

- 对图像和图表中的标签、标注和其他文本使用 **句子大小写**。
- 对表中的所有元素使用 **句子大小写** ：内容、标题、标签和标题。

#### 大写和结尾标点符号

##### 编号列表、字母列表和项目符号列表

每个列表项都以大写字母开头，除非大小写是列表所传达信息的重要组成部分。

每个列表项都用句点结束，但以下情况除外：

- 如果项目由单个单词组成。
- 如果项目不包含动词。
- 如果项目完全采用代码字体。
- 如果项目完全是链接文本或文档标题。

{octicon}`check;1.4em` 推荐：

该界面分为三个主要面板：
1. 控制面板
2. 属性面板
3. 视口设置面板

{octicon}`check;1.4em` 推荐：

要导出动画，请执行以下步骤：
1. 确保可见性。
2. 导出设置。
3. 添加 Note Tracks。

{octicon}`check;1.4em` 推荐：

环境纹理：
- envi 快照
- 背景纹理
- 绘制细节纹理
- 反射纹理

##### 使用插入标题的描述列表

- 以大写字母开始 run-in 标题。
- 以句点或冒号结束 run-in 标题，但在列表中保持一致。
- 您可以根据页面一致性等因素决定是否将结束标题的标点符号加粗。
- 对于标点符号后面的描述，请将第一个字母大写，如下所示：
  + 如果文本后跟句点，则以大写字母开始文本。
  + 如果文本后跟冒号，则以小写字母开头。
- 要结束描述性文本，请按如下方式添加标点符号：
  + 如果描述后跟句点，则以句点结束描述。
  + 如果描述后跟冒号，请执行以下任一作：
    - 如果描述是项目列表或没有动词的短短语，请不要包含句点。
    - 如果描述包含动词或表达独立思想，请以句点结束描述。
- 请勿使用破折号来衬托描述列表中的项的描述。

{octicon}`check;1.4em` 推荐:

此属性定义对象如何与地形碰撞交互：
- **Ignore Collision:** 对象的 Height 与其 Pivot Point 匹配。
- **Place Pivot:** 枢轴点直接放置在碰撞曲面上。
- **Place Pivot and Use Normal:** 对象的轴与景观的法线对齐。
- **Place 3-Point (bbox)**: 将在对象周围创建一个边界框。
- **Place Foundation (bbox):** 边界框基体的所有点都与碰撞表面对齐。

{octicon}`check;1.4em` 推荐：

有三种类型的 builds：
- **Full Build.** 构建所有资源。
- **Partial Pack Build.** 构建包含所需资源的特定包。
- **Partial Package Build.** 构建整个包。

#### 带连字符的单词中的大写

将标题和标题中带连字符的术语中的所有主要单词大写。

{octicon}`check;1.4em` 高级体系结构概述

{octicon}`x;1.4em` 高级体系结构概述

**例外:**

- **带连字符的单词带前缀：** 不要将带连字符的单词中的前缀大写，除非它们以标题或标题开头。

  {octicon}`check;1.4em` 重新评估系统流程

  {octicon}`x;1.4em` 重新评估系统流程

- **以单个字母开头的带连字符的单词：** 不要将带连字符的术语开头的单个字母大写，除非它以标题或标题开头。

  {octicon}`check;1.4em` X 射线分析结果

  {octicon}`x;1.4em` X 射线分析结果

- **带连字符的冠词、介词和并列连词：** 不要将带连字符的冠词、介词或并列连词大写，除非它们在标题或标题开始。

  {octicon}`check;1.4em` 端到端加密设置

  {octicon}`x;1.4em` 端到端加密设置

#### 大小写和冒号

使用小写字母将文本的第一个单词紧跟在冒号后面，除非文本属于例外情况之一。

{octicon}`check;1.4em` 系统分三个阶段处理数据：输入、处理和输出。

{octicon}`x;1.4em` 系统分三个阶段处理数据：输入、处理和输出。

**例外：**

- **专有名词：** 如果第一个单词是专有名词，则将其大写。
- **标题：** 如果冒号后面的文本是标题，则将第一个单词大写。
- **引用：** 如果冒号后面的文本是引用，则将第一个单词大写。

## 语言

### 缩略语

#### 缩写使用的关键准则

- 使用标准首字母缩略词，以提高可读性并节省读者时间。
- 在第一次引用时拼写出缩写。
- 避免使用受众可能不熟悉的专业缩写，除非它们有明确定义。

#### 何时拼写术语

- 当读者可能不熟悉某个缩写时，请在第一次提及时将其拼写出来，并在紧接着将缩写括在括号中。将拼写的术语及其缩写都*斜体化*。
- 对于该术语的所有后续提及，请仅使用缩写。
- 将直接以缩写形式使用的字母大写。
- 如果第一次提到缩写出现在标题或标题中，则可以直接使用缩写。然后，在标题后的第一段中拼写并定义缩写。

  {octicon}`check;1.4em` 细节级别 （LOD）

  {octicon}`check;1.4em` 图形用户界面 (GUI)

  {octicon}`check;1.4em` 可扩展标记语言 （XML）

#### 普遍接受的缩写

以下缩写是公认的，通常不需要拼写出来：

- API
- LOD
- FPS
- 文件格式，如 PNG、JPEG 或 OBJ
- 度量单位，如 MB、GB 或 TB
- URL
- GPU, CPU, RAM

### 文章

#### 使用 *The*

在文档中将 *the* 与产品名称一起使用取决于产品名称是被视为专有名词还是通用名词短语。

##### 何时使用 *The*

- **通用引用**。在引用产品的特定实例、功能或角色时使用 *the*。

  {octicon}`check;1.4em` Dagor Engine 渲染器支持高级实时照明技术。

- **功能上下文**。在描述产品在特定场景中的功能或交互方式时，请使用 *the*。

  {octicon}`check;1.4em` Dagor 引擎物理模块擅长模拟大规模可破坏环境。

- **With Modifiers**. 当产品名称由形容词、子句或描述性元素修饰时，使用 *the*。

  {octicon}`check;1.4em` 增强的 Dagor Engine API 简化了着色器开发。

##### 何时不使用 *the*

- 作为独立的专有名词。当产品名称单独作为专有名词时，请避免使用 *the*。

  {octicon}`check;1.4em` Dagor Engine 与自定义资产管道无缝集成。

- **在品牌或标题中**。当商品名称出现在商品名称或品牌词中时，请勿使用 *the*。

  {octicon}`check;1.4em` 探索 Dagor Engine 6 的新可能性。

**例外：**

- 由于品牌或既定用法，某些产品名称可能本身包含 *the*。
- 在列表或一般概述中，为了简洁起见，省略 *the* 是可以接受的：

  {octicon}`check;1.4em` 功能包括 GPU 驱动的渲染、多线程处理和地形优化。