|
Virtual AGC — AGS — LVDC — Gemini
Source-Code Annotations
for yaYUL and yaLEMAP
|
|
|
|
Please enable javascript in your browser to see a site-search form here.
|
Source-Code Presentation Formatting
The principal raison d'etre
for AGC/AGS assembly-language source code as provided by the Virtual
AGC project is to be able to assemble the source using the yaYUL/yaLEMAP programs
to obtain binary executable programs which can be run on the yaAGC/yaAGS CPU
simulators. However, there is a secondary purpose, and that is to
be able to compile the source code into a nice presentation format that
is both attractive and which can aid students of this software in
understanding how it operates. For this reason, the yaYUL/yaLEMAP assembler software has the
capability of creating an HTML form of assembly listings which can be
viewed in a browser.
The HTML form of the assembly listings has various useful properties
lacked by the raw source code, including the following:
- It has syntax highlighting, so that different types of language
elements (basic instructions, interpretive instructions, pseudo-ops,
variables, etc.) have different colorization and therefore can be
more-readily distinguished from each other.
- Usages of program-defined symbols (line labels, variables,
constants) are hyperlinked to the points where the symbols are actually
defined, thus making it easier to trace program flow.
- Modern annotations can be added to the software, to supplement
the program comments of the original developers. These modern
annotations are presented in a different visual style from the source
code, and so it is clear that they are supplemental rather than
original.
The Strategy of Modern Annotations
Addition of modern annotations to the source-code is an on-going
process that will likely take many years (or decades) to complete, and
at this writing (20090703) is only in its infancy. If you would
like to assist in this task, please look at the volunteer page. But note that helpful,
insightful annotations can only be the product of expert knowledge of
the affected source-code modules, so expect to work hard to produce
them. My general strategy for providing these annotations
is:
- To fully annotate the Apollo 11 source code—AGC Luminary 099, AGC
Comanche 055, AGS Flight Program 6—to the extent possible.
- To fully annotate changes in software from mission to
mission. For example, the Apollo 12 software (if it was
available) would be annotated to explain how it differs from Apollo 11
software.
Annotation Language
Annotations are added directly to AGC/AGS source-code files, where they
are transparently discarded during normal assembly, but are used in
creating HTML forms of the assembly listing. To create the HTML
output, yaYUL and yaLEMAP require the "--html"
command-line switch. Annotations are pure HTML, but can have
styling applied to them to provide a distinctive appearance generally
with few or no actual HTML tags needed. There are two forms of
syntax which may be used, and they may be intermixed, but we highly
recommend using only the form we call "##" annotations, and avoid the
form we call "<HTML>" annotations. The latter is described
only for completeness.
Recommended "##" Annotations
In this form of annotation, which is highly recommended, all embedded
HTML takes the form of normal program comments, except that the
comments begin with "##" instead of just "#". Only "##" comments
beginning at the start of a line participate in becoming embedded
HTML. In other words, there can be no leading text or spaces
preceding the "##" on a line. This form is recommended because in
most cases it naturally appears to be a program comment, and so is
relatively comfortable and non-intrusive for someone reading the source
files themselves. This idea is based on the style of annotations
used by the doxygen
system, though pure HTML is used in place of doxygen's custom markup language.
The basic markup looks like this:
...
... AGC or AGS source code ...
...
## HTML statements
## ,,,
...
... AGC or AGS source code ...
...
What happens is that any set of consecutive "##" lines has the "##"
stripped from the beginnings, and the remainders are inserted directly
into the output HTML. At any given time there is a default
styling in effect (more on this below). Prior to outputting the
embedded HTML, the styling that was being used for source code is
cancelled and the default styling for embedded HTML is initiated.
Similarly, at the end of the embedded HTML block, the default HTML
styling is terminated and the styling used for source code is started
again. Therefore, the "##" statements containing the embedded
HTML are usually very simple and often consist entirely of text without
any HTML tags at all. For example, with the default styling
presently being supplied, here's a side-by-side comparison of the
source code to HTML annotation:
## This is a <i>sample</i>
## annotation.
|
 |
