NAME
    MIME-tools - modules for parsing (and creating!) MIME entities

SYNOPSIS
    For coding examples, see the MIME::Tools module. This manpage is for
    installers.

CONTENTS
  Modules in this toolkit

        Module       DSLI   Description                                  Info
        ----------   ----   ------------------------------------------   ----
        MIME::
        ::Body       adpO   Abstract message holder (file, scalar, etc.) ERYQ
        ::Decoder    bdpO   OO interface for decoding MIME messages      ERYQ
        ::Entity     bdpO   An extracted and decoded MIME entity         ERYQ
        ::Field::*   bdpO   Mail::Field subclasses for parsing fields    ERYQ
        ::Head       bdpO   A parsed MIME header (Mail::Header subclass) ERYQ
        ::Parser     bdpO   Parses streams to create MIME entities       ERYQ
        ::ParserBase bdpO   For building your own MIME parser            ERYQ
        ::ToolUtils  bdpO   Utilities for the MIME-tools kit             ERYQ
        ::Tools      bdpO   For configuring the MIME-tools library       ERYQ
        ::Words      bdpO   Decode encoded words in MIME headers         ERYQ
        
        ::IO         ****   DEPRECATED; now done via IO:: modules        ERYQ
        ::Latin1     ****   DEPRECATED; may be moved to Text::           ERYQ

  Programs in this toolkit

        mimeabuse   - try hard to break MIME parsing
        mimedump    - dump out summary of the contents of a parsed MIME message
        mimeencode  - encode a file
        mimeexplode - explode one or more MIME messages
        mimeprint   - parse a MIME stream, and print the parsed entity
        mimesend    - send files via MIME mail, from the command line
        mimetour    - tour the possible encodings

  Layout of the distribution

        ./lib/MIME/         the MIME-tools classes
        ./Makefile.PL       the input to MakeMaker
        ./COPYING           terms and conditions for copying/using the software
        ./README            this file
        ./docs/             HTMLized documentation
        ./etc/              convenient copies of other modules you may need
        ./examples          sample executables
        ./t/*.t             the "make test" scripts
        ./testin/           files you can use for testing (as in "make test")
        ./testout/          the output of "make test"

REQUIREMENTS
    You'll need Perl5.002 or better, but you *should* get 5.004 as soon as
    possible... sorry, but it's the first release I know of with a non-
    broken FileHandle->new_tmpfile method. It's extremely worth upgrading to
    if you're using MIME-tools.

    You'll also need to obtain and install the following kits from the CPAN:

    IO-stringy
        This provides us with filehandle-like interfaces to scalars, and the
        ability to "wrap" foreign filehandles.

    MIME-Base64 (2.04 or higher)
        This kit contains MIME::Base64 and MIME::QuotedPrint, which perform
        the low-level MIME decoding. Get these from Gisle Aas' author
        directory. They are also reported to be in the LWP distribution.

    MailTools (1.09 or higher)
        This is Graham Barr's revamped set of Mail:: modules. Many of them
        are now superclasses of the MIME:: modules, and perform the core
        functionality of manipulating headers and fields.

    For your convenience, possibly-old copies of the MIME:: modules are
    provided in the ./etc directory, of the distribution, but they are NOT
    installed for you during the installation procedure.

AUTHOR
    MIME-tools was created by:

        ___  _ _ _   _  ___ _     
       / _ \| '_| | | |/ _ ' /    Eryq (President, Zero G Inc.)
      |  __/| | | |_| | |_| |     http://www.zeegee.com/
       \___||_|  \__, |\__, |__   eryq@zeegee.com
                 |___/    |___/

    For full credits, see the MIME::Tools module.

CHANGES
  Version 4.112

    MIME::Entity::print_body now recurses when printing multipart entities,
    and prints "everything following the header." This is more likely what
    people expect to happen. PLEASE read the "two body problem" section of
    MIME::Entity's docs.

  Version 4.111

    Clean build/test on Win95 using 5.004. Whew.

  Version 4.110

    Added make_multipart() and make_singlepart() in MIME::Entity.

    Improved handling/saving of preamble/epilogue.

  Version 4.109

    Overall
        Major version shift to 4.x accompanies numerous structural changes,
        and the deletion of some long-deprecated code. Many apologies to
        those who are inconvenienced by the upgrade.

        MIME::IO deprecated. You'll see IO::Scalar, IO::ScalarArray, and
        IO::Wrap to make this toolkit work.

        MIME::Entity deep code. You can now deep-copy MIME entities (except
        for on-disk data files).

    Encoding/decoding
        MIME::Latin1 deprecated, and 8-to-7 mapping removed. Really,
        MIME::Latin1 was one of my more dumber ideas. It's still there, but
        if you want to map 8-bit characters to Latin1 ASCII approximations
        when 7bit encoding, you'll have to request it explicitly. *But use
        quoted-printable for your 8-bit documents; that's what it's there
        for!*

        7bit and 8bit "encoders" no longer encode. As per RFC-2045, these
        just do a pass-through of the data, but they'll warn you if you send
        bad data through.

        MIME::Entity suggests encoding. Now you can ask MIME::Entity's
        build() method to "suggest" a legal encoding based on the body and
        the content-type. No more guesswork! See the "mimesend" example.

        New module structure for MIME::Decoder classes. It should be easier
        for you to see what's happening.

        New MIME decoders! Support added for decoding `x-uuencode', and for
        decoding/encoding `x-gzip64'. You'll need "gzip" to make the latter
        work.

        Quoted-printable back on track... and then some. The 'quoted-
        printable' decoder now uses the newest MIME::QuotedPrint, and amends
        its output with guideline #8 from RFC2049 (From/.). *Thanks to Denis
        N. Antonioli for suggesting this.*

    Parsing
        Preamble and epilogue are now saved. These are saved in the parsed
        entities as simple string-arrays, and are output by print() if
        there. *Thanks to Jason L. Tibbitts for suggesting this.*

        The "multipart/digest" semantics are now preserved. Parts of digest
        messages have their mime_type() defaulted to "message/rfc822"
        instead of "text/plain", as per the RFC. *Thanks to Carsten Heyl for
        suggesting this.*

    Output
        Well-defined, more-complete print() output. When printing an entity,
        the output is now well-defined if the entity came from a
        MIME::Parser, even if using parse_nested_messages. See MIME::Entity
        for details.

        You can prevent recommended filenames from being output. This
        possible security hole has been plugged; when building MIME
        entities, you can specify a body path but suppress the filename in
        the header. *Thanks to Jason L. Tibbitts for suggesting this.*

    Bug fixes
        Win32 installations should work. The binmode() calls should work
        fine on Win32 now. *Thanks to numerous folks for their patches.*

        MIME::Head::add() now no longer downcases its argument. *Thanks to
        Brandon Browning & Jason L. Tibbitts for finding this bug.*

