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