1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
|
% arara: lualatex
% arara: lualatex
% arara: clean: { extensions: [ aux, log, gz ] }
\documentclass[12pt,article,a4paper,oneside]{memoir}
\usepackage{fontspec}
\setmainfont{DejaVu Serif}
\setmonofont{DejaVu Sans Mono}
\setlrmarginsandblock{2.5cm}{2.5cm}{*}
\setulmarginsandblock{2.5cm}{*}{1}
\checkandfixthelayout
\usepackage[english]{babel}
\usepackage{enumitem}
\usepackage{etoolbox}
\usepackage{fancyvrb}
\usepackage{booktabs}
\newcommand{\albatross}{Albatross}
\newcommand{\command}[1]{{\ttfamily#1}}
\newcommand{\glyph}[1]{{\ttfamily#1}}
\newcommand{\hex}[1]{{\ttfamily0x#1}}
\newcommand{\uno}[1]{{\ttfamily U+#1}}
\newcommand{\val}[1]{{\ttfamily#1}}
\newcommand{\shortopt}[1]{{\ttfamily-#1}}
\newcommand{\longopt}[1]{{\ttfamily{-}{-}#1}}
\newcommand{\albatrossversion}{%
\InputIfFileExists{version.tex}{}{undefined}}
\renewcommand\maketitlehooka{{\centering
\em What flavour is it?\par}}
\title{A gentle introduction to \albatross}
\author{Island of \TeX}
\date{Version \albatrossversion\ -- \today}
\begin{document}
\maketitle
\chapter{Introduction}
\label{chap:introduction}
\epigraph{Albatross! Albatross! Albatross!}{\textsc{Monty Python}}
\albatross\ is a command line tool for finding fonts that contain a given
Unicode glyph. It relies on Fontconfig, a library for configuring and
customizing font access. The tool is written in Kotlin and requires a Java
virtual machine to run.
\chapter{Requirements}
\label{chap:requirements}
\epigraph{Two choc-ices please.}{\textsc{Monty Python}}
\albatross\ has two hard requirements: a Java virtual machine (at least version
8.0, from any vendor) and the \command{fc-list} tool provided by the Fontconfig
library, available in the system path. Linux and MacOS are known to have this
library. For Windows, note that the \TeX~Live distribution contains Fontconfig
tools. It is also highly recommended to use a terminal with Unicode support, as
\albatross\ will try to render the given glyphs.
\newpage
\chapter{Basic use}
\label{chap:basicuse}
\epigraph{I haven't got choc-ices. I only got the albatross.
Albatross!}{\textsc{Monty Python}}
The tool is a typical command line application, so we need to invoke it by
typing \command{albatross} in the terminal:
\bigskip
\begin{Verbatim}[frame=single, fontsize=\small, framesep=5mm]
__ __ __
.---.-.| | |--.---.-.| |_.----.-----.-----.-----.
| _ || | _ | _ || _| _| _ |__ --|__ --|
|___._||__|_____|___._||____|__| |_____|_____|_____|
Usage: albatross [OPTIONS] glyphs...
Options:
-s, --show-styles Show available font styles
-d, --detailed Show a detailed font list
-a, --ansi-level [n|a16|a256|tc]
Set the default ANSI level
-b, --border-style [1|2|3|4|5|6]
Set the border style
-o, --or Look for each glyph separately
-V, --version Show the version and exit
-h, --help Show this message and exit
\end{Verbatim}
\bigskip
Provided that \albatross\ is properly available in the underlying operating
system, we will get the help message listing all the available options and the
tool usage.
\section{Glyphs}
\label{sec:glyphs}
\epigraph{What flavour is it?}{\textsc{Monty Python}}
\albatross\ takes a list of glyphs, separated by spaces, as input. Three formats
are supported by the command line tool:
\begin{itemize}[label={--}]
\item The glyph itself, e.g, \glyph{ß} (Eszett). Internally, the tool will
convert it to the corresponding Unicode code point.
\begin{Verbatim}[frame=single, fontsize=\small, framesep=3.5mm]
$ albatross ß
\end{Verbatim}
\item The glyph as a Unicode code point in the hexadecimal notation, e.g,
\hex{DF}. The \hex{} prefix is mandatory.
\begin{Verbatim}[frame=single, fontsize=\small, framesep=3.5mm]
$ albatross 0xDF
\end{Verbatim}
Note that the tool takes the value as case insensitive, e.g, \hex{DF} is equal
to \hex{df} (or any case combination thereof).
\item The glyph as a Unicode code point using the multiset union notation, e.g,
\uno{DF}. The \uno{} prefix is mandatory.
\begin{Verbatim}[frame=single, fontsize=\small, framesep=3.5mm]
$ albatross U+DF
\end{Verbatim}
Be mindful that this notation expects an uppercase \glyph{U}.
\end{itemize}
Formats can be used interchangeably.
When a list of glyphs is provided, the tool will take a conjunctive approach and
look for fonts that contain all elements in such list (default behaviour). Use
the \shortopt{o} flag (or \longopt{or} for the long flag) to look for each glyph
separately. For instance:
\begin{itemize}[label={--}]
\item Look for fonts that contain both \glyph{a} and \glyph{b}:
\begin{Verbatim}[frame=single, fontsize=\small, framesep=3.5mm]
$ albatross a b
\end{Verbatim}
\item Look for fonts that contain \glyph{a} and fonts that contain \glyph{b},
separately:
\begin{Verbatim}[frame=single, fontsize=\small, framesep=3.5mm]
$ albatross --or a b
\end{Verbatim}
\end{itemize}
\section{Output}
\label{sec:output}
\epigraph{It's a bird, innit? It's a bloody sea bird\ldots\ it's not any bloody
flavour. Albatross!}{\textsc{Monty Python}}
\albatross\ prints the results as a table. The default behaviour is to just
display the font names, e.g,
\bigskip
\begin{Verbatim}[fontsize=\scriptsize]
Unicode code point DF mapping to ß
┌─────────────────────────────────────────────────────────────────────────────┐
│ Font name │
├─────────────────────────────────────────────────────────────────────────────┤
│ 3270Medium Nerd Font │
├─────────────────────────────────────────────────────────────────────────────┤
│ 3270Medium Nerd Font Mono │
├─────────────────────────────────────────────────────────────────────────────┤
...
├─────────────────────────────────────────────────────────────────────────────┤
│ Zilla Slab,Zilla Slab Medium │
├─────────────────────────────────────────────────────────────────────────────┤
│ Zilla Slab,Zilla Slab SemiBold │
└─────────────────────────────────────────────────────────────────────────────┘
\end{Verbatim}
\bigskip
There is a \shortopt{s} option (or \longopt{show-styles} for the long option)
that includes the styles available for each font, e.g,
\bigskip
\begin{Verbatim}[fontsize=\scriptsize]
Unicode code point DF mapping to ß
┌───────────────────────────────┬─────────────────────────────────────────────┐
│ Font name │ Available styles │
├───────────────────────────────┼─────────────────────────────────────────────┤
│ 3270Medium Nerd Font │ Medium │
├───────────────────────────────┼─────────────────────────────────────────────┤
│ 3270Medium Nerd Font Mono │ Medium │
├───────────────────────────────┼─────────────────────────────────────────────┤
...
├───────────────────────────────┼─────────────────────────────────────────────┤
│ Zilla Slab,Zilla Slab Medium │ Medium Italic, Italic, Medium, Regular │
├───────────────────────────────┼─────────────────────────────────────────────┤
│ Zilla Slab,Zilla Slab │ SemiBold, Regular, SemiBold Italic, Italic │
│ SemiBold │ │
└───────────────────────────────┴─────────────────────────────────────────────┘
\end{Verbatim}
\bigskip
For even more details, including the font type and paths, there is the
\shortopt{d} option (or \longopt{detailed} for the long option), e.g,
\bigskip
\begin{Verbatim}[fontsize=\scriptsize]
Unicode code point DF, font details, mapping to ß
┌──────────┬──────────────────────────────────────────────────────────────────┐
│ Name │ 3270Medium Nerd Font │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Type │ OpenType Font │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Files │ /home/paulo/.local/share/fonts/NerdFonts/3270-Medium Nerd Font │
│ │ Complete.otf │
└──────────┴──────────────────────────────────────────────────────────────────┘
Unicode code point DF, font details, mapping to ß
┌──────────┬──────────────────────────────────────────────────────────────────┐
│ Name │ 3270Medium Nerd Font Mono │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Type │ OpenType Font │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Files │ /home/paulo/.local/share/fonts/NerdFonts/3270-Medium Nerd Font │
│ │ Complete Mono.otf │
└──────────┴──────────────────────────────────────────────────────────────────┘
...
Unicode code point DF, font details, mapping to ß
┌──────────┬──────────────────────────────────────────────────────────────────┐
│ Name │ Zilla Slab,Zilla Slab Medium │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Type │ OpenType Font │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Files │ /usr/share/fonts/mozilla-zilla-slab/ZillaSlab-MediumItalic.otf │
│ │ ──────────────────────────────────────────────────────────────── │
│ │ /usr/share/fonts/mozilla-zilla-slab/ZillaSlab-Medium.otf │
└──────────┴──────────────────────────────────────────────────────────────────┘
Unicode code point DF, font details, mapping to ß
┌──────────┬──────────────────────────────────────────────────────────────────┐
│ Name │ Zilla Slab,Zilla Slab SemiBold │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Type │ OpenType Font │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Files │ /usr/share/fonts/mozilla-zilla-slab/ZillaSlab-SemiBold.otf │
│ │ ──────────────────────────────────────────────────────────────── │
│ │ /usr/share/fonts/mozilla-zilla-slab/ZillaSlab-SemiBoldItalic.… │
└──────────┴──────────────────────────────────────────────────────────────────┘
\end{Verbatim}
\medskip
For more verbosity, \longopt{detailed} can be combined with
\longopt{show-styles} to include all font details, e.g,
\medskip
\begin{Verbatim}[fontsize=\scriptsize]
Unicode code point DF, font details, mapping to ß
┌──────────┬──────────────────────────────────────────────────────────────────┐
│ Name │ 3270Medium Nerd Font │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Type │ OpenType Font │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Files │ /home/paulo/.local/share/fonts/NerdFonts/3270-Medium Nerd Font │
│ │ Complete.otf │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Styles │ Medium │
└──────────┴──────────────────────────────────────────────────────────────────┘
Unicode code point DF, font details, mapping to ß
┌──────────┬──────────────────────────────────────────────────────────────────┐
│ Name │ 3270Medium Nerd Font Mono │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Type │ OpenType Font │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Files │ /home/paulo/.local/share/fonts/NerdFonts/3270-Medium Nerd Font │
│ │ Complete Mono.otf │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Styles │ Medium │
└──────────┴──────────────────────────────────────────────────────────────────┘
...
Unicode code point DF, font details, mapping to ß
┌──────────┬──────────────────────────────────────────────────────────────────┐
│ Name │ Zilla Slab,Zilla Slab Medium │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Type │ OpenType Font │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Files │ /usr/share/fonts/mozilla-zilla-slab/ZillaSlab-MediumItalic.otf │
│ │ ──────────────────────────────────────────────────────────────── │
│ │ /usr/share/fonts/mozilla-zilla-slab/ZillaSlab-Medium.otf │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Styles │ Medium Italic, Italic, Medium, Regular │
└──────────┴──────────────────────────────────────────────────────────────────┘
Unicode code point DF, font details, mapping to ß
┌──────────┬──────────────────────────────────────────────────────────────────┐
│ Name │ Zilla Slab,Zilla Slab SemiBold │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Type │ OpenType Font │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Files │ /usr/share/fonts/mozilla-zilla-slab/ZillaSlab-SemiBold.otf │
│ │ ──────────────────────────────────────────────────────────────── │
│ │ /usr/share/fonts/mozilla-zilla-slab/ZillaSlab-SemiBoldItalic.… │
├──────────┼──────────────────────────────────────────────────────────────────┤
│ Styles │ SemiBold, Regular, SemiBold Italic, Italic │
└──────────┴──────────────────────────────────────────────────────────────────┘
\end{Verbatim}
\bigskip
Since the results can span several rows (the more common the glyph, the more
fonts will contain it), we strongly recommend using a pipeline and pass the
results to a terminal pager, e.g, the \command{less} utility:
\bigskip
\begin{Verbatim}[frame=single, fontsize=\small, framesep=3.5mm]
$ albatross ß | less
\end{Verbatim}
\section{Coloured output}
\label{sec:colouredoutput}
\epigraph{Do you get wafers with it?}{\textsc{Monty Python}}
\albatross\ supports terminal colours by including the \shortopt{a} option (or
\longopt{ansi-level} for the long option) followed by the corresponding colour
level. The following levels are available:
\bigskip
\bigskip
{\centering
\begin{tabular}{@{}ll@{}}
\toprule
Level & Description\\
\midrule
\val{n} & No colours at all (default)\\
\val{a16} & ANSI 16 colours\\
\val{a256} & ANSI 256 colours\\
\val{tc} & Support for true colours\\
\bottomrule
\end{tabular}\par}
\bigskip
\bigskip
Note that colours might mess the output when passed to a terminal pager. You
might need to either adjust the terminal pager accordingly (e.g, \command{less
-r} makes control characters to be displayed) or disable colours altogether
(which is the default behaviour).
\section{Table styles}
\label{sec:tablestyles}
\albatross\ provides 6 table styles. Include the \shortopt{b} option (or
\longopt{border-style} for the long option) followed by the corresponding border
style. The following styles are available:
\begin{itemize}[label={--}]
\item Style 1:
\begin{Verbatim}[fontsize=\scriptsize]
+-------------------------------+-----------------------------------------+
| Font name | Available styles |
+-------------------------------+-----------------------------------------+
| 3270Medium Nerd Font | Medium |
+-------------------------------+-----------------------------------------+
...
\end{Verbatim}
\item Style 2:
\begin{Verbatim}[fontsize=\scriptsize]
╭─────────────────────────────────────────────────────────────────────────╮
│ Font name │
├─────────────────────────────────────────────────────────────────────────┤
│ 3270Medium Nerd Font │
├─────────────────────────────────────────────────────────────────────────┤
...
\end{Verbatim}
\item Style 3:
\begin{Verbatim}[fontsize=\scriptsize]
Font name Available styles
3270Medium Nerd Font Medium
...
\end{Verbatim}
\item Style 4:
\begin{Verbatim}[fontsize=\scriptsize]
╔═══════════════════════════════╦═════════════════════════════════════════╗
║ Font name ║ Available styles ║
╠═══════════════════════════════╬═════════════════════════════════════════╣
║ 3270Medium Nerd Font ║ Medium ║
╠═══════════════════════════════╬═════════════════════════════════════════╣
...
\end{Verbatim}
\item Style 5:
\begin{Verbatim}[fontsize=\scriptsize]
┌───────────────────────────────┬─────────────────────────────────────────┐
│ Font name │ Available styles │
├───────────────────────────────┼─────────────────────────────────────────┤
│ 3270Medium Nerd Font │ Medium │
├───────────────────────────────┼─────────────────────────────────────────┤
...
\end{Verbatim}
\item Style 6:
\begin{Verbatim}[fontsize=\scriptsize]
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Font name ┃ Available styles ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ 3270Medium Nerd Font ┃ Medium ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
...
\end{Verbatim}
\end{itemize}
These are the keys to be used as option values:
\bigskip
\bigskip
{\centering
\begin{tabular}{@{}ll@{}}
\toprule
Key & Description\\
\midrule
1 & Style 1 (ASCII)\\
2 & Style 2 (rounded corners)\\
3 & Style 3 (blank)\\
4 & Style 4 (double lines)\\
5 & Style 5 (square corners, default)\\
6 & Style 6 (heavy lines)\\
\bottomrule
\end{tabular}\par}
\chapter*{License}
\epigraph{Course you don't get bloody wafers with it. Albatross!}{\textsc{Monty
Python}}
\albatross\ is licensed under the New BSD License. Please note that the New BSD
License has been verified as a GPL-compatible free software license by the Free
Software Foundation, and has been vetted as an open source license by the Open
Source Initiative.
\chapter*{Changelog}
\epigraph{How much is it?}{\textsc{Monty Python}}
\section*{0.4.0 (current)}
\begin{itemize}[label={--}]
\item Included support for the Unicode code point using the \uno{} multiset union
notation, which behaves exactly the same as the \hex{} counterpart. So \glyph{ß},
\hex{DF} and \uno{DF} denote the same Unicode entity.
\end{itemize}
\section*{0.3.0 (2021-01-13)}
\subsection*{Changed}
\begin{itemize}[label={--}]
\item Conjunctive behavior is now default. Previously, \command{albatross a b}
would have looked for fonts for \glyph{a} and separately for fonts for \glyph{b}.
As we see more use cases for looking for fonts that contain \glyph{a} as well as
\glyph{b}, we changed the default and left the previous behavior as
\command{albatross --or a b}.
\end{itemize}
\section*{0.2.0 (2020-12-09)}
\subsection*{Added}
\begin{itemize}[label={--}]
\item Inclusion of a man page.
\end{itemize}
\subsection*{Fixed}
\begin{itemize}[label={--}]
\item Windows paths were incorrectly parsed, causing font names and styles to be
displayed incorrectly.
\end{itemize}
\section*{0.1.0 (2020-12-07)}
\begin{itemize}[label={--}]
\item Initial release.
\end{itemize}
\chapter*{The team}
\epigraph{Ninepence.}{\textsc{Monty Python}}
\albatross\ is brought to you by the Island of \TeX. If you want to support
\TeX\ development by a donation, the best way to do this is donating to the
\TeX\ Users Group.
\vfill
{\centering\footnotesize\em No albatrosses were harmed during the making of this
user manual.\par}
\end{document}
|
