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:

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:

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.

Important Exceptions to ## Processing

In AGC source code, there are remarks present in the original source code, provided contemporaneously by the original AGC developers, and of necessity there are also comments added by "modern" annotators of the code, and it is essential to distinguish between those somehow.  No such method of distinguishing between these two types of comments has been formalized in any technical sense, but there are approaches which have been used.

One technique is the one described in the preceding section, which is simply to use '#' to precede all of the original comments, and '##' to precede all later comments.  This idea has great merit, but would result in a very poor presentation in HTML if all ## comments were always processed precisely as described in the preceding section.  The specific culprits would be the headers (consisting of a large number of comments describing the origin of the data, how it was edited, and so on) that we always add to the top of each AGC source-code file, as well as the page numbers we embed in the source-code files making it easy to relate the source-code to the original scans of the AGC programs or the hardcopies of the programs.

Consequently, there are two exceptions to the processing of ## comments:

These two exceptions should, in most cases, make it feasible to mark all "modern" comments with ##, while still taking advantage of the special highlighting that ## provides in the HTML-formatted output.

### Annotations

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"

More-generally, This command can be used to inject any amount of arbitrary HTML at any point in the HTML versions of the program listings, in a specific source-code file, and isn't limited to boilerplate that is duplicated in multiple files.  Thus it can be used to create annotations of any desired complexity.  However, it should be noted that while such annotations are great for the HTML versions of the program listings, they don't appear at all in the normal (non-HTML) listings output by yaYUL, nor in the source code itself, as anything other than a filename.  So its utility is limited to things that you only want to show up in the HTML versions of the program listings.  Note only that but the ### annotations are not automatically formatted for you in any way, in contrast to the ## annotations which are automatically formatted as shown earlier, and thus are somewhat harder to manage stylistically.  Most source-code sets do have a Main.annotations file which can be used as a template for producing ###-annotation formatting similar to the ## annotations.  Nevertheless, in these respects, the ## annotations, while more-limited in flexibility, are superior for routine program annotations.

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 2016-10-13.

Virtual AGC is hosted
              by ibiblio.org