企业官网建设流程全解析

• 嵌入式
• 固件

本指南面向所有希望为 Apollo-11 仓库贡献代码的开发者，核心主题是阿波罗 11 号制导计算机（AGC）汇编源码的转录校对规范。仓库中的Comanche055/（指令模块，代号 Colossus 2A）与Luminary099/（登月模块，代号 Luminary 1A）全部源码均由志愿者从纸质打印输出（printouts）手动数字化而来，因此本指南详细定义了"以扫描件为唯一基准"的逐字校对流程：从编辑器选型、格式化规范，到注释排版错误、空格密度与空行规则，读完即可上手完成一次合格的转录差异审查，并知道如何提交一份与扫描件完全一致的 Pull Request。本文内容以 Translations/CONTRIBUTING.id.md（印尼语贡献指南）及其英文原版 CONTRIBUTING.md 为主体，并结合仓库内真实 AGC 源文件展开佐证。

背景：一份必须"以扫描件为准"的开源代码

Apollo-11 仓库的定位非常明确——它是阿波罗 11 号制导计算机原始源码的存档库，而不是一份被"润色"过的现代代码。正如 README.md 所述，仓库内容由 Virtual AGC 社区与 MIT 博物馆合作数字化而成，目标是保存 Comanche 055 与 Luminary 099 的原始转录文本，并欢迎任何针对转录与原始扫描件之间差异的 Pull Request。

正因为源码来自手动数字化，转录过程中不可避免地混入了两类问题：

1. 原始扫描件本身就有的错误——当年的 NASA 工程师在纸质注释中写下的拼写错误；
2. 数字化过程中新引入的错误——人工转录、OCR 或排版环节产生的偏差。

因此贡献指南的核心原则只有一条：仓库中的转录代码必须被修改，使其与下列官方扫描打印输出完全一致：

• Comanche（指令模块 AGC）扫描打印输出
• Luminary（登月模块 AGC）扫描打印输出

此外，社区还提供了便捷的在线工具用于浏览两份扫描件（可在仓库 README.md 的 Attribution 一节找到 ibiblio 镜像入口）。在开始校对之前，请先把对应页面的扫描件调出来，逐行对照。

如何在仓库中定位要校对的模块

仓库目录结构即模块边界：

• Comanche055/：指令模块（CM）的 AGC 程序，装配版本Assemble revision 055 of AGC program Comanche by NASA，1969 年 4 月 1 日；
• Luminary099/：登月模块（LM）的 AGC 程序，装配版本Assemble revision 001 of AGC program LMY99 by NASA，1969 年 7 月 14 日。

每个.agc文件头部都带有标准的转录元信息。以 Comanche055/P11.agc 为例，其文件头（第 1~35 行）记录了 Copyright、Filename、Purpose、Assembler（yaYUL）、Contact、Mod history，并注明"Assemble revision 055 of AGC program Comanche by NASA"与"Page 533"字样。这类页号信息正是你比对扫描件时定位页码的依据——PDF 扫描件的每一页通常都标有对应页码。

工欲善其事：为你的编辑器安装 AGC 语法高亮

AGC 汇编语言是 1960 年代的产物，现代代码编辑器默认都不认识它。好消息是 GitHub 本身内置了对 AGC 汇编语言的语法支持（在线浏览 .agc 文件时已可高亮），但本地编辑器需要额外安装语言扩展。贡献指南列出了以下支持 AGC 语法高亮的编辑器及其扩展：

† 标记表示该扩展额外支持自动格式化，即保存文件时能自动套用下文所述的格式化规范。

这些扩展分别由社区成员维护，可在各编辑器的插件市场或 Virtual AGC 项目的Contributed/SyntaxHighlight目录中找到（Virtual AGC 是编译 AGC 源码的参考实现，详见 README.md 的 Compiling 一节）。装上语法高亮后，CS、TC、IMODES33这类 AGC 助记符与标签会被正确着色，校对时对代码结构的识别效率会明显提升。

格式化规范：三个必须遵守的硬性要求

在动手校对之前，先确保你的编辑器 / 扩展已启用正确的格式化设置，贡献指南给出的格式要求非常明确：

• 使用 TAB 进行缩进，不要用空格缩进；
• TAB 宽度为 8 个字符；
• 去除行尾的空格或 TAB（trim trailing whitespace）。

其中"TAB 宽度为 8"与 AGC 源码的物理排版历史直接相关：1960 年代的宽行打印机以 8 列为一个制表位，源代码的缩进层次、标签列、操作码列与操作数列都依赖这一固定列宽。即使现代编辑器默认 TAB 宽度是 4，校对 AGC 文件时也必须改为 8，否则列对齐关系会被破坏，无法与扫描件的排版对应。

提示：贡献指南注明，GitHub 平台本身以及上表中带 † 的三个扩展会自动帮你应用正确的格式化，但手动编辑时仍需自查。

校对要点一：注释必须与扫描件逐字精确匹配

这是整个校对工作的最高优先级规则：转录代码中的注释必须与扫描打印输出完全一致（用原文档的措辞即"MUSTmatch the scansexactly"）。

之所以要"精确"而不是"纠正"，是因为当年开发者写下的注释本身就包含错误，而这些错误同样属于历史的一部分。校对者需要处理两类典型的排版错误（Typographic Errors）：

1. 数字化把原本正确的拼写改错了→ 必须改回扫描件的原文；
2. 数字化"好心"修正了扫描件里的原始错误→ 必须还原成错误版本。

