DROPCONVERT v3.2 - Manipulate, Filter and Translate Text Files
==============================================================

Copyright (c) 1998 Simon A Carter for Crystal Software

DropConvert is SHAREWARE and may be trialed for a period of 30 days. After
this time you must either purchase the registered version (for $20) or
cease using the shareware version.

Please register your USAGE of DropConvert by sending email to
launch@ozemail.com.au, with your name and address, the version of
DropConvert you are using and any relevant comments or suggestions. By
registering DropConvert we can inform you of updates or improvements and
let you know when the next version is released.

If you like and use DropConvert, how about linking to our Web site (see
below)?

Please read the file ORDER.TXT for other registration options.


Online Web Registration at Albert's Ambry
=========================================
The registered version of DropConvert can be purchased and received
immediately on the Internet, eliminating shipping and handling costs.

Direct URL: http://secure.alberts.com/p?product=645&source=authprg

OR go to

  http://www.alberts.com

and search for: DropConvert

Click on the "Buy it" hotlink to register DropConvert.


Contact Information
===================
We are always happy to hear your comments! If you use and like
DropConvert, or have any suggestions for improvements, please drop us a
line! Other user's suggestions have made it what it is today.

Email:      launch@ozemail.com.au
  WWW:      http://www.ozemail.com.au/~launch
  Fax:      +61 (3) 9800-3078
Voice:      +61 (3) 9888-3104. After hours number. Please leave a
           contact name, number and time, and we will try to get back
           to you within 24 hours.
 Mail:      Simon Carter
           Crystal Software
           2 / 9 Woodbine Court
           Wantirna
           Victoria 3152
           AUSTRALIA.


Benefits
========
DropConvert is a powerful 32-bit utility that can apply a set of
conversion, translation and filtering operations to a group of files or to
the contents of the Windows clipboard.

Its myriad uses include:

    *   Cross-platform development
    *   Quick text processing
    *   Adding extra word-processing capabilities through converting the
        clipboard contents
    *   Adding line breaks between fixed-length records
    *   Performing multiple search/replaces on a batch of files - very
        useful for Web sites.
    *   Converting or reading mainframe, Unix, DOS, Amiga or Macintosh
        files
    *   Making HTML files readable without a Web browser
    *   Reducing the size of HTML files for faster page loading
    *   Reformatting text eg. preparing ASCII files for word processing
    *   Making text files readable that contain ANSI escape codes,
        binary characters or IBM graphics characters
    *   Adding an email reply prefix to every line
    *   Converting text from one language to another (eg Pascal to c)
    *   Reducing the size of source code
    *   Making global source code changes
    *   Correcting text files incorrectly FTP'd in binary mode.

DropConvert can be entirely command-line-driven for automation eg.
overnight batch runs. It is multi-threaded, so multiple conversions can
occur simultaneously. Multiple filters can be stacked in a user-defined
order, so multiple search and replace operations can occur in a single
pass.

DropConvert runs under Windows 95, 98 or NT.


Features
========
DropConvert can perform automated or manual line-feed conversion to and
from DOS, Unix, Amiga and Macintosh input formats, and convert fixed-
length records (with a user-specified length) to separate lines.

To make files smaller and/or more readable, DropConvert offers filters to:
    *   remove binary characters
    *   remove ANSI escape sequences
    *   remove blanks from the start and end of lines
    *   remove blank lines
    *   compress multiple whitespace to a single space
    *   remove HTML and SGML codes
    *   remove or resolve backspaces
    *   change IBM drawing characters to + and | and -

To manipulate the text in files, DropConvert offers filters to:
    *   perform arbitrary user-defined translations. The user can
        specify a string to be output for each of the 256 possible
        character codes. Strings can contain embedded control characters
    *   search and replace: with Case Sensitivity and Whole Words
        option. It gives the length of search and replace strings --
        especially useful for text replacement in binary files
    *   add line numbers
    *   add a prefix to every line (eg to add reply quotes to email)
    *   add text to the start and/or end of every file
    *   change character case: UPPERCASE, lowercase, tOGGLE cASE, Title
        Case, Sentence case
    *   word wrap text at a specified column
    *   expand tabs or compress spaces to tabs
    *   change character collating sequence: ASCII <=> EBCDIC. Useful
        for mainframes
    *   change Windows OEM <=> ANSI. Useful with Windows and non-English
        languages

