FIXTEXT.TXT                          1                         Nov 06, 1999

WIN95 AND WINNT NOTICE:  As with most  DOS-based  utilities,  this  program
doesn't  understand  the  weird  subdirectories,  long  filenames,  invalid
characters that  are  possible  under  Windows  95  and  Windows/NT.   Both
operating systems alias long filenames into names like MYFILE~1.TXT and you
will need to specify the aliased versions of file names to process them. If
you're not sure what the pseudo-name is, use the "DIR /X" command in DOS to
check.  Under some file structure systems in NT, the program may  not  work
at all.

The FIXTEXT.EXE program applies  a  character-translation  template  to  an
entire text file.  This allows you to change a whole bunch of characters at
once.  Features:

  * Can process text files of any size.
  * Can process DOS text files (lines ending with CR/LF),  Mac  text  files
    (lines ending with CR), Unix text files (lines  ending  with  LF),  and
    fixed length files (lines of a  fixed  length  without  any  CR  or  LF
    characters).
  * Can convert any of the above four types of text files  to  any  of  the
    other types of text files.
  * Automatically detects the type of input file if it's  a  standard  text
    file (lines ending with CR/LF, CR alone, or LF alone).
  * Ideal utility to convert all Unix text files to DOS text files.
  * Can be used on binary files but using the /REPLACE option isn't exactly
    recommended in this case...
  * Can load a user-defined character-translation tables.
  * Character-translation tables can let you do things like:
     - Convert all lowercase characters to uppercase characters
     - Translate  IBM  graphics  characters  into   standard   ASCII   text
       characters; this is very useful if you want to  print  the  document
       and are tired of getting weird stuff printing out.
  * Can translate tab characters into spaces.
  * Can fix up underscores and other backspace characters.
  * Can remove leading and/or trailing spaces from lines.
  * Can remove blank lines from files.
  * Can create a file showing all lines that were changed.
  * Can translate single characters into multiple characters or remove them
    entirely.
  * The input file specification can include standard DOS wildcards  or  an
    external  file  (@listfile)  containing  the  files  to  be   processed
    (although either prohibits specifying an output file name).
  * Pressing escape stops the program early.


Specifying parameters:

Parameters for this program can be set in the  following  ways.   The  last
setting encountered always wins:
  - Read from an *.INI file (see BRUCEINI.TXT file),
  - Through the use of an environmental variable (SET FIXTEXT=whatever), or
  - From the command line (see "Syntax" below)



FIXTEXT.TXT                          2                         Nov 06, 1999

The character translation file (lookup tables):

FIXTEXT will process a  character-translation  (lookup)  table  if  one  is
found.  This table can  be  in  your  standard  *.INI  file  (for  example,
FIXTEXT.INI) if desired or it can be a separate file  specified  using  the
/Linitfile parameter.

A sample FIXTEXT.INI file is provided.  You can modify this file or  create
your own.

There is also  a  separate  FIXTEXT.ISO  file  which  can  be  copied  over
FIXTEXT.INI if so desired.  It was done by Paul Rosenberg and converts  the
characters to characters of the ISO LATIN-1 character  set  which  is  what
Windows uses.  (Wayne Software has not actually  verified  the  conversions
used in this file.)

If no *.INI file is found (or if  "/-I"  or  "/INULL"  is  specified),  the
default translation table will be loaded.  This one  is  identical  to  the
original FIXTEXT.INI file and has these characteristics:

   - All characters in the decimal 032 to 125 range are left unchanged
   - Characters in decimal 24 to 27, and 176 to 223 are considered graphics
     characters and are translated into regular text characters,  typically
     ".", "X", "x", "|", "-", and "+"
   - Decimal characters 248 to 250 and 254 are changed into asterisks ("*")
   - All other characters are translated into spaces

As an example of  the  graphics  character  translation  that's  done,  the
following:

         Ŀ   ͻ                      +-+-+   +-+-+
                                      | | |   | | |
         Ĵ   ͹        becomes:      +-+-+   +-+-+
                                      | | |   | | |
            ͼ                      +-+-+   +-+-+