This is a sample annotation.
|
|
It is important to note that the <br>
tag must be used for paragraph breaks (if any), since otherwise all of
the text will be reflowed into one large paragraph as in the example
above.
Styles are defined with statements like "### STYLE=something" (note the use of
"###" rather than "##") and remain in effect until canceled or
changed. In theory, styles can be changed on-the-fly, but there
is presently (20090703) a bug which causes assembly to break if you do
that, so it's best at present to stick with a single style. The
types of style statement are as follows:
### STYLE=NONE
|
This means that no special
styling will be used.
|
### STYLE=BOX nn%
|
This means that the embedded
HTML will be placed in a centered box nn% the
width of the display.
|
###
STYLE=START html
|
These
three types of statements work together to create a user-defined
style. The START
command is used to define whatever HTML is needed to initiate the
style. For example, it might set a font face and a text
color. However, for complex styles, the startup HTML may be very
long and may not conveniently fit on a single line. (It is best
to keep the line lengths similar to those of the assembly-language
itself.) In that case, the START+
command can be used to supply as many continuation lines of HTML as may
be necessary. Finally, the END
command is used to supply the HTML needed to discontinue the style at
the end of the annotation.
|
###
STYLE=START+ html |
### STYLE=END html |
### STYLE=USER |
This is used to resume a
previous user-defined style which has temporarily been discontinued by STYLE=NONE or STYLE=BOX.
|
In some cases, it may be useful to take user-defined styles or
boilerplate annotations from a separate file, so that they can easily
be included in all source files without having to duplicate the same
material over and over. This is done with the statement
###
FILE="filename"
If a file called "Default.style" exists, it will automatically be
included at the start of every source file. The Default.style
supplied by Virtual AGC produces the sample annotations style shown
earlier. It creates a table with one row and two columns, with
the left-hand cell containing a graphic and the right-hand cell
containing the embedded HTML. The file itself looks like this:
###
STYLE=START <table style="text-align: left;" border="1"
cellpadding="2" cellspacing="2">
### STYLE=START+ <tbody>
### STYLE=START+ <tr>
### STYLE=START+ <td
style="white-space: nowrap; vertical-align: middle;">
### STYLE=START+ <img alt=""
src="Apollo32.png" style="width: 32px; height: 32px;" align="left">
### STYLE=START+ </td>
### STYLE=START+ <td
style="vertical-align: middle;">
### STYLE=END
</td></tr></tbody></table>
Finally, a statement like
###
ANCHOR=name
provides a destination for hyperlinks like "#name". This is exactly
equivalent to
###
<a name="name">
but is provided separately in order to be less intrusive when reading
the source files.
Deprecated "<HTML>" Annotations
This type of annotation, which (I repeat) I strongly advise against,
takes three possible forms, of which the prototypical form is:
...
... AGC or AGS source code ...
...
<HTML>
... HTML statements ...
</HTML>
...
... AGC or AGS source code ...
...
Note that the indentation between the <HTML> and </HTML> tags is not
really needed, but is just there to make the construct less
unattractive. However, the tags themselves are supposed to appear
by themselves, with nothing else on the line with them, and no leading
spaces. Using this form, any HTML whatsoever can be embedded, and
no styling is applied to it. However, any styling being applied
to the source code that precedes it is cancelled, and the source code
styling is then resumed after the embedded HTML, so even if the
embedded HTML is just simple text, it will still have a different
appearance in terms of font, size, and color than the surrounding
source code.
It is important to note that the <br>
tag must be used for paragraph breaks (if any), since otherwise all of
the text will be reflowed into one large paragraph.
There is nothing really wrong with this style of annotation, except
that it simply does not look like AGC assembly language, and is
therefore jarring when encountered in an assembly-language source file,
and that's why I advise against using it.
Similar to this is the form:
...
... AGC or AGS source code ...
...
<HTMLnn>
... HTML statements ...
</HTML>
...
... AGC or AGS source code ...
...
where nn
is supposed to be any decimal number from 1 to 99. This form
works exactly the same way as the "<HTML>"
form, except that the embedded HTML has a box drawn around it which is nn% as wide
as the display, thus calling even greater attention to the
annotation. The box is horizontally centered on the screen, but
the aligment within the box can be anything you like.
Finally, we have the form
...
... AGC or AGS source code ...
...
<HTML "filename">
...
... AGC or AGS source code ...
...
In this form, filename
is the name of a file containing HTML, but it will not generally be a
legal HTML file itself, since it will lack the necessary headings and
tags that a complete HTML file will have.
Last modified by Ronald Burkey on 2009-08-17.
