% 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}
\usepackage{hyperref}

\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
9, 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=\scriptsize, 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 [0|1|2|3|4|5|6]
                                     Set the border style
    -o, --or                         Look for each glyph separately
    -t, --include-tex-fonts          Include fonts from the TeX tree
    -c, --clear-cache                Clear the font cache
    -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.

\bigskip

It is worth noting that \albatross\ also provides proper grapheme support. According
to \href{https://stackoverflow.com/a/27331885}{this SO answer} (reproduced verbatim):

\begin{quotation}
A \emph{grapheme} is a sequence of one or more code points that are displayed as
a single, graphical unit that a reader recognizes as a single element of the writing
system. For example, both \glyph{a} and \glyph{ä} are graphemes, but they may consist
of multiple code points (e.g. \glyph{ä} may be two code points, one for the base
character \glyph{a} followed by one for the diaeresis; but there's also an alternative,
legacy, single code point representing this grapheme). Some code points are never part
of any grapheme (e.g. the zero-width non-joiner, or directional overrides).
\end{quotation}

Along these lines, in that same answer, we have a proper definition of a glyph is:

\begin{quotation}
A \emph{glyph} is an image, usually stored in a font (which is a collection of glyphs),
used to represent graphemes or parts thereof. Fonts may compose multiple glyphs into a
single representation, for example, if the above \glyph{ä} is a single code point, a font
may choose to render that as two separate, spatially overlaid glyphs.
\end{quotation}

When providing a glyph, \albatross\ will break it into multiple code points:

\begin{Verbatim}[frame=single, fontsize=\small, framesep=3.5mm]
$ albatross y̆
\end{Verbatim}
  
Since \glyph{y̆} is composed of two code points, \albatross\ will query all fonts
that have both \hex{79} and \hex{306}.

\bigskip

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}

\epigraph{Course you don't get bloody wafers with it. Albatross!}{\textsc{Monty
Python}}

\albatross\ provides 7 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 0 (basically no borders):

\begin{Verbatim}[fontsize=\scriptsize]
Name: 3270Medium Nerd Font
Styles: Medium
...
\end{Verbatim}

\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
0 & Style 0 (no borders)\\
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}

\section{\TeX\ fonts}

\epigraph{How much is it?}{\textsc{Monty Python}}

\albatross\ can include fonts from the \TeX\ tree in the query via the
\shortopt{t} option (or \longopt{include-tex-fonts} for the long option).
Please note that the font indexing might take a while for the first time.
For subsequent calls, \albatross\ will use a cache instead. To clear this
cache, use the \shortopt{c} option (or \longopt{clear-cache} for the long
option).

\chapter*{License}

\epigraph{Ninepence.}{\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{I'll have two please.}{\textsc{Monty Python}}

\section*{0.5.0 (current)}

\subsection*{Added}

\begin{itemize}[label={--}]
\item Experimental font look up in the current \TeX\ tree has been added.

\item The new border style (none, \shortopt{b0}) hides the border of the
tables entirely.

\item Support for graphemes has been added. Note that, when searching for
multiple glyphs using the \longopt{or} modifier (disjunctive behavior),
grapheme elements always will rely on conjunctive behavior.
\end{itemize}

\subsection*{Changed}

\begin{itemize}[label={--}]
\item Table for font names (default view) has no internal borders now.

\item Bump required Java version to 9. This drops support for Java 8.
\end{itemize}

\subsection*{Fixed}

\begin{itemize}[label={--}]
\item The conjunctive behavior introduce in 0.3.0 has not been working as
intended. Now it works as documented.
\end{itemize}

\section*{0.4.0 (2021-11-22)}

\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{Gannet on a stick.}{\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}
