MHonArc Resources: MIMEFILTERS

[Prev: MIMEEXCS] | [Resources][TOC] | [Next: MODTIME]

# MIMEFILTERS

## Syntax

Envariable

  N/A

Element

  `<MIMEFILTERS>`
  filter-specification
  ...
  `</MIMEFILTERS>`

Command-line Option

  N/A

## Description

The resource MIMEFILTERS is used to hook in user specifed filters into MHonArc. The MIMEFILTERS resource can only be set via the `MIMEFILTERS` element. The syntax for each line of the the `MIMEFILTERS` element is as follows:

content-type`;`routine-name`;`file-of-routine

The definition of each semi-colon-separated value is as follows:

content-type

  The MIME content-type the filter processes. An explicit content-type (base/subtype) or a base content-type (base/*) can be specified.

routine-name

  The actual routine name of the filter. The name should be fully qualified by the package it is defined in (e.g. "`mypackage::filter`").

file-of-routine

  The name of the file that defines routine-name. If the file is not a full pathname, MHonArc finds the file by looking in the standard include paths of Perl, and the paths specified by the PERLINC resource.

Whitespace is stripped out for each filter specification.

### Writing Filters

If you want to write your own filter for use in MHonArc, you need to know the Perl programming language. The following information assumes you know Perl.

NOTE | As of v2.5 of MHonArc, the API for filters is different from v2.4.x, and earlier. The following describes the v2.5 API for filters.

NOTE | The default filters provided by MHonArc are described in the Default Settings section.

#### Function Interface of Filter

MHonArc interfaces with MIME filters by calling a routine with a specific set of arguments. The prototype of the interface routine is as follows:

    sub filter {
        my($fields_hash_ref, $body_data_ref, $is_decoded, $filter_args) = @_;

        # Filter code here

        # The last statement should be the return value, unless an
        # explicit return is done. See the following for the format of the
        # return value.
    }

##### Parameter Descriptions

`$fields_hash_ref` | A reference to hash of message/part header fields. Keys are field names in lowercase and values are array references containing the field values. For example, to obtain the content-type, if defined, you would do:
      $fields_hash_ref->{'content-type'}[0]
Values for a fields are stored in arrays since duplication of fields are possible. For example, the `Received:` header field is typically repeated multiple times. For fields that only occur once, then array for the field will only contain one item.
`$body_data_ref` | Reference to body data. It is okay for the filter to modify the text in-place.
`$is_decoded` | Boolean flag if body data has been decoded. This is normally true unless some non-standard content-transfer-encoding is used. See MIMEDECODERS on how to register decoders for various content-transfer-encodings.
`$filter_args` | This is an optional argument string that may be used to modify the behavior of the filter. The format of this string is determined by the filter itself. The value of the string is set by the MIMEARGS resource.

##### Return Value

The return value is treated as a list. The first item of the list is a string representing the HTML markup to insert in the HTMLized message. An empty string, or `undef` may be returned to tell MHonArc that the routine was unable to filter data.

Any other list items are treated as names of any files that were generated by the filter. MHonArc needs to keep track if any extra files that a filter may generate in order for MHonArc to delete those files if the message gets removed from the archive.

NOTE | If you want MHonArc to treat the data as filtered, but not have anything displayed on the page, just return a string with a single space character.

NOTE | If the filter creates a subdirectory with files, the filter only needs to return the subdirectory in the return list. If the message gets removed, MHonArc will delete the entire directory.

#### Filter Writing Tips

The following recommendations/tips are given to help you write filters:

- Qualify your filter in its own package. This eliminates possible variable/routine conflicts with MHonArc.

- If the filter creates derived files (like the image filters), you may use the variable `$mhonarc::OUTDIR` to determine the location of the mail archive.

  NOTE | Do not include `$mhonarc::OUTDIR` as part as the filename that is returned to MHonArc. If the filter does create files, just return the base name.

- Look at the default filters contained in the distribution of MHonArc. You can use these as templates for writing your own.

- Make sure your Perl source file ends with a true statement (like "`1;`"). MHonArc just performs a `require` on the file, and if the file does not return true, Perl will abort execution.

- Test your filter before production use.

#### Using C

If a MIME filter requires the utilization of a C program, or other non-Perl executable, a Perl wrapper must be written for the program in-order to interface with MHonArc. The wrapper must follow the conventions described in Writing Filters.

## Default Setting

NOTE | It is important to have an explicit entry for `application/octet-stream` for handling unknown media-types.

    <MIMEFilters>
    application/octet-stream;  m2h_external::filter;	mhexternal.pl
    application/*;		   m2h_external::filter;	mhexternal.pl
    application/x-patch;	   m2h_text_plain::filter;	mhtxtplain.pl
    audio/*;		   m2h_external::filter;	mhexternal.pl
    chemical/*;		   m2h_external::filter;	mhexternal.pl
    model/*;		   m2h_external::filter;	mhexternal.pl
    image/*;		   m2h_external::filter;	mhexternal.pl
    message/delivery-status;   m2h_text_plain::filter;	mhtxtplain.pl
    message/external-body;     m2h_msg_extbody::filter;	mhmsgextbody.pl
    message/partial;	   m2h_text_plain::filter;	mhtxtplain.pl
    text/*;			   m2h_text_plain::filter;	mhtxtplain.pl
    text/enriched;		   m2h_text_enriched::filter;	mhtxtenrich.pl
    text/html;		   m2h_text_html::filter;	mhtxthtml.pl
    text/plain;		   m2h_text_plain::filter;	mhtxtplain.pl
    text/richtext;		   m2h_text_enriched::filter;	mhtxtenrich.pl
    text/setext;		   m2h_text_setext::filter;	mhtxtsetext.pl
    text/tab-separated-values; m2h_text_tsv::filter;	mhtxttsv.pl
    text/x-html;		   m2h_text_html::filter;	mhtxthtml.pl
    text/x-setext;		   m2h_text_setext::filter;	mhtxtsetext.pl
    video/*;		   m2h_external::filter;	mhexternal.pl
    x-sun-attachment;	   m2h_text_plain::filter;	mhtxtplain.pl
    </MIMEFilters>

The following describes the behavior of each filter.

### m2h_external::filter

The filter extracts the data into a separate file and puts a hyperlink to the file into the HTMLized message. The following is an example how the link is formatted:

  Attachment: `blueball.gif`
  Description: Blue ball GIF icon

The description text is retrieved from the `Content-Disposition` message header field, if defined. If not defined, a generic description will be provided based on the specified content-type of the data.

If the `useicon` filter argument has been specified for the filter, the following format will be used:

  `blueball.gif`
  Description: Blue ball GIF icon

The actual icon used is based upon the ICONS resource.

By default, the filter ignores any filename specification given in the message when writing the data to disk. A unique filename with an extenstion based upon sub-type is generated.

`m2h_external::filter` can take the following arguments:

`excludeexts=`ext1`,`... | A comma separated list of message specified filename extensions to exclude. I.e. If the filename extension matches an extension in excludeexts, the content will not be written. The return markup will contain the name of the attachment, but no link to the data. This option is best used with application/octet-stream to exclude unwanted data that is not tagged with the proper content-type. The `m2h_null::filter` can be used to exclude content by content-type.
`ext=ext` | Use ext as the filename extension. The filter already has a large list of extensions for various content-types. Use this argument if you process a content-type not recognized by the filter.
`forceattach` | Force images to never be displayed inline, overriding any Content-Disposition setting.
`forceinline` | Force images to be displayed inline, overriding any Content-Disposition setting.
`frame` | Draw a frame around the attachment link.
`iconurl="url"` | Use "url" as the url for the icon to use if the `useicon` option is set. This option will override any setting defined by the ICONS resource. The double quotes are required.
`inline` | Inline image data by default if content-disposition not defined.
`inlineexts=`ext1`,`... | A comma separated list of message specified filename extensions to treat as possible inline data. Applicable when content-type is not `image/`* and `usename` or `usenameext` is in effect.
`type="description"` | Use "description" as type description of the data. The double quotes are required. The filter already has a large list of descriptions for various content-types. Use this argument if you process a content-type not recognized by the filter.
`subdir` | Place derived file in a subdirectory of the archive. The subdirectory will be called "`msgMSGNUM`". This option may be useful if `usename` is specified to avoid security and name conflict problems.
`target=`name | Set the TARGET attribute of anchor link to file Default value is undefined (ie. no TARGET attribute will be written).
`useicon` | Include a content-type icon with the hyperlink to the derived file. The icon used is the value of the `iconurl` option or the icon defined by the ICONS resource.
`usename` | Use (file)name attribute for determining name of derived file. Use this option with caution since it can lead to filename conflicts and security problems (however, see the `subdir` option).
`usenameext` | Use (file)name attribute for determining the extension of derived file. Use this option with caution since it can lead to security problems (however, see the `subdir` option).

All arguments should be separated by at least one space.

The following table shows the default list of content-types with the filename extension used and a short description that `m2h_external::filter` recognizes:

Content-type | Extension | Description
--- | --- | ---
application/astound | `asd` | Astound presentation
application/envoy | `evy` | Envoy file
application/fastman | `lcc` | fastman file
application/fractals | `fif` | Fractal Image Format
application/iges | `iges` | IGES file
application/mac-binhex40 | `hqx` | Mac BinHex archive
application/mathematica | `ma` | Mathematica Notebook document
application/mbedlet | `mbd` | mbedlet file
application/ms-excel | `xls` | MS-Excel spreadsheet
application/ms-powerpoint | `ppt` | MS-Powerpoint presentation
application/ms-project | `mpp` | MS-Project file
application/msword | `doc` | MS-Word document
application/octet-stream | `bin` | Binary data
application/oda | `oda` | ODA file
application/pdf | `pdf` | Adobe PDF document
application/pgp | `pgp` | PGP message
application/pgp-signature | `pgp` | PGP signature
application/postscript | `ps` | PostScript document
application/rtf | `rtf` | RTF file
application/sgml | `sgml` | SGML document
application/studiom | `smp` | Studio M file
application/timbuktu | `tbt` | timbuktu file
application/vis5d | `v5d` | Vis5D dataset
application/vnd.framemaker | `fm` | FrameMaker document
application/vnd.hp-hpgl | `hpg` | HPGL file
application/vnd.lotus-1-2-3 | `123` | Lotus 1-2-3
application/vnd.lotus-approach | `apr` | Lotus Approach
application/vnd.lotus-freelance | `prz` | Lotus Freelance
application/vnd.lotus-organizer | `org` | Lotus Organizer
application/vnd.lotus-screencam | `scm` | Lotus Screencam
application/vnd.lotus-wordpro | `lwp` | Lotus WordPro
application/vnd.mif | `mif` | Frame MIF document
application/vnd.ms-excel | `xls` | MS-Excel spreadsheet
application/vnd.ms-powerpoint | `ppt` | MS-Powerpoint presentation
application/vnd.ms-project | `mpp` | MS-Project file
application/vnd.stardivision.calc | `sdc` | StarCalc spreadsheet
application/vnd.stardivision.chart | `sds` | StarChart document
application/vnd.stardivision.draw | `sda` | StarDraw document
application/vnd.stardivision.impress | `sdd` | StarImpress presentation
application/vnd.stardivision.impress-packed | `sdp` | StarImpress packed file
application/vnd.stardivision.mail | `smd` | StarMail mail file
application/vnd.stardivision.math | `smf` | StarMath document
application/vnd.stardivision.writer | `sdw` | StarWriter document
application/vnd.stardivision.writer-global | `sgl` | StarWriter global document
application/vnd.sun.xml.calc | `sxc` | OpenOffice Calc spreadsheet
application/vnd.sun.xml.calc.template | `stc` | OpenOffice Calc template
application/vnd.sun.xml.draw | `sxd` | OpenOffice Draw document
application/vnd.sun.xml.draw.template | `std` | OpenOffice Draw Template
application/vnd.sun.xml.impress | `sxi` | OpenOffice Impress presentation
application/vnd.sun.xml.impress.template | `sti` | OpenOffice Impress template
application/vnd.sun.xml.math | `sxm` | OpenOffice Math documents
application/vnd.sun.xml.writer | `sxw` | OpenOffice Writer document
application/vnd.sun.xml.writer.global | `sxg` | OpenOffice Writer global document
application/vnd.sun.xml.writer.template | `stw` | OpenOffice Write template
application/winhlp | `hlp` | WinHelp document
application/wordperfect5.1 | `wp` | WordPerfect 5.1 document
application/x-asap | `asp` | asap file
application/x-bcpio | `bcpio` | BCPIO file
application/x-bzip2 | `bz2` | BZip2 compressed data
application/x-compress | `Z` | Unix compressed data
application/x-cpio | `cpio` | CPIO file
application/x-csh | `csh` | C-Shell script
application/x-dot | `dot` | dot file
application/x-dvi | `dvi` | TeX dvi file
application/x-earthtime | `etc` | Earthtime file
application/x-envoy | `evy` | Envoy file
application/x-excel | `xls` | MS-Excel spreadsheet
application/x-gtar | `gtar` | GNU Unix tar archive
application/x-gzip | `gz` | GNU Zip compressed data
application/x-hdf | `hdf` | HDF file
application/x-javascript | `js` | JavaScript source
application/x-ksh | `ksh` | Korn Shell script
application/x-latex | `latex` | LaTeX document
application/x-maker | `fm` | FrameMaker document
application/x-mif | `mif` | Frame MIF document
application/x-mocha | `moc` | mocha file
application/x-msaccess | `mdb` | MS-Access database
application/x-mscardfile | `crd` | MS-CardFile
application/x-msclip | `clp` | MS-Clip file
application/x-msmediaview | `m14` | MS-Media View file
application/x-msmetafile | `wmf` | MS-Metafile
application/x-msmoney | `mny` | MS-Money file
application/x-mspublisher | `pub` | MS-Publisher document
application/x-msschedule | `scd` | MS-Schedule file
application/x-msterminal | `trm` | MS-Terminal
application/x-mswrite | `wri` | MS-Write document
application/x-net-install | `ins` | Net Install file
application/x-netcdf | `cdf` | Cdf file
application/x-ns-proxy-autoconfig | `proxy` | Netscape Proxy Auto Config
application/x-patch | `patch` | Source code patch
application/x-perl | `pl` | Perl program
application/x-pointplus | `css` | pointplus file
application/x-salsa | `slc` | salsa file
application/x-script | `script` | A script file
application/x-sh | `sh` | Bourne shell script
application/x-shar | `shar` | Unix shell archive
application/x-sprite | `spr` | sprite file
application/x-stuffit | `sit` | Macintosh archive
application/x-sv4cpio | `sv4cpio` | SV4Cpio file
application/x-sv4crc | `sv4crc` | SV4Crc file
application/x-tar | `tar` | Unix tar archive
application/x-tcl | `tcl` | Tcl script
application/x-tex | `tex` | TeX document
application/x-texinfo | `texinfo` | TeXInfo document
application/x-timbuktu | `tbp` | timbuktu file
application/x-tkined | `tki` | tkined file
application/x-troff | `roff` | Troff document
application/x-troff-man | `man` | Unix manual page
application/x-troff-me | `me` | Troff ME-macros document
application/x-troff-ms | `ms` | Troff MS-macros document
application/x-ustar | `ustar` | UStar file
application/x-wais-source | `src` | WAIS Source
application/x-zip-compressed | `zip` | Zip compressed data
application/zip | `zip` | Zip archive
audio/basic | `snd` | Basic audio
audio/echospeech | `es` | Echospeech audio
audio/microsoft-wav | `wav` | Wave audio
audio/midi | `midi` | MIDI audio
audio/wav | `wav` | Wave audio
audio/x-aiff | `aif` | AIF audio
audio/x-epac | `pae` | epac audio
audio/x-midi | `midi` | MIDI audio
audio/x-mpeg | `mp2` | MPEG audio
audio/x-pac | `pac` | pac audio
audio/x-pn-realaudio | `ra` | PN Realaudio
audio/x-wav | `wav` | Wave audio
chemical/chem3d | `c3d` | Chem3d chemical test
chemical/chemdraw | `chm` | Chemdraw chemical test
chemical/cif | `cif` | CIF chemical test
chemical/cml | `cml` | CML chemical test
chemical/cmsl | `cml` | Chemical Structure Markup
chemical/cxf | `cxf` | Chemical Exhange Format file
chemical/daylight-smiles | `smi` | SMILES format file
chemical/embl-dl-nucleotide | `emb` | EMBL nucleotide format file
chemical/gaussian | `gau` | Gaussian data
chemical/gaussian-input | `gau` | Gaussian input data
chemical/gaussian-log | `gal` | Gaussian log
chemical/gcg8-sequence | `gcg` | GCG format file
chemical/genbank | `gen` | GENbank data
chemical/jcamp-dx | `jdx` | Jcamp chemical spectra test
chemical/kinemage | `kin` | Kinemage
chemical/macromodel-input | `mmd` | Macromodel chemical test
chemical/mdl-molfile | `mol` | MOL mdl chemical test
chemical/mdl-rdf | `rdf` | RDF chemical test
chemical/mdl-rxn | `rxn` | RXN chemical test
chemical/mdl-sdf | `sdf` | SDF chemical test
chemical/mdl-tgf | `tgf` | TGF chemical test
chemical/mif | `mif` | MIF chemical test
chemical/mmd | `mmd` | Macromodel data
chemical/mopac-input | `mop` | MOPAC data
chemical/ncbi-asn1 | `asn` | NCBI data
chemical/pdb | `pdb` | Protein Databank data
chemical/rosdal | `ros` | Rosdal data
chemical/xyz | `xyz` | Xmol XYZ data
image/bmp | `bmp` | Windows bitmap
image/cgm | `cgm` | Computer Graphics Metafile
image/fif | `fif` | Fractal Image Format image
image/g3fax | `g3f` | Group III FAX image
image/gif | `gif` | GIF image
image/ief | `ief` | IEF image
image/ifs | `ifs` | IFS image
image/jpeg | `jpg` | JPEG image
image/pbm | `pbm` | Portable bitmap
image/pgm | `pgm` | Portable graymap
image/png | `png` | PNG image
image/tiff | `tif` | TIFF image
image/vnd | `dwg` | VND image
image/wavelet | `wi` | Wavelet image
image/x-cmu-raster | `ras` | CMU raster
image/x-pbm | `pbm` | Portable bitmap
image/x-pcx | `pcx` | PCX image
image/x-pgm | `pgm` | Portable graymap
image/x-pict | `pict` | Mac PICT image
image/x-pnm | `pnm` | Portable anymap
image/x-portable-anymap | `pnm` | Portable anymap
image/x-portable-bitmap | `pbm` | Portable bitmap
image/x-portable-graymap | `pgm` | Portable graymap
image/x-portable-pixmap | `ppm` | Portable pixmap
image/x-ppm | `ppm` | Portable pixmap
image/x-rgb | `rgb` | RGB image
image/x-xbitmap | `xbm` | X bitmap
image/x-xbm | `xbm` | X bitmap
image/x-xpixmap | `xpm` | X pixmap
image/x-xpm | `xpm` | X pixmap
image/x-xwd | `xwd` | X window dump
image/x-xwindowdump | `xwd` | X window dump
message/news | `822` | News post
message/rfc822 | `822` | Mail message
model/iges | `iges` | IGES model
model/mesh | `mesh` | Mesh model
model/vrml | `wrl` | VRML model
text/enriched | `rtx` | Text-enriched document
text/html | `html` | HTML document
text/plain | `txt` | Text document
text/richtext | `rtx` | Richtext document
text/setext | `stx` | Setext document
text/sgml | `sgml` | SGML document
text/tab-separated-values | `tsv` | Tab separated values
text/x-speech | `talk` | Speech document
video/isivideo | `fvi` | isi video
video/mpeg | `mpg` | MPEG movie
video/msvideo | `avi` | MS Video
video/quicktime | `mov` | QuickTime movie
video/vivo | `viv` | vivo video
video/wavelet | `wv` | Wavelet video
video/x-sgi-movie | `movie` | SGI movie

### m2h_msg_extbody::filter

This filter is designed to process `message/external-body` data. The filter attempts to translate the external-body paramaters into a linked URL with some descriptive information, if provided. The following access-types are supported: ANON-FTP, FTP, TFTP, LOCAL-FILE, and URL. Note, LOCAL-FILE is only supported if the `local-file` option is specified.

`m2h_msg_extbody::filter` can take the following arguments:

`local-file` | Support LOCAL-FILE access-type. This option is best used for internal local mail archives where it is known that readers will have direct access to the file.

### m2h_text_enriched::filter

This filter is designed to process text/enriched, or text/richtext, data. The following table summarizes the translation of text/enriched commands to HTML tags:

Text/Enriched Command | HTML Translation
--- | ---
<Bold> | <B>
<Italic> | <I>
<Underline> | <U>
<Fixed> | <TT>
<Smaller> | <SMALL>
<Bigger> | <BIG>
<FontFamily><Param>family</Param> | <FONT face="family">
<Color><Param>color</Param> | <FONT color="color">
<Center> | <P align="center">
<FlushLeft> | <P align="left">
<FlushRight> | <P align="right">
<FlushBoth> | <P align="both"> (not supported in HTML)
<ParaIndent> | <BLOCKQUOTE>
<Excerpt> | <BLOCKQUOTE>
<Lang> | Stripped

If the text/enriched contains non-ASCII character, the filter will convert the characters to the appropriate entity references.

NOTE | Only the ISO-8859-[1-10] character sets are recognized.

### m2h_text_html::filter

CAUTION | If you are worried about security, it is recommended that you disable support of text/html messages in your mail archives. There is no guarantee that this filter is robust enough to eliminate all possible exploits that can occur with HTML data.

This filter is designed to process `text/html`, or `text/x-html`, data. The filter modifies HTML documents so they can be included into the message pages without causing invalid markup to occur. The following modification are done to HTML documents when processed by MHonArc:

- The HEAD element is removed. Since some elements within the HEAD element may be relevant to the rest of the document, the following is done when removing the HEAD element:

  - The title will be extracted and prepended to the body data.
  - Any BASE URL will be propogated to any relative URLs in the document.

- Any markup related to scripting is removed for security reasons. The following tags are removed: `<applet>`, `<base>`, `<embed>`, `<form>`, `<ilayer>`, `<input>`, `<layer>`, `<link>`, `<meta>`, `<object>`, `<option>`, `<param>`, `<script>`, `<select>`, `<style>`, `<textarea>`. The following attributes are removed: `onload`, `onunload`, `onclick`, `ondblclick`, `onmousedown`, `onmouseup`, `onmouseover`, `onmousemove`, `onmouseout`, `onkeypress`, `onkeydown`, `onkeyup`. The `allowscript` option can be be used to override this behavior (see below).

- `cid:` URLs are resolved, if possible. Therefore, if image data related to the HTML document is included with the message, the URLs will be modified to the filenames of the images that were decoded.

`m2h_text_html::filter` can take the following arguments:

`allowcomments` | Preserve any comment declarations. Comment declarations are sometimes used to contain executable commands, like for server-side includes. Normally, comment declarations are munged to protect against potential exploits, but this option will disable that behavior. Use this options with EXTREME care.
`allownoncidurls` | Preserve URL-based attributes that are not cid: URLs. Normally, any URL-based attribute -- `href`, `src`, `background`, `classid`, `data`, `longdesc` -- will be stripped if it is not a cid: URL. This is to prevent malicious URLs that verify mail addresses for spam purposes, secretly set cookies, or gather some statistical data automatically with the use of elements that cause browsers to automatically fetch data: `IMG`, `BODY`, `IFRAME`, `FRAME`, `OBJECT`, `SCRIPT`, `INPUT`.
`allowscript` | Preserve any markup associated with scripting. This includes elements and attributes related to scripting. This option can cause security problems for your archive since someone can introduce foreign client-side code. Use this options with EXTREME care.
`attachcheck` | Honor attachment disposition. By default, all text/html data is displayed inline on the message page. If `attachcheck` is specified and Content-Disposition specifies the data as an attachment, the data is saved to a file with a link to it from the message page. CAUTION: If `attachcheck` is specified, the HTML data is saved "as-is". For example, no stripping of scripting-based markup is performed and no resolution of cid URLs are performed.
`nofont` | Remove font tags.
`notitle` | Do not print extracted title at the beginning of converted output. Since this filter strips out HEAD markup so the document can be included into the message page, this filter will extract the title and print the title of the document before the document body. The `notitle` argument disables this behavior.

### m2h_text_plain::filter

This filter is designed to process text/plain messages and messages with no MIME information. The filter is also used to process text messages of an unknown subtype.

The default behavior of the filter is wrap the data in the HTML PRE element and escape special characters. It will also convert text that looks like a URL into a hyperlink. If the data contains non-ASCII character, the filter will convert the characters to the appropriate entity reference.

NOTE | The functions registered via the CHARSETCONVERTERS are used to handle character set processing.

`m2h_text_plain::filter` can take the following arguments:

`asis=`set1`:`... | Colon separated lists of charsets to leave as-is. Only HTML special characters will be converted into entities. The default is "`us-ascii:iso-8859-1`".
`attachcheck` | Honor attachment disposition. By default, all text/plain data is displayed inline on the message page. If `attachcheck` is specified and Content-Disposition specifies the data as an attachment, the data is saved to a file with a link to it from the message page.
`default=`charset | Character set to use as the default if no character set is defined for the message. If option not specified, "`us-ascii`" is used.
`inlineexts=`ext1`,`... | A comma separated list of message specified filename extensions to treat as inline data. Applicable only when `uudecode` is specified.
`htmlcheck` | Check if message is actually an HTML message (to get around abhorrent MUAs). The message is treated as HTML if the first non-whitespace data looks like the start of an HTML document.
`keepspace` | Preserve all spaces if the `nonfixed` option is specified. All spaces and tabs will be translated to the equivalent number of &nbsp; entity references.
`maxwidth=`# | Force the maximum width of lines to be # characters in length. Any lines longer than # characters will be wrapped.
`nonfixed` | Do not wrap message text in the HTML PRE element. This will cause text to be rendered in the default font (which is normally proportionally spaced). Each line of the message will have a `<BR>` appended in order to preserve the line representation of the message.
`nourl` | Do not hyperlink URLs.
`quote` | Italicize quoted message text.
`target=`name | Set the TARGET attribute of an anchor links generated from hyperlinking URLs.
`usename` | When decoding uuencoded data, use the full filename specified when write the data to disk instead of just the filename extension. Note: Be aware that there are potential security problems when using this option.
`uudecode` | Decode any embedded uuencoded data. Including uuencoded data within messages was a way to trasmit binary data via email before MIME was developed. The inclusion of uuencoded data is deprecated within email, but is still common in the USENET (binary) newsgroups. Note, specifying `uudecode` adds extra overhead in the processing of text messages, including messages without any uuencoded data. Uuencoded data is treated as `application/octet-stream` data for purposes of checking if the data should be excluded when checked against the MIMEEXCS resource. Therefore, if `application/octet-stream` data is listed in MIMEEXCS, uuencoded data will be excluded.

All arguments should be separated by at least one space.

### m2h_text_setext::filter

This filter converts text/setext and text/x-setext messages to HTML.

### m2h_text_tsv::filter

This filter converts text/tab-separated-values to HTML. The tabular data will be converted into an HTML table.

### m2h_null::filter

This filter can be used to exclude message content from archives. You can register this filter to any content-type you do not want to store in your archives. For example, the following resource setting excludes all images:

    <MIMEFilters>
    image/*; m2h_null::filter; mhnull.pl
    </MIMEFilters>

The markup returned by this filter displays the a one line description of what was excluded. Examples:

    <<attachment: HelloWorld.jpg>>
    <<application/postscript>>
    <<inline: image/jpg>>

If the disposition is available, it will be shown. If a filename was specified, it will be shown. If there was no filename, the content-type is shown.

## Resource Variables

N/A

## Examples

The following code is an example filter for converting `text/tab-separated-values` into an HTML table:

    package m2h_text_tsv;

    sub filter {
        my($fields, $data, $isdecode, $args) = @_;
        my($field, $line, $ret);
        local($_);

        $$data =~ s/^\s+//;
        $ret  = "<table border=1>\n";
        foreach $line (split(/\r?\n/, $$data)) {
    	$ret .= "<tr>";
    	foreach $field (split(/\t/, $line)) {
    	    $ret .= "<td>$field</td>";
    	}
    	$ret .= "</tr>\n";
        }
        $ret .= "</table>\n";
        ($ret);
    }

    1;

## Version

1.0

## See Also

CHARSETCONVERTERS, MIMEARGS, MIMEDECODERS, MIMEEXCS, PERLINC

[Prev: MIMEEXCS] | [Resources][TOC] | [Next: MODTIME]