OS/2 Professional/OS2PRO194.ISO/os2/editor/cawf/cawf407.lzh/00README

Text File | 1993-12-31 | 16KB | 415 lines

Cawf - nroff-like text formatter

Cawf is a C version of awf, Henry Spencer's Amazingly Workable (text)
Formatter.  (Awf is written in awk and appears in comp.sources.unix,
Volume 23, Issue 27.)  Cawf and awf provide a usable subset of raw nroff
capabilities and the styles of the man(7), me(7) and ms(7) macro sets.  One
of cawf's virtues is that it will run on PC clones under MS-DOS or OS/2.  It
is also, like awf, totally independent of any licensed Unix source code.
Another cawf virtue is that it supports more nroff functions and one more
macro style -- ME -- than awf.

This distribution contains: complete source; make files for Unix, MS-DOS,
and OS/2; documentation (raw and formatted); and MS-DOS executables for cawf
and a companion output filter, bsfilt.

This is the version 4.07 distribution of cawf.  Changes include:

    *  Some rudimentary output device support has been added, via a device
       configuration file.

    *  The code has been converted to use unsigned characters.

    *  An attempt has been made to make the code ANSI C compliant.

    *  The following bugs have been fixed:

        A bug in the locating of the device file has been corrected,
        so that the code performs as documented.

        Null macro arguments are ignored.

        Some unused arguments to local functions have been more
        carefully type cast to avoid portability problems.

    *  The .fl and .rn requests are now supported.

    *  Limited support has been added for the non-break request control
       character, the acute accent (').

    *  Argument count conditionals -- operating on \n(.$ -- may now use
       the >= and <= operators in addition to [<=>].

    *  Macros may be terminated with "..", ".", "''" or "'".

    *  String interpolation is performed if it is specified at the start
       of the defined value -- i.e., the string value may be a request
       for interpolation of another string.

    *  In .ds string values "\\b" is converted to '\b' and "\\\\"" is
       converted to '\\'.  No other sequence, beginning with '\\', is
       modified.

    *  The .tr request has been enhanced to handle named characters and
       string interpolation.

    *  The SS macro is now included in man.mac.

    *  The cawf version number is now displayed in the help output.

    *  A limited -me macro set is included in me.mac.

    *  Some forms of the hyphen -- e.g., one of two `-' characters at
       the start of a word or ME(7)'s \*- -- will now be output in bold
       or italic face, if they're in effect.  See cawf(1) for a complete
       description of the rules of hyphenation and the output of hyphen
       characters.

       A bug was corrected in the handling of the \*(em hyphen.

    *  Three part titles -- the .tl and .lt commands -- are now supported.

    *  4.02 handles TABs better.

    *  4.03 handles NULL characters in font and device definitions
       properly.

    *  4.04 changes include:

       o  The -n<starting_page_number> and -o<page_number_range> options
          are supported.

       o  The current date is preset in the ME td string or the
          MS DY string.

       o  The MS CH string is preset to "- % -" and the CH string
          is preset to \*(DY.

       o  Some minor bug fixes were made.

          .  The binary search in the Nreq() function in nreq.c is
         now constrained to the proper length.

          .  Null strings -- e.g., defined with ".ds xx" -- are
         now handled correctly.

    *  4.05 changes include:

       o  MS-DOS now uses the Borland C++ 3.1 compiler.  Accordingly:

          .  The bsfilt.mak and cawf.mak make files for MS Quick C
         have been replaced by makefile.bcc.

          .  Some additional ANSI C purifications have been performed.
         (The _ANSI definition is now required for Borland C++ 3.1.)

       o  Two new initialization directives are supported:

          .  .^b lf n

         This directive sets the page footer section line count to
         n-1.

          .  .^b lh n

         This directive sets the page header section line count to n.

           See cawf(1) for a more complete description of them.

    *  4.06 changes include:

       o  Header and footer strings may now contain some in-text
          codes, including:

          .  Font specifications via \f;

          .  Number register interpolations via \n;

          .  String interpolations via \*;

          .  Escaping of other characters with \.

          See cawf(1) for a more complete description of the header
          and footer controls.

       o  Some Borland C++ 3.1 source code dependencies are now
          controlled under the _BCC #define.

       o  Hard spaces -- "\ " -- are handled better.

    *  4.07 changes include:

       o  Support was added for OS/2, using the Microsoft or EMX GNU
          C compilers.  The __EMX__ definition selects some code
          conditionally defined for the EMX GNU C compiler.

          The OS/2 support was provided by Darrel Hankerson
          <[e-mail]>.  Executables may be obtained via
          anonymous ftp from ftp-os2.cdrom.com (192.153.46.2) in
          pub/os2/all/unix/cawf4*.zip.  Please direct questions about
          compiling and using cawf under OS/2 to Darrel.


CONTENTS
--------

This Unix distribution of cawf includes:

    00readme    this file
    00diffs        description of differences between cawf and [nt]roff
    *.c and *.h    source files to build cawf and bsfilt (bsfilt
            removes Backspaces from cawf output)
    bsfilt.1    nroff source for the bsfilt manual page
    bsfilt.def    linker definition file for OS/2 16 bit versions
    bsfilt.exe    bsfilt executable for MS-DOS
    bsfilt32.def    linker definition file for OS/2 32 bit versions
    cawf.1        nroff source for the cawf manual page
    cawf.def    linker definition file for OS/2 16 bit versions
    cawf.exe    cawf executable for MS-DOS
    cawf32.def    linker definition file for OS/2 32 bit versions
    common        initialization file for CAWFLIB library
    device.cf    output device configuration file for CAWFLIB library
    dumb.dev    device description file for CAWFLIB library
    Makefile    Unix-style make file
    makefile.bcc    Borland C++ 3.1 command-line make file
    makefile.os2    makefile for Microsoft C and EMX GNU C (mostly for
            OS/2, but will produce DOS executables, too)
    man.mac        man(7) macros for CAWFLIB library
    me.mac        me(7) macros for CAWFLIB library
    ms.mac        ms(7) macros for CAWFLIB library
    strcasecmp.c    the strcasecmp() function from BSD4.3 (See the
            discussion under STRCASECMP for information on when
            you might need to use this.)



LIBRARY
-------

To use cawf, you must select a location for the CAWFLIB library files.  The
distributed cawf.exe expects to find them in c:\sys\lib\cawf, but you can
alter that with the CAWFLIB environment variable, or you can change the
CAWFLIB #define in cawf.h and rebuild cawf from the sources.

CAWFLIB contains a minimum of six files:

    common        common raw nroff commands to get cawf started
    dumb.dev    a set of character definitions for a plain, "dumb"
            ASCII device - e. g., the console display, a CRT or
            a basic line printer
    device.cf    the output device configuration file
    man.mac        the man(7) macros
    me.mac        the me(7) macros
    ms.mac        the ms(7) macros

You may want to add your own macro files to the library.  Just name them
"m[your-name].mac", following the usual nroff naming convention for macro
files.

If you have fancy output devices with special character specifications, you
may want to generate new *.dev files for them.  Follow the format of dumb.dev
in making new character specifications.  To define characters for a new
device, select a name prefix for it and create a file in CAWFLIB with the
name "<prefix>.dev".  To use the new file, set the TERM environment variable
to <prefix> - e. g., when I test cawf on Unix, I need a vt100.dev, because
my TERM environment variable value is usually vt100.  All I do is make
vt100.dev a symbolic link to dumb.dev.  Even that isn't even necessary,
because cawf will use dumb.dev if it can't find TERM.dev.

In addition to the character specifications possible through the *.dev files,
cawf provides one-time font selection and bold or italic face support for
output devices via its -d and -f options.  Cawf can be directed to issue
specific device codes for bold and italic characters, and one font can be
specified for the entire document.  Cawf has some built-in output device
support, and addition support is contained in the device configuration file,
device.cf.  Additional devices may be defined in device.cf.

It is not necessary to generate a new *.dev file for each output device
definition.  Only when you need special character definitions do you need to
create a *.dev file.  The dumb.dev file is adequate for most devices you
define in device.cf.


SOURCES
-------

A Unix make file and a make file for Borland's C++ 3.1 compiler are included.
The Unix make file has some definitions that help tune it to the local Unix
environment:

    _ANSI        must be defined for Borland C++ 3.1 to effect
            proper function prototype declarations.

    _BCC        must be defined to use Borland C++ #pragma
            statements.

    CAWFLIB        is a string that can be used in lieu of changes
            to cawf.h's CAWFLIB #define.

    __EMX__        must be defined when using the EMX GNU C compiler
            (usually under OS/2).  You must also use the special
            make file, makefile.os2.  See the OS/2 INFORMATION
            section.

    MALLOCH        is a string that should be defined when a UNIX
            environment has a <malloc.h>, unless it also has a
            <stdlib.h> with prototypes for malloc() and its
            relatives.  In the latter case, you should define
            STDLIB, but you don't need to define MALLOCH.

    STDLIB        indicates that standard library function prototype
            definitions may be found in <stdlib.h>.

            STDLIB must be defined for Borland C++

            If STDLIB is not defined, the cawf sources try to
            define their own library function return values.

    __STR__        The definition of this string must be deleted when
            using the xlc 1.2 compiler on the RISC/System 6000
            under AIX 3.2.  Put

                -U__STR__

            in the Makefile DEFS string.  This must be done
            because the xlc 1.2 compiler does not correctly inline
            string functions when compiling pass3.c.

    UNIX        switches the build environment to Unix.  You may also
            have to decide about MALLOCH, STDLIB, __STR__ and USG
            when you define UNIX.

            Do not define UNIX for Borland C++ 3.1; do define
            _ANSI and STDLIB.

    USG        adjusts for System V.  (UNIX must also be defined.)

            You may also need to define USG to select the proper
            header file for string function prototypes.  If UNIX
            and USG are defined, "proto.h" selects <string.h>;
            if only UNIX, <strings.h>.  Cawf needs the more
            complete set of definitions, including strchr() and
            strrchr().  If <string.h> #includes <strings.h>, as
            is sometimes the case, define only UNIX.

I have built and tested cawf in the UNIX context under AIX 3.2 (see the
note above on __STR__), BSD4.3-Tahoe, Sequent DYNIX, ETAV (SYSV 3.0),
NeXTStep 3.0, SunOS 4.1.1 and Ultrix 2.2.  If you build under another Unix
variant, you may have to adjust the source code, header files and Makefile
to fit.  Check the Makefile first for hints.


STRCASECMP
----------

Some platforms don't provide the strcasecmp() or strcmpi() functions for
case-insensitive string comparisons.  Strcasecmp() is used several times in
the Defdev() function of the device.c module.  Strcasecmp() is redefined in
device.c to be stricmp() for the EMX GNU C compiler for OS/2, and strcmpi()
for other non-UNIX compilers, including Borland C++ 3.1.

If you don't have either function in your run-time library, consider using
the strcasecmp() function in the enclosed strcasecmp.c file.  It is freely
distributable, subject to the restrictions noted in its comments.  You may
have to modify the code slightly -- Chet Creider reports that the Xenix C
compiler in the 2.3.0 Development System (based on Microsoft C 5.0) doesn't
accept the "const" keyword, while the 2.3.1 compiler (based on Microsoft C
5.1) does.  If you have a 2.3.0 system, remove the "const" keywords from
strcasecmp.c before compiling it.


ANSI C COMPLIANCE
-----------------

Some effort has been devoted to making the cawf sources ANSI C compliant.
The header file proto.h contains function prototypes that enable ANSI C
argument checking.  The state of definition of the __STDC__ symbol is used
to select options that depend on strict adherence to the ANSI C standard --
e.g., the need for the isascii() test before islower() or isupper().  If
your ANSI compiler doesn't define this variable when it's acting in strict
ANSI C mode, you may have to define it in the Makefile.

The Borland C++ 3.1 compiler must have the _ANSI symbol defined for proper
function prototype handling.


OS/2 INFORMATION
----------------

Cawf was ported to OS/2 in 1991 by Kai Uwe Rommel <[e-mail]>.
The lastest round of porting was done by Darrel Hankerson
<[e-mail]>.  I do not include OS/2
executables and cannot give OS/2 assistance, because I do not have an OS/2
test platform.  Executables may be obtained via anonymous ftp from
ftp-os2.cdrom.com (192.153.46.2) in pub/os2/all/unix/cawf4*.zip.  Please
direct questions about compiling and using cawf under OS/2 to Darrel.

Here's a note from Darrel:

    The "emxbnd" target will produce an executable which runs under both
    OS/2 2.x and DOS (32-bit), but requires run-time support from the emx
    distribution (available from ftp-os2.cdrom.com). It is possible to
    include the runtime support in the executable, in order to simplify
    the installation (at the price of larger executables).  The 16-bit
    "mscbnd" exe will run under all versions of OS/2 and DOS.


MS-DOS AND OS/2 SHELL CONSIDERATIONS
------------------------------------

The MS-DOS version of cawf was created to run under the KornShell of the
Mortis Kern Systems Toolkit.  One ramification of using MKS' ksh is that it
supports the separate standard error and standard output streams.  Hence,
cawf blithely distributes its error messages to the standard error file, and
assumes the user's shell is capable of separating them from standard output.

If you don't use the MKS KornShell, but do want to separate the output
streams, you'll have to modify the cawf source code, or obtain a shell that
does.  As a rudimentary aid to the modification process, cawf uses a separate
stream pointer, Efs, for writing error output, but sets it to stderr.  You
can change that process to open a separate error file and set Efs to point
to it.

There are several freely distributed shells that will separate standard
error and standard output streams.  Look for versions of ksh, bash and
Stewartson's sh for OS/2 1.x, OS/2 2.x, and MS-DOS on ftp-os2.cdrom.com
(192.153.46.2).


COPYRIGHTS AND CREDITS
----------------------

The sources are copyrighted, but freely distributable under usual terms -
retention of credit, etc.

Please acknowledge:

    AT&T for their public-domain release of getopt(3) at the 1985
    UNIFORUM conference;

    Chet Creider, Bob Hardy and Ted Campbell for their contributions
    to font filtering;

    Henry Spencer for awf and his regular expression package;

    Andy Tanenbaum for his help in ANSI C compliance, including his
    ansi.h header file from Minix.

    Ed Tankus for suggesting useful feature additions.

    Darrel Hankerson for working on the OS/2 port.

Henry says about awf, "I can't believe I really wrote this."  Those are
my sentiments exactly about cawf, but I also understand that necessity
sometimes forces us to do what we would prefer to avoid.


BUGS AND ENHANCEMENTS
---------------------

I'll be glad to hear about bugs and needs for enhancements, but make no
promises about delivering fixes or upgrades in response.

Vic Abell <[e-mail]>
27 December 1993