experimental old/new eatmydata support switch
[shellsnippets/shellsnippets.git] / mksh / bdfctool.1
1 .\" $MirOS: X11/extras/bdfctool/bdfctool.1,v 1.10 2013/05/17 21:51:40 tg Exp $
2 .\"-
3 .\" Copyright © 2012, 2013
4 .\"     Thorsten “mirabilos” Glaser <tg@mirbsd.org>
5 .\"-
6 .\" Try to make GNU groff and AT&T nroff more compatible
7 .\" * ` generates ‘ in gnroff, so use \`
8 .\" * ' generates ’ in gnroff, \' generates ´, so use \*(aq
9 .\" * - generates ‐ in gnroff, \- generates −, so .tr it to -
10 .\"   thus use - for hyphens and \- for minus signs and option dashes
11 .\" * ~ is size-reduced and placed atop in groff, so use \*(TI
12 .\" * ^ is size-reduced and placed atop in groff, so use \*(ha
13 .\" * \(en does not work in nroff, so use \*(en
14 .\" * <>| are problematic, so redefine and use \*(Lt\*(Gt\*(Ba
15 .\" Also make sure to use \& especially with two-letter words.
16 .\" The section after the "doc" macropackage has been loaded contains
17 .\" additional code to convene between the UCB mdoc macropackage (and
18 .\" its variant as BSD mdoc in groff) and the GNU mdoc macropackage.
19 .\"
20 .ie \n(.g \{\
21 .       if \ 1\*[.T]\ 1ascii\ 1 .tr \-\N'45'
22 .       if \ 1\*[.T]\ 1latin1\ 1 .tr \-\N'45'
23 .       if \ 1\*[.T]\ 1utf8\ 1 .tr \-\N'45'
24 .       ds <= \[<=]
25 .       ds >= \[>=]
26 .       ds Rq \[rq]
27 .       ds Lq \[lq]
28 .       ds sL \(aq
29 .       ds sR \(aq
30 .       if \ 1\*[.T]\ 1utf8\ 1 .ds sL `
31 .       if \ 1\*[.T]\ 1ps\ 1 .ds sL `
32 .       if \ 1\*[.T]\ 1utf8\ 1 .ds sR '
33 .       if \ 1\*[.T]\ 1ps\ 1 .ds sR '
34 .       ds aq \(aq
35 .       ds TI \(ti
36 .       ds ha \(ha
37 .       ds en \(en
38 .\}
39 .el \{\
40 .       ds aq '
41 .       ds TI ~
42 .       ds ha ^
43 .       ds en \(em
44 .\}
45 .\"
46 .\" Implement .Dd with the Mdocdate RCS keyword
47 .\"
48 .rn Dd xD
49 .de Dd
50 .ie \a\\$1\a$Mdocdate:\a \{\
51 .       xD \\$2 \\$3, \\$4
52 .\}
53 .el .xD \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8
54 ..
55 .\"
56 .\" .Dd must come before definition of .Mx, because when called
57 .\" with -mandoc, it might implement .Mx itself, but we want to
58 .\" use our own definition. And .Dd must come *first*, always.
59 .\"
60 .Dd $Mdocdate: May 17 2013 $
61 .\"
62 .\" Check which macro package we use, and do other -mdoc setup.
63 .\"
64 .ie \n(.g \{\
65 .       if \ 1\*[.T]\ 1utf8\ 1 .tr \[la]\*(Lt
66 .       if \ 1\*[.T]\ 1utf8\ 1 .tr \[ra]\*(Gt
67 .       ie d volume-ds-1 .ds tT gnu
68 .       el .ds tT bsd
69 .\}
70 .el .ds tT ucb
71 .\"
72 .\" Implement .Mx (MirBSD)
73 .\"
74 .ie "\*(tT"gnu" \{\
75 .       eo
76 .       de Mx
77 .       nr curr-font \n[.f]
78 .       nr curr-size \n[.ps]
79 .       ds str-Mx \f[\n[curr-font]]\s[\n[curr-size]u]
80 .       ds str-Mx1 \*[Tn-font-size]\%MirOS\*[str-Mx]
81 .       if !\n[arg-limit] \
82 .       if \n[.$] \{\
83 .       ds macro-name Mx
84 .       parse-args \$@
85 .       \}
86 .       if (\n[arg-limit] > \n[arg-ptr]) \{\
87 .       nr arg-ptr +1
88 .       ie (\n[type\n[arg-ptr]] == 2) \
89 .       as str-Mx1 \~\*[arg\n[arg-ptr]]
90 .       el \
91 .       nr arg-ptr -1
92 .       \}
93 .       ds arg\n[arg-ptr] "\*[str-Mx1]
94 .       nr type\n[arg-ptr] 2
95 .       ds space\n[arg-ptr] "\*[space]
96 .       nr num-args (\n[arg-limit] - \n[arg-ptr])
97 .       nr arg-limit \n[arg-ptr]
98 .       if \n[num-args] \
99 .       parse-space-vector
100 .       print-recursive
101 ..
102 .       ec
103 .       ds sP \s0
104 .       ds tN \*[Tn-font-size]
105 .\}
106 .el \{\
107 .       de Mx
108 .       nr cF \\n(.f
109 .       nr cZ \\n(.s
110 .       ds aa \&\f\\n(cF\s\\n(cZ
111 .       if \\n(aC==0 \{\
112 .               ie \\n(.$==0 \&MirOS\\*(aa
113 .               el .aV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
114 .       \}
115 .       if \\n(aC>\\n(aP \{\
116 .               nr aP \\n(aP+1
117 .               ie \\n(C\\n(aP==2 \{\
118 .                       as b1 \&MirOS\ #\&\\*(A\\n(aP\\*(aa
119 .                       ie \\n(aC>\\n(aP \{\
120 .                               nr aP \\n(aP+1
121 .                               nR
122 .                       \}
123 .                       el .aZ
124 .               \}
125 .               el \{\
126 .                       as b1 \&MirOS\\*(aa
127 .                       nR
128 .               \}
129 .       \}
130 ..
131 .\}
132 .\"-
133 .Dt BDFCTOOL 1
134 .Os MirBSD
135 .Sh NAME
136 .Nm bdfctool
137 .Nd convert BDF and bdfc font files
138 .Sh SYNOPSIS
139 .Nm
140 .Fl c
141 .Nm
142 .Fl d
143 .Op Fl F
144 .Nm
145 .Fl e
146 .Op Fl a
147 .Nm
148 .Ic +e
149 .Sh DESCRIPTION
150 The
151 .Nm
152 utility converts (mostly) fixed-width bitmap fonts between the
153 .Tn BDF
154 file format as used by
155 .Tn XFree86\(rg
156 and the
157 .Ic bdfc
158 format as specified below.
159 It operates as a filter, i.e. takes its input from the standard
160 input stream and writes data to standard output.
161 .Pp
162 The options are as follows:
163 .Bl -tag -width XXX
164 .It Fl a
165 In edit mode, emit ASCII (1:2) encoding for an unset bit
166 .Pq Sq Li \&. ,
167 a set bit
168 .Pq Sq Li \&#
169 and the line end separator
170 .Pq Sq Li \&\*(Ba .
171 .It Ic +a
172 In edit mode, emit Unicode (1:1) encoding (default).
173 .It Fl d
174 Decompress the font from bdfc into
175 .Tn BDF .
176 .It Fl c
177 Compress the font from
178 .Tn BDF
179 or the bdfc edit form to bdfc, also sorting and weeding out
180 any duplicates (later occurrence wins).
181 .It Fl e
182 Expand selected glyphs inside the bdfc file into the edit form,
183 which uses U+3000 and U+4DC0 to represent unset and set bits,
184 respectively, so they can be visually edited.
185 This mode operates on glyphs and does not need to be passed the
186 whole file, e.g. using \*(haK/ in the jupp text editor.
187 .It Ic +e
188 Revert selected glyphs from edit form back to compressed form
189 .Pq without whole-file validation .
190 .It Fl F
191 Do a fast decompression with no error checking.
192 Run this on files passed through
193 .Nm
194 .Fl c
195 .Em only .
196 Used by the
197 .Mx
198 .Tn XFree86\(rg
199 build process.
200 .El
201 .Sh BDFC FORMAT DESCRIPTION
202 A
203 .Ic \&.bdfc
204 file is a compressed, editable representation of a subset of the
205 .Ic Bitmap Distribution Format Pq BDF
206 as used for fixed-width fonts in the
207 .Tn XFree86\(rg
208 windowing system.
209 .Pp
210 Every file starts with a line consisting of
211 .Dq Li "=bdfc 1" ,
212 where
213 .Ql \&1
214 is the version number.
215 The format is line-oriented and only somewhat stateful.
216 It is optimised for being operated on using the jupp text editor and
217 .Nm mksh
218 shell scripts.
219 Lines starting with an apostrophe U+0027 and a space U+0020, or
220 consisting of only an apostrophe before the newline, can be
221 used anywhere inside the file, except within the trailing-data lines
222 of an edit block (see below), to denote a comment, which is retained
223 (tacked on to the following character).
224 .Pp
225 Next comes a block of font header information that are just
226 passed through, prefixed with a
227 .Dq Li h .
228 After that, list the font properties, prefixed with a
229 .Dq Li p
230 each, and followed by a
231 .Dq Li C
232 on a line by itself, which will deal with emitting the
233 .Li STARTPROPERTIES
234 number, the properties and
235 .Li ENDPROPERTIES
236 and marks the place where
237 .Li CHARS
238 is put in
239 .Tn BDF .
240 .Pp
241 Finally, there is the character block, which is somewhat stateless.
242 There are two types of entries for that block, glyph defaults and glyph data.
243 The block is ended with a period
244 .Pq Dq Li .\&
245 on a line by itself.
246 .Pp
247 Glyphs are sorted by their font encoding / Unicode code point, and each
248 glyph occurs only once, although the
249 .Nm
250 tool in the
251 .Fl c
252 operation mode is able to take glyphs in any order and weed out duplicates.
253 The character name can be omitted if it matches the form
254 .Dq Li uni Ns Ar 20AC
255 where
256 .Dq Ar 20AC
257 is the four-nibble uppercase Unicode codepoint of the glyph, in this
258 example the Euro sign.
259 .Pp
260 Glyph defaults are lines in the format
261 .Dl d 540 0 9 0 0 \-4
262 where the first
263 .Dq Li d
264 is the line type, and the next values are, in order, the arguments to the
265 .Li SWIDTH
266 and
267 .Li DWIDTH
268 and the third and fourth argument to the
269 .Li BBX
270 .Tn BDF
271 commands.
272 (The first and second arguments of
273 .Li BBX
274 are derived from the glyph data line instead.)
275 .Pp
276 The glyph defaults are used in encoding every subsequent glyph for
277 .Tn BDF
278 and are valid until the next glyph default line, which means that
279 a character block must start with one, and that sorting may need
280 to duplicate or move such lines, as handled by
281 .Nm
282 .Fl c .
283 .Pp
284 Finally, let's talk about the glyph data lines.
285 The standard (condensed) form looks like
286 .Dl c 0020 6 00:00:00:00:00:00:00:00 space
287 which are, in this order, the type of the line, the encoding of
288 the glyph, the width (in bit) of the glyph (first argument of
289 .Li BBX ) ,
290 the glyph data (in whole bytes, uppercase nibbles, as in
291 .Tn BDF ,
292 but colon-separated; the number of which yields the second argument to
293 .Li BBX )
294 and the glyph name (which, as explained above, is optional)
295 consisting of up to 14 alphanumeric characters.
296 .Pp
297 The editing form is a multi-line form and
298 .Em must not
299 be used in persistent storage, revision control or transmission.
300 Its first line looks like
301 .Dl e 0020 6 8 space
302 which is basically the same as the standard form, except that the
303 number of lines replaces the bitmap data.
304 This is followed by (in this case eight) lines that comprise of
305 (in this case six) occurrences of either U+3000 (to denote an unset
306 pixel) or U+4DC0 (to denote a set pixel), followed by U+258C (to
307 denote, as a visual help, the next character).
308 The compression script also accepts a dot U+002E or a space U+0020
309 as null-bit, a hash U+0023 or an asterisk U+002A as set bit, and a
310 pipe sign / bar U+007C as line end marker.
311 You should use the regular form if your display font has an 1:2
312 ratio (e.g. 8x16, 9x18) and the alternative form if it has an 1:1
313 ratio (e.g. 8x8 pixels), and switch fonts if it has a different
314 ratio altogether.
315 .Pp
316 The trailing dot does not denote the end of file for the
317 .Fl c
318 operation, as it can handle concatenated files, but is used
319 to have an easy way to switch between the file and glyph sections,
320 since the former does not use a structured line format.
321 .Sh RETURN VALUES
322 The
323 .Nm
324 utility exits with one of the following values:
325 .Pp
326 .Bl -tag -width XXX -compact
327 .It Li 0
328 No error occurred.
329 .It Li 1
330 Wrong usage.
331 .It Li 2
332 An error during processing occurred, e.g. invalid input.
333 .It Li 3
334 A strict mode
335 .Pq Fl d
336 error occurred, e.g. invalid input.
337 .It Li 4
338 An error in an external program, such as
339 .Xr mktemp 1 ,
340 occurred.
341 .El
342 .Sh EXAMPLES
343 The following example should be a minimal valid font demonstrating
344 all features of the bdfc format:
345 .Bd -literal
346 =bdfc 1
347 \&' $ucs\-fonts: 4x6.bdf,v 1.5 2002\-08\-26 18:05:49+01 mgk25 Rel $
348 hFONT \-Misc\-Fixed\-Medium\-R\-Normal\-\-6\-60\-75\-75\-C\-40\-ISO10646\-1
349 hSIZE 6 75 75
350 hFONTBOUNDINGBOX 4 6 0 \-1
351 pFONT_ASCENT 5
352 pFONT_DESCENT 1
353 pDEFAULT_CHAR 0
354 C
355 d 640 0 4 0 0 \-1
356 e 0000 4 6 char0
357 #.#.\*(Ba
358 \&....\*(Ba
359 #.#.\*(Ba
360 \&....\*(Ba
361 #.#.\*(Ba
362 \&....\*(Ba
363 c 0020 4 00:00:00:00:00:00 space
364 c 018F 4 00:C0:60:A0:40:00
365 \&.
366 .Ed
367 .Sh SEE ALSO
368 .Xr bdftopcf 1 ,
369 .Xr fstobdf 1
370 .Pp
371 The
372 .Tn XFree86\(rg
373 .Ic Bitmap Distribution Format ,
374 version 2.1, specification
375 .Sh AUTHORS
376 .An Thorsten Glaser Aq tg@mirbsd.org
377 wrote this tool because
378 .Xr cvs 1
379 does not scale for multi-thousand-line files,
380 to have a one-line-per-glyph format that matches
381 .Tn BDF .
382 .Sh CAVEATS
383 .Nm
384 has its own ideas of how a
385 .Tn BDF
386 font file should look like, and if you deviate from that,
387 you might get an error; although, support for more features
388 can surely be added.
389 .Pp
390 .Dq Li ENCODING \-1
391 support is missing.
392 The glyph encoding is currently treated as the primary key;
393 values from 0000 to FFFF inclusive are valid, the zero-padding
394 is mandatory.
395 .Pp
396 The current practical limit on glyph width is 32.
397 0-bit wide glyphs cause an error; those with height 0 are
398 silently converted to an unset 1x1 bitmap.