chiark / gitweb /
keys.delete-keeper: Add commentary, because it's bit complicated.
[distorted-keys] / extract-profile.1
1 .\" -*-nroff-*-
2 .ie t \{\
3 .  ds o \(bu
4 .  if \n(.g .fam P
5 .\}
6 .el \{\
7 .  ds o o
8 .\}
9 .de hP
10 .IP
11 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
12 ..
13 .de VS
14 .sp 1
15 .RS
16 .nf
17 .ft B
18 ..
19 .de VE
20 .ft R
21 .fi
22 .RE
23 .sp 1
24 ..
25 .TH extract-profile 1 "3 May 2015" "distorted.org.uk key management"
26 .SH NAME
27 extract-profile \- determine configuration using inheritance and substitution
28 .SH SYNOPSIS
29 .B extract-profile
30 .I section
31 .IR file | directory ...
32 .SH DESCRIPTION
33 The
34 .B extract-profile
35 utility reads a number of
36 .BR .ini -style
37 configuration files from the named
38 .IR file s
39 and
40 .IR directori es,
41 combines the sections according to inheritance rules (described below),
42 performs substitutions on the values,
43 and writes the resulting effective contents of the named
44 .I section
45 to standard output.
46 .PP
47 A
48 .I directory
49 named on the command line
50 causes files within to be examined:
51 specifically, each file whose name consists only of
52 upper- and lowercase letters,
53 digits,
54 underscores
55 .RB (` _ '),
56 and
57 hyphens
58 .RB (` \- ')
59 will be processed;
60 other files are ignored,
61 as are objects in the
62 .I directory
63 which aren't files
64 (so, in particular, directories are not processed recursively).
65 The files within a directory are processed
66 in ascending lexicographic order.
67 It may be useful to prefix filenames with numbers
68 in order to ensure that they're read in the correct order.
69 .SS Command-line options
70 The following options are recognized.
71 .TP
72 .B \-h, \-\-help
73 Print an overview
74 of the options and commands
75 to standard output
76 and exit successfully.
77 .TP
78 .B \-\-version
79 Print the version number
80 of the
81 .B distorted-keys
82 package
83 to standard output
84 and exit successfully.
85 .SS Configuration data model
86 A
87 .I property
88 has a
89 .I name
90 and a
91 .IR value .
92 A property's name must consist only of
93 upper- and lowercase letters,
94 digits,
95 underscores
96 .RB (` _ '),
97 and
98 percent signs
99 .RB (` % ').
100 A property is
101 .I internal
102 if its name contains
103 a percent sign;
104 otherwise it is
105 .IR external .
106 .PP
107 A
108 .I direct section
109 has a name,
110 an
111 .I inclusion list
112 of other sections,
113 and a collection of
114 .I direct properties
115 with distinct names.
116 .PP
117 There is a special section 
118 named
119 .B @GLOBAL
120 which is implicitly included by every other section.
121 .SS Configuration syntax
122 Configuration files are line-oriented.
123 Leading and trailing whitespace is always ignored.
124 There is no line-continuation syntax.
125 There are four kinds of lines.
126 .hP \*o
127 .IR "Blank lines" ,
128 consisting only of whitespace,
129 are ignored.
130 .hP \*o
131 .IR Comments ,
132 beginning with 
133 hash
134 .RB (` # ')
135 or
136 semicolon
137 .RB (` ; '),
138 are also ignored.
139 .hP \*o
140 .IR "Section headings" ,
141 consisting of a name
142 surrounded by square brackets
143 .RB (` [ ... ] '),
144 cause the following assignments,
145 as far as the next section heading
146 or the end of the file,
147 to define or override properties in the named section.
148 .hP \*o
149 .IR Assignments ,
150 of the form
151 .I name
152 .B =
153 .I value
154 or
155 .I name
156 .B :
157 .IR value ,
158 define (or override) direct properties
159 or pseudoproperties
160 in the current section.
161 Spaces around the
162 .RB ` = '
163 or
164 .RB ` : '
165 are optional and, if present, ignored.
166 Hyphens
167 .RB (` - ')
168 in the
169 .I name
170 are converted to
171 underscores
172 .RB (` _ ').
173 Assignments preceding the first section header in a file
174 apply to the special section
175 .BR @GLOBAL .
176 .PP
177 The same property
178 or pseudoproperty
179 may be defined multiple times in a section:
180 only the last definition is significant;
181 earlier definitions are silently ignored.
182 .PP
183 Pseudoproperties have names beginning with an at sign
184 .RB (` @ ').
185 The following pseudoproperties are recognized.
186 .TP
187 .B @include
188 The value is a list of section names separated by whitespace.
189 The current section's inclusion list is set to
190 the corresponding named sections.
191 .PP
192 Sections may be defined in any order.
193 The same section may be defined more than once:
194 the effect is the same as a single section containing
195 all of the assignments of the individual sections
196 in the same order.
197 .SS Inheritance
198 The
199 .I inferiors
200 of a section
201 .I S
202 are the sections in
203 .IR S 's
204 inclusion list,
205 together with their inferiors.
206 It is an error if a section is its own inferior.
207 (Consequently, it is an error if
208 .B @GLOBAL
209 has a non-empty inclusion list.)
210 If
211 .I T
212 is an inferior of
213 .I S
214 then
215 .I S
216 is a
217 .I superior
218 of
219 .IR T .
220 .PP
221 A section
222 .I S
223 has an
224 .I effective property
225 named
226 .I P
227 if either
228 .I S
229 has a direct property named
230 .IR P ,
231 or any inferior of
232 .I S
233 has a direct property named
234 .IR P .
235 .PP
236 If
237 .I S
238 has an effective property named
239 .I P
240 then
241 .IR P 's
242 .I defining set
243 consists of those sections out of
244 .I S
245 and its inferiors
246 which have a direct property named
247 .IR P .
248 The
249 .I reduced defining set
250 for
251 .I P
252 consists of those sections in the
253 .I defining set
254 of
255 .I P
256 which have no superiors in the defining set.
257 .PP
258 If all of the sections in the reduced defining set for
259 .I P
260 assign the same value to
261 .I P
262 then that is the
263 .I effective value
264 for
265 .I P
266 in
267 .IR S ;
268 otherwise the configuration is erroneous.
269 .PP
270 Note that, 
271 according to these rules,
272 if
273 .I S
274 has a direct property
275 .I P
276 then
277 .I S
278 has an effective property
279 .I P
280 with the same value.
281 .SS Output
282 The
283 .B extract-profile
284 program's output consists of assignments
285 .IB name = value
286 for the effective properties of the named
287 .IR section ,
288 one per line,
289 in an arbitrary order.
290 .SH AUTHOR
291 Mark Wooding, <mdw@distorted.org.uk>
292 .SH SEE ALSO
293 .BR distorted-keys (7).