1DETOXRC(5)                  BSD File Formats Manual                 DETOXRC(5)
2

NAME

4     detoxrc — configuration file for detox(1)
5

OVERVIEW

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

IMPORTANT

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

SYNTAX

17     The format of this configuration file is C-like.  It is based loosely off
18     named's configuration files.  Each statement is semicolon terminated, and
19     modifiers on a particular statement are generally contained within
20     braces.
21
22     sequence "name" {...};
23         Defines a sequence of filters to run a filename through.  "name"
24         specifies how the user will refer to the particular sequence during
25         runtime.  Quotes around the sequence name are generally optional, but
26         should be used if the sequence name does not start with a letter.
27
28         There is a special sequence, named "default", which is the default
29         sequence used by detox.  This can be overridden through the command
30         line option -s or the environmental variable DETOX_SEQUENCE.
31
32         Sequence names are case sensitive and unique throughout all
33         sequences; that is, if a system wide file defines normal_seq and a
34         user has a sequence with the same name in their .detoxrc, the users'
35         normal_seq will take precedence.
36
37     iso8859_1 {filename "/path/to/filename";};
38         This translates ISO 8859-1 (aka Latin-1) characters into lower ASCII
39         equivalents.  The output is not necessarily safe, and should also be
40         run through the safe filter.
41
42         Under normal circumstances, the filename syntax is not needed.  Detox
43         looks in several locations for a file called iso8859_1.tbl, which is
44         a set of rules defining how an ISO 8859-1 character should be trans‐
45         lated.
46
47         In the event this table doesn't exist, you have two options.  You can
48         download or create your own, and tell detox the location of it using
49         the filename syntax shown above, or you can let detox fall back on
50         its internal tables.  The internal tables translate the same as the
51         stock translation tables.
52
53         You can chain together multiple iso8859_1 translations, as long as
54         the default value of all but the last one is set to nothing.  This is
55         explained in detox.tbl(5).
56
57         This filter is mutually exclusive with the utf_8 filter.
58
59     utf_8 {filename "/path/to/filename";};
60         This translates Unicode characters, encoded by the UTF-8 translation
61         method, into safe equivalents.
62
63         This operates in a manner similar to iso8859_1, except it looks for a
64         translation table called unicode.tbl.
65
66         The default internal translation for Unicode characters only contains
67         the lower 256 characters of Unicode, which is equivalent to the set
68         of Basic Latin and Latin-1 characters.
69
70     uncgi;
71         This translates CGI escaped strings into their ASCII equivalents. The
72         output of this is not necessarily safe, and could contain ISO 8859-1
73         chars or potentially UTF-8 characters.
74
75     safe {filename "/path/to/filename";};
76         This could also be called "safe for UNIX-like operating systems".  It
77         translates characters that are difficult to work with in UNIX envi‐
78         ronments into characters that are not.
79
80         In earlier versions this filter was entirely internal.  Starting with
81         1.2.0, this filter is controlled by a translation table.  In the
82         absense of the translation table, the previous code will be employed
83         for the translation.  Also, prior to 1.2.0, the safe filter removed
84         leading dashes to prevent the hassle of dealing with a filename in
85         the format -filename.  This functionality is exclusively handled by
86         the wipeup filter now.
87
88         See the SAFE section for more details on what this filter translates
89         by default.
90
91     wipeup {remove_trailing;};
92         This wipes up any excessive characters.  For instance, multiple
93         underscores or dashes will be converted into a single underscore or
94         dash.  Any series of dash and underscore (i.e. "_-_") will be con‐
95         verted into a single dash.
96
97         The remove trailing option removes a dash or underscore followed
98         immediately by a period.
99
100         See the WIPEUP section for more details on what this filter trans‐
101         lates.
102
103     max_length {length value;};
104         This trims a file down to the length specified (or less).  It is con‐
105         scious of extensions and attempts to preserve anything following the
106         last period in a filename.
107
108         For instance, given a max length of 12, and a filename of
109         "this_is_my_file.txt", the filter would output "this_is_.txt".
110
111     lower;
112         This translates uppercase characters into lowercase characters.
113
114     # Comments
115         Any thing after a # on any line is ignored.
116

EXAMPLE

118     sequence default {
119       uncgi;
120       iso8859_1 {
121         filename "iso8859_1.tbl";
122       };
123     # utf_8 {
124     #   filename "unicode.tbl";
125     # };
126       safe {
127         filename "safe.tbl";
128       };
129       wipeup {
130         remove_trailing;
131       };
132     # max_length {
133     #   length 128;
134     # };
135     };
136

SAFE

138     The following characters are translated by the stock safe filter.  They
139     can be tuned by updating safe.tbl or creating a copy of safe.tbl and
140     updating your rc file.
141
142   Rules that apply anywhere in the filename:
143           Safe       Original
144           _and_      &
145           _          space ` ! @ $ * \ | : ; " ' < > ? /
146           -          ( ) [ ] { }
147

WIPEUP

149     The following characters are translated by the wipeup filter.
150
151   Rules that apply anywhere in the filename:
152           Wipeup    Original
153           -         -_
154           -         _-
155           -         --
156           _         __
157
158   Rules that apply only at the beginning of a filename:
159     Any leading dashes are stripped to prevent programs from interpreting
160     these files as command line options.
161
162           Wipeup     Original
163           removed    - _ #
164
165   Rules that apply when remove trailing is enabled:
166           Wipeup    Original
167           .         .-
168           .         -.
169           .         ._
170           .         _.
171

SEE ALSO

173     detox(1), detox.tbl(5).
174

AUTHORS

176     detox was written by Doug Harple.
177
178BSD                             August 3, 2004                             BSD
Impressum