                  Release Notes for WPLS2RTF v2.01
                  ================================



    [This is the second version of a program that used to go by the
     name of WP2RTF, dated April 1, 1992. It supersedes that one.]



January 30, 1996 Notes
======================


Contents

	Elevator Statement
	The Author
	Included
	Features
	Installing
	Using
	Caveats
		Determining filenames and -paths
		DOS memory stupidity
		Strange warnings from WinWord
	Translation Configuration
	History
	Disclaimer
	Rules and Regulations
	Ancient Release Notes, Including Translation File Documentation


<+> Elevator Statement <+>

WPLS2RTF translates files in the First Word [Plus] format to RTF (Rich
Text Format) files, an interchange format supported by many word
processors and widely in use as a means of exchanging documents.
Supplied are Atari ST, Macintosh, and DOS binaries, and
source-cum-makefile that should compile just about anywhere where
there's a decent ANSI C compiler available (like gcc, for example).

Ok, I'm lying a bit. In fact, WPLS2RTF is a translation framework that
allows the target format to be specified. I never took much trouble
actually writing much translation files though -- although I *did*
write one for TeX, once. Anyway...


<+> The Author <+>

WPLS2RTF 2.01 was written by J. Scheerder; early versions (called WP2RTF)
date back to 1990. The author can be reached by email as:

	<URL mailto:js@cs.vu.nl>
	<URL mailto:js@phil.ruu.nl>
	<URL mailto:js@let.ruu.nl>, <URL mailto:Jeroen.Scheerder@let.ruu.nl>

and you should be able to get it through
	<URL http://www.cs.vu.nl/~js/warez/js-ware.html>

if for some reason you should need to get it again.

The Macintosh version leans heavily on the application framework
DropShell, written by Leonard Rosenthol <leonardr@netcom.com>, Marshall
Clow <mclow@san_marcos.csusm.edu> and Stephan Somogyi
<somogyi@ziff.com>: thanks, good folks, for writing this.


<+> Included <+>

The full 2.01 release consists of the following files/directories:

	Changes.201
	wpls2rtf.txt
either	1st Word Plus  RTF (FAT)
or	w2rmacprg.hqx
	[Universal]
		TEST.DOC
		TEST.rtf
		wpls2rtf.x
		wpls2tex.x
		wpls2txt.x
	[Unix]
		Makefile
		wpls2rtf.sh
	[TOS]
		JS_START.O
		WPLS2RTF.PRJ
		WPLS2RTF.TTP
	[DOS]
		WPLS2RTF.EXE
		WPLS2RTF.PRJ
	[src]
		wpls2rtf.c
		wpls2rtf.h
either		[MacOS]
			DSUserProcs.diff
			wpls2rtf.68k.
			wpls2rtf.bh
			wpls2rtf.dos.
			wpls2rtf.fat.
			wpls2rtf.rsrc
			wpls2rtf.make
or		macosdev.hqx

Due to possible limitation in file names, archiving techniques and
differences between the various operating systems I'm distributing a
number of versions. If you did not get the full release as a BinHexed
Stuffit archive, the Macintosh stuf that could not be stored in an
archive that knows nothing about files' resource forks will appear in
as BinHexed-encoded Stuffit archives within the distribution.l.

There are also partial (OS-specific) releases, in which you'll typically
find the OS-specific stuff of a single OS only, i.e. some archive that
contains 'wpls2rtf.txt', the 'Universal' and one of the 'MacOS', 'Unix'
'TOS' and 'DOS' directories.

A bit of explanation of the what's what in this file tree:

+ Changes.201: A brief history of program development
+ wpls2rtf.txt: you're reading it now. DOS/TOS (CRLF) line breaks.
+ w2rmacprg.hqx or 1st Word Plus  RTF (FAT), the Macintosh application
[Universal]
	+ *.x: translation configuration files, DOS/TOS line breaking
	  (but will work with Unix or Macintosh line breaks). The
	  settings in the 'wpls2rtf.x' translation file are identical
	  to the settings that are built into the program;
	* TEST.DOC: a sample First Word Plus document, covering just
	  about every possible interesting combination of special
	  formatting;
	+ TEST.rtf, the result of a conversion of TEST.DOC;
[Unix]
	+ Makefile: a makefile, can't you read? It has Unix line breaks;
	+ wpls2rtf.sh: a sample (Unix) Bourne shell (sh) wrapper script;
[TOS]
	+ WPLS2RTF.TTP: Atari ST/TT (TOS) binary;
	+ WPLS2RTF.PRJ:	A Pure C project file;
	+ JS_START.O:	Startup code for Pure C;
