About ripwraps 1.0


ripwraps takes care of the gory details involved in producing
RIPscrip(tm)'s compact representation.  Each of the RIPscrip(tm)
commands described in _RIPscrip Graphics Protocol Specification_,
Revision 1.54, by TeleGrafix Communications, Inc. has a
corresponding rip_* procedure.  In accordance with the
RIPscrip(tm) protocol and C calling conventions, nearly all
formal parameters are typed as unsigned integers, save those few
representing strings, which are typed as const char *.  In
addition, five commands have alternative ripv_* interfaces.
These are functionally equivalent to their rip_* counterparts,
but accept some of their parameters as unsigned char or unsigned
short arrays, depending on the particular call.

ripwraps also includes a number of ripio_* functions.  They're
unique to this implementation.  Those marked "internal" should
not normally be called by the user.  Others are described below.


An application program should #include "ripwraps.h" and link
against ripwraps.o.  Since ripwraps.h will normally reside in
a different directory than the application's source, the
compiler may need to be told where to look for it, e.g.

	cc -I/usr/local/include ...


While a naive program can get away with only calling rip_*
procedures, this will not produce the most efficient output
possible.  That requires a little cooperation on your part:

Call  ripio_set_autoflush(0);  before any other rip_* (or
ripv_*) procedures.  Call ripio_flush() when you're done
with your RIPscrip(tm) commands, and before surrendering control
to any code that might produce "normal" (non-graphic) output.
That's all there is to it!

ripio_get_autoflush() returns the current "autoflush" setting.
It is included for completeness, although it's not likely to be
needed.


Besides declaring prototypes, ripwraps.h defines several
constants that can make your code more readable, e.g.

	rip_fill_style(RIP_SOLID_FILL, RIP_BLUE);

is equivalent to

	rip_fill_style(1, 1);

...but much clearer!  Note that some of ripwraps' names may
differ slightly from those in the Telegrafix documentation.
Use ripwraps.h to guide you!  (Note that not all numeric
values have symbolic names, particularly where "Level 1"
commands are concerned.)
	

>>> Now look at the sample program ripcal.c.  With no arguments,
ripcal produces a calendar for the current month (with today's
date highlighted), and smaller calendars for the previous and
coming months in the upper corners.  Given a month and year, it
displays a calendar for that month.


Advanced topics:

RIPscrip(tm) interpreters recognize three ANSI sequences that
technically aren't RIP commands.  These can be generated using
ripio_query(), ripio_disable(), and ripio_enable().


ripwraps normally wraps output lines based on an 80-character
line length.  This can be changed (if needed) using
ripio_set_width() and obtained using ripio_get_width().


By default, ripwraps uses stdio to write to the standard output
file.  It's possible to intercept and divert ripwraps' output
stream by registering an alternative character output function;
e.g. if net were a file descriptor attached to a network socket,

	ripio_set_putc(telnet, (void *)fdopen(dup(net), "w"));

int telnet(int c, void *fp)
{
	if (c=='\n') putc('\r', (FILE *)fp);
	putc(c, (FILE *)fp);
	if (c=='\r') putc('\0', (FILE *)fp);
	else if (c=='\377') putc(c, (FILE *)fp);
	return ferror((FILE *)fp) ? EOF : c;
}

would produce output compatible with the TELNET protocol.

Note that it isn't necessary to use stdio at all; this mechanism
is general enough to support arbitrary output filters.  The
current setting can be retrieved using ripio_get_putc_func() and
ripio_get_putc_arg(), e.g.

	(void)fclose((FILE *)ripio_get_putc_arg());


Miscellany:

1) rip_*/ripv_* procedures perform no "sanity checking."  The
   caller is responsible for ensuring that arguments are
   appropriate.  E.g. it is a grave error to call a procedure
   taking a string argument with a string containing a newline.

2) It is possible for a single application to send output to
   several different destinations using the ripio_set_putc()
   facility (provided that ripio_flush() is called beforehand),
   but this isn't recommended--an object-oriented implementation
   of ripwraps is called for here.

3) ripwraps is incapable of producing "inline" RIPscrip(tm)
   directly.

4) Call rip_line_style() before any procedures using "Line
   Thick."  rip_reset_windows() does not reset the current line
   style thickness to normal.  (Surprise!)

5) Don't believe everything you read in the Telegrafix
   documentation.


Eric P. Scott
Department of Computer Science
San Francisco State University
February 1994
---
RIPscrip is a trademark of TeleGrafix Communications, Inc.
Other brand or product names are the trademarks or registered
trademarks of their respective holders.
