• 嵌入式
• 固件

Apollo-11 仓库保存的是阿波罗 11 号制导计算机（AGC）的原始源码，其中Comanche055对应指令舱（Command Module）的 Colossus 2A 程序，Luminary099对应登月舱（Lunar Module）的 Luminary 1A 程序。本文基于仓库的德文版贡献指南 Translations/CONTRIBUTING.de.md（其英文原版见 CONTRIBUTING.md），系统讲解这批手工数字化转写的汇编代码的校对方法、格式规范、空行与空格规则，以及为常见编辑器配置 AGC 语法高亮的具体方案，帮助你提交与原始扫描件完全一致的补丁。

背景：为什么这份源码需要专门校对

本仓库的所有.agc文件均由纸质打印件人工数字化转写而来（转写工作由 Virtual AGC 社区与 MIT 博物馆协作完成，详见 README.md 的 Attribution 一节），因此转写过程中不可避免地引入了拼写错误与各种差异。仓库维护的目标，是让源码与以下两份扫描打印件逐字一致：

• Comanche 055 的 AGC 打印件（对应Comanche055目录）
• Luminary 099 的 AGC 打印件（对应Luminary099目录）

仓库中每个源码文件头部都带有版权、文件名、用途、汇编器（yaYUL）及 Mod history 注释，例如 Comanche055/FRESH_START_AND_RESTART.agc 标注了"Comanche, build 055"与"pp. 181-210"的页码引用，并在文件内以# Page 181、# Page 182的形式标记每个扫描页面的起点（如 Comanche055/AGC_BLOCK_TWO_SELF-CHECK.agc 中的# Page 1394）。这些页面标记正是逐页比对扫描件时的定位锚点。

实用提示：贡献指南还提供了在线浏览工具，可以很方便地在两个程序集的扫描件中定位翻页，便于快速对照。

校对的核心任务：消除转写与扫描件之间的差异

贡献指南明确要求，检查的范畴是扫描件与仓库源码之间的所有差异。这包括转写时遗漏的字符、误增的字符、注释排版不一致等。在提交 Pull Request 之前，务必确认你的修改与扫描件保持一致（这正是文档最后"Anmerkung"一节的叮嘱）。

注释（Kommentare）：必须与扫描件逐字精确一致

转写源码中的注释必须与扫描件完全一致（MUST），这是所有校对规则中优先级最高的一条。指南特别指出两类需要警惕的常见错误：

排版性拼写错误（Typographische Fehler）

• 原始开发者有时会在注释中留下排版性拼写错误，而最初转写时有人"好心"地把它们改正了，导致转写结果与扫描件不符——必须把转写内容还原成扫描件中的错误写法。
• 反之，如果某个词在转写中出现了扫描件里没有的拼写错误，则该错误必须被修正。

文档给出的示例极具说服力：若转写注释中是SPACECRAFT，而扫描件上印的是SPAECRAFT（漏了一个C），则转写必须被改回SPAECRAFT，即便它"语法上错误"。这条规则的目的是忠实保留历史文档的原貌，而不是"修正"历史。

空格（Leerzeichen）

注释中两个字符之间的空格应当（SHOULD）与扫描件吻合。在大多数情况下（详见 #316 的讨论），遵循以下约定：

• 单空格：用于分隔新单词；
• 双空格：用于新句子开头；
• 三空格：用于缩进。

注意扫描件并非每一页都遵守这一泛化规则——如果扫描件中只有单空格而约定是双空格，那么以扫描件为准，使用单空格。也就是说，扫描件是第一权威。

仓库中的真实注释很好地印证了这一规则。例如 Comanche055/T4RUPT_PROGRAM.agc：

LAMPTEST CS IMODES33 # BIT 1 OF IMODES33 = 1 IF LAMP TEST IN MASK BIT1 # PROGRESS.

这条# BIT 1 OF IMODES33 = 1 IF LAMP TEST IN注释将句子在页内拆行续写，续行注释以单个空格起始；而在 Comanche055/FRESH_START_AND_RESTART.agc 中可以看到大量以双空格甚至更多空格对齐的缩进注释块，体现了扫描件中"新句子双空格、缩进多空格"的排印习惯。

空行规则（Zeilenumbrüche）：R0000 列与列 8 的秘密

空行规则是本指南中技术含量最高的一部分，它涉及早期 AGC 汇编打印件特殊的行号编码机制。规则分两种情况：

带R0000的行

