You've already forked UnrealEngineUWP
mirror of
https://github.com/izzy2lost/UnrealEngineUWP.git
synced 2026-03-26 18:15:20 -07:00
346 lines
13 KiB
Plaintext
346 lines
13 KiB
Plaintext
INTSourceChangelist:3108692
|
||
Availability:Docs
|
||
Title:Epic Games文档风格指南
|
||
Crumbs:DocumentationGuidelines
|
||
Description:为虚幻引擎4创建文档的风格指南。
|
||
|
||
[TOC(start:2)]
|
||
|
||
(#documentationpolicies)
|
||
## 文档策略
|
||
|
||
(#documentlocationandnaming)
|
||
### 文档位置和命名
|
||
|
||
文档源文件作为.udn文件存储在Perforce中的Engine/Documentation/Source文件夹中。文件名必须包含一个语言代码，指定用来编写文档的语言。文件名应当是对文档内容的描述。
|
||
文档的存储方式是每个文件一个文件夹，这样文档的目录路径更具辨识度。在命名文件夹时务必谨慎，名称应当含义明确，清楚直观。尽量不要在文件夹名称中使用重复元素来构成路径。实际文档名称重复是可以接受的，而且通常倾向于使用重复名称。
|
||
|
||
| 好示例 | 差示例 |
|
||
| --- | --- |
|
||
| Materials/Editor/UserGuide | Materials/MaterialEditor/MaterialEditorUserGuide |
|
||
|
||
例如，英语版本的 **虚幻编辑器用户指南** 文档命名为`UnrealEditorUserGuide.INT.udn`，并存储在`Editor/UserGuide`目录中。
|
||
|
||
同样，仅可能避免页面标题冗长繁琐。例如，想象一个 **开始** 部分，其中包含一个 **内容** 部分，后者又包含一个 **材质** 页面。其中每一个页面最后可能都采用如下命名：
|
||
|
||
* 开始虚幻引擎之旅
|
||
* 开始内容开发之旅
|
||
* 开始材质创建之旅
|
||
|
||
|
||
这些名称完全没有问题，但并排查看就显得冗长。这尤其是在页面顶部以面包屑形式显示时，这些名字会连续显示，这个问题就尤为明显。如果在名称中使用多种变化会更加有用，这样名称仍能描述页面内容，但彼此对比起来不会显得冗余。
|
||
|
||
(#contentchunking)
|
||
### 内容分块
|
||
|
||
大家往往容易在一页中塞入过多的内容。最好将内容按照逻辑划分成多个块，让各个页面保持合理大小，便于理解。
|
||
|
||
比如，动画中的_混合空间_主题。关于_混合空间_的所有内容都可以放在一页当中，如创建、在Vim蓝图中使用等，但最好将这些子主题拆分成独立页面，并以一般概述页面作为其父级：
|
||
|
||
* 混合空间
|
||
* 创建混合空间
|
||
* 编辑混合空间
|
||
* 使用混合空间
|
||
|
||
|
||
(#identityandbranding)
|
||
### 身份和品牌
|
||
|
||
公司、引擎、游戏等名称应当在所有文档中保持一致。下文提供了这些名称的正确拼写、大小写、编号和标点。
|
||
|
||
* Epic Games, Inc.
|
||
* 虚幻引擎3/虚幻引擎4
|
||
* 战争机器/战争机器2/战争机器3
|
||
* 无尽之剑/无尽之剑2/无尽之剑3
|
||
* 堡垒之夜
|
||
|
||
|
||
[REGION:note]
|
||
在页面上定义后仅使用简短名称（UE3/UE4/GoW/IBD），如虚幻引擎4（UE4）。
|
||
[/REGION]
|
||
|
||
(#types)
|
||
### 类型
|
||
|
||
在讨论数据类型——类名、资源类型等——时，始终使用正确的大小写来匹配类型定义。这有助于区分虚幻引擎中的特定类型和某些词语的泛指使用。此外，让这些名称使用斜体来表示它们是有特殊意义的。
|
||
|
||
例如：
|
||
|
||
| 正确 | 不正确 |
|
||
| ------- | --------- |
|
||
| _Actor_ | actor |
|
||
| _Material_ | material |
|
||
| _StaticMesh_或_Static Mesh_ | staticmesh或static mesh |
|
||
| _ParticleSystem_或_Particle System_ | particlesystem或particle system |
|
||
|
||
(#uielements)
|
||
### UI元素
|
||
|
||
用户界面的特定部分，如 **内容浏览器** 或 **场景大纲视图** 应使用适当的大小写，并显示为粗体。
|
||
|
||
[REGION:tip]
|
||
某些面板用名称加“面板”来指代，例如 **细节** 面板，但“面板”二字无需大写或加粗。这里唯一例外的情况是，在UI中显示“面板”作为窗口、面板或其他界面部分的一部分。
|
||
[/REGION]
|
||
|
||
| 正确 | 不正确 |
|
||
| ------- | --------- |
|
||
| **Content Browser** | Content Browser或 **content browser** |
|
||
| **Scene Outliner** | Scene outliner或 **scene outliner**
|
||
| **Details** panel | Details panel或 **Details Panel** |
|
||
|
||
(#grammarandpunctuation)
|
||
## 语法和标点
|
||
|
||
(#spacingbetweensentences)
|
||
### 句子间隔
|
||
|
||
连续句子之间只需要一个空格。
|
||
|
||
(#commaswithseries)
|
||
### 列举用逗号
|
||
|
||
用逗号分隔的一连串列举项始终在最后一项前面使用一个逗号。虽然严格来说可以省略最后一个逗号，但始终使用一个逗号有助于避免模棱两可，让读者不清楚这些项是独立的还是作为一个整体。
|
||
|
||
| 清楚明确 | 模棱两可 |
|
||
| --- | --- |
|
||
| This, that and those, them, and the other one | This, that and those, them and the other |
|
||
|
||
(#formattingandlayout)
|
||
## 格式和布局
|
||
|
||
(#metadata)
|
||
### 元数据
|
||
|
||
所有文档页面都必须有以下元数据：
|
||
|
||
* Title——文档的标题；显示在浏览器的标题栏中，作为1级页面标题。
|
||
* Crumbs——以逗号分隔的路径列表，形成导航层级。每个页面都有任意数量的Crumbs元数据条目。
|
||
* Description——简短摘要；显示在搜索结果页面上。元数据以key:value对形式存储在所有源文档顶部，一行一对。
|
||
|
||
|
||
(#headings)
|
||
### 标题
|
||
|
||
文档中的主要部分应当使用标题表示（2级到6级）。
|
||
|
||
标题后面应始终有一些文本或其他内容，但需放在任何副标题前面。如果标题不能具体指代内容，请考虑将其移除并重新组织。
|
||
|
||
不要在文档中跳过标题级别。例如，4级标题一定不可以紧跟在2级标题后面。
|
||
|
||
(#pagetitles)
|
||
#### 页面标题
|
||
|
||
页面标题会自动插入到页面中，始终使用1级标题表示。在任意文档中，都应该只有这一个1级标题。不要对文档中的其他部分使用1级标题。
|
||
|
||
(#capitalizationofheadings)
|
||
#### 标题大小写
|
||
|
||
在标题中，除了连词（and、or等）和介词（to、of、on等），其他单词都应该首字母大写。所有标题都采用相同的大小写方式，不同的标题级别采用正确的样式来加以区分。
|
||
|
||
(#lists)
|
||
### 列表
|
||
|
||
列表可以是有序列表、无序列表或定义列表。无序列表应始终用于顺序并不重要的项。教程等有顺序的说明应始终使用有序列表。定义特定术语应使用定义列表。
|
||
|
||
(#unorderedlists)
|
||
#### 无序列表
|
||
|
||
无序列表应始终使用“* ”语法定义。在查看存在列表的源代码时，就可以一目了然的看到这一点。
|
||
|
||
* 无序项目 1
|
||
* 无序项目 2
|
||
* 无序项目 3
|
||
* 无序项目 4
|
||
|
||
* 无序项目 1
|
||
* 无序项目 2
|
||
* 无序项目 3
|
||
* 无序项目 4
|
||
|
||
|
||
虽然使用“- ”或“+ ”语法对于创建列表是有效的，我们想要在所有文件档中保持统一。
|
||
|
||
(#orderedlists)
|
||
#### 有序列表
|
||
|
||
要创建有序列表，可以用任意数字后跟一个句点来作为一行的开头。按照1、2、3、4、5等对项目编号是很自然的做法；但是，有序列表中的每个项应始终使用“1.”语法创建。
|
||
|
||
1.第一项
|
||
1.第二项
|
||
1.第三项
|
||
1.第四项
|
||
|
||
1. 第一项
|
||
1. 第二项
|
||
1. 第三项
|
||
1. 第四项
|
||
|
||
|
||
这样便于插入和对项目重新排序，而不必担心编号问题。
|
||
|
||
(#definingitems)
|
||
#### 定义项目
|
||
|
||
在定义术语时，使用定义列表。
|
||
|
||
注意：对于属性、菜单选项、工具栏按钮等描述，应使用表格。详见“表格”部分。
|
||
|
||
(#texteffects)
|
||
### 文字效果
|
||
|
||
(#boldanditalics)
|
||
#### 加粗和斜体
|
||
|
||
粗体或加粗文本应始终使用“**”语法，相对应的是“__”版本：
|
||
|
||
**加粗文本**
|
||
|
||
粗体或强调文本应始终使用“_”语法，相对应的是“*”版本：
|
||
|
||
_强调文本_
|
||
|
||
在创建加粗斜体文本时，语法是“**_”和“_**”：
|
||
|
||
**_加粗强调文本_**
|
||
|
||
通过遵守这些约定，就可以清楚地表达作者的本意。在尝试创建粗体文本时很容易遗漏*或_，或者想要创建斜体文本时意外添加了两个**或__。如果我们知道使用**始终表示粗体，_始终表示斜体，那么不会对作者想要添加的格式存疑了。
|
||
|
||
(#notes,tips,warnings,andquotes)
|
||
### 注释、提示、警告和引用
|
||
|
||
以注释、提示或警告形式表示的特殊信息应当使用容器来与其他内容区分开来。使用注释、提示或警告类的`<div>`元素将自动创建一个有颜色的框和特殊图标，将`<div>`中的信息包裹起来。
|
||
|
||
(#note)
|
||
#### 注释
|
||
|
||
[REGION:note]
|
||
这是注释。它在黄色框中，您可以在左上角看到注释图标。
|
||
[/REGION]
|
||
|
||
[REGION:note]
|
||
这是注释。它在黄色框中，您可以在左上角看到注释图标。
|
||
[/REGION]
|
||
|
||
(#tip)
|
||
#### 提示
|
||
|
||
[REGION:tip]
|
||
这是提示。它在绿色框中，您可以在左上角看到提示图标。
|
||
[/REGION]
|
||
|
||
[REGION:tip]
|
||
这是提示。它在绿色框中，您可以在左上角看到提示图标。
|
||
[/REGION]
|
||
|
||
(#warning)
|
||
#### 警告
|
||
|
||
[REGION:warning]
|
||
这是警告。它在红色框中，您可以在左上角看到警告图标。
|
||
[/REGION]
|
||
|
||
[REGION:warning]
|
||
这是警告。它在红色框中，您可以在左上角看到警告图标。
|
||
[/REGION]
|
||
|
||
(#quote)
|
||
#### 引用
|
||
|
||
[REGION:quote]
|
||
这是引用文本。它在蓝色框中，您可以在左上角看到引用图标。
|
||
[/REGION]
|
||
|
||
[REGION:quote]
|
||
这是引用文本。它在蓝色框中，您可以在左上角看到引用图标。
|
||
[/REGION]
|
||
|
||
(#images)
|
||
### 图像
|
||
|
||
图像是指文档中显示的任何图形。
|
||
|
||
(#formatsandresolution)
|
||
#### 格式和分辨率
|
||
|
||
源图像尽可能使用PNG文件，因为此类文件质量较高，而且文件大小很合适。
|
||
按照将要显示的分辨率来创作图片。如果同一个图像要多次使用，
|
||
且每次使用分辨率不同，则以将会显示的最高分辨率创作。动态调节大小
|
||
通常结果的质量不如预期。
|
||
|
||
图像大小：
|
||
|
||
| 用途 | 最大图像宽度 |
|
||
| --- | -------------- |
|
||
| 标准 | 720像素 |
|
||
| 条幅 | 1180像素 |
|
||
| 材质网络、蓝图图表 | 无限制，但应该符合[lightboxing](#Lightboxing)要求。|
|
||
|
||
(#quality)
|
||
#### 质量
|
||
|
||
默认情况下，所有图像都会转换为jpeg并进行压缩。图像质量有时可能会在
|
||
压缩为jpeg时成为问题。可以使用[图像属性](DocumentationGuidelines/Syntax#ImageProperties)。
|
||
来控制压缩质量，甚至完全覆盖转换以在
|
||
发布的页面中使用原始源图像。
|
||
|
||
(#effects)
|
||
#### 效果
|
||
|
||
图像不应该有任何类型的样式或效果。请勿使用圆角、阴影和其他边框效果。这些应该通过样式来处理，这样才能根据需要自由更改，而不必重新生成源内容。
|
||
|
||
(#imagetables)
|
||
#### 图像表
|
||
|
||
通常使用表格来显示图像，第一行包含图像列，第二行包含选项。如果使用普通表格，因为应用的样式，可能会在一定程度上不够美观。
|
||
|
||
|  |  |
|
||
| ------ | ------ |
|
||
| 未过滤层列表 | 过滤层列表 |
|
||
|
||
|  |  |
|
||
| ------ | ------ |
|
||
| 未过滤层列表 | 过滤层列表 |
|
||
|
||
因此，已经提供了特殊_imagetable_区域。在这类区域中放入表格，会使界面看起来更简洁，更美观：
|
||
|
||
[REGION:imagetable]
|
||
|  |  |
|
||
| ------ | ------ |
|
||
| 未过滤层列表 | 过滤层列表 |
|
||
[/REGION]
|
||
|
||
[REGION:imagetable]
|
||
|  |  |
|
||
| ------ | ------ |
|
||
| 未过滤层列表 | 过滤层列表 |
|
||
[/REGION]
|
||
|
||
(#imagecallouts)
|
||
#### 图像注标
|
||
|
||
通常，需要在图像中创建编号注标来引用文本中的编号列表。在图像中产生这些编号注标时，被标注的区域需要用黄色笔画勾勒出来。圆角用于描绘相邻界面的区域。后面应当紧跟编号列表。
|
||
|
||
编号本身应该采用以下样式来确保一致：
|
||
|
||
|
||
* **字体：**Arial或相似的无衬线字体
|
||
* **样式：**粗体+斜体
|
||
* **颜色：**黄色(#fdf242)
|
||
|
||
|
||
|
||
|
||
1. **工具栏**——显示当前正在编辑的_动画序列_的名称。
|
||
1. **轨迹列表**——可编辑的轨迹列表，用于创建/编辑通知。请参阅下文，以了解有关创建和移除轨迹以及创建和处理通知的说明。
|
||
1. **时间轴**——在 **视口** 面板中显示关于预览播放的信息并提供相关控制。
|
||
|
||
|
||
在该示例中，您可以看到界面各个部分的分解图和编号方式，后面紧跟着一个编号列表。
|
||
|
||
(#lightboxing)
|
||
### Lightboxing
|
||
|
||
对于在页面上以覆层形式能呈现最佳显示效果的大图像和其他内容，应当使用Lightbox。一般而言，这意味着将链接包含在`lightbox`[区域](DocumentationGuidelines/Syntax#Regions)中。具体的语法取决于使用lightbox的内容类型。请参阅语法页面上的[Lightbox](DocumentationGuidelines/Syntax#ImageLightboxing)部分以了解更多详细信息。
|
||
|
||
[refepiclogo]：Logo_Epic-New.jpg "Here's a title"(w:50 h:50 a:left convert:true quality:75 fill:#000000)
|