
   BOMBADIL - Module for rectifying some Calamus errors
   -----------------------------------------------------------------------------

     >>> IMPORTANT:
     >>>
     >>> Please read also the files in the folder INFO\MODULES\BOMBADIL!
     >>> You will find there:
     >>>
     >>> - INSTRUCT.TXT   Operating instructions for the module
     >>> - FAQ.TXT        Questions and answers about BOMBADIL
     >>> - CONTACT.TXT    Contact address of the program's author
     >>> - USENOTES.TXT   Usage notes
     >>> - VERSION.TXT    Overview of all versions published to date
     >>> - BOMBADIL.TXT   A small accompanying lyric :-)


   What's it for?
   --------------
   All known versions of Calamus S and SL contain an error that can 
   damage the data structure when transporting objects via the Calamus 
   clipboard. As a whole row of circumstances has to come together before 
   this bug bites, it appears fairly rarely, which makes it rather 
   insidious: Suddenly for no reason objects suddenly cannot be 
   transferred to the document. Due to the non-reproducible nature of 
   this behaviour it took some years after the publication of Calamus 
   S/SL until this error could be discovered and localised.

   The guilty party for this erroneous behaviour incidentally is not the 
   clipboard, but a portion of the general document management structure. 
   For a long time, the preconditions necessary to trigger this error 
   could only be produced from the clipboard. Unexplainable effects 
   during the development of the text editor "Eddie" then brought the 
   background of this error to light. It is quite possible that some 
   other functions of the Calamus system are affected by this.

   The error is of a conceptual nature and unfortunately cannot be 
   remedied by a simple patch. The effects are very complex and without 
   explanation of the technical context almost impossible to describe.
   We can only say: Certain references of objects in the source document 
   get lost. If changes are made to the colour or style list in the 
   document, then the clipped objects are not updated.

   The concept of BOMBADIL is in any case as a kind of "watcher": The 
   module "supervises" the document structure and intervenes to correct 
   errors when it finds them.


   What else can it do?
   --------------------
   Over the years BOMBADIL has grown to become a regular collection of 
   bugfixes. In the meantime ten know errors in Calamus and its modules 
   could be overcome, or their effects remedied:

    The structural error that can appear with clipboard operations, 
     amongst others (see descriprtion above).

    All versions of the Calamus Document Converter since 1994 have 
     problems when loading some old documents that were created with 
     Calamus 1.09. Normally a colour as well as a colour layer list 
     (for the spot colours) will be created during loading. For some 
     reason the converter omits the colour layer list in some cases. 
     From version 5 on BOMBADIL can recognize this condition and remedy 
     it. The functionality is included in the clipboard bugfix and can 
     be switched on and off with it.

    With operating system extensions such as WinCom, for instance, it 
     is possible to move windows over the left screen border offscreen. 
     Unfortunately Calamus reacts to such actions with dumb system 
     disorder: The window is inflated to its full size and jumps across 
     the screen.

     BOMBADIL ensures that windows can be correctly moved over the left 
     screen border.

  >>> This error was remedied in Calamus SL 96. <<<


    Sometimes the style list of a document becomes somewhat confused.
     Text frames can no longer be formatted, or changes to the styles 
     have no effect on the document any more. In such cases you should 
     use the checking function built into BOMBADIL on the text, which can 
     sort the "lost" styles correctly into the style list again.

    The caches created by the Raster Generator are appended to the 
     relevant document and also saved with it. Unfortunately the 
     mechanism for clearing caches built into the 1993 Calamus version 
     contains an error: The raster caches are NEVER cleared. As a result 
     the document grows over time due to steadily increasing raster 
     caches to an unbelievable size. With the help of BOMBADIL one can 
     get rid of these caches once more.

     In newer Calamus versions this function can be used for fast and
     convenient clearing of the raster caches.

    With certain actions, colours with an invalid format may arise in a 
     document. As a result of this, access to the colour dialog is no 
     longer possible, for instance.  A known cause of this problem is the 
     Bridge module: During the conversion of text frames containing 
     underlined text into vector graphic frames, defective object colours 
     arise regularly. This bugfix is able to find such colours and repair 
     them.

    Under MagiC or MagiCMac a crash or system freeze can arise when 
     the task popup (which is obtained by clicking in the menu bar) is 
     opened. The blame for this lies in the key code display in the  
     Calamus Top Row. The error may be reproduced in the following 
     manner:

     - Click in the menu bar to open the popup
     - Move the mouse cursor back and forth in the Top Row
     - Move the mouse back into the popup -> the system freezes or crashes

     With the relevant bugfix the key code display may be switched off,
     so that this effect can no longer happen.

  >>> In Calamus SL versions from May 1997 on this error was remedied. <<<


    If a number of certain conditions is fulfilled, Calamus crashes 
     when outputting mask groups. The error occurs when:

     - We are dealing with inverted mask groups
     - The output has been rotated
     - The output is at a relatively high resolution

     Finally a largely unpredictable random element is added to this, 
     as this bug is connected with a non-initialised program variable. 
     Depending on what is currently contained at the corresponding memory 
     address, one can get a (2 bomb) crash or not.

  >>> In Calamus SL versions from May 1997 on this error was remedied. <<<


    Very sporadically when imagesetting pages with large RGB or CYMK 
     images the system will crash with two bombs and the additional code 
     "PICt, PICt, PICs, MOD SCOS". The larger the available working 
     memory, the image data and the output resolution, the more probable 
     that this error appears. BOMBADIL is able to find this defect in the 
     image output and remedy it.
     
     This bugfix only works with Calamus versions from 1994 onwards.

  >>> In Calamus SL versions from May 1997 on this error was remedied. <<<


    Likewise during imagesetting of large documents (but not only there) 
     a further error can strike that is lodged in the memory management 
     routines and leads to the system crashing. When memory becomes tight 
     (print output at high resolution leads almost always to the maximum 
     capacity of working memory being used), in specific circumstances 
     the packing and reorganization function of memory management gets 
     some data structures mixed up. This error only appeared sporadically 
     and was, in fact, extraordinarily difficult to reproduce - which is 
     a necessary prerequisite for being able to find and remedy it. For 
     several days Klaus Garms and I worked making test imagesetting 
     outputs with a modified version of the PostScript printer driver 
     under various Calamus configurations with different documents, until 
     the crash appeared - at first sporadically, and finally in a 
     controllable and reproducible way. Only certain actions (load the 
     document of the Merge manual, then store all images on pages 48 to 
     64 with the Fine Data module, call the Print dialog and output pages 
     63 and 64 in reverse order colour separated at 5000 dpi ...) created 
     the critical constellation of memory objects and gaps that led to 
     errors when reserving the buffer for outputting the second page to 
     be printed, and resulted in a bus error (2 bombs).
     
     (While I am writing this text, I am listening to Queen's "It's a 
     kind of magic" from the CD of the same name ... not exactly 
     inappropriate! ;-) )
     
  >>> In Calamus SL versions from August 1998 on this error was remedied. <<<



   Installation
   ------------
  The folders on this floppy disk are organized in exactly the same way 
  as your Calamus installation. So you can just copy the complete disk 
  contents with the exception of this README.TXT file into your Calamus 
  folder on the hard disk; the files are already sorted into the correct 
  folder structure.

  In some circumstances some of the files may already be present on your 
  hard disk. Just copy the new versions on the floppy disk over the 
  existing ones.

  
   BOMBADIL is loaded like any other module in the Calamus Modules dialog:

    Launch Calamus and load BOMBADIL.CXM in the "External Modules" 
     dialog.

    If BOMBADIL is to be loaded automatically when Calamuys is launched,
     then please select in the "Options" menu the entry "Save System 
     Settings". Save the settings as usual in the "Modules" group.

    Pleae note: Not all bugfixes are activated as a default! In 
     particular with an update to a new version of BOMBADIL all NEW 
     bugfixes are initially switched off. In case of doubt take a peek at 
     the relevant dialog boxes.



   Credits
   -------
   I'd like to thank the following people for bug-reports (in Calamus), 
   bug-reports (in BOMBADIL), suggestions and tips. I hope that the list 
   is to some extent complete.

      Roland Behme
    Matthias Bracke
        Mark Coles
         Ulf Dunkel
       Klaus Garms
        Ulli Hahndorf
      Pierre Hansen
     Andreas Inckemann
      Werner Jrgensen
    Thorsten Liebold
     Hendrik Meinl
      Thomas Plasa
     Manfred Radijewski
   Christian Schwab
     Raimund Thiel

   (in alphabetical order)

   Also many thanks to everyone who have helped further development of 
   BOMBADIL with their shareware contributions.

   Last but not least: Special thanks to Michael Monscheuer, who is 
   working on removing errors in the Calamus kernal to make BOMBADIL 
   superfluous.



   We wish you success with BOMBADIL 

      Harald Siegmund (Program author)
      Raimund Thiel (Text idea)
      Klaus Garms (Bugfix for memory management)



   Calamus is a registered trademark of the company MGI.

   -----------------------------------------------------------------------------
   A final word:

      "We apologise for the inconvenience"

   (Douglas Noel Adams, "So long and thanks for all the fish")
