This is a program to translate text files between different formats, the 
program is not complete or fully tested but it has never been published 
before and does a job that I find useful.

  To explain what the program does I will first outline the problem that 
it solves, this has to do with the documentation files in NorthC.

  The files have to be stored on the disk in a format that "MuchMore" can 
deal with, I happen to have decided to store all my documents in pure 
ASCII.  So the next obvious question is how to create the documents, well 
this is quite easy, I happen to know Richard Stallman's "Emacs" editor 
quite well so I use "memacs".  The problem is that "memacs" while being 
great for quickly moving blocks of text around and general editing, 
suffers from a couple of problems, first there is no easy way to set up 
the justification I want, and more importantly there is no way to check 
that the spelling is correct.  The justification I could write a special 
program for, the spelling is more of a problem, there are plenty of spell 
checking programs unfortunately most of them are for American rather than 
English.  Well the solution is that I have a program that will do English 
spelling, and justification, a "proper" word processor that I use to type 
documents and letters, so what I need is a program to translate a text 
file from "normal" ASCII to the format the program requires, and of course 
a program to translate back to ASCII.

  Well rather than write two special programs to translate into document 
form and from document for I thought I would just write the one program to 
translate a text file based on a data file.

  The data file describes the way that the translation is to be done, the 
first thing to note is that any line starting with a '#' will be treated 
as a comment, any line starting with a '$' will set a variable, so for 
example

    # This is a comment
    $line 75

sets the line length to 75 characters.  The first "real" data in the file 
tells the program how to translate between the formats, the '\' character 
has a special meaning

    "\\"    becomes '\'
    "\n"    becomes a <newline> character
    "\t"    becomes a <tab> character
    "\_"    becomes a <translates to> character
    "\ "    becomes a <space> character

so for example

    \n\t\_\t

says that any <newline> character followed by a <tab> will translate to a 
single <tab> character.  The next interesting question occurs when we have 
two translations such as,

    \n\_\t
    \n\t\_\ ?

the question is if we see a <newline> character in the file should we replace 
it with a tab or should we wait to see if the next character is a <tab>.  The 
answer is of course that we must wait, but this does restrict the translations 
we can put in the data file.  In general if you put the short translations 
first then things will work out about right.

  Each translation sequence appears on a separate line, the last translation 
sequence has a blank line after it.  After the translations there is a list 
of the files to do the translations on, for example

    Changes    "NorthC:CHANGES"              "t:Changes"
    Contents   "NorthC:CONTENTS"             "t:Contents"
    NthCREADME "NorthC:README"               "t:NthCREADME"

this give three entries for each file, first a name by which the file can 
be reffered, second the source file name and finally the destination file 
name.

  If you specify an object to transfer with the "-o" flag, for example

    translate -oChan "NorthC to doc"

then the program will translate all the files whose names start with "Chan", 
this allows you to deal with small sets of file at a time.

  As the program currently stands it has not been tested, it does what I want 
it to do and I could not be bothered to take it much further.  If you find 
any bugs, or manage to improve the program please send me a copy, and tell 
me if I can include it on the NorthC disk.