home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / emulate / resgrep0.lha / ResGrep03b / doc / ResGrep.doc < prev    next >
Text File  |  1992-06-16  |  16KB  |  513 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                   ResGrep
  7.  
  8.  
  9.  
  10.  
  11.                              Version 0.3 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 'ResGrep' there are two functional units:
  28.     you can decide which resource will be converted, and you can
  29.     determine 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.     doubleclick 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 and
  41.     the application is ARexx. The selected resource is converted to
  42.     IFF and written to a file or the clipboard. After that, a ARexx
  43.     script or a external (shell-)command is executed.
  44.  
  45.  
  46.  Hard- and Software Requirements
  47.  
  48.     You only need a Amiga with 512KB RAM, AmigaOS 2.0, ixemulib
  49.     and some Mac Resource Files. If you want to convert Mac PICTs,
  50.     you also need 'picttoppm' and 'ppmtoilbm'. (They are freeware
  51.     and can be found on many boards in the pbm-plus package.)
  52.  
  53.     Life is easier if you have a little bit more memory, a harddisk,
  54.     a lot of Mac Resource Files and some programs that support
  55.     ARexx, e.g. a graphic program, a sound program, a binary file
  56.     editor...
  57.  
  58.     Recomanded is a >50Mhz chip set if you want to open more than
  59.     ten windows. (Try an see! That's no program bug! It's the
  60.     7.19MHz chip set. Why it's *SO SLOW*? Como please change!)
  61.  
  62.  
  63.  Install
  64.  
  65.    The simple way
  66.  
  67.     Doubleclick the Install icon. A window opens and you had to
  68.     answer to some questions about the names of the directories
  69.     where to install ResGrep.
  70.  
  71.    The hard way
  72.  
  73.     Copy the ResGrep executable and the utility programs (i.e.
  74.     compress, unsit and mac2ami; they can be found in the 'c' -
  75.     directory) to somewhere in your path. Copy the other files to
  76.     a place where they will life (e.g. 'copy df1:ResGrep
  77.     Work:Progs all'). You may want to delete the sources placed in
  78.     the 'source' directory. Assign ResGrep: to the directory.
  79.     (e.g. 'assign ResGrep: Work:Progs/ResGrep'). Be sure to have
  80.     'ixemulib.library' in your LIBS: directory.  Assign (if you
  81.     haven't already) BIN: to the directory where the editors, i.e.
  82.     graphics- or soundeditor, are placed. Maybe you want to use
  83.     the 'add' option from 'assign'.
  84.  
  85.    The 'BIN:' assign
  86.  
  87.     The 'BIN:' assign is never used internally from ResGrep. It's
  88.     only used in the macros and conversions rules. If you don't
  89.     want to use the 'BIN:' assign, you can edit the rules and the
  90.     macros and change the 'BIN:progname' to the program's full
  91.     path (e.g. 'work:usr/bin/progname').
  92.     
  93.    Nota Bene
  94.  
  95.         ResGrep needs some stack, i.e. 4096 bytes is not enough. Use
  96.     at least 25000 byte! I don't know how much ResGrep uses, but
  97.     with this value it never gurus. (WARNING: Do NOT use 'srun'
  98.     from SKsh-Shell without the '-s' parameter! Use: 'srun -s
  99.     25000 ResGrep'.)
  100.     
  101.  
  102.  Mac Files
  103.  
  104.     Mac files consists of three parts, called forks: the data fork,
  105.     the info fork and the resource fork.
  106.  
  107.     The info fork contains system data for the MacOS and the Finder.
  108.  
  109.     The data fork contains the data, i.e. the program's code, the
  110.     ASCII characters of a text.
  111.  
  112.     The resource fork contains all the other data, i.e. sound,
  113.     pictures, icons, menus, menubars, requester, alerts, dialogs,
  114.     texts, version numbers, code, window definitions, palettes...
  115.     (You see, thats the most interested fork. :-) )
  116.  
  117.  
  118.  How to get Mac Files to your Amiga
  119.  
  120.     There are a lot of ways to get Mac files to the Amiga. Two of
  121.     them -- those I have used -- are described here.
  122.  
  123.    Use StuffIt archives
  124.  
  125.     The simplest way is to stuff the files on a Mac with StuffIt
  126.     (the most common packer on a Mac), transfer them via modem or
  127.     M*-DOS disks from Mac to Ami and unstuff them. Every Mac file
  128.     falls into the three pieces described above. The unstuff
  129.     program, called 'unsit' is included in this distribution. The
  130.     manual page is placed in the 'doc' directory.
  131.  
  132.  
  133.    Use M*-DOS disks
  134.  
  135.     Save the files on the Mac to a M*-DOS disk. Put the disk in
  136.     the Amiga and list the contents. There will be a (hidden)
  137.     directory named 'RESOURCE.FRK' or 'RESOURC&'. Change to this
  138.     directory. There will be the resource forks of the Mac files.
  139.  
  140.  
  141.  How to use
  142.  
  143.    Start ResGrep
  144.  
  145.     Doubleclick the icon from Workbench or type 'ResGrep' in a
  146.     shell. The main window opens with the title: 'ResGrep -
  147.     FileList' and a file requestor appears.
  148.  
  149.    Convert Resources to Amiga files
  150.  
  151.     At first open a resource file. You can choose the name with the
  152.     file requester. Later on, to do this, select 'Open...' from the
  153.     Project Menu. The filename with a unique number appears in the
  154.     main window. In every window titel that belongs to this file,
  155.     these number will appear. - To display the resource types of a
  156.     file, click at the resource's type. A window with resource types
  157.     will open.
  158.  
  159.     To display the resources IDs of a specific resource type click
  160.     at the resource type. To export the data click on the resource
  161.     id.
  162.  
  163.     If you want to open a window that is already open, the window is
  164.     activated and poped to front.
  165.  
  166.    Hide and Reveal windows
  167.  
  168.     If you work with some resource files there may be a lot of open
  169.     windows. With the menuitem 'Hide >>' you can hide one (the
  170.     active) window, some (all windows that were opened with clicks
  171.     in the active window) or all windows. These windows disapears
  172.     but the contents, size and positions is saved. With 'Reveal >>'
  173.     the hidden windows appear with their old contents and at the old
  174.     position.
  175.  
  176.    Edit the conversion rules
  177.  
  178.     Choose 'Edit Conversions...' from the Settings Menu. A requester
  179.     opens.    For every resource type you can now specify the data
  180.     format to convert to, the filename the data is written to,
  181.     whether the data is written to a file or the clipboard and the
  182.     command to be executed after the data is written.
  183.  
  184.     To add a rule, select 'Add...', to remove select 'Remove'. ;-)
  185.     (Builtin rules cannot be removed.)
  186.  
  187.  
  188.  How to use - an example
  189.  
  190.     There is an example file called "Helmut.sit" in the directory
  191.     "MacProgs".  Here is the description how to convert the
  192.     resources of this file to an Amiga usable form:
  193.  
  194.    Unpack the archive
  195.  
  196.     Unpacking is only possible from the CLI or a shell. Type:
  197.         'cd ResGrep:MacProgs'
  198.     to change to the 'MacProgs' directory, then type
  199.         'unsit Helmut.sit'
  200.     The computer works for about 30 seconds (a 7.19Mhz 68000,
  201.     A3000 may be faster) and it has unpacked three files: (type
  202.     'list' to see that all files exsists and have the same length)
  203.          -> Helmut.info             128 ----rwed Today
  204.          -> Helmut.rsrc           76015 ----rwed Today
  205.          -> Helmut.data           empty ----rwed Today
  206.     The resources can be found in the file "Helmut.rsrc". You may
  207.     want to delete the "Helmut.info" and "Helmut.data" files.
  208.     Note: the "Helmut.info" file isn't a Amiga "*.info" file with
  209.     Workbench and icon information. It's the info fork from the
  210.     Mac file.
  211.  
  212.    Starting ResGrep
  213.  
  214.     To start ResGrep, doubleclick the icon or type 'ResGrep' in
  215.     the CLI or a shell. (Be sure to have about 25000 byte stack;
  216.     see 'Instalation' for further information.)
  217.  
  218.    Loading the resource file
  219.  
  220.     There will open a window and a file requester. Open the file
  221.     "Helmut.rsrc" with the file requester. The requester will
  222.     disappear and the name of the file with a leading unique number
  223.     is displayed in the window. (This number appears in every
  224.     window title concerning this file.)
  225.  
  226.    Opening the resource types window
  227.  
  228.     Click (once) a the name of the file, i.e.
  229.     "1 MacProgs/Helmut.rsrc". A window with all resources types
  230.     will open. There are six different resources in this file:
  231.     ICN#, PICT, STR#, ics#, snd , vers.
  232.  
  233.    The ICN# resource
  234.  
  235.     Click (once) the ICN#. Another window will open with the IDs
  236.     and names of the ICN# resorces. In this example there is only
  237.     one ICN# resource, with the ID -16455 and without a name. Click
  238.     (once) the ID. Now the programm converts the Mac icon to
  239.     IFF-ILBM and writes it to the clipboard. To use the icon,
  240.     start a painting programm or the IconEdit and paste the
  241.     picture from the clipboard (Edit-Menu: Paste; shortcut:
  242.     right-Amiga V) into the programm. Now you can edit and save
  243.     the picture.
  244.  
  245.     You can close the window where the ID is display by
  246.     clicking at the 'close window' gadget or by pressing
  247.     rigth-Amiga K.
  248.  
  249.    The PICT resource
  250.  
  251.     To convert the PICT resource you must have the 'picttoppm' and
  252.     the 'ppmtoilbm' programm from the pbm-plus package and these
  253.     programms must be in BIN:.
  254.  
  255.     Click the PICT line in the resource type window. A window will
  256.     open with one ID (128) an no name. Click on the ID. The skript
  257.     is started that converts the PICT to IFF-ILBM. About 45
  258.     seconds later the picture is displayd and there is a file
  259.     'T:picture.ilbm' thats obtains the picture.
  260.  
  261.    The STR# resource
  262.  
  263.     Click the STR# line in the resource type window. A window with
  264.     two resource IDs and names will open:
  265.         1000 Koan
  266.         1001 Fahrenheit
  267.  
  268.     If you click one of the IDs, the resource is written to the
  269.     clipboard. In your editor you can now paste the text. (e.g.
  270.     start 'emacs' and press rigth-Amiga V)
  271.  
  272.     Note: no mapping is done yet! (Mac uses CR instead of LF to
  273.     end a line.)
  274.  
  275.    The ics# resource
  276.  
  277.     It's a small icon. See 'The ICN# resource' how to use.
  278.  
  279.    The snd  resource
  280.  
  281.     Click the snd line and an window will open. Click the ID line
  282.     and after some moments the sound will be played (if you have
  283.     'play8svx' in BIN:) and is written to 'T:SoundOut'.
  284.  
  285.    The vers resource
  286.  
  287.     Click (once) on the vers line in the resource type window. A
  288.     window with four lines will be open. Click on the IDs. A
  289.     window will open where the version information is displayed.
  290.  
  291.  
  292.  Conversion Rules
  293.  
  294.     At the moment, there are only a few conversions: (B = builtin,
  295.     M = Macro, E = Extern command)
  296.  
  297.     from    to          type description
  298.  
  299.     <all>    raw data      B    You can ever save the resource 'as
  300.                    it is' to a file. Be carefull:
  301.                    *never ever* write non IFF data to
  302.                    the clipboard!
  303.  
  304.     ICN#    IFF-ILBM      B    B&W icon, 32 * 32 pixel
  305.  
  306.     PICT    IFF-ILBM      ME   Use the 'pbmplus' commands to convert a
  307.                    PICT to ILBM. (There are to macros: one
  308.                    uses files and the picture is displayed,
  309.                    and one that uses pipes (it needs less
  310.                    memory than the first, but the pic
  311.                    isn't displayed, because I don't know
  312.                    a program, that displays a pic from
  313.                    stdin). (pict.rexx / pictpipe.rexx)
  314.  
  315.     STR#    IFF-FTXT      B
  316.  
  317.                   M    A macro for GnuEmacs is included.
  318.                    Start GnuEmacs before exporting some
  319.                    STR#. (emacs.rexx)
  320.  
  321.     STR#    plain ascii   B    I have implemented this, because
  322.                    a lot of editors do not understand FTXT.
  323.  
  324.     icl4    IFF-ILBM      B    16 colour icon , 32 * 32 pixel
  325.  
  326.     icl8    IFF-ILBM      B    256 colour icon , 32 * 32 pixel
  327.  
  328.     ics#    IFF-ILBM      B    B&W icon, 16 * 16 pixel
  329.  
  330.     ics4    IFF-ILBM      B    16 colour icon, 16 * 16 pixel
  331.  
  332.     ics8    IFF-ILBM      B    256 colour icon, 16 * 16 pixel
  333.  
  334.     snd    IFF-8SVX      B    Only a very small subset of sound
  335.                    commands is implemeted: one. It
  336.                    searches the first sampled sound area
  337.                    and converts it to 8SVX.
  338.  
  339.     vers    <display>     ME   A nice demo. Here you can see how to
  340.                    write your own extern commands.
  341.                    A ARexx skript is called, whitch
  342.                    displays the version resource. (vers.rexx)
  343.  
  344.    Some usefull hints
  345.  
  346.     Look through the conversions list in the 'Edit conversions'.
  347.     There are examples for all actually implemented functions.
  348.  
  349.     In the 'Command' field specify the full path name of the
  350.     command.
  351.  
  352.     I use 'play8svx' to play IFF-8SVX files and 'zap' to dispaly raw
  353.     data. If you'll use other programs, change the 'Command' field.
  354.  
  355.  
  356.  Bugs, bugs, bugs...
  357.  
  358.     The documentation - I'm not good in English. Is there somebody
  359.     out, who'll write a new (maybe good) documentation? (Although I
  360.     hope all of you can use this program with this bad docs.)
  361.  
  362.     Compressed resources can't be unpacked, because I haven't
  363.     found documentation about the compression method. Is it
  364.     possible that there is no information about compressed
  365.     resources in the 'Inside Macintosch'? (MANY 'PICT's are
  366.     compressed!) There are two ways to get the uncompressed
  367.     resource:
  368.     - Use 'ResEdit'. Cut a compressed resource with Command-X and
  369.       paste it with Command-V. After this the resource is uncompressed.
  370.     - Send me documentation about the compression algorithm.
  371.  
  372.     Masks of ICN# and ics# icons are ignored.
  373.  
  374.     Write more and more conversions. (Feel free to send me your
  375.     viewers, conversion routines or ARexx skripts - they will be
  376.     included in the distribution.)
  377.  
  378.     Fix some minor bugs in the menu selection. (Close for the main
  379.     window do not work; print isn't implemented; the checkmark
  380.     before 'Autosave settings?' do not switch; 'Save icons?' isn't
  381.     implemented; only one settings file is supported yet, though you
  382.     can't choose a filename after selected 'Load Settings...' or
  383.     'Save settings as...'.)
  384.  
  385.     If the 'Edit conversions' or 'Add conversion' window is active,
  386.     all other windows are disabled, but no clock (or other wait)
  387.     pointer is shown.
  388.  
  389.     A direct ARexx Port isn't implemended yet. (Never select the
  390.     'ARexx' in the 'Edit conversions' window.) If you want to use
  391.     ARexx use the 'rx' command.
  392.  
  393.     The 'Find...' buttons hasn't any function yet.
  394.  
  395.     You can't 'Cancel' the modifications in the 'Edit conversion'
  396.     window.
  397.  
  398.     If the command do not exsists, no warning or error message is
  399.     displayed. The return code of the command is ignored.
  400.  
  401.     It's impossible to close a project.
  402.  
  403.  
  404.  Trademarks
  405.  
  406.     Amiga is a registered trademark of Commodore-Amiga, Inc.
  407.  
  408.     GCC by GNU. (all to say) ported by Markus Wild.
  409.  
  410.     ResGrep is no trademark of Andreas Florath.
  411.  
  412.     AmigaDOS is a trademark of Commodore-Amiga, Inc.
  413.  
  414.     GUI the Commodore HIG (greetings from LISA).
  415.  
  416.     ARexx is a trademark of Wishfull Thinking Development Corp.
  417.  
  418.     Mac build by Apple Computer.
  419.  
  420.     ResGrep by Apple Computer.
  421.  
  422.     M*-DOS is no operating system running not on HALs.
  423.  
  424.  
  425.  Thanx
  426.  
  427.     Jan van den Berg for GadToolsBox. A great program.
  428.  
  429.     Markus Wild for GCC20.
  430.  
  431.     Allan G. Weber for his permission to include 'unsit' in this
  432.     distribution.
  433.  
  434.     The Mac users Armin and Joannes.
  435.  
  436.     Ute for mental support.
  437.  
  438.  
  439.  Bibliograpy
  440.  
  441.     "Inside Macintosch"; Addison-Wesely; Reading, Massachusetts;
  442.     all volumes.
  443.  
  444.     "AMIGA - User Interface Style Guide"; Addison-Wesely; Reading,
  445.     Massachusetts; 1991
  446.  
  447.  
  448.  Copyright
  449.  
  450.     ResGrep IS COPYRIGHTED BY ANDREAS FLORATH.
  451.  
  452.     THIS IS THE WRITTEN PERMISSON TO OWN IT, USE IT, COPY IT AND
  453.     GIVE IT TO EVERYBODY.
  454.  
  455.     But there are some restrictions:
  456.     - it's strictly forbidden to use ResGrep for any military
  457.       program or programs that discriminate against somebody or
  458.       against a group
  459.     - it's forbidden to use ResGrep for any comercial program (if
  460.       want to use, please contact the author)
  461.     - it's forbidden to sell a disk whitch contains ResGrep for
  462.       more than 6,- DM (value at 04.1992)
  463.     - it's forbidden to modify the executable module
  464.     - only Fred Fish may distribut this program on a PD-Disk serie
  465.  
  466.     No warranty is given to any part of this porgram.
  467.     USE IT ON YOUR OWN DISK! :-) (Oh, I mean RISK!)
  468.  
  469.  
  470.  Why ResGrep? Why Version 0.3 beta?
  471.  
  472.     I released it in this early state, because the program is
  473.     stable, (never called the Guru to meditation) and I don't know
  474.     *who* will use it and *what* (s)he will need. (I will not invest
  475.     more time and work in this project if nobody will use it.) I
  476.     write it because I love the nice pings, pongs and ticks shipped
  477.     with the MacOS.
  478.  
  479.     Now, ResGrep can convert PICTs and icons, I often use it to get
  480.     Mac pictures and icons working on my Amiga.
  481.  
  482.  
  483.  The big request
  484.  
  485.     *Please*, if you use the program, (e)mail! If you need some
  486.     other conversion *please* contact me (or write one, see file
  487.     'export.cc')! If you have written a ARexx skipt for an external
  488.     program or a conversion function *please* send! If you find a
  489.     bug *please* let me know!
  490.  
  491.  
  492.  The address
  493.  
  494.     Andreas Florath
  495.     Boxgraben 12
  496.     D-5100 Aachen
  497.     Germany
  498.  
  499.     Email: florath@pool.informatik.rwth-aachen.de
  500.  
  501.  
  502.  Comming soon
  503.  
  504.     At the moment I'm writing a external program to convert the MENU
  505.     resources. (Maybe I had to specify an IFF-MENU type -- that
  506.     will be a hard (and long) work...)
  507.     Resizable windows are nice.
  508.     
  509.  
  510.  The End
  511.  
  512.     Have Fun!
  513.