原文档给出一个极具代表性的例子：如果数字化注释中是SPACECRAFT，而扫描件上印的是SPAECRAFT（漏了字母C），那么转录代码必须被纠正为SPAECRAFT。同理，如果某个单词在数字化文本中拼错了、但扫描件拼写正确，则必须修正转录文本。

这个规则在仓库源码中有真实对应。以 Comanche055/CONTRACT_AND_APPROVALS.agc 第 38 行为例，转录注释为：

# * PROJECT 55-23870, SPONSORED BY THE MANNED SPACECRAFT *

该文件同时保留了大量值得对照的细节，例如第 57 行 "COLOSSUS PROJECT MANGER"（MANGER系MANAGER之误）——这类注释中的原始笔误正是贡献指南要求保留的对象。校对者的任务不是把MANGER改成MANAGER，而是确保它与扫描件印刷内容逐字符一致。

校对要点二：注释中的空格密度约定

注释内任意两个字符之间的空格数量，也应尽量与扫描件一致。贡献指南参考了社区讨论（原文档引用了 PR #316 的评审讨论），归纳出如下默认约定：

需要注意的是，这只是一条通用经验法则，并非所有扫描页面都严格遵循。规则本身强调：如果扫描件某页实际只印了 1 个空格而不是 2 个，就照扫描件用 1 个空格——扫描件永远优先于约定。

以中英文贡献指南中都给出的格式化示例为参照，把散乱空格整理为统一密度的过程大致如下：单词间单空格、句号后双空格、续行缩进三空格。这一规则的意义在于：空格密度在扫描件上承载了句读信息，转录时保持密度即保持原件的可读性结构。

校对要点三：换行与空行规则（R0000 列的特殊地位）

AGC 打印输出在每一页左侧带有行号列，其中R开头的行号（如R0819）出现在第 1 列。贡献指南对换行给出两条硬性规则：

规则 1：带R0000的换行必须与扫描件完全一致。当一行的第 1 列出现R0000形式的行号时，该行与上一行之间的换行关系是打印排版刻意为之，必须原样保留。

规则 2：不含R0000的连续空行最多 1~2 行。

• 若两个非空行之间夹着超过 2 个连续空行，则删除多余的空行；
• 带R0000的行不计入这个"1~2 行"的限额——也就是说，R0000行之间的空行可以不受此限。

原文档给出了一个非常直观的对照示例。假设扫描件对应的原始排版如下（含 3 个连续空行与错位行号）：

R0819 SUBROUTINE TO SKIP... R0820 0821 LAMPTEST CS IMODES33

则转录代码应整理为（最多保留 2 个空行，且行号需对齐）：

R0819 SUBROUTINE TO SKIP... R0820 0820 LAMPTEST CS IMODES33

注意第二个示例中行号从0821修正为0820——因为删除了一个多余空行后，后续代码行号整体前移，必须同步校正以保持与扫描件逐行对应。

空行密度背后的排版机制

为什么会有"1 个空行 / 2 个空行"这种密度限制？贡献指南解释了原始打印机制：在源图片中，这些空行是由第 8 列上一个未打印的数字控制的——

• 数字2强制"双倍行距"（即 1 个空行）；
• 数字3强制"三倍行距"（即 2 个空行）；
• 数值4~8在打印规范中被定义过，但从未被实际使用。

换言之，扫描件上的空行密度是打印列控制符的可视化结果，转录时必须忠实地把它还原为"最多连续 2 个空行"的形式，多余的空行一律删掉。

提交 PR 之前的最后检查

贡献指南在结尾给出了唯一且必须遵守的验收标准：在你提交 Pull Request 之前，请确保你的所有改动与原始扫描打印输出保持一致。

结合仓库 CONTRIBUTING.md 与 README.md 的流程，一次完整的贡献可以总结为以下步骤：

1. 选对模块：根据改动所在文件判断属于Comanche055/还是Luminary099/，并定位对应的扫描打印输出页码范围（每个 .agc 文件头部的 Pages 注释即为页码索引，如 Comanche055/P11.agc 头部的Pages: 533-550）；
2. 配置编辑器：安装对应的 AGC 语法扩展，设置 TAB 宽度为 8、开启去除行尾空白；
3. 逐行比对：优先核对注释（拼写、空格密度），再核对换行与空行规则（R0000 行、空行上限）；
4. 自查格式化：确认没有行尾空格、缩进使用 TAB；
5. 提交 PR：在 PR 描述中说明发现的差异与依据的扫描件页码，方便维护者复核。

整个仓库的贡献文档均以多种语言维护，除本文依据的 Translations/CONTRIBUTING.id.md 外，还包括 Translations/CONTRIBUTING.zh_cn.md 等二十余种语言版本，且 CONTRIBUTING.md 与各翻译版之间通过语言导航互相索引。若发现任一语言版本的贡献指南与英文原版存在差异，同样欢迎通过 PR 修正。

结语

对现代开发者而言，为一份 1969 年的汇编源码做校对是一件"反直觉"的工作：我们要的不是"修正错误"，而是"还原历史"。阿波罗 11 号 AGC 源码之所以被以逐字一致的精度保存，是因为它不仅是可编译的代码，更是一件需要被原样保留的工程史料。掌握了注释精确匹配、空格密度约定、R0000 换行规则与空行上限这四把标尺，你就可以放心地打开任一.agc文件，与扫描件展开一次严谨、可追溯的差异审查。

• 嵌入式
• 固件