6bceeebfc3f668641fa83bc71a04afc2011657f6
[shellsnippets/shellsnippets.git] / mksh / bdfctool.1
1 .\" $MirOS: X11/extras/bdfctool/bdfctool.1,v 1.9 2012/09/01 21:15:29 tg Exp $
2 .\"-
3 .\" Copyright © 2012
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: September 1 2012 $
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 .Sh DESCRIPTION
148 The
149 .Nm
150 utility converts (mostly) fixed-width bitmap fonts between the
151 .Tn BDF
152 file format as used by
153 .Tn XFree86\(rg
154 and the
155 .Ic bdfc
156 format as specified below.
157 It operates as a filter, i.e. takes its input from the standard
158 input stream and writes data to standard output.
159 .Pp
160 The options are as follows:
161 .Bl -tag -width XXX
162 .It Fl a
163 In edit mode, emit ASCII (1:2) encoding for an unset bit
164 .Pq Sq Li \&. ,
165 a set bit
166 .Pq Sq Li \&#
167 and the line end separator
168 .Pq Sq Li \&\*(Ba .
169 .It Ic +a
170 In edit mode, emit Unicode (1:1) encoding (default).
171 .It Fl d
172 Decompress the font from bdfc into
173 .Tn BDF .
174 .It Fl c
175 Compress the font from
176 .Tn BDF
177 or the bdfc edit form to bdfc, also sorting and weeding out
178 any duplicates (later occurrence wins).
179 .It Fl e
180 Expand selected glyphs inside the bdfc file into the edit form,
181 which uses U+3000 and U+4DC0 to represent unset and set bits,
182 respectively, so they can be visually edited.
183 This mode operates on glyphs and does not need to be passed the
184 whole file, e.g. using \*(haK/ in the jupp text editor.
185 .It Fl F
186 Do a fast decompression with no error checking.
187 Run this on files passed through
188 .Nm
189 .Fl c
190 .Em only .
191 Used by the
192 .Mx
193 .Tn XFree86\(rg
194 build process.
195 .El
196 .Sh BDFC FORMAT DESCRIPTION
197 A
198 .Ic \&.bdfc
199 file is a compressed, editable representation of a subset of the
200 .Ic Bitmap Distribution Format Pq BDF
201 as used for fixed-width fonts in the
202 .Tn XFree86\(rg
203 windowing system.
204 .Pp
205 Every file starts with a line consisting of
206 .Dq Li "=bdfc 1" ,
207 where
208 .Ql \&1
209 is the version number.
210 The format is line-oriented and only somewhat stateful.
211 It is optimised for being operated on using the jupp text editor and
212 .Nm mksh
213 shell scripts.
214 Lines starting with an apostrophe U+0027 and a space U+0020, or
215 consisting of only an apostrophe before the newline, can be
216 used anywhere inside the file, except within the trailing-data lines
217 of an edit block (see below), to denote a comment, which is retained
218 (tacked on to the following character).
219 .Pp
220 Next comes a block of font header information that are just
221 passed through, prefixed with a
222 .Dq Li h .
223 After that, list the font properties, prefixed with a
224 .Dq Li p
225 each, and followed by a
226 .Dq Li C
227 on a line by itself, which will deal with emitting the
228 .Li STARTPROPERTIES
229 number, the properties and
230 .Li ENDPROPERTIES
231 and marks the place where
232 .Li CHARS
233 is put in
234 .Tn BDF .
235 .Pp
236 Finally, there is the character block, which is somewhat stateless.
237 There are two types of entries for that block, glyph defaults and glyph data.
238 The block is ended with a period
239 .Pq Dq Li .\&
240 on a line by itself.
241 .Pp
242 Glyphs are sorted by their font encoding / Unicode code point, and each
243 glyph occurs only once, although the
244 .Nm
245 tool in the
246 .Fl c
247 operation mode is able to take glyphs in any order and weed out duplicates.
248 The character name can be omitted if it matches the form
249 .Dq Li uni Ns Ar 20AC
250 where
251 .Dq Ar 20AC
252 is the four-nibble uppercase Unicode codepoint of the glyph, in this
253 example the Euro sign.
254 .Pp
255 Glyph defaults are lines in the format
256 .Dl d 540 0 9 0 0 \-4
257 where the first
258 .Dq Li d
259 is the line type, and the next values are, in order, the arguments to the
260 .Li SWIDTH
261 and
262 .Li DWIDTH
263 and the third and fourth argument to the
264 .Li BBX
265 .Tn BDF
266 commands.
267 (The first and second arguments of
268 .Li BBX
269 are derived from the glyph data line instead.)
270 .Pp
271 The glyph defaults are used in encoding every subsequent glyph for
272 .Tn BDF
273 and are valid until the next glyph default line, which means that
274 a character block must start with one, and that sorting may need
275 to duplicate or move such lines, as handled by
276 .Nm
277 .Fl c .
278 .Pp
279 Finally, let's talk about the glyph data lines.
280 The standard (condensed) form looks like
281 .Dl c 0020 6 00:00:00:00:00:00:00:00 space
282 which are, in this order, the type of the line, the encoding of
283 the glyph, the width (in bit) of the glyph (first argument of
284 .Li BBX ) ,
285 the glyph data (in whole bytes, uppercase nibbles, as in
286 .Tn BDF ,
287 but colon-separated; the number of which yields the second argument to
288 .Li BBX )
289 and the glyph name (which, as explained above, is optional)
290 consisting of up to 14 alphanumeric characters.
291 .Pp
292 The editing form is a multi-line form and
293 .Em must not
294 be used in persistent storage, revision control or transmission.
295 Its first line looks like
296 .Dl e 0020 6 8 space
297 which is basically the same as the standard form, except that the
298 number of lines replaces the bitmap data.
299 This is followed by (in this case eight) lines that comprise of
300 (in this case six) occurrences of either U+3000 (to denote an unset
301 pixel) or U+4DC0 (to denote a set pixel), followed by U+258C (to
302 denote, as a visual help, the next character).
303 The compression script also accepts a dot U+002E or a space U+0020
304 as null-bit, a hash U+0023 or an asterisk U+002A as set bit, and a
305 pipe sign / bar U+007C as line end marker.
306 You should use the regular form if your display font has an 1:2
307 ratio (e.g. 8x16, 9x18) and the alternative form if it has an 1:1
308 ratio (e.g. 8x8 pixels), and switch fonts if it has a different
309 ratio altogether.
310 .Pp
311 The trailing dot does not denote the end of file for the
312 .Fl c
313 operation, as it can handle concatenated files, but is used
314 to have an easy way to switch between the file and glyph sections,
315 since the former does not use a structured line format.
316 .Sh RETURN VALUES
317 The
318 .Nm
319 utility exits with one of the following values:
320 .Pp
321 .Bl -tag -width XXX -compact
322 .It Li 0
323 No error occurred.
324 .It Li 1
325 Wrong usage.
326 .It Li 2
327 An error during processing occurred, e.g. invalid input.
328 .It Li 3
329 A strict mode
330 .Pq Fl d
331 error occurred, e.g. invalid input.
332 .It Li 4
333 An error in an external program, such as
334 .Xr mktemp 1 ,
335 occurred.
336 .El
337 .Sh EXAMPLES
338 The following example should be a minimal valid font demonstrating
339 all features of the bdfc format:
340 .Bd -literal
341 =bdfc 1
342 \&' $ucs\-fonts: 4x6.bdf,v 1.5 2002\-08\-26 18:05:49+01 mgk25 Rel $
343 hFONT \-Misc\-Fixed\-Medium\-R\-Normal\-\-6\-60\-75\-75\-C\-40\-ISO10646\-1
344 hSIZE 6 75 75
345 hFONTBOUNDINGBOX 4 6 0 \-1
346 pFONT_ASCENT 5
347 pFONT_DESCENT 1
348 pDEFAULT_CHAR 0
349 C
350 d 640 0 4 0 0 \-1
351 e 0000 4 6 char0
352 #.#.\*(Ba
353 \&....\*(Ba
354 #.#.\*(Ba
355 \&....\*(Ba
356 #.#.\*(Ba
357 \&....\*(Ba
358 c 0020 4 00:00:00:00:00:00 space
359 c 018F 4 00:C0:60:A0:40:00
360 \&.
361 .Ed
362 .Sh SEE ALSO
363 .Xr bdftopcf 1 ,
364 .Xr fstobdf 1
365 .Pp
366 The
367 .Tn XFree86\(rg
368 .Ic Bitmap Distribution Format ,
369 version 2.1, specification
370 .Sh AUTHORS
371 .An Thorsten Glaser Aq tg@mirbsd.org
372 wrote this tool because
373 .Xr cvs 1
374 does not scale for multi-thousand-line files,
375 to have a one-line-per-glyph format that matches
376 .Tn BDF .
377 .Sh CAVEATS
378 .Nm
379 has its own ideas of how a
380 .Tn BDF
381 font file should look like, and if you deviate from that,
382 you might get an error; although, support for more features
383 can surely be added.
384 .Pp
385 .Dq Li ENCODING \-1
386 support is missing.
387 The glyph encoding is currently treated as the primary key;
388 values from 0000 to FFFF inclusive are valid, the zero-padding
389 is mandatory.
390 .Pp
391 The current practical limit on glyph width is 32.
392 0-bit wide glyphs cause an error; those with height 0 are
393 silently converted to an unset 1x1 bitmap.