DETOXRC(5)		  FreeBSD File Formats Manual		    DETOXRC(5)

NAME
     detoxrc -- configuration file for detox(1)

OVERVIEW
     detox allows for configuration of its sequences through config files.
     This document describes how these files work.

IMPORTANT
     When setting up a new set of rules, the safe filter must always be run
     after a translating filter (or series thereof), such as the utf_8 or the
     uncgi filters.  Otherwise, the risk of introducing illegal characters
     into the filename is introduced.

SYNTAX
     The format of this configuration file is C-like.  It is based loosely off
     named's configuration files.  Each statement is semicolon terminated, and
     modifiers on a particular statement are generally contained within
     braces.

     sequence "name" {...};
	 Defines a sequence of filters to run a filename through.  "name"
	 specifies how the user will refer to the particular sequence during
	 runtime.  Quotes around the sequence name are generally optional, but
	 should be used if the sequence name does not start with a letter.

	 There is a special sequence, named "default", which is the default
	 sequence used by detox.  This can be overridden through the command
	 line option -s or the environmental variable DETOX_SEQUENCE.

	 Sequence names are case sensitive and unique throughout all
	 sequences; that is, if a system wide file defines normal_seq and a
	 user has a sequence with the same name in their .detoxrc, the users'
	 normal_seq will take precedence.

     iso8859_1 {filename "/path/to/filename";};
	 This translates ISO 8859-1 (aka Latin-1) characters into lower ASCII
	 equivalents.  The output is not necessarily safe, and should also be
	 run through the safe filter.

	 Under normal circumstances, the filename syntax is not needed.  Detox
	 looks in several locations for a file called iso8859_1.tbl, which is
	 a set of rules defining how an ISO 8859-1 character should be trans-
	 lated.

	 In the event this table doesn't exist, you have two options.  You can
	 download or create your own, and tell detox the location of it using
	 the filename syntax shown above, or you can let detox fall back on
	 its internal tables.  The internal tables translate the same as the
	 stock translation tables.

	 You can chain together multiple iso8859_1 translations, as long as
	 the default value of all but the last one is set to nothing.  This is
	 explained in detox.tbl(5).

	 This filter is mutually exclusive with the utf_8 filter.

     utf_8 {filename "/path/to/filename";};
	 This translates Unicode characters, encoded by the UTF-8 translation
	 method, into safe equivalents.

	 This operates in a manner similar to iso8859_1, except it looks for a
	 translation table called unicode.tbl.

	 The default internal translation for Unicode characters only contains
	 the lower 256 characters of Unicode, which is equivalent to the set
	 of Basic Latin and Latin-1 characters.

     uncgi;
	 This translates CGI escaped strings into their ASCII equivalents. The
	 output of this is not necessarily safe, and could contain ISO 8859-1
	 chars or potentially UTF-8 characters.

     safe;
	 This could also be called "safe for UNIX-like operating systems".  It
	 translates characters that are difficult to work with in UNIX envi-
	 ronments into characters that are not.

	 See the SAFE section for more details on what this filter translates.

     wipeup {remove_trailing;};
	 This wipes up any excessive characters.  For instance, multiple
	 underscores or dashes will be converted into a single underscore or
	 dash.	Any series of dash and underscore (i.e. "_-_") will be con-
	 verted into a single dash.

	 The remove trailing option removes a dash or underscore followed
	 immediately by a period.

     max_length {length value;};
	 This trims a file down to the length specified (or less).  It is con-
	 scious of extensions and attempts to preserve anything following the
	 last period in a filename.

	 For instance, given a max length of 12, and a filename of
	 "this_is_my_file.txt", the filter would output "this_is_.txt".

     lower;
	 This translates uppercase characters into lowercase characters.

     # Comments
	 Any thing after a # on any line is ignored.

EXAMPLE
     sequence default {
       uncgi;
       iso8859_1 {
	 filename "iso8859_1.tbl";
       };
     # utf_8 {
     #	 filename "unicode.tbl";
     # };
       safe;
       wipeup {
	 remove_trailing;
       };
     # max_length {
     #	 length 128;
     # };
     };

SAFE
     The following characters are translated by the safe filter.

   Rules that apply anywhere in the filename:
	   Safe       Original
	   _and_      &
	   _	      space ` ! @ $ * \ | : ; " ' < > ? /
	   -	      ( ) [ ] { }

   Rules that apply only at the beginning of a filename:
     Any leading dashes are stripped to prevent programs from interpreting
     these files as command line options.

	   Safe       Original
	   removed    -
	   _	      # ( ) [ ] { }

SEE ALSO
     detox(1), detox.tbl(5).

AUTHORS
     detox was written by Doug Harple.

FreeBSD 5.3			August 3, 2004			   FreeBSD 5.3