Documentation Conventions

Structures in Memory and I/O space

These shall be drawn with the lowest address at the top, and addresses incrementing down the page. This is consistent with declarations in C:

    struct {
base+0 alpha char alpha;
base+1 beta char beta
    }

Memory Maps

These shall be drawn with the lowest address at the top, and addresses incrementing down the page. This is consistent with structures described above.

0000

...

FFFF
start

...

end
 
 
 

Diagrams and Figures

These shall have their titles at the top. This is opposite to most paper documents. I suspect pictures were historically labelled at the bottom, so that the titles of large pictures on a wall were at a readable height. However, when titles are made an HTML bookmark, and browsers jump to them, they appear in the top left. If the diagram was above the title, it would not be seen without scrolling. Therefore it is more ergonomic to have the title above.

Where several diagrams follow each other, there shall be a horizontal line between them to clarify which title belongs to which diagram

Stack diagrams

These shall be drawn with the top of the stack at the top of the page, like so.

    push,   push,   pop,   pop  
FFFE         K        
FFFF     J   J   J    
0000                  

In the example above, the stack pointer is initially cleared to zero and the stack is empty. The first 'push' pre decrements the SP to FFFF and writes the first byte (J) to the stack.

This is a very intuitive convention, because in real life stacks of objects start at the bottom and build upwards. A stack of coins on a desk is a good example, because coins have a range associated integer values.

It is certainly more correct that the common analogy of the pop-up stack of plates in cafeteria, which suggests the whole stack of objects moves around.

By good fortune, most of the common processors decrement the stack pointer when objects are pushed onto the stack.
This allows the stack diagram convention to be consistent with the memory map convention.

Active Low Signals

These shall be indicated by prefixing with the character '!'. This is because HTML does not support overlining, and the '/' character is slightly ambiguous when used in a signal has two meanings. For example, R/W on the 6502 indicates Reading when high and Writing when low. The signal name could be read as Read Not Write (correct) or Read Or Write (wrong). Using '!' clarifies the name R/!W by explicitly indicating the active low part, and the name is read as Read or Not Write.

Best viewed with...

Internet Explorer. I use this to check my pages. It's not great on all machines, due to the way people write their pages. Specifying sizes of graphic objects in pixels, or fonts, means that text gets very hard to read if you have small pixels. As I discovered on my laptop, which is 1400x1050 pixels in a 15" diagonal screen. IE6 only has 5 settings for magnifying default text sizes, but this is ignored if the page source specifies the font size. Thus I found myself squinting at squitty little text that was hard enough to read on my old 1024 x 768 display.

Mozilla Firefox lets you zoom all text, which is handy if you have poor eyesight (or wish to avoid eyestrain). Unfortunately it doesn't show tables the same way as IE6: the table and cell border colour attributes are all default greys, while many of my pages rely on such colours. According to http://validator.w3.org/ there is no attribute "BORDERCOLOR" so I assume this is a Microsoft non-standard feature, but a very useful one in my opinion.

This site is designed with Aerial as the default font, as this is simple and easy to read. Courier New is the default fixed-pitch font.

Internet Explorer seems to have some bugs. Most irritatingly it fails to show tabbed preformatted text when 'Text Size' is not 'Medium' text. This pressures pages to use space characters instead. It also fails to handle the 'expand/contract' icon when scrolling images using a thumbwheel mouse, leaving bits of the icon up and down the screen. Firefox does not have these problem.

HTML generated by Frontpage Express

This is a compromise between the tedium of editing HTML directly with a text editor, and using Microsoft Word. The latter describes everything in so much detail that files end up being three times bigger. And because it specifies so much, IE6 does not zoom them.

Conventions for physics units

See the NIST rules for unit names. For example, volt is only capitalised at start of sentences.