  --------------------------------------------------------------------------

  MEX.TXT

  Author  : Steve Johnson
  CIS#    : [100036,1061]
  Written : 29 May 1991
  Revision: 1.21 - 15 December 1994
  AutoCAD : Release 12

  --------------------------------------------------------------------------

  Files   : MEX.TXT      : External documentation file (this file).
            MEX.LSP      : Main AutoLISP source code.
            ACADMEX.LSP  : AutoLISP file containing functions required
                           by MEX.LSP.  Rename as ACAD.LSP or add
                           (load "ACADMEX.*") to ACAD.LSP or MEX.LSP.
                           This file represents a subset of the functions
                           either included or stubbed in the Water Authority
                           of Western Australia's ACAD.LSP.

  --------------------------------------------------------------------------

  Purpose : Allows explosion of blocks, xrefs, dimensions and polylines.
            Provides additional explosion features over standard AutoCAD.
            Two commands are provided: MEX and MEXALL, plus a function
            (mex_main SS ETYP SHOW).  MEX allows user selection of entity
            type and objects, and explodes only one level.  MEXALL explodes
            anything and everything it can in the current space, down to
            the deepest level.  (mex_main) allows programmers to create 
            other functions which perform MEX-type explosions.
  Warning : Just because MEX makes it easy to explode things does not make it
            a good idea.  Exploding is essentially the process of removing
            intelligence and associativity from a drawing, and will almost
            certainly increase the drawing size.  So think carefully before
            lighting the touchpaper.
  Notes   : Polylines (and derivatives such as meshes) are exploded normally.
            Dimensions have their DEFPOINTS removed after explosion. New
            dimension entities are placed on the layer of the original
            entity, as are any new layer 0 entities created by exploding
            blocks.  Similarly, BYBLOCK entities have their colour and/or
            linetype set to match the original entity.  Mirrored blocks are
            exploded by mirroring the block, exploding and re-mirroring the
            new entities.  Minserted blocks are exploded into an array of
            single blocks.  Blocks with attributes are exploded, then each
            attribute definition created by the explosion is erased and each
            of the pre-explosion attributes are replaced by a piece of text
            with the appearance of the original attribute.  The visibility
            of attributes is respected: ie. if an attribute is invisible
            because it is defined as such or because of the setting of
            ATTDISP/ATTMODE, then no text entity is created in its place.
            Blocks with unequal X, Y and Z scales cannot be exploded.
            If such blocks are selected, they are placed in selection set
            UXB and any new entities created by explosion are placed in GR.
            XREFs are bound rather than exploded (ie. they become normal
            blocks, which may be subsequently exploded if required).  If one
            XREF is selected, all XREFs in the drawing of the same name are
            bound.
  Restrictions:
            Does not explode blocks with unequal X, Y, Z scale factors except
            for mirrored blocks.

  --------------------------------------------------------------------------

  Command : MEX
  Purpose : AutoCAD command to explode specified entities by one level.
            Extensive detail is provided about what MEX is doing.
  Format  : MEX
            Entity type to explode (Block/Dimension/Polyline) <All>:
            Select objects to explode...
            Select objects:
  Usage   : Noun/Verb selection is supported: the "Select objects" prompts
            are suppressed if entities are preselected, but the entity type
            filter is still performed on the selected objects. Only entities
            in the current space are selected.

  Command : MEXALL
  Purpose : AutoCAD command to explode all entities to the deepest possible
            level.  No prompts are issued and minimal messages displayed.
  Usage   : All entities in the current space are selected.

  Function: (mex_main SS ETYP SHOW)
  Purpose : Provides API for MEX-type AutoCAD commands.
  Params  : SS: selection set (may contain unexplodable entities)
            ETYP: entity type string ("Block" "Dimension" "Polyline" or "Xref")
            SHOW: if T, messages are displayed.  If nil, messages supressed.
  Returns : A list of any XREFs which have been bound during the explosion
            process.  If none have been bound, returns nil.
  Globals : UXB: selection set for unexploded blocks.  This should generally
            be initialised by the calling function, eg. (setq UXB (ssadd)).
            (mex_main) will initialise it if it does not exist or add to the
            UXB selection set if it already exists.
  Example : (mex_main (ssget) "Polyline" nil)
            Will prompt the user for objects and explode all of the polylines
            in the selection set without displaying any messages.  Will
            return nil because no XREFs are involved.  Will not affect UXB.

  --------------------------------------------------------------------------

  Revision history:

  1.21    : 15 December 1994
  Notes   : Exploding blocks with attributes does not now create TEXT
            entities which contain only spaces.  Now respects visibility
            or invisibility of attributes in conjunction with ATTMODE.
  Modified: MEX.TXT, MEX.LSP

  1.2     : 31 October 1994
  Notes   : Modified way in which attributes are dealt with.  Previously, 
            any ATTDEFs created by explosion were converted to TEXT entities
            if the attribute tags matched.  This caused problems if the
            block definition attribute definitions did not match the block
            insertion attributes.  This situation is legal in AutoCAD, but
            means that an explosion need not produce the equivalent ATTDEFs
            to the ATTRIBs which existed before, and it meant that MEX did
            not always create the equivalent TEXT entities.  MEX also had
            problems with drawings with attribute tags not in upper case.
            Such corrupt drawings could be created by other applications
            such as MicroStation's faulty DWG/DXF export.
            Thanks to beta testers Jim Arthur, Brandon Bartlett and Alberto
            Chiarvetto.  This version was not generally released.
  Modified: MEX.TXT, MEX.LSP

  1.1     : 7 June 1994
  Notes   : Fixed bug where routine crashed if it encountered XREFs, and
            added the facility which binds them instead.  Divided code
            into (C:MEX) and (mex_main) to provide an API, and used that API
            to create (C:MEXALL) command.  Changed entity type to mixed case
            in messages, and made the messages optional within the API.
            Removed <All> as the default for MEX entity selection.
  Modified: MEX.TXT, MEX.LSP

  1.0     : 26 May 1994
  Notes   : Initial release via CompuServe.
            General tidy-up.  Many functions made local.  Specific (lasent)
            function removed and replaced by generic (lastent) function.
            Layer 0, colour and linetype BYBLOCK now treated seperately,
            which means dimensions with different colours now explode as
            expected.  MINSERTs now explode correctly in different UCSs.
  New     : MEX.TXT, ACADMEX.LSP
  Modified: MEX.LSP

  0.2     : 12 May 1993
  Notes   : Exploded blocks with attributes now create text entities, not
            attribute definitions with modified tags.
  Modified: MEX.LSP

  0.1     : Some time in 1992
  Notes   : Updated for Release 12, including support for Noun/Verb selection.
  Modified: MEX.LSP

  0.0     : 29 May 1991
  Notes   : Initial Water Authority release for Release 11.
  New     : MEX.LSP

  --------------------------------------------------------------------------

  Copyright: (c) Water Authority of Western Australia 1991-4.

  Disclaimer: This software is provided "as is" without express or
  implied warranty.  All implied warranties of fitness for any particular
  purpose and of merchantability are hereby disclaimed.  If it eats your
  drawings, tough luck.  Engage brain before use.

  Permission notice: Permission to use, copy, and distribute this
  software for any purpose and without fee is hereby granted, provided
  that it is distributed unmodified and with all supporting files and
  documentation, including this file with the above copyright notice,
  disclaimer and this permission notice.

  AutoCAD is a registered trademark of Autodesk, Inc.
  CompuServe is a registered trademark of CompuServe, Inc.

  --------------------------------------------------------------------------
