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.