ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Apollo-11 仓库贡献指南:AGC 登月代码的逐页校核、格式规范与提交要点

Apollo-11 仓库贡献指南:AGC 登月代码的逐页校核、格式规范与提交要点 嵌入式固件【免费下载链接】Apollo-11Original Apollo 11 Guidance Computer (AGC) source code for the command and lunar modules.项目地址https://gitcode.com/GitHub_Trending/ap/Apollo-11点击查看免费下载导读Apollo-11 仓库存放的是阿波罗 11 号任务中两套真实运行过的制导计算机Apollo Guidance Computer简称 AGC的原始汇编源码指挥/服务舱使用的 Colossus 2A代号 Comanche 055位于 Comanche055/和登月舱使用的 Luminary 1A代号 Luminary 099位于 Luminary099/。这些代码并非原生的电子文件而是由 Virtual AGC 与 MIT Museum 的相关人员从纸质打印稿手工数字化而来因此转写过程中难免混入人工拼写错误。本文基于仓库官方贡献指南本文件为 越南语翻译版英文原文见 CONTRIBUTING.md系统讲解如何对照原始扫描件逐页校对源码、遵循仓库统一的排版格式并在提交 Pull Request 前完成自查。读完本文你将掌握 AGC 源码的校对验收标准、注释与空白的精确匹配规则以及符合 yaYUL 汇编器与仓库风格的行文规范能够安全地参与这一极具史料价值项目的贡献。仓库背景与贡献前提数字化源码的由来根据 README.md 的说明本仓库的源码经由 Paul Fjeld 依据 MIT Museum 提供的一份纸质打印稿hardcopy数字化转写而来随后由 Virtual AGC 团队与 MIT Museum 共同整理。所以仓库中的代码并不是标准答案纸质扫描件才是事实的唯一来源。贡献者的核心任务就是发现并修正转写稿与扫描件之间的一切差异。每个.agc文件开头都有一段标准化的头注释记录文件的出处与版权信息例如 EXECUTIVE.agc# Copyright: Public domain. # Filename: EXECUTIVE.agc # Purpose: Part of the source code for Colossus 2A, AKA Comanche 055. # Assembler: yaYUL # Pages: 1208-1220 # This source code has been transcribed or otherwise adapted from digitized # images of a hardcopy from the MIT Museum. ...这段注释同时透露了三个关键信息文件属于 Colossus 2AComanche 055、汇编器为 yaYUL、对应打印稿的页码范围是 1208–1220。校对时这些信息可用于快速定位到扫描件的对应页码。两份待校对的对象仓库按航天器程序版本组织成两个目录Comanche055/指令舱 AGC 程序 Comanche 055 的全部源码如 MAIN.agc 是装配清单assembly listing其余如 EXECUTIVE.agc、RCS-CSM_DIGITAL_AUTOPILOT.agc 等是按功能划分的模块文件Luminary099/登月舱 AGC 程序 Luminary 099 的全部源码同样有 MAIN.agc 装配清单以及 P70-P71.agc、THE_LUNAR_LANDING.agc 等功能模块。在 Comanche055/MAIN.agc 中可以看到装配清单通过$模块文件名.agc 页注释把整个程序串联起来$INTERRUPT_LEAD_INS.agc # pp. 131-132 $T4RUPT_PROGRAM.agc # pp. 133-169 $DOWNLINK_LISTS.agc # pp. 170-180 $FRESH_START_AND_RESTART.agc # pp. 181-210每行右侧的# pp. x-y注释标明该模块对应纸质打印稿的页码范围这正是逐页校对时定位扫描件的索引依据。校对参考的扫描件贡献指南要求源码最终必须与以下两类官方扫描件保持一致Comanche055程序的 AGC 打印件扫描Luminary099程序的 AGC 打印件扫描。同时CONTRIBUTING.md 还提供了可直接在线浏览双程序扫描件的辅助站点。由于校对工作量大指南特别强调在创建 PR 之前务必确认你的改动与扫描件内容一致。准备编辑环境语言支持与 AGC 语法高亮GitHub 内置支持GitHub 对 AGC 汇编语言内置了语法高亮支持因此在 GitHub 网页上直接浏览.agc文件即可获得正确的着色。但本地编辑器默认并不认识 AGC 这种语言需要安装对应的语言扩展。各编辑器的 AGC 扩展贡献指南列出了以下支持 AGC 语法高亮的编辑器及其扩展标注 † 的扩展还额外支持自动格式化编辑器扩展来源是否支持自动格式化AtomAlhadis/language-agc† 是CodeBlocksVirtual AGC 贡献的 CodeBlocks 高亮方案否EclipseVirtual AGC 贡献的 Eclipse 高亮方案否KateVirtual AGC 贡献的 Kate 高亮方案否ProgrammersNotepadVirtual AGC 贡献的 ProgrammersNotepad 高亮方案否Sublime Text 3jimlawton/AGC-Assembly† 是TextPadVirtual AGC 贡献的 TextPad 高亮方案否Vimwsdjeg/vim-assembly否Visual Studio Codewopian/agc-assembly† 是jEditVirtual AGC 贡献的 jEdit 高亮方案否对于 CodeBlocks、Eclipse、Kate、ProgrammersNotepad、TextPad、jEdit扩展均托管在 Virtual AGC 项目virtualagc/virtualagc的Contributed/SyntaxHighlight目录下可按对应编辑器子目录安装。小贴士选择带 † 标记的扩展如 Atom、Sublime Text 3、Visual Studio Code可以在编辑保存时自动套用仓库要求的排版格式从源头减少后续的人工格式校对工作。格式规范让代码与 1969 年的打印稿保持一致仓库的排版规范直接继承了纸质打印稿的排版方式。GitHub 内置语法支持以及上文标注 † 的扩展会自动保证你使用正确的格式但手工编辑时仍需遵守以下三条硬性要求使用 Tab 缩进Use tab indentation——不要用空格代替缩进Tab 宽度为 8Use tab width of 8——一个 Tab 显示为 8 个字符宽这是当年打印机的列宽删除行尾空格Trim trailing whitespace——行尾不得残留多余空白字符。这些约定在源码中随处可见。以 EXECUTIVE.agc 为例指令用 Tab 对齐到第 9 列、操作数用 Tab 对齐到约定列位注释以#起头并保持统一的空白规则# Page 1208 BLOCK 02 # TO ENTER A JOB REQUEST REQUIRING NO VAC AREA: COUNT 02/EXEC NOVAC INHINT AD FAKEPRET # LOC(MPAC 6) - LOC(QPRET) TS NEWPRIO # PRIORITY OF NEW JOB NOVAC C(FIXLOC)可以看到助记符如INHINT、AD、TS统一从第 9 列一个 Tab 之后开始操作数与注释之间的对齐同样依靠 Tab 完成行尾注释#前的空白也是有规律的。另外仓库还配套了 Markdown 文档的 lint 检查。根目录 package.json 中的脚本显示所有*.md包括Translations/目录都要通过markdownlint-cli2校验lint: markdownlint-cli2 *.md translations/*.md Comanche055/*.md Luminary099/*.md --config .markdownlint.yml, lint:fix: markdownlint-cli2 *.md translations/*.md Comanche055/*.md Luminary099/*.md --config .markdownlint.yml --fix这说明不仅.agc代码有格式要求仓库内的说明文档同样纳入格式管理。校对要点注释、拼写与空白校对总目标贡献指南明确指出任何扫描件与仓库源码之间的差异都是需要修正的目标。换言之源码是转写结果扫描件是验收基准。注释必须逐字精确匹配转写代码中的注释Comments必须与扫描件精确一致。这包括注释的文字内容必须逐字对应扫描件注释的排版间距也应尽量复现扫描件。为什么如此严格因为这份代码具有历史文物的属性注释中的原版拼写、排版甚至错误都要原样保留以便后人能通过这份仓库反推 1969 年程序员实际的书写原貌。常见问题一拼写错误Typographic Errors指南指出两类拼写问题原始开发者留下的拼写错误当年程序员手写的注释里本身就有错别字而最初的数字化转写过程中部分这类错误被好心纠正了数字化过程引入的拼写错误转写本身也制造了扫描件中没有的新错别字。校对原则是以扫描件为准双向纠错。指南给出了一个非常典型的例子如果转写稿的注释里写的是SPACECRAFT而扫描件上印的是SPAECRAFT少了中间的C那么转写稿必须被改为SPAECRAFT。反过来如果某个词在转写稿里拼错了、但扫描件里拼写正确那么同样必须修正为正确拼写。核心判断标准只有一个对照扫描件。常见问题二注释中的空格注释中两个字符之间的空格应当与扫描件一致。在绝大多数情况下遵循以下惯例新单词之间用1 个空格新句子之间用2 个空格缩进用3 个空格。但指南同时强调并非所有扫描页面都严格遵守这一概括如果某页扫描件实际只用了 1 个空格而不是 2 个那就以扫描件为准、使用 1 个空格。换句话说扫描件优先于惯例。常见问题三换行与空行Line breaks换行规则是校对中最容易出错、也最有讲究的部分第 1 列带R0000的换行这类行如R0819、R0820这类页标/行标必须与扫描件完全一致第 1 列不带R0000的换行连续空行只允许出现 1 或 2 个如果出现超过 2 个连续空行必须删掉多余的空行特别地第 1 列是R0000的行不计入空行计数。为什么打印稿会产生这种超量空行指南结合原始图像给出了解释在源图像中这些空白是由第 8 列上一个未打印出来的数字造成的——数字2强制产生两个空格宽即 1 个空行数字3强制产生三个空格宽即 2 个空行值4到8虽然也被定义过但从未实际使用。因此当转写稿中出现 3 个以上连续空行时往往是数字化阶段把这种列 8 数字的排版意图多转写出了空行应当清理。指南还给出了一个完整的修正示例。下面的写法连续 3 个空行是不合规的R0819 SUBROUTINE TO SKIP... R0820 LAMPTEST CS IMODES33应当修正为最多 2 个连续空行且行标与扫描件对齐R0819 SUBROUTINE TO SKIP... R0820 LAMPTEST CS IMODES33实际源码中这类行标 缩进的排版模式在仓库里大量存在。例如 EXECUTIVE.agc 中每隔一段就会出现# Page 1209、# Page 1210这样的页注释说明每个源文件都是按打印稿的物理页面逐页转写的# Page 1209 TS L 2 CAF EXECBANK TS BBANK TCF CHANJOB -1 # Page 1210 # TO VOLUNTARILY SUSPEND A JOB UNTIL THE COMPLETION OF SOME ANTICIPATED EVENT (I/O EVENT ETC.): JOBSLEEP TS LOC对比之下可以体会到代码块之间的空行数量、页注释的插入位置都是与扫描件逐页对应的任意增删都会破坏转写稿 ↔ 打印稿的可追溯性。提交前的自检清单在创建 Pull Request 之前请逐项确认对照扫描件你修改的每一行都与 Comanche 或 Luminary 的对应扫描页一致注释精确匹配注释文字、大小写、标点、拼写均与扫描件一致包括那些故意保留的历史错误空格符合扫描件单空格/双空格/三空格的使用遵循扫描件实际排版换行合规第 1 列带R0000的行与扫描件完全一致不带R0000的连续空行不超过 2 个格式规范使用 Tab 缩进、Tab 宽度为 8、无行尾空格文档一致性若同时修改了 Markdown 文档可通过npm run lint运行仓库配置的 markdownlint 检查参考 package.json。只有所有改动都经得起扫描件的逐字核对这份 PR 才符合仓库的验收标准。结语阿波罗 11 号 AGC 源码的价值不仅在于能编译运行更在于它是人类首次登月工程的原始数字遗产。仓库为这份遗产制定了近乎苛刻的校对规范以纸质扫描件为唯一基准、注释逐字精确、空白与换行严格对齐、Tab 宽度固定为 8。理解并遵守这些规则既能保证提交的代码通过审查也是对这些 1969 年代码与其作者们的最基本尊重。上手时建议从最简单的拼写错误修正开始借助带自动格式化的编辑器扩展如 Visual Studio Code 的wopian/agc-assembly降低格式门槛再用扫描件逐页验证即可平稳进入 Apollo-11 仓库的贡献流程。赞分享嵌入式固件【免费下载链接】Apollo-11Original Apollo 11 Guidance Computer (AGC) source code for the command and lunar modules.项目地址https://gitcode.com/GitHub_Trending/ap/Apollo-11点击查看免费下载相关推荐Apollo-11 仓库贡献指南AGC 源码逐页校勘、格式规范与编辑器工具链Apollo 11 仓库贡献指南AGC 源码逐页校勘、格式规范与编辑器工具链 导读 本文以 Translations/CONTRIBUTING.ca.md 嵌入式固件Apollo-11 仓库贡献指南AGC 源代码数字化校对、格式规范与提交实操Apollo 11 仓库贡献指南AGC 源代码数字化校对、格式规范与提交实操 本篇指南围绕 Apollo 11 仓库的 繁体中文贡献文档 https://li嵌入式固件Apollo-11 仓库贡献指南AGC 源码数字化校对与提交规范实战Apollo 11 仓库贡献指南AGC 源码数字化校对与提交规范实战 导读 本文以 Apollo 11 仓库存放 Apollo 11 登月任务指令舱 Com嵌入式固件上一篇5分钟快速上手pyannote.audio说话人日志完整指南下一篇探秘Pymunk轻松实现2D物理引擎的魔法创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表