It may not look as good but it certainly prints better on most printers.

The lookup table is an ASCII text file which consists of a series of  lines
in the following format:

        inchar = outstr

where "inchar" is the character to change from  and  "outstr"  is  what  to
change the character to.  Both portions can consist  of  regular  non-space
ASCII text characters (like "A" or "z") as well as hexadecimal  values  (in
the form &Hxx) or decimal values (in the form \nnn).  "outstr" can  consist
of 0 (the word "(NONE)"), 1, or 2  or  more  replacement  characters  while
"inchar" can only represent a single character.  You cannot use a space  or
equal sign in either "inchar" or "outstr"; use the hexadecimal  or  decimal
representations instead.  The table does not have to be  in  any  specified
order.  Lines can end with "/*" followed by a comment if you want.

Hexadecimal and decimal equivalents are explained in BRUCEHEX.TXT.


FIXTEXT.TXT                          3                         Nov 06, 1999

Examples:

         a    = A /* Translate lowercase "a" into capital "A"
         \032 =  _  /*  Translate  space  (decimal  032,  &H20  too)   into
              underscore
         &H0c = <PAGE>\013\010 /* Translate page eject character  into  the
              word "<PAGE>" followed by carriage return/line feed
         \027 = \032    /* Translate escape character to a space
         \027 = (NONE)  /* Remove excape characters entirely

Since lines beginning with "/" are treated as  command-line  defaults,  you
must use \047 or &H2F if you want to override the definition of "/".

Note that when characters are not translated into single characters, all of
the  single-character  translations  are  performed  first  and  then   the
remaining translations are performed in the order they were specified.   So
something like the following would  result  in  some  lines  being  changed
twice:

        A = CAPITAL_A
        a = A

In this case, all lowercase "a" characters would first be  translated  into
an uppercase "A", and then the same character would then be translated into
the string "CAPITAL_A".



FIXTEXT.TXT                          4                         Nov 06, 1999

Syntax:

    FIXTEXT { filespec | (filelist) | @listfile }
      { outspec [ /OVERWRITE | /-OVERWRITE | /OVERASK ] | /REPLACE }
      [ /n ] [ /TO CRLF | /TO CR | /TO LF | /TO n ] [ /TEXT | /BINARY ]
      [ /TRIM | /RTRIM | /LTRIM | /-TRIM ] [ /ZAPNULL ] [ /-FIXBS ]
      [ /-FIXTAB ] [ /EJECT=str ] [ /-EOF ] [ /Frptfile | /-F ]
      [ /Q | /Qn ] [ /Linitfile | /-L ] [ /MONO ]
      [ /Iinitfile | /-I ] [ /-ENV ] [ /? ] [ /?HEX ]

"filespec" is the input file specification to process.   Can  include  path
and wildcard information if desired.

"(filelist)" allows you to specify multiple files to be processed from  the
command line.  File names should be separated by spaces.  They may  include
drive, path, and wildcard information.  Remember that a command line in DOS
cannot exceed 127 characters so you're limited as  to  how  many  different
file specifications you can provide in this fashion.

"@listfile" allows you to have a variety of file specifications saved in  a
text file named "listfile".  Each line in the file should  consist  of  one
file specification, each of which can  include  a  path  and  wildcards  if
desired.  Blank lines and lines  beginning  with  semi-colons,  colons,  or
quotes are ignored.

     One caveat about the @listfile parameter:  I  had  problems  with  the
     program reprocessing the same files twice.  The subroutine would  find
     the file, rewrite it, and  then  the  new  (modified)  file  would  be
     detected as yet another file.  This created a loop which did  horrible
     things.  As a result, the  program  tries  to  skip  files  that  it's
     already handled.  It does this by looking at the file name but, due to
     space limitations, it ignores the path of the file.  So if you have  a
     @listfile and it mentions two  files  named  the  same  thing  in  two
     different subdirectories, the program will miss the second one.   This
     applies to wildcarded files as well. Sorry about that!  The  only  way
     to get around this is to have multiple @listfile's and invoke  FIXTEXT
     multiple times.

"outspec" is the name of the file to create.  It can include  a  drive  and
path specification.  You have to specify either an outspec or the  /REPLACE
option.  If your input specification  includes  more  than  one  file  name
(either through the use  of  wildcards  or  else  by  using  the  @listfile
option), "outspec" must be an output file  path,  not  an  individual  file
name.  Otherwise, it has to be an individual file name.

"/OVERWRITE" says to overwrite the output file if it exists already.

"/-OVERWRITE" says to abort if the output file exists already.

"/OVERASK" says to prompt if the output file exists already;  this  is  the
default.


FIXTEXT.TXT                          5                         Nov 06, 1999

"/REPLACE" says to write the results  to  a  temporary  file  and,  if  the
program finds characters to change and runs successfully,  to  replace  the
original file with the fixed temporary file.  The original file is  renamed
with a BAK extension if you use this option.  You have to specify  *either*
an output file name or the /REPLACE option.

"/n" specifies that the input file doesn't have any carriage return or line
feed indicators at all and that, in fact, lines are all fixed length.   The
routine automatically detects the  standard  text  files  (lines  end  with
CR/LF, CR alone, or LF alone); only fixed-length input files  require  this
parameter.

"/TO CRLF" specifies that the output lines are to end with the standard DOS
CR/LF combination.

"/TO CR" specifies that the output lines are to end with the  standard  Mac
CR character only.

"/TO LF" specifies that the output lines are to end with the standard  Unix
LF character only.

"/TO n" specifies that the output lines are to be written as  fixed  length
records of line length n.

"/TEXT" specifies that the file is a text file with definite lines.

"/BINARY" says you want to process a binary file, with no definable  lines.
This is sometimes useful when you have a file in a native  word  processing
format (like a WordPerfect file) and you want to dump it out as ASCII text.
You'll lose the paragraph  breaks  (unless  you're  pretty  good  with  the
character-translation file but you'll get  something  at  least.   Invoking
/BINARY automatically invokes /-TRIM, /-ZAPNULL, /-FIXBS, and /-FIXTAB.

"/TRIM" says to remove all leading and  trailing  spaces  from  the  lines.
Initially defaults to "/RTRIM".

"/RTRIM" removes all trailing spaces.  This is initially the default.

"/LTRIM" removes all leading spaces.  Initially defaults to "/RTRIM".

"/-TRIM" skips removing any leading or trailing spaces.

"/ZAPNULL" says to kill off any blank lines found in the file (whether  the
blanks were created by one of your changes or not).  Initially defaults  to
"/-ZAPNULL".


FIXTEXT.TXT                          6                         Nov 06, 1999

"/-FIXBS" says to not resolve backspace characters.  These usually show  up
as solid rectangles with  circles  in  them.   "/FIXBS"  is  initially  the
default.

"/FIXBS" says to resolve backspace characters.  This is done by removing  a
pair of characters for each backspace.  So  "A",  (BACKSPACE),  "A",  which
might appear as overstriking on some printers, will  come  out  as  just  a
single "A".  This is initially the default.

"/-FIXTAB" says to not expand tab characters.  The tab  itself  will  still
remain in your output file.  If you wanted to replace it with  a  space  or
get rid of it entirely, go into FIXTEXT.INI and change \009 to be equal  to
\032 (space) or NULL (to get rid of it entirely.   "/FIXTAB"  is  initially
the default.

"/FIXTAB" says  to  expand  tab  characters.   When  it  runs  into  a  tab
character, it figures there are tab positions set  every  eight  characters
and it expands the lines with spaces to make the tabs correspond  to  these
positions.  This is initially the default.

"/EJECT=str" says to replace the page eject  character  (decimal  12)  with
another  string.   This  replacement  can  be  0  characters  (if  you  say
"/EJECT=(NONE)"), 1 character, or 2 or more  characters.   The  string  can
include text, decimal, or hexadecimal characters (see  BRUCEHEX.TXT).   Any
/EJECT=str   specification   overrides    any    specification    in    the
character-translation tables.

"/-EOF" says to not automatically add an end-of-file indicator at  the  end
of the output file.  "/EOF" is initially the default.

"/EOF" ends each file with an end-of-file (decimal 26) indicator.  This  is
initially the default.

"/Frptfile" specifies the file name  to  write  out  the  results  of  this
program to.  By default, no report is created.  If you want  one,  however,
it will include the date, time, and file name being processed  as  well  as
all lines that had problems.  The file is  appended  to  each  time  so  it
contains a running log of what you've run.  You can change this  file  name
to something else (and provide drive and path information  if  desired)  or
you can say /-F and avoid creating the file altogether.

"/-F" says to skip producing  the  changed-line  file  entirely.   This  is
initially the default.

"/Q" turns off the line-by-line status messages.

"/Qn" shows a status message every n-number of lines/blocks.   The  default
is "/Q25".


FIXTEXT.TXT                          7                         Nov 06, 1999

"/L" says to read all  character-translation  codes  from  your  /Iinitfile
file.  This is initially the default.

"/Linitfile" says that the "Character-translation" codes  are  found  in  a
file other than from the default  "/Iinitfile"  file.   This  is  primarily
useful if you want to have a master *.INI file and a separate  code  lookup
table.

"/-L" skips loading any character translation tables at all.   The  program
just does tab expansions and changing text formats (say, DOS text into Unix
text) then.

"/MONO" (or "/-COLOR") does not try to override screen  colors.   Initially
defaults to "/COLOR".

"/COLOR" (or "/-MONO") allows screen colors  to  be  overridden.   This  is
initially the default.

"/Iinitfile" says to  read  an  initialization  file  with  the  file  name
"initfile".  The file specification *must* contain a period.  Initfiles are
described in the BRUCEINI.TXT file.  Initially defaults to "/IFIXTEXT.INI".

"/-I" (or "/INULL") says to skip loading  the  character-translation  table
and initialization file.  In this case, the  default  character-translation
table is used.  See the "Character-translation table" discussion above.

"/ENV" says to look for %var% occurrences in the command line  and  try  to
resolve any apparent environmental variable references.   See  BRUCEINI.TXT
for more information.  This is initially the default.

"/-ENV" says to skip resolving apparent %var% occurrences  in  the  command
line.  Initially defaults to "/ENV".

"/?" or "/HELP" or "HELP" shows you the syntax for the command.

"/?HEX" gives you a hexadecimal and decimal conversion table.


FIXTEXT.TXT                          8                         Nov 06, 1999

Return codes:

FIXTEXT returns the following ERRORLEVEL codes:
        0 = no problems, changes made
        1 = no problems, no changes made
      249 = non-text file encountered despite /TEXT option
      254 = program aborted
      255 = syntax problems, file not found, or /? requested


Author:

This program was written by Bruce Guthrie of Wayne Software.   It  is  free
for use and redistribution provided relevant documentation is kept with the
program, no changes are made to the program or documentation, and it is not
bundled with commercial programs or charged  for  separately.   People  who
need to bundle it in for-sale packages must pay a $50 registration  fee  to
"Bruce Guthrie" at the following address.

Additional information about this and other Wayne Software programs can  be
found in the file BRUCE.TXT which should be included in  the  original  ZIP
file.  The recent change  history  for  this  and  the  other  programs  is
provided in the HISTORY.ymm file which should be in the same ZIP file where
"y" is replaced by the last digit of the year and "mm"  is  the  two  digit
month of the release; HISTORY.611 came out in  November  1996.   This  same
naming convention is used in naming the ZIP file (FIXTXymm.ZIP)  that  this
program was included in.

Comments and suggestions can also be sent to:

                Bruce Guthrie
                Wayne Software
                113 Sheffield St.
                Silver Spring, MD 20910

                e-mail: WayneSof@erols.com   fax: (301) 588-8986
                http://www.geocities.com/SiliconValley/Lakes/2414
             or find through http://www.erols.com/waynesof

Please provide an Internet e-mail address on all correspondence.


