常用中文标点符号¶
技术文档中容易用错的标点符号主要有:句号、逗号、顿号、分号、冒号、引号、括号、书名号、连接号、破折号、省略号、感叹号、斜杠与反斜杠。下文介绍了它们的使用规范。
句号¶
句号的形式为“。”,表示陈述语气,用于句末停顿。
句号表示一个句子的意思已经完整,技术文档中应善用句号切分语意,帮助用户理清逻辑。
【错误示例】原因是 DM 需要保存同步的 binlog position 信息,但是 MySQL binlog position 官方定义使用 uint32 存储,所以超过 4G 部分的 binlog position 的offset 值会溢出,就会存储的是一个错误的 binlog position,在重启 task 或者 dm-worker 后,需要使用该 binlog position 重新解析 binlog/relay log,进而出现上面的错误。
【正确示例】由于 DM 需要保存同步的 binlog position 信息,且MySQL binlog position 官方定义使用 uint32 存储,因此超过 4G 部分的 binlog position 的offset 值会溢出。这会导致存储的是一个错误的 binlog position。在重启 task 或者 dm-worker 后,需要使用该 binlog position 重新解析 binlog/relay log,进而出现上面的错误。
逗号¶
逗号的形式为“,”,表示句子内部的一般性停顿。
逗号使用最为普遍,但不能滥用。技术文档中不要出现“一‘逗’到底”的错误,即整个段落除了段落结尾外,全部停顿都使用逗号。
【错误示例】首先判断出错发生在 relay log 写入还是 binlog replication/syncer unit 同步(通过日志出错信息中的 component 信息即可判断),如果错误发生在 relay log 模块,binlog replication/syncer unit 保存的断点都是正确的情况,可以先停止任务,停止 DM-worker,手动调节 relay meta 的binlog-position 到4,重启 DM-worker 重新拉取 relay log ,relay log 写入正常后启动任