gno/usr.orca.bin/udl/README

=============================================================================
udl -	Convert EOL formats freely between MS-DOS (CR/LF), Unix/Amiga (LF),
     	and Apple (CR).

	(c) 1993-1996 Soenke Behrens, Devin Reade

	Version 1.15: $Id: README,v 1.8 1996/01/22 01:01:32 gdr Exp $
=============================================================================

Udl converts text files between CR, LF and CR/LF (Apple, Unix and MS-DOS).
It is a very fast utility that ensures that the integrity of the file
cannot be compromised during the translation.  It is also much easier
to use than tr(1).

=========
Compiling:
=========

There are two makefiles included:
	Makefile.gs	- for use on the Apple IIgs running GNO
	Makefile.unx	- for use with Unix systems.

Although udl on the IIgs can be run from either GNO or ORCA shells,
it cannot be built with the standard ORCA installation due to a lack
of additional libraries.

The IIgs distribution should contain a binary of udl, including a 
resource fork.  Therefore, you should be able to skip straight to the
section on installation.  For those who must know, however, building the
binaries under GNO should just be a matter of typing 'dmake -f Makefile.gs'.

If you are compiling on Unix operating systems that have been previously
tested, you should be able to just type 'make -f Makefile.unx'.  This
will select the appropriate DEFINES for your system.  For an explanation
the various DEFINES, see the section below on "DEFINES Definitions".

Note that compilation of udl _requires_ an ANSI C compiler.

If you are compiling to a new system, add in another set of defines
and let us know about them.

Note that udl.c assumes that getopt() is declared in <unistd.h> and that
the function strdup() exists in <string.h>. You might have to change
these includes if that's not the case.  Ensure you use cpp conditional
compilations to match your platform (and to avoid breaking the code for
other platforms).

============
Installation
============

Apple IIgs with GNO
^^^^^^^^^^^^^^^^^^^
Type 'dmake install -f Makefile.gs'.  By default this copies the binary
into "/usr/local/bin" and the man page into "/usr/local/man/man1".  (You
_are_ using version 3.x of 'man', are you not?  *blatent plug*)  If you
don't like these locations, either modify the BINDIR and MANDIR
macros in the makefile or install the files by hand.

If you have describe(1) installed, you can update the udl(1) entry
with the file "describe.udl".  See the descu(8) and descc(8) man pages
for details.

Apple IIgs with Orca/Shell
^^^^^^^^^^^^^^^^^^^^^^^^^^
Copy the following files to their respective destinations:

	udl		to		17
	help/udl	to		17/help

Unix systems
^^^^^^^^^^^^
Type 'make -f Makefile.unx install'.  By default the binary will
go into /usr/local/bin and the man page into /usr/local/man/man1.
This assumes root access.  If this does not match your plans and/or
access permissions, either copy the files by hand or change the
BINDIR, MANDIR, and OWNER_GROUP macros in the makefile.

===================
DEFINES Definitions
===================

If you have problems compiling or are porting udl to a new operating
system, define the following macros in the makefile as necessary.
They should be used as the value of $(DEFINES_$(OS)) where $(OS) is
your operating system as returned by `uname -sr | tr ' ' '_'`.

	HAS_ATEXIT if your system has atexit()

	_POSIX_C_SOURCE and _POSIX_SOURCE if your compiler is Posix compliant

	READDIR_RETURNS_DOT if your direct readdir() function will return
	entries for "." and "..".  SunOS 4.x and 5.x (Solaris) are known to 
	do this.

	BROKEN_REALLOC if your realloc() doesn't behave like malloc() when
	passed a NULL pointer as the first argument.

	BROKEN_DIRENT_STRUCT if you find that the first two letters of 
	filenames obtained during directory recursion (as shown when the
	"-v" flag is used) seem to be missing.  Some installations of
	Solaris are known to do this.

	GNO if you are compiling on the IIgs.  This will allow for both
	':' and '/' as pathname separators.

	OVERFLOW_CHECK  Udl uses one recursive subroutine.  Define this if
	you want to check for stack overflows for this routine (independent
	of any compiler flags).  Strongly recommended.

	CHECK_STACK if you want stack usage to be displayed (IIgs only).
	You will also have to specify -l/usr/lib/stack in LDFLAGS.

