summaryrefslogtreecommitdiff
path: root/support/albatross/doc/albatross-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/albatross/doc/albatross-manual.tex')
-rw-r--r--support/albatross/doc/albatross-manual.tex140
1 files changed, 115 insertions, 25 deletions
diff --git a/support/albatross/doc/albatross-manual.tex b/support/albatross/doc/albatross-manual.tex
index 1a3c2c5b21..e15d1d1ce7 100644
--- a/support/albatross/doc/albatross-manual.tex
+++ b/support/albatross/doc/albatross-manual.tex
@@ -16,6 +16,7 @@
\usepackage{etoolbox}
\usepackage{fancyvrb}
\usepackage{booktabs}
+\usepackage{hyperref}
\newcommand{\albatross}{Albatross}
\newcommand{\command}[1]{{\ttfamily#1}}
@@ -56,7 +57,7 @@ virtual machine to run.
\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
+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
@@ -75,24 +76,26 @@ 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
+\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
@@ -139,6 +142,41 @@ Be mindful that this notation expects an uppercase \glyph{U}.
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
@@ -365,11 +403,22 @@ might need to either adjust the terminal pager accordingly (e.g, \command{less
\section{Table styles}
\label{sec:tablestyles}
-\albatross\ provides 6 table styles. Include the \shortopt{b} option (or
+\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]
@@ -447,6 +496,7 @@ These are the keys to be used as option values:
\toprule
Key & Description\\
\midrule
+0 & Style 0 (no borders)\\
1 & Style 1 (ASCII)\\
2 & Style 2 (rounded corners)\\
3 & Style 3 (blank)\\
@@ -456,10 +506,20 @@ Key & Description\\
\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{Course you don't get bloody wafers with it. Albatross!}{\textsc{Monty
-Python}}
+\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
@@ -468,9 +528,39 @@ Source Initiative.
\chapter*{Changelog}
-\epigraph{How much is it?}{\textsc{Monty Python}}
+\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}
-\section*{0.4.0 (current)}
+\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
@@ -513,7 +603,7 @@ displayed incorrectly.
\chapter*{The team}
-\epigraph{Ninepence.}{\textsc{Monty Python}}
+\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