AWF

Section: User Commands (1)
Updated: 13 July 1990
Index Return to Main Contents

NAME

awf - amazingly workable (text) formatter

SYNOPSIS

awf -macros [ file ] ...

DESCRIPTION

Awf formats the text from the input file(s) (standard input if none) in an imitation of nroff's style with the -man or -ms macro packages. The -macro option is mandatory and must be `-man' or `-ms'.

Awf implements the following raw nroff requests:

       .\"    .ce     .fi     .in     .ne     .pl     .sp
       .ad     .de     .ft     .it     .nf     .po     .ta
       .bp     .ds     .ie     .ll     .nr     .ps     .ti
       .br     .el     .if     .na     .ns     .rs     .tm

and the following in-text codes:

\$    \%     \*     \c     \f     \n     \s

plus the full list of nroff/troff special characters in the original V7 troff manual.

Many restrictions are present; the behavior in general is a subset of nroff's. Of particular note are the following:

*: Point sizes do not exist; .ps and \s are ignored.
: * Conditionals implement only numeric comparisons on \n(.$, string comparisons between a macro parameter and a literal, and n (always true) and t (always false).
: * The implementation of strings is generally primitive.
*: Expressions in (e.g.) .sp are fairly general, but the |, &, and : operators do not exist, and the implementation of \w requires that quote (') be used as the delimiter and simply counts the characters inside (so that, e.g., \w'\(bu' equals 4). White space at the beginning of lines, and imbedded white space within lines, is dealt with properly. Sentence terminators at ends of lines are understood to imply extra space afterward in filled lines. Tabs are implemented crudely and not quite correctly, although in most cases they work as expected. Hyphenation is done only at explicit hyphens, em-dashes, and nroff discretionary hyphens.

MAN MACROS

The -man macro set implements the full V7 manual macros, plus a few semi-random oddballs. The full list is:

.B   .DT     .IP     .P      .RE     .SM
.BI  .HP     .IR     .PD     .RI     .TH
.BR  .I      .LP     .PP     .RS     .TP
.BY  .IB     .NB     .RB     .SH     .UC

.BY and .NB each take a single string argument (respectively, an indication of authorship and a note about the status of the manual page) and arrange to place it in the page footer.

MS MACROS

The -ms macro set is a substantial subset of the V7 manuscript macros. The implemented macros are:

.AB  .CD     .ID     .ND     .QP     .RS     .UL
.AE  .DA     .IP     .NH     .QS     .SH     .UX
.AI  .DE     .LD     .NL     .R      .SM
.AU  .DS     .LG     .PP     .RE     .TL
.B   .I      .LP     .QE     .RP     .TP

Size changes are recognized but ignored, as are .RP and .ND. .UL just prints its argument in italics. .DS/.DE does not do a keep, nor do any of the other macros that normally imply keeps.

Assignments to the header/footer string variables are recognized and implemented, but there is otherwise no control over header/footer formatting. The DY string variable is available. The PD, PI, and LL number registers exist and can be changed.

OUTPUT

The only output format supported by awf, in its distributed form, is that appropriate to a dumb terminal, using overprinting for italics (via underlining) and bold. The nroff special characters are printed as some vague approximation (it's sometimes very vague) to their correct appearance.

Awf's knowledge of the output device is established by a device file, which is read before the user's input. It is sought in awf's library directory, first as dev.term (where term is the value of the TERM environment variable) and, failing that, as dev.dumb. The device file uses special internal commands to set up resolution, special characters, fonts, etc., and more normal nroff commands to set up page length etc.

FILES

All in /usr/skunk/lib/awf (this can be overridden by the AWFLIB environment variable):

common common device-independent initialization
dev.*  device-specific initialization
mac.m* macro packages
pass1  macro substituter
pass2.base     central formatter
pass2.m*       macro-package-specific bits of formatter
pass3  line and page composer

DIAGNOSTICS

Unlike nroff, awf complains whenever it sees unknown commands and macros. All diagnostics (these and some internal ones) appear on standard error at the end of the run.

HISTORY

Written at University of Toronto by Henry Spencer, more or less as a supplement to the C News project.

rh None of the above really want to admit it. lh

BUGS

There are plenty, but what do you expect for a text formatter
written entirely in (old) awk?

The
-ms
stuff has not been checked out very thoroughly.

This document was created by man2html, using the manual pages.
Time: 04:06:58 GMT, December 02, 2024

AWF