[DOS]
	+ WPLS2RTF.EXE: 80x86 PC (MS/PC-DOS) binary;
	+ WPLS2RTF.PRJ:	A Borland C project file.
[src]
	+ wpls2rtf.c: This is The Source, Luke. (DOS/TOS line breaks,
	  should bother no compiler);
	+ wpls2rtf.h: The Source's headerfile;
	+ macosdev.hqx
	  or [MacOS]
	  	+ wpls2rtf.bh, the sourcefile from which the Balloon
	  	  Help Compiler creates the help balloons for for dialogs
	  	  and menus;
		+ wpls2rtf.68k., the (CodeWarrior 8) project to make
		  the M68K Macintosh application;
		+ wpls2rtf.dos., the (CodeWarrior 8) project to make
		  the DOS application;
		+ wpls2rtf.fat., the (CodeWarrior 8) project to make
		  the FAT Macintosh application (note that you'll need
		  the 68k project too: that's the Way of the Warrior);
		+ wpls2rtf.rsrc, the resource file;
		+ DSUserProcs.diff, a diff file containing the;
		  modifications to the DropShell 2.0 file 'DSUserProcs.c'
		  needed to compile the program. The DropShell sources
		  are not included, get them from your favorite Info-Mac
		  ftp archive;
		+ wpls2rtf.make, an MWP makefile to build an MPW tool.


<+> Features <+>

Preserved on translation:

	+ Styles (bold, italic, ...);
	+ Soft spacing;
	+ _All_ characters (at least in theory :-]);
	+ Footnotes.
	
Disappearing on translation:
	- Ruler-based formatting (design choice);
	- Headers and footers (design choice, result of previous);
	- Images (ditto);
	- A few characters (notably the Hebrew stuff)
	  [These could easily be added by adding appropriate
	  code to a translation file].


<+> Installing <+>

Unpack the archive. If you didn't know how to do that, you would not be
reading this file, so I suppose you already did. After unpacking, go to
the directory (folder) that contains the stuff you need. If you're
using...
Unix:	You need to compile it first: edit 'Makefile' to your liking
	and type 'make'. This should get you a program called
	'wpls2rtf'. Typing 'make install' will copy 'wpls2rtf' to the
	directory you chose in the makefile, and set appropriate
	file permissions;
MacOS:	Put '1st Word Plus >> RTF' wherever you want it.
	If you'd like to use the MPW tool version, build it and put
	'wpls2rtf' somewhere in MPW's search path;
TOS:	Put 'WPLS2RTF.TTP' (and optionally 'WPLS2RTF.X') wherever you
	want to put it -- somewhere in your PATH would be smart, I guess;
DOS:	Put 'WPLS2RTF.EXE' (and optionally 'WPLS2RTF.X') wherever you
	want to put it -- somewhere in your PATH would be smart, I guess.


<+> Using <+>

* If you're using a Macintosh: simply drop the files, folders or disks
onto the application icon, or start the program and select the files to
convert using the 'File' menu item 'Convert File...'. To get the
program's version number, use the Finder-command 'Get Info'

* If you're not using a Macintosh, the program's usage is:

	Usage:	wpls2rtf [-t translator] [-u] [-v] file ...

		-t	Specify a translation configuration file to use
		-u	Show program usage
		-v	Show program version and creation date

which, put a bit more verbosely, means that you can supply any number of
arguments to it the way you usually do -- typing them in on a
commandline, dropping stuff on an icon, writing scripts, whatever. Any
argument starting with a '-' is interpreted as a switch rather than a
filename to convert; switches and parameters are passed to the program
in the same way. For example, to convert a file 'foo' and 'bar' and find
out the version info on...
Unix:	In your shell, issue the command "wpls2rtf -v foo bar";
TOS:	In the GEM Desktop, open 'WPLS2RTF.TTP' and type "-v foo bar"
	in the dialog that follows; in a CLI (i.e. gulam, mupfel, bash,
	...) type "wpls2rtf -v foo bar";
DOS:	In DOS, key in "wpls2rtf -v foo bar".
Most graphic shells and file managers allow dragging files onto program
icons to start the program with the name(s) of the file(s) dropped on its
icon. This is probably the easiest way to convert files in Unix, TOS and
WinDOS.

Note that WPLS2RTF is indifferent about linebreaking: although 1st Word
Plus files are normally (and must be) using CRLF line termination, these
things tend to get converted when transferring files. For that reason,
DOS/TOS (CRLF), Unix (LF), Mac (CR) and pathological (LFCR) are treated
equally.