DropConvert offers the following file processing options:
    *   can skip binary files (those with less than 80% readable
        characters) The user
    *   can also be prompted whether to process a binary file or not
    *   can prompt before processing each file
    *   can retain the original file's time and date
    *   can recurse into subdirectories
    *   can process both text and binary files of any size
    *   test mode, where output goes to a new file rather than
        overwriting the original file

Special features include:
    *   Filter lists can be saved and loaded, and inserted at the
        current cursor position
    *   Files can be quickly viewed with their associated application
    *   Many methods of adding files to the list - selected via
        wildcards on the command line, specified in the application,
        drag and drop from explorer or via a Browse dialog
    *   Accepts a list filename on the command line to include large
        lists of files that couldn't otherwise be specified. Can be used
        in conjunction with the Load List From File and Save List To
        File facilities
    *   Accepts wildcards on the command line and in list files. The
        wildcards are expanded during processing


Installation
============
DropConvert is simple to install, and no configuration is required. A
single copy can be placed on the file server for everyone to access.

Create a new directory for DropConvert under your c:\Program Files
directory. Extract all the files to this directory.

   c:\> cd "Program Files"    [Enter]
   c:\Program Files> mkdir "DropConvert"   [Enter]
   c:\Program Files> cd "DropConvert"   [Enter]
   c:\Program Files\DropConvert> pkunzip a:\dropconv.zip [Enter]

DropConvert will create the registry entries that it needs when it is
first run. It will also create a new desktop icon.


   Creating an Explorer Context Menu
   ---------------------------------
   You can add a file association for DropConvert so it will appear when
   you right-click on a text file.  In an Explorer window, click
   View\Options. Select the "File Types" tab and the "Text Document"
   entry and click "Edit". Click "New" and give it an appropriate
   "Action" name (like "DropConvert...") and use
   
     "C:\Program Files\DropConvert\DropConvert.exe" "%1"
   
   as the program path and name.


How To Use DropConvert
======================
Using DropConvert is simple:

  1.   Select the desired conversion/translation options by selecting them
     from the menus. Some filters can be customised by selecting them in the
     list and then changing the fields shown on the right hand side
  2.   If you wish to process the contents of the clipboard (and leave the
     result in the clipboard), the final stage is to click on "Clipboard"
  3.   Click on the Files tab and choose the files to process. There are
     four main methods for doing so:
     
       a)  Provide the names of the files you wish to process on the
           command line, either by name (using wildcards) or in a list file
           (using the /f=<filename> option)
       b)  Drag and drop the files from Windows Explorer either onto
           DropConvert's main window or onto its icon
       c)  Type a filespec (eg. a:\*.txt) into the files dialog box and
           click [Add]
       d)  Click the browse button, then select a group of files and then
           click [Ok]
       e)  ...or any combination of these methods
       
       The resulting file list can be edited by selecting entries and
       pressing [Remove] to remove selected entries or by pressing [Remove
       All] to remove all entries
       
  4.   The [View] button can be used to display the selected file(s) in
     their associated applications
5.   If desired, click on the File Options tab to changing processing
options
6.   Click the "Go" button to start conversion
7.   While the conversion is in progress, you can click the "Cancel"
button to cancel it, or you can use the main window to build up another
conversion job.


While DropConvert allows filtering and replacing in binary files (such as
.DOC, .XLS etc), these proprietary format files may contain internal
counters that can be corrupted if the file contents are indiscriminately
altered.  As a result, the application that created the file may not be
able to read it. For best results, replace in ASCII text files (such as
.HTM, .RTF, .TXT, .INI, .C, .CPP, .H etc). In particular, Word files
should be converted to the RTF format, which can be safely processed.


