样式规范

文本

• 章节
  • 每章开头对全章做介绍
  • 结构标题一致
    • 小结
    • 练习
    • 扫码直达讨论区
    • 参考文献（如有）
  • 引用
    • 在每节结尾处引用
• 字符串
  • 使用中文双引号
• 符号描述
  • 时刻t（不是t时刻）
  • 形状使用英文标点
    • (10, 20) 不是 （10，20）
• 空格：
  • 文本中中文和英文、数字、数学公式、特殊字体等之间不要加空格
  • 非行首的:numref:、:cite:等前留有一个英文空格（否则网页不渲染）
  • 代码注释同上
• 人称
  • 第一人称 → 我们
  • 第二人称 → 读者、你、大家
• 工具或部件
  • Gluon, MXNet, NumPy, spaCy, ResNet-18, Fashion-MNIST, matplotlib
    • 这些都作为词，不要带重音符
  • backward函数
    • 不是“backward()函数” （不要带括号）
  • for循环
• 术语
  • 统一使用
    • 函数（非方法）
    • 实例（非对象）
    • 区分：超参数和参数
    • 区分：小批量随机梯度下降和随机梯度下降
    • 权重、偏差、标签
    • 模型训练、模型预测（推断）
    • 训练数据集、验证数据集、测试数据集
  • 中文优先于英文
    • 首次出现，注明原英文术语
      • 无须加粗
      • 无须加引号
  • 中英文对照统一标准
    • https://github.com/mli/gluon-tutorials-zh/blob/master/README.md

数学

• 数学符号样式一致
  • https://github.com/goodfeli/dlbook_notation/blob/master/notation_example.pdf
• 书本页宽限制
  • 每行长度
• 引用
  • 上式和下式
  • 以上N式，以下N式
• 公式末放英文标点
  • 逗号：,
  • 句号：.
• 赋值符号
  • \leftarrow

图片

• 软件
  • 使用OmniGraffle制图，以100%的大小导出pdf（infinite canvas），再使用pdf2svg转成svg
• 样式
  • 格式：
    • svg
    • png
      • export resolution: 144
  • 大小：
    • 横向：不超过400像素
    • 纵向：不超过200像素
  • 粗细：
    • StickArrow
    • 1pt
    • arrow head size: 50%
  • 字体：
    • 英文：STIXGeneral, 9pt（下标和上标：6pt）
    • 中文：PingFang SC, 9pt
  • 下标和上标中的数字和括号不要斜体
  • 颜色：
    • 非填充深蓝色（与黑相近）：
      • 5B7DAA
    • 填充蓝色（与黑对比）
      • 深：66BFFF
      • 淡：B2D9FF
• 版权
  • 不使用网络图片
• 位置
  • 两张图不可以较邻近
    • 两张图拼一下
• 引用
  • 手动引用（例如，图7.1）
• matplotlib
  • 大小
  • 分辨率

代码

• 使用utils.py封装多次使用函数
  • 首次出现函数，书里给出函数实现
• Python规范一致
  • PEP8
    • 二元操作符换行：操作符和后一元一起换行 (https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator)
• 将相邻赋值语句尽可能合并为同一行
  • 如 num_epochs, lr = 5, 0.1
• 变量名一致
  • num_epochs
    • 迭代周期
  • num_hiddens
    • 隐藏单元个数
  • num_inputs
    • 输入个数
  • num_outputs
    • 输出个数
  • net
    • 模型
  • lr
    • 学习率
  • acc
    • 准确率
  • 迭代中
    • 特征：X
    • 标签：y, y_hat 或 Y, Y_hat
    • for X, y in data_iter
  • 数据集：
    • 特征：features或images
    • 标签：labels
    • DataLoader实例：train_iter, test_iter, data_iter
• 注释
  • 中文
  • 句末不加句号
• 书本页宽限制
  • 每行不超过78字符
    • In [X]: 79字符不会自动换行（X = 1, ..., 9）
    • In [XX]: 78字符不会自动换行（XX = 10, 11, ..., 99）
  • 打印结果自动换行
• imports
  • import alphabetically
  • from mxnet.gluon import data as gdata, loss as gloss, nn, utils as gutils
• 打印名称
  • epoch（从1开始计数）, lr, loss, train acc, time
  • 5行左右
• 打印变量
  • 代码块最后一行尽量不用print()语句，例如x, y而不是print('x:', x, 'y:', y)
• 字符串
  • 使用单引号
• 其他
  • nd.f(x) → x.nd
  • random_normal → random.normal
  • multiple imports
  • .1 → 1.0
  • 1. → 1.0
  • remove namescope

超链接

• 内链格式
  • “线性回归”一节
• 外链
  • 层
  • 无须暴露URL

英翻汉的常见问题

• 遇到不确定的地方，可以翻阅中文版第一版的处理方法（即我们需要遵照的出版标准），以及查阅人工翻译 http://www.jukuu.com/
• 建立中英文术语对照表，全书术语翻译要完全一致。
• 语法要正确（如不能缺主语、谓语）、句子要通顺（硬翻不妥就意译）、不要漏内容。
• 代码注释要翻译。注意：i) 每行不要超过78字符，注释末尾不用加句号。 ii) # 后要空一个半角字符（英文空格）。iii) 如果注释与代码同行，# 前要空两个半角字符（英文空格）。iv）保留注释中的``符号（为了表示代码部分，如变量名、函数名等）。v）注释中中文和英文之间不要空格。vi）贪婪换行：只有当一行注释抵到78字符时再换行。
• 不要新加空行（这样会另起一个自然段）。
• 术语要保留英文翻译。现在很多地方漏了英文翻译。格式：术语（terminology）
• 正文和代码注释均使用中文标点。例如，中文括号要用全角括号（），不是英文半角()。例外：所有表示形状的括号和逗号（逗号后紧跟半角英文空格）用英文半角，例如“(批量大小, 词数)”而不是“（批量大小，词数）”
• 英文在标题里或句首全部不要首字母大写（即便在标题的第一个词）。除非本身是首字母大写的术语
• 不要客气。“您”->“你”，去掉“请”