home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / programm / utility / resgrep0.lzh / ResGrep / doc / ResGrep.doc
Encoding:
Text File  |  1992-04-24  |  10.1 KB  |  337 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                                                   ResGrep
  7.  
  8.  
  9.  
  10.                           
  11.                                               Version 0.2 beta
  12.  
  13.  
  14.  
  15.  
  16.                        Idea and Written: Andre Florath
  17.  
  18.                                           copyright 1992 by Andre Florath
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  Introduction
  25.  
  26.     ResGrep is a program to convert Apple Macintosch resource forks
  27.     to IFF. In the program there are two functional units: you can
  28.     decide which resource will be converted, and you can determine
  29.     how to convert the data.
  30.  
  31.     I wrote this program, because there are a lot *good* icons,
  32.     sounds, pictures on a Mac, and because I want to learn C++.
  33.     (It's my first program written in C++.)
  34.  
  35.     To select the resources you only have to click (only once; no
  36.     doubleckick is needed) at the type and id of the resource
  37.     (similar to ResEdit). But in ResGrep there are no editors or
  38.     viewers as there are in ResEdit. Your "normal" programs, i.e. a
  39.     texteditor, a graphic- or a soundeditor, undertake the task of
  40.     viewing or editing the data.  The interface between ResGrep an
  41.     the application is ARexx. The selected resource is converted to
  42.     IFF and written to a file or the clipboard. After that, an ARexx
  43.     script or an external (shell-)command is executed.
  44.  
  45.  
  46.  Hard- and Software Requirements 
  47.  
  48.     You only need an Amiga with 512KB RAM, AmigaOS 2.0, ixemulib
  49.     and some Mac Resource Files.
  50.  
  51.     Life is easier if you have a little bit more memory, a harddisk,
  52.     a lot of Mac Resource Files and some programs that support
  53.     ARexx, e.g. a graphic program, a sound program, a binary file
  54.     editor... 
  55.  
  56.     Recomanded is a >50Mhz chip set if you want to open more than
  57.     ten windows. (Try and see! That's no program bug! It's the
  58.     7.19MHz chip set. Why it's *SO SLOW*? Como please change!)
  59.     
  60.  
  61.  Install
  62.  
  63.     Copy the ResGrep executable to somewhere in your path. Copy the
  64.     other files to a place where they will live (e.g. 'copy
  65.     df1:ResGrep dh0:Progs all'). You may want to delete the sources
  66.     placed in the 'src' directory. Assign ResGrep: to the directory.
  67.     (e.g. 'assign ResGrep: dh0:Progs/ResGrep'). Be sure to have
  68.     'ixemulib.library' in your LIBS: directory. 
  69.  
  70.  
  71.  Mac Files
  72.  
  73.     Mac files consists of three parts, called forks: the data fork,
  74.     the info fork and the resource fork.
  75.  
  76.     The info fork contains system data for the MacOS and the Finder.
  77.  
  78.     The data fork contains the data, i.e. the program's code, the
  79.     ASCII characters of a text.
  80.  
  81.     The resource fork contains all the other data, i.e. sound,
  82.     pictures, icons, menus, menubars, requester, alerts, dialogs,
  83.     texts, version numbers, code, window definitions, palettes...
  84.     (You see, thats the most interesting fork. :-) )
  85.  
  86.  
  87.  How to get Mac Files to your Amiga 
  88.  
  89.     There are many ways to get Mac files to the Amiga. Two of them
  90.     -- those I have used -- are described here.
  91.  
  92.    Use StuffIt archives 
  93.  
  94.     The simplest way is to stuff the files on a Mac with StuffIt,
  95.     transfer them via modem or M*-DOS disks from Mac to Ami and
  96.      unstuff them. Every Mac file falls into the three pieces
  97.     described above. (The unstuff program is available on most 
  98.     boxes -- see Mac/Unix directory.)
  99.  
  100.    Use M*-DOS disks
  101.  
  102.     Save the files on the Mac to a M*-DOS disk. Put the disk in
  103.     the Amiga and list the contents. There will be a (hidden)
  104.     directory named 'RESOURCE.FRK' or 'RESOURC&'. Change to this
  105.     directory. There will be the resource forks of the Mac files.
  106.  
  107.  
  108.  How to use
  109.  
  110.    Start ResGrep
  111.  
  112.     Doubleclick the icon from Workbench or type 'ResGrep' in a
  113.     shell. The main window opens with the title: 'ResGrep -
  114.     FileList' and a file requester appears.
  115.  
  116.    Convert Resources to Amiga files 
  117.  
  118.     At first open a resource file. You can choose the name with
  119.     the file requester. Later on, to do this, select 'Open...'
  120.     from the Project Menu. The filename with a unique number
  121.     appears in the main window. In every window titel that belongs
  122.     to this file, this number will appear.  - To display the
  123.     resource types of a file, click at the resource's type. A
  124.     window with resource types will open.
  125.  
  126.     To display the resources IDs of a specific resource type click
  127.     at the resource type. To export the data click on the resource
  128.     id. 
  129.  
  130.     If you want to open a window that is already open, the window is
  131.     activated and popped to front.
  132.  
  133.    Hide and Reveal windows
  134.  
  135.     If you work with some resource files there may be a lot of open
  136.     windows. With the menuitem 'Hide >>' you can hide one (the
  137.     active) window, some (all windows that are opened while clicking
  138.     in the active window) or all windows. These windows disapear
  139.     but the contents, sizes and positions are saved. With 'Reveal >>'
  140.     the hidden windows appear with their old contents and at the old
  141.     position. 
  142.  
  143.    Edit the conversion rules
  144.  
  145.     Choose 'Edit Conversions...' from the Settings Menu. A requester
  146.     opens.  For every resource type you can now specify the data
  147.     format to convert to, the filename the data is written to,
  148.     whether the data is written to a file or the clipboard and the
  149.     command to be executed after the data is written. 
  150.  
  151.     To add a rule, select 'Add...', to remove select 'Remove'. ;-)
  152.  
  153.  
  154.  Conversion Rules 
  155.  
  156.     At the moment, there are only a few conversions: (B = builtin,
  157.     M = Macro, E = Extern command)
  158.     
  159.     from    to            type description
  160.  
  161.     <all>   raw data      B    You can ever save the resource 'as 
  162.                    it is' to a file. Be carefull: 
  163.                    *never ever* write non IFF data to 
  164.                    the clipboard!
  165.  
  166.     STR#    IFF-FTXT      B
  167.  
  168.                   M    A macro for GnuEmacs is included.
  169.                    Start GnuEmacs before exporting some
  170.                                STR#. 
  171.  
  172.     STR#    plain ascii   B    I have implemented this, because 
  173.                    a lot of editors do not understand FTXT.  
  174.  
  175.     snd     IFF-8SVX      B    Only a very small subset of sound 
  176.                    commands is implemeted: one. It
  177.                    searches the first sampled sound area
  178.                    and converts it to 8SVX. Actually the
  179.                             sound is played after writing it.
  180.  
  181.     vers    <display>     E    A nice demo. Here you can see how to
  182.                    write your own extern commands.
  183.                    An ARexx script is called, which 
  184.                    displays the version resource.
  185.  
  186.    Some useful hints
  187.  
  188.     Look through the conversions list in the 'Edit conversions'.
  189.     There are examples for all actually implemented functions. 
  190.  
  191.     In the 'Command' field specify the full path name of the
  192.     command.
  193.  
  194.     I use 'play8svx' to play IFF-8SVX files and 'zap' to dispaly
  195.     raw data. If you'll use these programs, you may change the
  196.     paths. If you'll use other programs, change the 'Command'
  197.     field.
  198.  
  199.  
  200.  Bugs, bugs, bugs...
  201.  
  202.     The documentation - I'm not good in English. Is there somebody
  203.     out, who'll write a new (maybe good) documentation? (Although I
  204.     hope all of you can use this program with this bad docs.)
  205.  
  206.         Write more and more conversions. (Feel free to send me your
  207.     viewers, conversion routines or ARexx scripts - they will be
  208.     included in the archive.)
  209.  
  210.     Clean up the source.
  211.  
  212.     Fix some minor bugs in the menu selection. ('Close' for the main
  213.     window does not work; print isn't implemented; the checkmark
  214.     before 'Autosave settings?' does not switch; 'Save icons?' isn't
  215.     implemented; only one settings file is supported yet, though you
  216.     can't choose a filename after selected 'Load Settings...' or
  217.     'Save settings as...'.)
  218.  
  219.     If the 'Edit conversions' or 'Add conversion' window is active,
  220.     all other windows are disabled, but no clock (or other wait)
  221.     pointer is shown.
  222.  
  223.     A direct ARexx Port isn't implemended yet. (Never select the
  224.     'ARexx' in the 'Edit conversions' window.) If you want to use
  225.     ARexx use the 'rx' command.
  226.  
  227.     The 'Find...' buttons haven't any function yet.
  228.  
  229.     You can't 'Cancel' the modifications in the 'Edit conversion'
  230.     window. 
  231.  
  232.     If the command does not exsist, no warning or error message is
  233.     displayed. The return code of the command is ignored.
  234.  
  235.     It's impossible to close a project.
  236.  
  237.  
  238.  Trademarks
  239.  
  240.     Amiga is a registered trademark of Commodore-Amiga, Inc.
  241.  
  242.         GCC by GNU. (all to say) ported by Markus Wild.
  243.  
  244.         ResGrep is no trademark of Andreas Florath.
  245.  
  246.         AmigaDOS is a trademark of Commodore-Amiga, Inc.
  247.  
  248.         GUI the Commodore HI (greetings from LISA).
  249.  
  250.         ARexx is a trademark of Wishfull Thinking Development Corp.
  251.  
  252.     Mac built by Apple Computer.
  253.  
  254.     ResEdit by Apple Computer.
  255.  
  256.     M*-DOS is no operating system and not running on HALs.
  257.  
  258.  
  259.  Thanx
  260.  
  261.     Jan van den Berg for GadToolsBox. A great program.
  262.  
  263.     Markus Wild for GCC20.
  264.  
  265.     The Mac users Armin and Joannes.
  266.  
  267.     Ute for mental support.
  268.  
  269.  
  270.  Bibliograpy
  271.  
  272.     "Inside Macintosch"; Addison-Wesely; Reading, Massachusetts; 
  273.     all volumes.
  274.  
  275.         "AMIGA - User Interface Style Guide"; Addison-Wesely; Reading,
  276.         Massachusetts; 1991
  277.  
  278.  
  279.  Copyright
  280.  
  281.         ResGrep IS COPYRIGHTED BY ANDREAS FLORATH.
  282.  
  283.         THIS IS THE WRITTEN PERMISSON TO OWN IT, USE IT, COPY IT AND
  284.     GIVE IT TO EVERYBODY.
  285.  
  286.     But there are some restrictions:
  287.         - it's strictly forbidden to use ResGrep for any military
  288.       program or programs that discriminate against somebody or
  289.       against a group 
  290.      - it's forbidden to use ResGrep for any commercial program (if
  291.       want to use, please contact the author) or to sell a disk
  292.       which contains it for more than 6,- DM (value at 04.1992)
  293.     - it's forbidden to modify the executable module
  294.     - only Fred Fish may distribute this program on a PD-Disk serie
  295.  
  296.         No warranty is given to any part of this porgram.
  297.         USE IT ON YOUR OWN DISK! :-) (Oh, I mean RISK!)
  298.  
  299.  
  300.  Why ResGrep? Why Version 0.2 beta?
  301.  
  302.     I released it in this early state, because the program is
  303.     stable, (never called the Guru to meditation) and I don't know
  304.     *who* will use it and *what* (s)he will need. (I will not invest
  305.     more time and work in this project if nobody will use it.) I
  306.     write it because I love the nice pings, pongs and ticks shipped
  307.     with the MacOS.
  308.  
  309.  
  310.  The big request
  311.  
  312.     *Please*, if you use the program, (e)mail! If you need some
  313.     other conversion *please* contact me (or write one, see file
  314.     'export.cc')! If you have written an ARexx script for an external
  315.     program or a conversion function *please* send! If you find a
  316.     bug *please* let me know!
  317.  
  318.  
  319.  The address
  320.  
  321.     Andreas Florath
  322.     Boxgraben 12 
  323.     D-5100 Aachen 
  324.     Germany 
  325.  
  326.     Email: AX000FL@DACTH11.bitnet    
  327.            (preferred!)    
  328.  
  329.            AX000FL@vm1.rz.rwth-aachen.de
  330.  
  331.            florath@cip-s01.informatik.rwth-aachen.de 
  332.            (please use only when problems with DACTH11)
  333.  
  334.  
  335.  The End
  336.  
  337.     Have Fun!