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.
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:
- Any comment of the form "## Page ..." is simply treated as
a regular comment, and printed with two ## rather than one #,
but not subject to any special highlighting as described in the
preceding section; and
- File headers — defined as any sequence of lines beginning
with ## in column 1 or lines that have nothing but blanks in
them — are also treated as normal comments without any special
highlighting.
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.
This page is available under the Creative
Commons No Rights Reserved License
Last modified by Ronald Burkey on 2017-01-11.
