1DETOXRC(5) BSD File Formats Manual DETOXRC(5)
2
4 detoxrc — configuration file for detox(1)
5
7 detox allows for configuration of its sequences through config files.
8 This document describes how these files work.
9
11 When setting up a new set of rules, the safe and wipeup filters must al‐
12 ways 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
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 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 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 Sequence names are case sensitive and unique throughout all se‐
33 quences; that is, if a system wide file defines normal_seq and a user
34 has a sequence with the same name in their .detoxrc, the users'
35 normal_seq will take precedence.
36 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 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 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 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 This filter is mutually exclusive with the utf_8 filter.
58 utf_8 {filename "/path/to/filename";};
60 This translates Unicode characters, encoded by the UTF-8 translation
61 method, into safe equivalents.
62 This operates in a manner similar to iso8859_1, except it looks for a
64 translation table called unicode.tbl.
65 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 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 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 In earlier versions this filter was entirely internal. Starting with
81 1.2.0, this filter is controlled by a translation table. In the ab‐
82 sence 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 See the SAFE section for more details on what this filter translates
89 by default.
90 wipeup {remove_trailing;};
92 This wipes up any excessive characters. For instance, multiple un‐
93 derscores 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 The remove trailing option removes a dash or underscore followed im‐
98 mediately by a period.
99 See the WIPEUP section for more details on what this filter trans‐
101 lates.
102 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 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 lower;
112 This translates uppercase characters into lowercase characters.
113 # Comments
115 Any thing after a # on any line is ignored.
116
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
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 up‐
140 dating your rc file.
141 Rules that apply anywhere in the filename:
143 Safe Original
144 _and_ &
145 _ space ` ! @ $ * \ | : ; " ' < > ? /
146 - ( ) [ ] { }
147
149 The following characters are translated by the wipeup filter.
150 Rules that apply anywhere in the filename:
152 Wipeup Original
153 - -_
154 - _-
155 - --
156 _ __
157 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 Wipeup Original
163 removed - _ #
164 Rules that apply when remove trailing is enabled:
166 Wipeup Original
167 . .-
168 . -.
169 . ._
170 . _.
171
173 detox(1), detox.tbl(5).
174
176 detox was written by Doug Harple.
177BSD August 3, 2004 BSD