The following are the DEFINES values for tested operating systems:

	APPLE IIGS:  (use "dmake -f Makefile.gs")
	^^^^^^^^^^

	ORCA/Shell and GNO/ME: (tested with occ)
		-DGNO -D_POSIX_C_SOURCE -D_POSIX_SOURCE -DHAS_ATEXIT
		-DOVERFLOW_CHECK

	TESTED UNIX OS's: (use "make -f Makefile.unx")
	^^^^^^^^^^^^^^^^
	SunOS 4.x: (tested with gcc)
		-DREADDIR_RETURNS_DOT -DBROKEN_REALLOC
		-D_POSIX_C_SOURCE -D_POSIX_SOURCE

	SunOS 5.x (Solaris): (tested with SUNWspro cc)
		-DREADDIR_RETURNS_DOT -DBROKEN_DIRENT_STRUCT
		-D_POSIX_C_SOURCE -D_POSIX_SOURCE

	AIX 3.2: (tested with xlc)
		-DBROKEN_REALLOC -D_POSIX_C_SOURCE -D_POSIX_SOURCE

	Linux 1.2.3: (tested with gcc)
		-DREADDIR_RETURNS_DOT -D_POSIX_C_SOURCE -D_POSIX_SOURCE
		-DHAS_ATEXIT

================
Revision History:
================

v1.01
	Tabs are left alone now. Also recognizes CR/LF (MeSsy-DOS).

v1.02
	Does no longer read in the complete file, instead creates a temp
	file in prefix 3/.

v1.03
	Fixed a bug, allocated not enough mem for strncpy.

v1.1
	Changed to use static GS/OS strings again. Made faster by factor
	5.8.

v1.11
	Cleaned the code up a bit, wrote a Makefile, all output by udl is
	prefixed with the name it was invoked with.

v1.12
	Sped up Apple <-> Unix conversion further (factor 1.5).

v1.12 (Unix)
	(December 1993)
	Modified source to produce a Unix version

v1.13
	(Updated by Devin Reade, November 1994)
	Added ability to recurse through directories (-R flag).
	Changed behavior to ignore binary files rather than exiting.
	Merged Unix and Apple IIgs versions.
        No message is printed out when a binary file (or, in the IIgs
           implementation, a non-TXT or non-SRC file) is encountered
           unless the -v option is specified.

v1.14
	(Soenke Behrens, Devin Reade, February 1995)
	udl creates a temporary file in the directory of the
	   source file, not in /tmp. This reduces the likelihood of
	   data loss in the event of a system crash or powerdown.
	udl now accepts something like "udl -R directory/" without
	   affixing an extra '/' to "directory/".
	Fixed bug (via the BROKEN_DIRENT_STRUCT macro) that was causing
	   filename-munging on Solaris.  It seems that the sys/stat.h header
	   file doesn't agree with the stat implementation.
	Modified Makefile.gs to properly write the new executable over
	   the old resource fork for udl.  The resource fork originates with
	   the file udl.r.
	Added suggested defines to the README for various Unix platforms.
	Man page changes, including grammar and the deletion of a bug that
	   no longer exists.
	Fixed bug where invoking 'udl -u directory' would attempt to
	   deref a NULL pointer, causing either memory tromping (IIgs) or
	   a core dump (Unix).
	Tested under SunOS 4.x, SunOS 5.x (Solaris), and AIX.

v1.15
	(Devin Reade, January 1996)
	Changed Makefile.unx to select what should be the proper
	   defines automatically, based on the result of `uname -sr`.
	Added Linux defines.
	Changed references and definition of "mktemp" to "Mktemp".  There
	   is a discrepancy between the internal implementation and
	   other common Unix versions.
	Added a section to this README on installation, and moved the
	   description of the DEFINES from the makefiles to here.
	On the IIgs version, the resource fork is now created from a
	   resource source file that is compiled, rather than using
	   an interactive tool to create the resource fork.
	Changed source filenames to use the 8.3 format in anticipation of
	   MS-DOS support.  This does not affect the file names upon which
	   udl operates.

=======
Authors
=======

Original code by Soenke Behrens <sbehrens@contech.demon.co.uk>
with modifications and version-merging by Devin Reade <gdr@myrias.com>

==========
Legalities:
==========

This program contains material from the Orca/C Run-Time Libraries,
copyright 1987-1996 by Byte Works, Inc.  Used with permission.

=============================================================================