f91bc2804d
This commit slightly improves the formatting of the manuals. My
OpenBSD machine uses mandoc(1) to format manuals. I check the manuals
with `mandoc -T lint` and fix most of the warnings. I also make
other changes where mandoc didn't warn me.
roff(7) says, "Each sentence should terminate at the end of an input
line," but we often forgot this rule. I insert some newlines after
sentences that had ended mid-line.
roff(7) also says that blank lines "are only permitted within literal
contexts." I delete blank lines. This removes some extra blank lines
from mandoc's output. If I do want a blank line in the output, I call
".sp 1" to make it in man(7). If I want a blank line in the source,
but not the output, I put a plain dot "." so roff ignores it.
Hyphens used for command-line options, like \-a, should be escaped by
a backslash. I insert a few missing backslashes.
mandoc warns if the date in .TH doesn't look like a date. Our manuals
had a missing date or the RCS keyword "$Revision$". Git doesn't
expand RCS keywords. I put in today's date, 2017-01-18.
Some manuals used tab characters in filled mode. That doesn't work.
I use .nf to turn off filled mode, or I use .IP in man(7) to make the
indentation without a tab character.
ack(1) defined a macro .SB but never used it, so I delete the
definition. I also remove a call to the missing macro .RF.
mandoc warns about empty paragraphs. I deleted them. mandoc also
warned about these macro pairs in anm(1):
.SM
.B text
The .SM did nothing because the .B text is on a different line. I
changed each pair to .SB for small bold text.
I make a few other small changes.
53 lines
1.7 KiB
Groff
53 lines
1.7 KiB
Groff
.TH EM_B 6 2017-01-18
|
|
.ad
|
|
.SH NAME
|
|
em_b \- ACK B compiler
|
|
.SH SYNOPSIS
|
|
.B ~em/lib/ack/em_b
|
|
.RI [ options ]
|
|
.SH DESCRIPTION
|
|
.I em_b
|
|
is a port of the ABC B compiler to the ACK.
|
|
Interested parties will be
|
|
interested in the upstream distribution here:
|
|
.nf
|
|
.sp
|
|
https://github.com/aap/abc
|
|
.fi
|
|
.PP
|
|
However, the version here has been heavily modified \(em bug reports should be
|
|
filed with the ACK, not with the upstream compiler.
|
|
.PP
|
|
Since B was designed for machines with word addressing, some hacking is
|
|
required to make it work on modern, byte addressed machines.
|
|
The generated
|
|
code expects B variables to contain word addresses, and then generates
|
|
code to transform these into native addresses before use (which,
|
|
unfortunately, impacts performance).
|
|
However, the ACK's linker doesn't know
|
|
how to emit word addresses into the program's data sections, and so a
|
|
separate fixup stage has to happen at runtime, just before \fBmain()\fP,
|
|
to convert the byte addresses into word addresses.
|
|
.PP
|
|
The end result is that using multiple source files with B is somewhat
|
|
unwieldy, requiring each module to be explicitly named and then an extra
|
|
stage to generate the fixup code.
|
|
See the \fBack\fP(1) and \fBabmodules\fP(1) for details.
|
|
.SH OPTIONS
|
|
.I em_b
|
|
accepts the following flags:
|
|
.IP \-w\ \fIsize\fP
|
|
Sets the word size, used for scaling addresses.
|
|
Usually either 2 or 4.
|
|
.IP \-B\ \fIname\fP
|
|
Sets the name of the module currently being compiled (used to generate the
|
|
fixup table symbol name).
|
|
Defaults to \fImain\fP if not specified.
|
|
.IP \-i\ \fIfilename\fP
|
|
The source B file.
|
|
.IP \-o\ \fIfilename\fP
|
|
The output compact EM bytecode file.
|
|
.SH SEE ALSO
|
|
\fIack\fR(1), \fIabmodules\fR(1)
|
|
.SH REMARKS
|
|
It is very unlikely the \fIem_b\fP will ever be useful for anything.
|