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