home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / utility / misc / convx.lha / Convert / Convert.doc < prev    next >
Encoding:
Text File  |  1992-09-01  |  11.8 KB  |  301 lines
  1.  
  2.  
  3.                       ╗ ╗ ╗ ╗ ╗  C O N V E R T  ½ ½ ½ ½ ½
  4.  
  5.                         version 1.12, August 31th, 1992
  6.  
  7.                                  User Manual
  8.  
  9.         ***************************************************************
  10.  
  11.                                   Contents
  12.  
  13.                    1. Introduction - What does "Convert" ?
  14.                    2. Getting started
  15.                    3. Working with "Convert"
  16.                    4. Creating own conversion descriptions
  17.                    5. Error messages
  18.  
  19.         ***************************************************************
  20.  
  21.  
  22.         1. Introduction
  23.  
  24.  
  25.         "Convert" is a powerful file conversion program. It covers the
  26.         application domain of all ASCII conversion tools between Amiga
  27.         and MS-DOS or any other computer system. This means, that file
  28.         conversion with "Convert" does NOT affect the physical format of
  29.         a file but only its contents. Physical conversion is not subject
  30.         of "Convert" and thus assigned to tools like "CrossDOS".
  31.  
  32.         "Convert" can be used to replace bytes or pairs of bytes in a
  33.         file by another byte or another pair of bytes or by nothing.
  34.         Therefore it can be used tasks as follows:
  35.  
  36.         - replacing TABs in an ASCII file with blank character(s)
  37.         - stripping controls in an ASCII file
  38.         - converting ASCII-files between Amiga and MS-DOS, MS-DOS and
  39.           Amiga, Amiga and Mac, Mac and Sun, Amiga and Sun etc.
  40.  
  41.         What are "conversion descriptions" ?
  42.  
  43.         All that "Convert" needs, is a set of "replacement records"
  44.         which it can apply to its input files. This set is in the
  45.         following called "conversion description".
  46.         You can create your individual conversion descriptions by
  47.         creating several "replacement records" with a text editor using
  48.         the simple syntax described in Chapter 4. These "records" are
  49.         stored to a conversion description file which can be parsed by
  50.         "Convert".
  51.  
  52.         The draft of specifying the conversion by a simple text file
  53.         makes "Convert" more powerful than any other conversion tool
  54.         and thus allows the application of "Convert" for almost all
  55.         conversion problems.
  56.  
  57.  
  58.         ***************************************************************
  59.  
  60.  
  61.         2. Getting started
  62.  
  63.  
  64.         Installation
  65.  
  66.         To install "Convert" double-click the "Install" icon. This short
  67.         shell script will copy the libraries required by "Convert" into
  68.         the LIBS: directory. The program needs
  69.  
  70.         - arp.library (v39.1),
  71.         - reqtools.library (v38.362 or higher) and
  72.         - intuisup.library (v4.5 or higher).
  73.         
  74.         Furthermore, you must have a directory from where "Convert" reads
  75.         its conversion description files. If this directory is not the
  76.         same as the one where "Convert" is placed, you must assign the
  77.         logical device "CVT:" to it.
  78.         If "Convert" starts, first it looks in the current directory for
  79.         conversion descriptions. If it cannot find any matching file
  80.         (with the extension ".cvt"), it tries to get files from "CVT:".
  81.         NOTE: If "Convert" cannot find any description files, it will
  82.         NOT work !
  83.  
  84.  
  85.         Starting "Convert"
  86.  
  87.         You can start "Convert" by entering its name in the shell or by
  88.         double-clicking its icon.
  89.         If the program can locate at least one conversion description,
  90.         it opens a window which contains the control panel of "Convert".
  91.         This panel consists of following elements:
  92.  
  93.         * Source file list *
  94.  
  95.         This list on the left side of the buttons displays the names of
  96.         all files to be converted. The names are shown without path
  97.         name, except if you select two files in different directories
  98.         with the same name. Then the whole path name is displayed.
  99.  
  100.         * Conversion list *
  101.  
  102.         This list on the right side of the buttons displays the names
  103.         of the conversion description files which "Convert" could locate
  104.         at the start. The currently selected conversion description file
  105.         is shown by a high-lighted selection. By default the first name
  106.         of the list is selected.
  107.  
  108.         * Button "Clear" *
  109.  
  110.         You can use this button for deleting the current contents of the
  111.         source file list. If the files in this list have not been
  112.         converted yet, you will be asked to confirm your decision.
  113.  
  114.         * Button "Add files..." *
  115.  
  116.         If you click this button, a file requester will appear. You can
  117.         then select the files which you want to convert by clicking on
  118.         the file names while holding the SHIFT key. In addition there are
  119.         buttons for selecting and de-selecting all files and for pattern
  120.         matching (absolutely great, Nico !).
  121.         Press the button "Ok" to add the selected files to the source file
  122.         list.
  123.  
  124.         * Button "Remove" *
  125.  
  126.         You can use this button for deleting the currently selected item
  127.         in the source file list. If the files in this list have not been
  128.         converted yet, you will be asked to confirm your decision.
  129.  
  130.         * Button "Start" *
  131.  
  132.         A click on this button starts the conversion process.
  133.  
  134.         * Button "About..." *
  135.  
  136.         Click this button to get short information about "Convert".
  137.  
  138.         * Button "Quit" *
  139.  
  140.         You can use this button for exiting "Convert". If the files in the
  141.         source file list have not been converted yet, you will be asked
  142.         to confirm your decision. You can also quit by clicking in the
  143.         close gadget of "Convert"'s window.
  144.  
  145.  
  146.         ***************************************************************
  147.  
  148.  
  149.         3. Working with "Convert"
  150.  
  151.  
  152.         When you have started "Convert" from the shell or from workbench,
  153.         it will open a window which contains a small control panel.
  154.         The source file list on the left side of the buttons is empty,
  155.         so the buttons "Clear" and "Start" are "ghosted".
  156.         Whenever you want to append files to the source file list, press
  157.         the button "Add files". A file requester will appear which allows
  158.         you to select the desired files. Press the "Ok" button to
  159.         append the files to the source file list.
  160.         Before you start the conversion process, make sure you have
  161.         selected the correct conversion description in the list on the
  162.         right side of the buttons. The current description is shown in
  163.         the string gadget below the list.
  164.         The conversion process can be started by pressing the "Start"
  165.         button. "Convert" will open a window which gives you a simple
  166.         trace about the conversion.
  167.         If the conversion description contains no syntax errors, the
  168.         conversion should be performed without any problem. Otherwise
  169.         you have to correct the description file with a text editor.
  170.         At the end "Convert" informs you with a simple requester about
  171.         the success of the conversion process.
  172.         If there were no problems, you can return to the control panel.
  173.         Usually you will want to clear the source file list for the next
  174.         conversion procedure or to quit from "Convert".
  175.  
  176.  
  177.         ***************************************************************
  178.  
  179.  
  180.         4. Creating own conversion descriptions
  181.  
  182.  
  183.         A conversion description file consists of a set of replacement
  184.         records. Such a record describes how a byte or a pair of bytes
  185.         should be replaced by another byte or another pair of bytes or
  186.         by nothing.
  187.         The structure of a conversion description can thus be described
  188.         with the following grammar in EBNF:
  189.  
  190.         ConvDescr = { ReplRec }.
  191.         ReplRec = Byte [ "," Byte ] "->" [ Byte [ "," Byte ] ].
  192.         Byte = digit { digit }.
  193.  
  194.         digit = "0"|"1"|"2"|..|"9".
  195.  
  196.         Each replacement record must be written in a separate line.
  197.  
  198.         Furthermore a conversion description may contain comments which
  199.         are written like in the programming languages Ada or Eiffel
  200.         (beginning with "--", until end of line). The comments must NOT
  201.         occur after a replacement record.
  202.  
  203.         Example:
  204.  
  205.         -- this is a short example of a conversion description
  206.  
  207.         --replace the byte pair (14,37) with the byte 121
  208.         14,37->121
  209.         --replace the byte 154 with the byte 254
  210.         154->254
  211.         --strip the byte pair (31,201)
  212.         31,201->
  213.  
  214.         --the following lines are incorrect:
  215.         14,37,->12
  216.         ->13
  217.         20->41 --this comment does not belong here !
  218.  
  219.         (end of file)
  220.  
  221.  
  222.         ***************************************************************
  223.  
  224.  
  225.         5. Error Messages
  226.  
  227.  
  228.         "Convert" distinguishes between internal and user errors.
  229.  
  230.         Internal errors are reported by a short output in the shell
  231.         window or a requester with the title "FATAL ERROR". If an
  232.         internal error occurs, the reason may be lack of memory. The
  233.         execution of "Convert" is immediately terminated and you have
  234.         to increase the free memory size by quitting from another
  235.         application before restarting "Convert".
  236.         There exists one special internal error which is raised, if
  237.         "Convert" cannot find any conversion description files. This
  238.         error is named
  239.  
  240.         "Cannot find a conversion description ! - No conversion possible."
  241.  
  242.  
  243.         User errors are reported in a requester named "Information".
  244.         Errors of this kind may occur during a conversion process.
  245.         In this case "Convert" will stop the process and return to the
  246.         control panel. The user errors are listed below.
  247.  
  248.         "Error in conversion description or description file not found"
  249.  
  250.         This error may occur at the beginning of the conversion process
  251.         when "Convert" tries to open and to parse the current
  252.         conversion description file.
  253.         Since the list of description files is created at the start of
  254.         "Convert", another task may have removed the requested file.
  255.         Otherwise a syntax error in the file has been encountered which
  256.         must be corrected before you restart the conversion process.
  257.  
  258.         "File not found or conversion of empty file attempted"
  259.  
  260.         This error may occur during the conversion process, when
  261.         "Convert" cannot open a source file. Another task may have
  262.         removed the file between the selection of the file and the
  263.         beginning of the conversion process.
  264.  
  265.         "Could not get/set file date"
  266.  
  267.         This message appears if the handler process of the device from
  268.         which the source files are read does not understand the SET_DATE
  269.         command. "Convert" tries to save the old date of a file, since
  270.         only the file structure should be changed.
  271.         If the device driver of your harddisk does not support date
  272.         setting, then try the conversion with another device, i.e. RAM:.
  273.  
  274.         "Cannot create temporary file"
  275.  
  276.         In general "Convert" does not save the converted file directly
  277.         over the original file, but creates a temporary file in the same
  278.         directory where the original file is located. If a write-protected
  279.         file with the same name ("CvtTmp_<task address>") exists in this
  280.         directory ,this message tells you that "Convert" will save the
  281.         converted file directly over the original file.
  282.  
  283.         "Cannot write converted file"
  284.  
  285.         If one of the source files is opened for output by another
  286.         task during the conversion process, this error will be reported.
  287.  
  288.  
  289.         ***************************************************************
  290.  
  291.  
  292.         If you find any bugs or you have any ideas how to improve this
  293.         this product, then contact me:
  294.  
  295.               ///   Rainer Koppler
  296.              ///    Stelzhamerstra▀e 9
  297.         \\\ ///     A-4623 Gunskirchen
  298.          \\X//      Austria/Europe
  299.  
  300.         internet: rainer@soft.uni-linz.ac.at
  301.