Skip to content

Latest commit

 

History

History
189 lines (131 loc) · 4.74 KB

书写规范.md

File metadata and controls

189 lines (131 loc) · 4.74 KB

书写规范（Writing Conventions）

本文档给出了包含文档内的书写约定。 请作者与贡献者参考以下约定检查格式，内容一致性与正确性。

这个风格指南随着时间的推移而演变，因为额外的约定被识别出来，并且过去的约定因语言本身的变化而变得过时。规范大多数来自于常见错误的总结。

许多项目都有自己的风格指南。如果发生任何冲突，此类特定于项目的指南优先于该项目。

1 内容格式

参考章节-第7章。

1.1 小节包含内容

  • n-前沿.md
  • n.m-章节名.md
  • ...

1.2 小节内容

  1. 添加各个章节和小节序号。
  2. 提那家章节目录，例如可以通过Markdown All in One插件自动化。
# 7.1 小节名

xxx

小节目录

## 7.1.1 子节名
...

## 小结与讨论

本章我们xx。

请读者思考，xx？

## 参考文献
-
-

1.3 文字

  1. 保持中文，中文（英文）。

例如： Figure改为图片

  1. 英文，数字，长序号两侧加空格，标点符号两侧不需要添加

例如： 使用 TensorFlow 框架 使用 TensorFlow， 批尺寸（Batch Size）， 图 1.3.2， 例如 1 中所示 为 $ x $ 字节

1.4 链接

Http链接不直接暴露。放于语法文字。

1.5 图片

  1. 注意追加图序号。
<center><img src="./img/1/7-1-1-jobsubmission.png" /></center>
<center>图 7.1.1 多租环境提交运行作业（<a href="https://xx">图片引用</a>）</center>
  1. 图片清晰度可以看到内容细节。
  2. 图片宽高调整自然。
  3. 图片添加引用。
  4. 图片要有对应格式解释。
  5. 图片文字尽量汉化。

1.6 代码

  1. 代码放于 ``` ```中。
# 启动脚本
python train.py --batch_size=256  --model_name=resnet50
  1. 追加适当注释解释文字。

1.7 表格

  1. 追加表序号。
  2. 使用Markdown语法保持格式一致。
  3. 通过语法让表格居中。
表 1.2.1 不同图像分类问题数据集的数据量
MNIST ImageNet Web Images
6万样本 1600万样本 10亿量级图像样本
10分类 1000分类 开放分类
  1. 表格要有对应文字解释。
  2. 如果表格需要用到公式，可以参考下面语法以公式呈现表格。

$$ \begin{array}{|c|c|c|} \hline & 比特数 & 取值范围 \\ \hline FP32& 32 & -3.4 \times 10^{38} \sim + 3.4 \times 10^{38} \\ \hline FP16& 16 & -65504 \sim +65504 \\ \hline INT8 & 8 & -128 \sim +127 \\ \hline \end{array} $$

1.8 概念，工作与文献引用

  1. 正文中概念，相关工作，或者文献需要追加引用链接。
  2. 英文概念能用中文解释的尽量用中文解释。
  3. 如果为某文献创造的概念，一定需要加概念引用。

例如： 单指令流多数据流（SIMD）

1.9 参考文献

向Markdown中添加参考文献引用，并且在点击参考文献引用标记时，能够自动跳转到“参考文献”一节中参考文献的详细条目，需要以下两步：

  1. 增加锚点 “参考文献”是Markdown文件末尾独立的一节，向这一节中添加具体的参考文献条目信息和锚点，如下所示：

    # 参考文献

<div id="ref1"></div>

1. [参考文献](链接)

    注：参考文献条目信息可以使用Google Scholar或是其他文献检索工具导出ACM Ref格式的参考文献信息。

  2. 增加引用 在引用改参考文献的正文部分增加对锚点的引用，使用<sup>标注引用，如下所示：

    这里是引用了参考文献1的正文[<sup>[1]</sup>](#ref1)。

1.10 语法生效检查

请校验预览正文

例如： **文字 ** 多空格则无法呈现 文字

1.11 字符

  1. ASCII字符两侧可以加空格保持美观。例如 x 初值为 100 情况下。
  2. （）和，和。和“”等使用中文输入法中的标点符号。

1.12 中英文混杂问题

  • 原则能用中文就用中文
  • 首次提到需要
    • 人工智能（Artificial Intelligence），简称 AI
    • 前面提到后，后面可以使用简称 AI
  • 例外：
    • 如果 Netron，TensorFlow 这类特定工具名字，可以用英文
    • 动词要尽量用中文
    • 专有通用名词尽量用中文。例如，编译器

2. 术语约定

术语是约束内容一致性重要的方法。

  1. 正文中英文 中文术语（英文术语-首字母大写），如果需要引用加引用链接。

例如：

部署（Deployment）

注意：中文和括号之间不加空格。

  1. 追加到 术语表.md
英文 中文 缩写 首次提交人
Deployment 部署 xx