This is a typical osimplay routine...
....................................................................

                # "ALLOW TIMEOUTS!"  Frank Da Cruz (kermit)


L sendHID               # send A to HID with wait/send-anyway
        push C
                = 10000000 to C
   L sendHIDwait
                when not C-1 sendHIDbail
                        recieve byte 0x64
                        AND byte $_______I to A
                when not zero   short sendHIDwait
   L sendHIDbail
        pull C
        send byte 0x60
                                                return

.....................................................................

Some of this is similar to stock C-world dogma as enunciated by e.g. Rob
Pike, and some isn't.

Indentation is a radical improvement for assembly. Bizarre, isn't it?
People have learned thier assembly formatting style from FORTRAN
compilers. Mechanistic formatting is also indicative of fear of doing
something non-standard in the vicious world of assembly. Fear osimplay's
slowness, bugs in areas I haven't used osimplay for, shell-state-issues
treachery and so on, but please, be bold enough to be legible.

Indentation is subjective. Make it beautiful. Indent on any important
state-change, like a change in $cell, pushes, whatever. I usually indent a
call by 2 spaces, implying, to my eye, a splice.

Linus is out to lunch. Tabs are not 8 spaces. Tabs are tabulations to the
next preset tab-stop. Tabulation is "make a table". Columnize. 8 is
standard in C-land because tab was hardwired to 8 on a Teletype Model 37.
8 also happens to be hardwired in Pico, which is my plain-typing-editor,
and Pico overrides the shell if you have other settings. That's a "just
live with it" in exchange for Pico's deeply considered simplicity, but
tabs are tabs. If you want 4 spaces, use 4 spaces. If you want tabs, don't
use editors and formatters that un-tab them.

Capitalization is ala English as much as possible. Acronyms are
capitalized; common name words aren't. I tend not to capitalize words like
count in ringcount, but if there's an acronym I stick it where it obviates
that problem, as in sendHIDwait. On the other hand, if you name something
after Ken Thompson, capitalize it ala Ken, not ken.

Verbosity is proportional to rarity. Pike et al do the same, but not with
assembly "mnemonics" like "=" and "return". 

This code is only commented above it. Comments are transient, but if code
is stable, which the above actually probably isn't, the above format is
about right.

HID is Human Input Device, keyboard or mouse. That is global to the file
the above routine is in, which justifies the neologizing. It's also
explained in that file. Back to Pike: humans handle context well, if they
know what it is. That's how "=" and "HID" came about.

I used $_______I instead of 1. That's because it's the 0-bit, not the
number 1. $bit0 would have been good too.

osimplay doesn't do flow-control abstractions for plain branches. The
above code may not be obvious, but it's unambiguous. Proper factoring will
prevent real rat's-nests. If you ever want your code to work, that is.

The above routine was two routines, which got un-factored into the one
shown. That was because the component routine was not useful outside the
above routine. Thus the namespace burden was not worth the per-routine
simplicity. BUT, if things are useful separately, keep them separate. The
debuggability of a routine is inversely exponentially proportional to its
size. Size in this case means complexity. A big unrolled loop is
semantically the same size as the looping version, or smaller. But the
above routine is right about at the line where you want to fight hard to
not get any bigger. 

osimplay currently has no facilities for name scoping. Bash has locals,
but I haven't fooled with them in osimplay. Labels need to be verbose, or
common and important. For macros you have to not use internal label names.
Use $((H+whatever)) and figure the branch offset by hand. Then there's the
JET Thomas approach of using e.g. KDFNVVKVNNVFnvfjnvff for a highly
forgettable interior label. sendHIDbail could just as easily be
ldfvkgfuhgfugfb or fkbffhffhf. Be nimble though; I actually had a conflict
like that once.

I like my returns at the right end of the line. Personal preference. I
like just the starts of routines hitting the left margin.  Return is a
very indicative instruction, though, and gets a spare line in the
post-assembly listing for that reason.

The L line of a routine is the most important comment, much like a Forth
stack diagram or a C declaration, simply because it's easy to grep up a
glossary with those lines.

There is no variable name for 0x64 in the above, which is the keyboard
controller command input port on a post-MCA PC. What it is is evident from
context.  Slinging lots of constants and structs feels like programming,
but puts no bits in RAM. A comment is as good as a macro. No comment may
be better.

The left side of the screen is important stuff. Comments work toward the
left from the right. Code works left TO right. The routine name is
left-most.

Code according to context. You don't use a first-order triangulation
theodolite to set the line to trim a hedge by. If you don't need
super-lean-mean code code then go for clarity and genericness.

Use the cheap stuff liberally; labels and whitespace. 

I'm in the habit in assembly now of pushing anything I touch that I wasn't
passed. sendHID gets A passed to it, but it clobbers C also without having
been passed it, so it saves the incoming C on the stack. Do that all the
time and you just know if you aren't passing it you won't be losing it.