<+> Caveats <+>

*** How the program determines what files to look for, and where ***

WPLS2RTF handles some things rather peculiarly. When starting without an
explicit specification of the translation file, it tries to load a
default translation file; on failure, it uses internal translation
settings. The name of this translation configuration file is constructed
by removing the extension from the program name, if that information
could be obtained (otherwise the program name is set to 'wpls2rtf'; the
default translation file for the Macintosh application is fixed, "1st
Word Plus  RTF.x"). The program name with '.x' appended is the name of
the default translation file. In the translation file, the extension to
use for converted files can be set; if that is omitted, the program
tries to determine a reasonable extension, in the following way: In
turn, the name of the translation file is used to determine a naming
scheme for translated files: with only the base file name part
considered, the extension (if any) ignored, the last '2' is searched. If
there is no '2', the last 3 characters (if available) are used;
otherwise, the first 3 characters (if...) after the '2' will be taken.
If no extension is found this way, '.tra' is defaulted to. An example
may serve to clarify. Suppose the program is started as:
	/usr/local/bin/word+2rtf.sparc mydoc.doc,
	wp2txt mydoc.doc,
	wrdpls2ltx mydoc.doc,
	wrdpls2latex mydoc.doc,
	wrdpls-to-ltx mydoc.doc,
	wrdpls-to-latex mydoc.doc,
	me2 mydoc.doc
then the default translation file is
	/usr/local/bin/word+2rtf.x,
	wp2txt.x,
	wrdpls2ltx.x
	wrdpls2latex.x
	wrdpls-to-ltx.x
	wrdpls-to-latex.x
	me2.x
and if these default translation files are found and do not contain an
explicit extension setting, the extension to use is:
	.rtf,
	.txt,
	.ltx,
	.lat,
	.ltx,
	.tex,
	.tra
respectively. In short: the default translation filename is determined by
the program name. The default extension is set in the translation file,
or generated from its name as explained above in case none was provided.
Note that if you always want a translation file loaded, you have to
make sure it's named properly (as explained above) and put in the
right place. The former isn't too hard: simply start the program once
without any arguments, in the 'Usage:' message you'll be told what
the program thinks its name is. That (with '.x' appended) is the name
you should use for the default translation configuration file.
Where does this file go? How should it be named? Let's see. Can we
use an environment variable (and do we want that)? No. This would work
fine on Unix and TOS; on MacOS, the concept makes no sense, and on DOS,
well...
Can we determine a path by looking at the program invocation? Yes -- if
this information can be obtained at all, that is. Therefore, WPLS2RTF
tries hard to find its own location to be able to locate the default
translation file. So what happens? First, it tries to get the program
invocation. If this succeeds _and_ contains a full path specification,
things are easy. If the program invocation does not contain a path, or
none can be determined, no path to the translation file is available.
Should this prove to be problematic, a possible workaround is supplying
the full pathname using the '-t' switch. It should be fairly easy writing
scripts to do so, on most any platform: as an example, I've included
a Unix shell script.
On a final note, here's what I have seen happen in this respect:
- In TOS and DOS the program is aware its location and will be able
  to find the default translation file in its own directory;
- In Unix and MPW, the program gets to see your invocation of it -- if
  it's in your PATH and you type its name, it will see only its name.
  If you specify a full or a relative path to it, though, it will see
  that and be able to find its default translation file in that path
  (this is how the sample wrapper script gets away with it);
- In MacOS, the program will always find 'wpls2rtf.x' when it's by its
  side.

*** DOS memory stupidity ***

DOS is stupid about memory. It wouldn't know about large wads of
available memory if all bytes in it dressed in loud colours and started
singing "Tons-O'-Memory Are Here Again" -- it's *that* stupid about it.
For that reason, you can have lots of it installed, with your programs
unable to utilize it; Windows isn't much better at it, except for
Windows NT, which is a bit smarter about memory and addressing and
managing it. This has to do with OS design, or rather, the fact that DOS
and Windoze miss out completely on that. I tried getting the tool
compiled in such a way that at least the full 640k addressable space
(betareleases were by mistake built with a memory limit of 64kB) can be
put to use, but have been unable to test that due to lack of
sufficiently big First Word documents. If this kind of thing bothers you,
I suggest you get a real OS.

*** Strange warnings from WinWord ***

There have been reports of WinWord 2 complaining about an 'invalid style
name' (or something similar) when interpreting WPLS2RTF output. I have
not been able to reproduce this consistently, although I have seen the
phenomenon occur (in WinWord 7). No other applications object: nor Word
on the Macintosh, WP on Mac or Unix, not WriteNow, nothing; and I have
not found errors in the generated RTF.
Luckily, there's good news: notwithstanding the warning alert, the
RTF code gets interpreted just dandy. All is well. For the time being,
therefore, I think it not unreasonable to let things be and ask you to
live with any of these possibly faulty warnings you might get from
WinWord.


<+> Translation Configuration <+>

WRDPLS2RTF is not a mere monolithic First Word [Plus] to RTF translator
(misleading-program-names-r-us!): its translation can be controlled
by means of a translation configuration file you can write (or adapt)
yourself. See a translation file ('wpls2rtf.x' will do) and the ancient
notes below for detailed information.


<+> History <+>

Over the years there have been numerous inquiries about the WP2RTF
converter that this program supersedes; most had to do with spurious '}'
characters getting inserted, causing the RTF interpretation to halt
prematurely.

Most times, my response was guiding inquirers through the tedious
process of fixing up broken RTF code; but as luck has it, while I
went into lengths of trouble trying to get a description of the
First Word [Plus] file format at the time and failed, I was contacted
by someone who provided the lacking information.

You get flaky converters if you base them on superficial examination
of a file format at hand; but now came the opportunity to rewrite the
blasted thing in accordance with a true specification. The result is a
tool that works better (and cleaner and more concise code). Kudos to
mrs. L.F.Burrell-Davis for the file format documentation!

Eventually, somewhere in mid-December '95 I had a converter that looked
adequately functional with respect to translation correctness; I added
a load of features, made lots of things behave smarter, tested on
various platforms, and did a Macintosh implementation (using the very handy application framework
DropShell). In the course of December '95 and January '96 I added lots
of options, and finally released version 2.0. Everything after that has
been minor nit picking.


<+> Disclaimer <+>

I tested on MacOS, TOS, SunOS, Solaris, Ultrix, MachTen Unix and DOS,
and it worked well -- that is, it worked well for me. I cannot guarantee
it to work at all on your particular machine, however: if it ends up
destroying your file systems I won't take responsibility, sorry. All I
can say is that I did not write the code with that or any other wicked
things in mind. Really.


<+> Rules and Regulations <+>

The WPLS2RTF translator is JoJo-ware. If you like it (1) send me a
message (so I'll be feeling good) and (2) get yourself a Jonathan
Richman (or a Modern Lovers) album/disc/tape/whatever (so _you_'ll
be feeling good). I'm no relative to Jonathan, by the way, nor am I
in any sense commercially involved with him or his music. Still,
JoJo-ware it is!


<+> Ancient Release Notes, Including Translation File Documentation <+>

April 1, 1992 Notes
===================

I finally got fed up with manually translating WordPlus files into
various other word processors. I always lost the extended characters
in the translation; furthermore each line became a paragraph.

Then I came across a utility called 1WP2TEX (or something like that)
which had an elementary configuration file in which various
characteristics could be configured. Alas, my aim was to get the files
to a Macintosh word processor; and I could not get 1WP2TEX configured
to do that.
The reason for this is that the easiest way (in my opinion) of
converting texts is using an intermediate file format. There exists a
standardized exchange format (with layout info) called RTF - rich
text format - that suits all our needs.
However, the limits of the 1WP2TEX program did not allow for the RTF
header I needed. So I wrote a similar converter.

How does it work? Well, WP2RTF uses the files to translate as
parameters. Furthermore, the first parameter can be '-t', in which
case the second parameter must be the name of a translation file.
The default translation file is called 'wp2rtf.x', which (as its
name suggests) handles translation to RTF. It may be easy to write
a translator for (La)TeX, I have not tried.

The format of a translation file is simple.
Each line starts with either a valid keyword or a character number
(in hex, preceded by '$'), followed by a separating character; the
rest of the line is assigned to the character (keyword).

Valid keywords are:

.ext	the (full, include the '.') extension to use for converted files 
init0	the initialization strings 0..9
  .
  .
init9

exit		termination string
paragraph	paragraph separator
bold		bold command
underlined	underlined command
italic	italic command
light	light command
super	superscript command
sub		subscript command
blockstart	start style block
blockend	end style block
footnote	start of footnote command
endnote	end of footnote command



Enjoy, J. Scheerder

email:	js@cs.vu.nl
	js@phil.ruu.nl
	js@let.ruu.nl, Jeroen.Scheerder@let.ruu.nl
