-
Notifications
You must be signed in to change notification settings - Fork 0
Aurora 12 Transcription
With many thanks to Don Eyles (for providing the listing) and the Internet Archive (for performing the scanning), we are currently in the process of transcribing the Lunar Module System Test program AURORA Revision 12. Transcribing listings like this one is a big task, so please read on if you're interested in helping us out!
The scans are available in full resolution in our archive.org collection, and smaller, reduced quality copies are available at the ibiblio site.
Chunks of work that are available are in the Aurora 12 milestone, and marked as "help wanted".
This filtered issue view shows all such tasks.
You can pick out any of these to work on that you'd like -- just leave a comment on the issue saying that you'd like to take on the task. For first-contributors, we recommend starting with shorter sections. There's plenty that are only 2-5 pages long!
Alternatively, if you'd like us to pick for you, leave a comment on this issue or send an email to one of the addresses listed on it, and we'll get back to you.
Once a task has been picked out, we'll drop the "help wanted" tag, mark it as in progress, and assign it to ourselves. The last step is unfortunately necessary since GitHub won't let us assign issues to users without push access to this repository. But in reality, it just means we're putting along the issue for you while you work on it! We'll also help you get set up if needed.
The recommended way to get going is to fork this repository.
Once you've got a local copy of your fork, you can find the skeleton file for the code you'll be transcribing in the Aurora12 folder.
Do it before you really get going. You'll save yourself (and us) a lot of time!
Using the scans available at the links above, start transcribing. The issue for your chunk of work should indicate whether or not there is a suitable Luminary 099 file to start with, or if pieces of code can be found in other Luminary 099 files, or if the task largely requires writing stuff from scratch.
Outside of the general formatting concerns, here is what you should keep in mind:
-
Don't worry about anything to the left of the label column, aside from comment lines that extend all the way to the left. It's largely metadata or binary provided to or generated by YUL, and it doesn't matter for our purposes. The labels constitute our leftmost data.
-
Differences in comments count! Ideally we'd like letter-for-letter transcriptions of everything. And unlike the code, we don't get any checks at the end that the comments are correct. So please pay special attention to making the comments exactly match the scans, even if they have typos! There's also likely to be a lot of lines of code that are the same as lines in Luminary, but that have slightly different comments. Be sure to change them too, not just the code!
-
This listing of Aurora was used by members of the DAP Group for development, and as such, has a number of handwritten notes scattered throughout (though mostly focused in the DAP sections). There's even several instances of instructions being crossed out, and replacements written next to them. In all situations, transcribe what was printed by YUL, not what the programmers suggest in their notes. However, the handwritten notes are very cool, so please include them in ##-style annotations as described in the Formatting section!
When in doubt about how to handle a situation, just ask us on the issue, or look at how it was done for other listings. They are all available here.
Once you're happy with your work, open a pull request back to us, and reference the issue it corresponds to. We'll give your changes a quick review and merge them in... and give you another task, if you're willing to stick with it!
Before getting into specifics, it is worth pointing out that yaYUL, our assembler, is now capable of reformatting code. To get yourself going with it, do the following in your clone of the repository:
mstewart:~/virtualagc$ cd yaYUL
mstewart:~/virtualagc/yaYUL$ makeAnd that's it! To reformat your code, you can do the following:
mstewart:~/virtualagc/Aurora12$ yaYUL --format DAPIDLER_PROGRAM.agc > DAPIDLER_PROGRAM.agc.newSwapping out DAPIDLER_PROGRAM for whatever you're working on, of course. yaYUL prints out the reformatted code to its standard output, so you need to redirect it to a new file. You can then review the changes in your .new file to make sure you're happy with the results, and then copy it over the original un-reformatted code.
NOTE: If you're starting from a Luminary 099 file, it's a good idea to do this first, or you'll end up with a terrible mess of tabs and spaces.
With all that said, here's what it actually does:
We're trying to standardize on a single indentation for Aurora, and 8 space indents is what was chosen. Set your editor for 8 spaces, and please try to avoid tabs!
The character '#' is used to begin comments. This wasn't the case for the original YUL, so you'll need to add it at the front of every comment.
Comments on their own line should start in column 1. Comments on the same line as code or data should start in column 41 (5 indentations).
Include in your transcription the beginning of each page. An example from Luminary 099:
SETTIME5 CAF MS100
TS TIME5
# Page 1413
TCF RESUME
EBANK= AOSQ
IDLERADR 2CADR DAPIDLER
Programmer-defined names (such as program labels and constants being defined) begin in column 1. They are 8 characters or less in size, and may contain any character except '#', and may not begin with the character '$'. (For example, "-1/(D)+A" would be a legal constant name or program label.)
In some cases, a line may have no program label but may have a field such as "-1", "+1", "+110", etc., preceding the opcode. These notations appear to serve merely as comments, and are simply ignored by yaYUL. They should be placed starting in column 2.
AKA two indentation levels in. If preceded by a "-", the "-" should go in column 17.
AKA three indentation levels in. Options to these operands can be added with spaces separating them.
A #**# comment can be inserted to denote comments written by us humans, rather than by listing itself. We use it for the page breaks, as seen above, and various other discussions about the code.
For Aurora, we also intend to use this feature to capture the notes written onto the listing by the DAP Group developers. If you find an instruction crossed out, with stuff scribbled next to it, make a note of it and copy it all down with a #**# comment.
We'll still gladly accept your help! Just email us as described in the "Getting an Assignment" section and we can handle things that way.