home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Archived / Internet / Utils / webg017 / Mimemap / ReadMe < prev   
Text File  |  1999-08-14  |  9KB  |  225 lines
  1. MimeMap a.k.a. Welcome to the wierd and wonderful world of freeware
  2. ======= (Release 5)
  3.  
  4. A number of programs have recently been writing their own MIME handling code.
  5. This is pointless. There is a saying about reinventing wheels which is
  6. unfortunately untrue of computing. The reason for this is copyright. It's a
  7. pain. "You can't distribute x from package y without paying sum z to a
  8. numbered swiss bankaccount, and in any case you'll not get support for it
  9. anyhow." The MimeMap module is one of these things. ANT own the copyright,
  10. and therefore we can't distribute it in our programs.
  11.  
  12. So, we end up with people re-writing it (usually badly) every time they want
  13. to use it. This isn't to say that MimeMap is written well, but it is the
  14. 'official' way of doing things. Hence, it is pointless.
  15.  
  16. So, after chatting with Joseph Heenan on IRC with him putting forward his
  17. arguments against supporting MimeMap and me generally complaining because I'm
  18. an awkward person, it was decided that until a freeware MimeMap module became
  19. available, he would not support it.
  20.  
  21. A very reasonable argument.
  22.  
  23. So, now it exists, and there can be no arguments on that score.
  24.  
  25.  
  26. Other rants on the same topic
  27. -----------------------------
  28. I like things being modular. Sometimes they may be badly thought out or
  29. implemented, but modularity is a Good Thing. The MimeMap module is a Good
  30. Thing by that token. The Resolver module is a Good Thing. However, the same
  31. restrictions apply to it, so people insist on including large chunks of
  32. Stewart Brodie's probably excellent resolver code in every application. Why
  33. is this wrong ? Two reasons :
  34.   1) It's duplicating code which is available elsewhere in the system (if the
  35.      Resolver were freely available)
  36.   2) It's no bloody good to BASIC programmers who just want a simple
  37.      multitasking resolve.
  38.  
  39. And, as if that were not enough, the same thing happens with services. If you
  40. use C you're really happy. You've got the lovelly 'getservent' call. But we
  41. humble BASIC and assembler programmers have to re-write the whole thing every
  42. time.
  43.  
  44. Actually that latter is untrue. It would be true, if I hadn't written the
  45. IServices module which does just that. Along similar lines is the socket error
  46. code lookup, and IServices includes that too.
  47.  
  48. Someday, we'll have a truely usable internet suite. I hope.
  49.  
  50.  
  51. MimeMap interface
  52. -----------------
  53. Paraphrased from the ANT web site documentation :
  54.  
  55. MimeMap_Translate (&50B00)
  56. => R0 = input type
  57.    R1 = input data
  58.    R2 = output type
  59.    R3 = output buffer, 128 bytes long
  60. <= R3 = output buffer, or value
  61.  
  62. Converts one form of type to another.
  63.  
  64. Types available are :
  65.   0   RISC OS type number (in r1/r3)
  66.   1   RISC OS type name (pointed to by r1/r3)
  67.   2   MIME type name (pointed to by r1/r3)
  68.   3   Extension name (pointed to by r1/r3)
  69. Other Reserved
  70.  
  71. Extension name may be preceeded by a dot, it will be ignored. When returning
  72. extensions, only the first one is given. This is the published interface by
  73. ANT.
  74.  
  75.  
  76. *MimeMap [<filetype> | &<number> | <type>/<subtype> | .<extension> ]
  77.  
  78. Displays either a particular type, or the whole MimeMap database.
  79.  
  80.  
  81. *ReadMimeMap
  82.  
  83. Forces a re-read of the MimeMap database. This should not be necessary unless
  84. the database lives on a remote server or is modified remotely.
  85.  
  86.  
  87. <Inet$MimeMappings>
  88.  
  89. This is the file used to read mappings from.
  90.  
  91.  
  92. Deviance from ANTs MimeMap module
  93. ---------------------------------
  94. Sorry, but a few things are different :
  95.  
  96.  * When you do *MimeMap, the textual representation of the type is given after
  97.    the hex type.
  98.  * The previously published MimeMap interface (&BCD00) is now obsolete and
  99.    should never have been used by ANT. &50B00 is correct.
  100.  * *ReadMimeMap and loading the module take place much faster
  101.  * Memory usage is probably slightly higher, and my module is about 1k longer.
  102.    That's my general laziness and reuse of libraries rather than writing things
  103.    afresh. Sorry.
  104.  * The MimeMap file is monitored for changes and as soon as a change is made
  105.    it is re-read.
  106.  * Error text from the modules is slightly different.
  107.  * Parsing of the MimeMap file with respect to wildcards is slightly different.
  108.    In practice this will make little difference I feel.
  109.  * Passing invalid types to the module will not give address exceptions
  110.  * Calling other SWIs than MimeMap_Translate will give 'MimeMap SWI not known'
  111.    (ANT's treats all SWIs as the same).
  112.  
  113. Anything else that is different about the modules is purely my own fault,
  114. please contact me (gerph@thevillage.ndirect.co.uk)
  115.  
  116.  
  117. Other notes
  118. -----------
  119. * MimeMap should live as System:Modules.Network.MimeMap, or Inet:Rm.MimeMap.
  120. * This module is version 0.10, which is the same as the version of MimeMap
  121.   which I have. You should ensure that you are using 0.10 or later. Earlier
  122.   versions of the ANT mapper are probably broken and should never be used.
  123. * There is no excuse for not supporting MimeMap now as this module is freely
  124.   available for distribution.
  125. * You should never set or modify Inet$MimeMappings, unless that is the
  126.   point of doing so. This is a user defined variable, which will be set
  127.   when MimeMap loads if it is not already. It defaults to InetDBase:MimeMap
  128.  
  129.  
  130. Ensuring the module
  131. -------------------
  132. If you use the MimeMap module in an application you should ensure it in the
  133. !Run file of the application. The following template should suffice for most
  134. purposes :
  135.  
  136. Set MimeMap$Path System:Modules.Network.,Inet:Rm.
  137. RMEnsure MimeMap 0.10 RMLoad MimeMap:MimeMap
  138. RMEnsure MimeMap 0.10 Error This application requires MimeMap version 0.10. Please contact your supplier
  139. Unset MimeMap$Path
  140.  
  141.  
  142. MimeMap file
  143. ------------
  144. The MimeMap file, pointed to by Inet$MimeMappings has the following format :
  145.  
  146. * Lines starting with a # are comments, space or tab are comments and are
  147.   ignored.
  148. * Each line consists of up to four entities :
  149.      Mime type/subtype pair
  150.      RISC OS name
  151.      RISC OS type number (in hex)
  152.      List of extensions, whitespace seperated
  153.   These are whitespace (tab or space) seperated. The Mimetype and RISC OS
  154.   name are wildcard matched when a translation is requested, with * matching
  155.   multiple characters, and # matching single characters. All textual
  156.   comparisons are case insentitive. The type number may be specified as * to
  157.   match any.
  158. * Each extension should start with a period (.), but this is not required.
  159. * It is usual to group by MIME type.
  160. * Many to one mappings are possible on all fields, but bear in mind that
  161.   the file is checked from top to bottom and terminates on the first match
  162.   (wild or not).
  163. * As stated above, order in the file /is/ important.
  164.  
  165. And example file is kindly supplied by Joseph Heenan and is covered by the
  166. same licence as this package. An 'up to date' copy of this file can be
  167. obtained from <http://www.ping.demon.co.uk/acorn.download.html>.
  168.  
  169.  
  170. Thanks
  171. ------
  172. Many thanks are due to Joseph Heenan, without whom this module would never
  173. have come about and whose support and critisisms have made it what you see
  174. now. It is also to Joseph Heenan that I owe thanks for writing the ModInst
  175. program, specifically for this purpose.
  176.  
  177. Andrew Hodgkinson must be thanked for his very helpful comments on how
  178. Browse deals with Mime-types and aid in understanding why FTP fetches were
  179. dying because of MimeMap.
  180.  
  181.  
  182. Licence
  183. -------
  184.     MimeMap - a free alternative to the ANT/Acorn mapper
  185.     Copyright (C) 1998, Justin Fletcher
  186.     
  187.     This program is free software; you can redistribute it and/or modify
  188.     it under the terms of the GNU General Public License as published by
  189.     the Free Software Foundation; either version 2 of the License, or
  190.     (at your option) any later version.
  191.  
  192.     This program is distributed in the hope that it will be useful,
  193.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  194.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  195.     GNU General Public License for more details.
  196.  
  197.     You should have received a copy of the GNU General Public License
  198.     along with this program; if not, write to the Free Software
  199.     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
  200.  
  201.  
  202. History
  203. -------
  204. Release 1:
  205.   Contained a misfeature which caused it to crash on RISC OS 3.1.
  206. Release 2:
  207.   RISC OS 3.1 failure has been tracked to the 'realloc()' routine returning
  208.   -1 under some circumstances. The only time this may occur (by my reading
  209.   of the documentation) is when the pointer passed to it was not allocated
  210.   using calloc or malloc. Since it always has, I do not understand why it
  211.   fails.
  212.   Inet$MimeMappings variable is now set when the module loads /and/
  213.   initialisation continues (used to exit anyhow).
  214. Release 3:
  215.   Release 2 failed to copy strings correctly into their destination buffers.
  216.   This resulted in Browse crashing regularly.
  217. Release 4:
  218.   Provided a 'shortcut' for upcalls which we are not interested in. This
  219.   prevents certain OLE based applications which use PipeFS as their transfer
  220.   medium from running very slowly.
  221. Release 5:
  222.   If Inet$MimeMap is set to "" then it is now treated as unset. Somebody
  223.   appears to have reported this on the Pluto list. Odd how it wasn't reported
  224.   to me though.
  225.