User Interface
==============

   File Lists
   ----------
   DropConvert can read the file list from a file. This means that you
   can easily create a list of files to process for various tasks, and
   load it when required rather than go through the laborious task of
   adding the files to the list each time.
   
   The file consists of a single file specification per line eg.
   
   c:\my documents\*.txt
   c:\bp\*.pas
   d:\job_ads\*.*
   
   To load a file list, click on the load icon on the files tab. An open
   dialog box appears. Select one or more files to load and click on the
   Ok button.
   
   The currently displayed file list can be saved to a file by clicking
   on the save icon on the files tab. A save dialog appears and an
   existing filename can be selected or a new one specified.
   
   A file list can be loaded from the command line by using the
   /F=<filename> option.
   
   
   Filter Lists
   ------------
   DropConvert can read a filter list from a file. This means that you
   can easily define a filtering operation for different tasks, and load
   it when required rather than go through the laborious task of setting
   up the filters each time.
   
   A filter file is stored in an internal format and should not be
   edited.
   
   To load a filter list, select File\Open Filter List. An open dialog
   box appears. Select a filter to load and click on the Ok button. A
   filter list can also be inserted at the current cursor position by
   selecting File\Insert Filter List.
   
   The currently displayed filter list can be saved to a file by
   selecting File\Save filter List. A save dialog appears and an existing
   filename can be selected or a new one specified.
   
   A filter list can be loaded from the command line by using the
   /L=<filename> option.
   
   
   Unprintable Characters
   ----------------------
   DropConvert allows you to embed control characters in search and
   replace strings, line prefixes and user-defined replacement strings.
   Once you know the ASCII code of the character to embed, precede it
   with a '\' character and enter its 3 digit decimal code (leading
   zeroes are required). To include the '\' character you must double it
   ie '\\'.
   
   Eg.
   
   To search for "hello" followed by a tab followed by "there" followed
   by a DOS end of line,
   
   Enter the search string as "hello\009there\013\010", where \009 is the
   code for a Tab, \013 if the code for a carriage return and \010 is the
   code for a line feed (see the table at the end of this document).
   
   
   Drag and Drop
   -------------
   Files dropped from Windows Explorer onto either DropConvert's icon,
   its minimised window or its open window are automatically placed in
   the files list.
   
   
File Options
============
The following options only apply when files are being processing - they do
not apply to the clipboard.

   Prompt for each file
   --------------------
   Before processing each file, DropConvert prompts the user to confirm
   that the file should be processed.
   
   This option cannot be enabled from the command line.
   
   
   Retain original file date/time
   ------------------------------
   The processed file is given the same date and time as the original
   file.
   
   This option can be enabled on the command line by using the /N option.
   Retaining the date and time is disabled by default.
   
   
   Binary files
   ------------
   Generally it isn't useful to process binary files, because they have
   structure imposed on them by the file format (unlike text files).
   Files that look like they are binary (less than 80 of the first 100
   characters are readable) are considered to be binary.
   
   This option can be enabled on the command line by using the /B=P
   (process binary files) or /B=S (skip binary files) option. The option
   to prompt cannot be chosen from the command line.
   
   
   Test mode
   ---------
   The processed file is output to a new file. This is handy to ensure
   that you don't destroy your original file. The new file is the
   original file's name with '.dCv' added to it.
   
   This option can be enabled on the command line by using the /T option.
   Test mode is disabled by default.