• 凡是在第 1 列出现R0000的行，其换行（空行数量）必须与扫描件精确一致（MUST）。
• 带R0000的空行不参与下面第 2 条的计数。

不带R0000的行

• 这类行之间的空行应当只保留连续 1～2 个空行（1 or 2 blank lines in a row）。
• 如果空行超过 2 个，删除多余的空行（带R0000的行不计算在内）。

深层原理：列 8 中未打印的数字

指南揭示了一个有趣的原始机制：在源图像（扫描件）中，这些多余的空白行是由第 8 列一个未打印的数字造成的：

• 第 8 列为2时，强制产生双倍空格（即在视觉上表现为 1 个空行）；
• 第 8 列为3时，强制产生三倍空格（表现为 2 个空行）；
• 值为4到8之间的情况虽然有定义，但从未被使用过。

更多背景可参见 #159。

规范示例

文档给出了一个完整的"改前/改后"示例，原始内容为：

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

应被规范化为：

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

这个示例包含两层含义：

1. 将连续 3 个空行缩减为 2 个空行（满足"最多 2 个空行"的规则，且R0820行不计入计数）；
2. 第 1 列从0821纠正为0820——正是列 8 中未打印数字机制所导致的行号位移，需要以扫描件为准还原。

该示例中的指令在仓库中真实存在：Comanche055/T4RUPT_PROGRAM.agc 处正是LAMPTEST CS IMODES33（其上方第 1033 行注释# SUBROUTINE TO SKIP IF LAMP TEST NOT IN PROGRESS.与示例中的SUBROUTINE TO SKIP...一脉相承），可视为该规则在真实代码库中的直接落点。

格式规范（Formatierung）：Tab、宽度与尾随空格

贡献指南对源码文件的机械格式提出了三条硬性要求，GitHub 的 AGC 语法支持和下文提到的部分编辑器扩展会自动保证这些规范：

• 使用 Tab 缩进（Use tab indentation）；
• Tab 宽度为 8（Use tab width of 8）；
• 去除行尾空格（Trim trailing whitespace）。

这些规范在仓库源码中体现得十分明显：所有.agc文件的操作码与操作数之间均使用制表符对齐，例如 Comanche055/T4RUPT_PROGRAM.agc 中的IFAILJMP TCF ITURNON、30RDMSK OCT 76400等指令，标签列、操作码列、操作数列在 Tab 宽度 8 的对齐下整齐排布。之所以要求 Tab 而非空格，正是为了与当年打印件上的列对齐方式一致，使逐行比对扫描件成为可能。

编辑器配置：AGC 汇编语法高亮扩展

GitHub 已内置 AGC 汇编语言的语法高亮支持，但本地的代码编辑器默认没有。贡献指南为以下编辑器列出了可用的 AGC 语言扩展（标注 † 的支持自动格式化，能自动落实上面的格式规范）：

其中，Atom（language-agc）、Sublime Text 3（AGC-Assembly）和 Visual Studio Code（agc-assembly）三个扩展同时提供自动格式化能力；Virtual AGC 项目（即负责扫描转写的社区）则为 CodeBlocks、Eclipse、Kate、ProgrammersNotepad、TextPad、jEdit 贡献了对应的语法高亮方案。若你使用 Visual Studio Code，还可以参考agc-assembly扩展的用户设置项来调整高亮与格式化行为。

提交 PR 前的最终检查

贡献指南在结尾给出了一条总括性叮嘱：在创建 Pull Request 之前，请确保你的修改与扫描件一致。结合全文，可以整理出一份提交前自查清单：

1. 注释是否与扫描件逐字一致（包括保留历史拼写错误）？
2. 注释空格是否为"新词单空格、新句双空格、缩进三空格"，且以扫描件实际排版为准？
3. 带R0000的行的空行数量是否与扫描件完全一致？
4. 不带R0000的行的连续空行是否已控制在 1～2 个？
5. 是否使用了 Tab 缩进、Tab 宽度 8、并清除了行尾空格？

按照这套规范校对，既能保证仓库源码与历史扫描件的逐字节一致，也为 AGC 汇编代码的自动化比对（如 yàYUL 汇编与 diff 校验）提供了稳定的文本基础。你可以先在仓库中浏览 Comanche055 与 Luminary099 两个目录下的任意.agc文件，对照# Page NNNN标记与扫描件逐页核验，再提交你的第一份贡献。

• 嵌入式
• 固件