Filters
=======
This section describes the filters whose purpose is not obvious.


   Remove ANSI Escape Sequences
   ----------------------------
   ANSI (American National Standards Institute) codes are included in
   various streams of information (most commonly BBS connections), to
   provide a remote computer with control over cursor positioning, text
   attributes, etc. They are also used in connections between
   minicomputers and mainframe computers and the terminals connected to
   them.
   
   The need to use an ANSI filter can be recognised when something like
   the following example shows up in a file viewed in a text editor:
   
                        <[0;1;4mas<[m - MC88000 assembler
   
   In this example the "as" near the beginning is displayed in a
   different colour than the rest of the line when the ANSI codes are
   properly processed. The Escape (ASCII 27) codes above have been
   replaced by the < symbol to make this line printable.
   
   The Remove ANSI Escape Sequences filter can be used to filter out
   these codes and "clean up" the text so that it can be used in standard
   fashions such as copying and pasting into a word processor. On Unix
   machines the man (manual) help utility will only allow page-by-page
   browsing through a file in a forward direction. By piping the man
   output to a text file, transferring it to a DOS machine, and running
   it through the Remove ANSI Escape Sequences filter (and the Convert
   EOL filter - Unix to DOS if desired), a standard DOS editor can be
   used for browsing through the file, quoting from it, etc.
   
   This filter can be enabled on the command line by using the /RA
   option.
   
   
   Remove Binary Characters
   ----------------------------
   Readable text generally only uses characters in the range 32-127. This
   filter removes all characters outside of this range, while leaving in
   carriage returns (13) and line feeds (10).
   
   This filter can be enabled on the command line by using the /RB
   option.
   
   
   Character Set Translation
   -------------------------
   Windows maintains two character sets, OEM and ANSI. ANSI is Window's
   internal character set, while OEM is specific to the country or locale
   that the computer operates in (eg Sweden). A file saved as OEM and
   sent to a different country will appear garbled unless it is first
   converted to ANSI.
   
   This filter can be enabled on the command line by using the /H<A|O>
   option.
   
   
   Representation Translation
   --------------------------
   The character representation defines the decimal code assigned to
   various symbols eg. Under ASCII, the letter 'A' is encoded as 65.
   Under EBCDIC, the letter 'A' is encoded as 193, which, if viewed on an
   ASCII-based machine, is '-'. This filter converts between these two
   representations. Some characters are not present in both
   representations and therefore assume the closest match.
   
   This filter can be enabled on the command line by using the /P<A|E>
   option.
   
   
   Add text to start of lines
   --------------------------
   The line prefix filter is used to add a string to the start of every
   line. This can be useful for adding "quote" characters to email
   replies, where the received mail has '> ' inserted in the left margin
   to differentiate it from the sender's responses. It can also be used
   to indent text by setting the string to a number of spaces.
   
   This filter can be enabled on the command line by using the
   /AS=<string> option.
   
   
   Word Wrap
   ---------
   The word wrap filter ensures that no lines are longer than the
   specified column width. Once a line extends beyond the column width,
   DropConvert scans the line backwards for the first space character,
   and inserts a CR/LF (\013\010) after it. If it can't find a space, it
   then searches for a '-'. If it can't find either of these, it simply
   breaks the line at the column width.
   
   This filter can be enabled on the command line by using the
   /WW<number> option.
   
   
   Translate IBM Drawing Characters
   --------------------------------
   The character set used by PCs includes special characters for drawing
   lines and boxes and for shading. These characters do not exist on
   other machines (eg Unix, Macintosh etc), and hence these characters
   will not be displayed correctly (usually as gibberish). This filter
   converts the special characters to the +, - and | characters which
   exist in all character sets and hence will always display properly.
   
   This filter can be enabled on the command line by using the /DD
   option.
   
   
Command Line Options - Summary
==============================
DropConvert can be run from a DOS shell or from a shortcut with parameters
to make it run totally automatically. This is very useful for performing
conversions automatically or on machine start up (by making the short cut
an entry in the Start Up folder).


Usage:
   DropConvert [options] [wildcards]

Where [options] is zero or more of:
<wildcard>      A wildcard or filename to add to the list of files to
                process
/AE=<string>    Add string to end of every file
                
                For strings with embedded spaces, surround the whole
                parameter in quotes eg
                  DropConvert "/AE=\013\010- (c) Copyright 1998 Simon
                Carter"
/AS=<string>    Add string to start of every line
/AT=<string>    Add string to top (start) of every file
/AL<first>,<inc Add line numbers, starting with first, and going up in
r>              steps of incr
/B<P|S>         Skip binary files. Default: Skip. Use
                  P  Process binary files
                  S  Skip binary files
/C<U|L|S|T|I>   Case translation.
                  U  UPPER CASE - changes all letters to upper case
                  L  lower case - changes all letters to lower case
                  S  Sentence case - capitalises the first letter of the
                    first word in each sentence
                  T  Title Case - capitalises the first letter of every
                    word
                  I  tOGGLE cASE - changes all upper case letters to lower
                    case and vice versa
/D<A|B|E|H|K|L| Remove
O|R|S|W>          A  ANSI codes - removes ESC[ sequences
                  B  Binary characters - removes all chars > 127
                  D  Translate IBM drawing characters
                  E  Blanks from End of Lines
                  H  HTML and SGML. Removes all text inside <> pairs
                  K  Backspaces
                  L  Blank lines
                  R  Resolve backspaces ie remove any previous characters
                  S  Blanks from Start of Lines
                  W  Multiple whitespace ie replace with single space
/E[R]<D|M|U|A|F End-of-Line (line feed) conversion.
[cpr]><D|M|U|N> 
                Specify 'R' to NOT remove extraneous line feed characters
                (eg #13 characters in a Unix file). The default is on. The
                option only has effect for Mac, Dos and Unix input file
                formats.
                
                Input format:
                  M  Mac
                  D  DOS
                  U  Unix/Amiga
                  A  Auto
                  F  Fixed Length, followed by the number of characters
                    per record (cpr).
                Output format:
                  M  Mac
                  D  DOS
                  U  Unix/Amiga
                  N  None
                
                eg /EF172D converts from 172 character fixed length record
                to DOS
/F=<filename>   Load filter list from filename
/G              Go! Begin a conversion thread with the specified options.
                You can specify extra options and follow them with /G
                again to start a second thread of execution. All options
                return to default settings
/H<O|A>         Character set translation
                  O  OEM -> ANSI
                  A  ANSI -> OEM
/I              Subdirectory recursion. Default: On. Specifying this
                option turns it off
/L=<filename>   Name of a list file to process for wildcards. The file
                should contain one wildcard per line eg.
                
                C:\docs\*.txt
                D:\unix\*.*
                ...etc
/P<A|E>         Collating sequence translation
                  A  ASCII -> EBCDIC
                  E  EBCDIC -> ASCII
/Q              Exit after completion. Default: Off. Enabling this option
                causes DropConvert to exit immediately after all
                conversion threads complete
/R=<replace>    Replace string. For strings with embedded spaces, surround
                the whole parameter in quotes eg
                DropConvert /SWC=Roses "/R=Yellow Violets"
/S[W][C]=<searc Search string.
h>              
                To specify a case-sensitive search (ie the search string's
                capitalisation must be matched exactly), specify 'C'
                between the '/S' and '='. The default is a case-
                insensitive search.
                
                To only match whole words, specify 'W' between the '/S'
                and '='. The default is to match the search string
                anywhere (even within other words).
                
                For strings with embedded spaces, surround the whole
                parameter in quotes eg
                DropConvert "/SC=roses are blue" "/R=violets are yellow"
/T              Test mode. Default: Off. Specifying this option turns test
                mode on
/TS<number>     Expands tabs to spaces. Each tab is replaced by from 0 to
                number-1 spaces depending on the current column
/ST<number>     Compresses spaces to tabs. Tab stops are number columns
                apart
/U=<filename>   User defined translation - loads the specified .udt file
/WW<number>     Word wrap with column width of number


Standard ASCII codes
====================
ASCII = American National Standard Code for Information Interchange

Quoted-Printable encoding uses 3 digit decimal code prefixed by \ eg. CR
is \013.
Decimal   Code    ASCII
      0 NUL       Null
      1 SOH       Start of Heading (CC)
      2 STX       Start of Text (CC)
      3 ETX       End of Text (CC)
      4 EOT       End of Transmission (CC)
      5 ENQ       Enquiry (CC)
      6 ACK       Acknowledge (CC)
      7 BEL       Bell
      8 BS        Backspace (FE)
      9 HT        Horizontal Tabulation (FE)
     10 LF        Line Feed (FE)
     11 VT        Vertical Tabulation (FE)
     12 FF        Form Feed (FE) or Page Eject
     13 CR        Carriage Return (FE)
     14 SO        Shift Out
     15 SI        Shift In
     16 DLE       Data Link Escape (CC)
     17 DC1       Device Control 1
     18 DC2       Device Control 2
     19 DC3       Device Control 3
     20 DC4       Device Control 4
     21 NAK       Negative Acknowledge (CC)
     22 SYN       Synchronous Idle (CC)
     23 ETB       End of Transmission Block (CC)
     24 CAN       Cancel
     25 EM        End of Medium
     26 SUB or    Substitute or End of File
        EOF
     27 ESC       Escape
     28 FS        File Separator (IS)
     29 GS        Group Separator (IS)
     30 RS        Record Separator (IS)
     31 US        Unit Separator (IS)
     32 SP        Space
     33 !         Exclamation Point
     34 "         Quotation Mark
     35 #         Number Sign, Octothorp, "pound"
     36 $         Dollar Sign
     37 %         Percent
     38 &         Ampersand
     39 '         Apostrophe, Prime
     40 (         Left Parenthesis
     41 )         Right Parenthesis
     42 *         Asterisk, "star"
     43 +         Plus Sign
     44 ,         Comma
     45 -         Hyphen, Minus Sign
     46 .         Period, Decimal Point, "dot"
     47 /         Slash, Virgule
     48 0         0
     49 1         1
     50 2         2
     51 3         3
     52 4         4
     53 5         5
     54 6         6
     55 7         7
     56 8         8
     57 9         9
     58 :         Colon
     59 ;         Semicolon
     60 <         Less-than Sign
     61 =         Equal Sign
     62 >         Greater-than Sign
     63 ?         Question Mark
     64 @         At Sign
     65 A         A
     66 B         B
     67 C         C
     68 D         D
     69 E         E
     70 F         F
     71 G         G
     72 H         H
     73 I         I
     74 J         J
     75 K         K
     76 L         L
     77 M         M
     78 N         N
     79 O         O
     80 P         P
     81 Q         Q
     82 R         R
     83 S         S
     84 T         T
     85 U         U
     86 V         V
     87 W         W
     88 X         X
     89 Y         Y
     90 Z         Z
     91 [         Opening Bracket
     92 \         Reverse Slant
     93 ]         Closing Bracket
     94 ^         Circumflex, Caret
     95 _         Underline, Underscore
     96 `         Grave Accent
     97 a         a
     98 b         b
     99 c         c
    100 d         d
    101 e         e
    102 f         f
    103 g         g
    104 h         h
    105 i         i
    106 j         j
    107 k         k
    108 l         l
    109 m         m
    110 n         n
    111 o         o
    112 p         p
    113 q         q
    114 r         r
    115 s         s
    116 t         t
    117 u         u
    118 v         v
    119 w         w
    120 x         x
    121 y         y
    122 z         z
    123 {         Opening Brace
    124 |         Vertical Line
    125 }         Closing Brace
    126 ~         Tilde
    127 DEL       Delete
    128           Reserved
    129           Reserved
    130           Reserved
    131           Reserved
    132 IND       Index (FE)
    133 NEL       Next Line (FE)
    134 SSA       Start of Selected Area
    135 ESA       End of Selected Area
    136 HTS       Horizontal Tabulation Set (FE)
    137 HTJ       Horizontal Tabulation with
                 Justification (FE)
    138 VTS       Vertical Tabulation Set (FE)
    139 PLD       Partial Line Down (FE)
    140 PLU       Partial Line Up (FE)
    141 RI        Reverse Index (FE)
    142 SS2       Single Shift Two (1)
    143 SS3       Single Shift Three (1)
    144 DCS       Device Control String (2)
    145 PU1       Private Use One
    146 PU2       Private Use Two
    147 STS       Set Transmit State
    148 CCH       Cancel Character
    149 MW        Message Waiting
    150 SPA       Start of Protected Area
    151 EPA       End of Protected Area
    152           Reserved
    153           Reserved
    154           Reserved
    155 CSI       Control Sequence Introducer (1)
    156 ST        String Terminator (2)
    157 OSC       Operating System Command (2)
    158 PM        Privacy Message (2)
    159 APC       Application Program Command (2)
160-254           
    255           Invisible space
NOTES:
  (1) Introducer
  (2) String Delimiter
  (CC) Communication Control
  (FE) Format effector
  (IS) Information Separator
