summaryrefslogtreecommitdiff
path: root/support/albatross
diff options
context:
space:
mode:
Diffstat (limited to 'support/albatross')
-rw-r--r--support/albatross/README.md57
-rw-r--r--support/albatross/doc/albatross-manual.pdfbin80161 -> 86396 bytes
-rw-r--r--support/albatross/doc/albatross-manual.tex140
-rw-r--r--support/albatross/doc/albatross.14
-rw-r--r--support/albatross/doc/version.tex2
5 files changed, 172 insertions, 31 deletions
diff --git a/support/albatross/README.md b/support/albatross/README.md
index 1f00d4325f..9d7a3bac2c 100644
--- a/support/albatross/README.md
+++ b/support/albatross/README.md
@@ -1,13 +1,18 @@
# Albatross
![Language: Kotlin](https://img.shields.io/badge/Language-Kotlin-blue.svg?style=flat-square)
-![Minimum JRE: 8.0](https://img.shields.io/badge/Minimum_JRE-8.0-blue.svg?style=flat-square)
+![Minimum JRE: 9](https://img.shields.io/badge/Minimum_JRE-9-blue.svg?style=flat-square)
![Current version](https://img.shields.io/badge/dynamic/json.svg?color=blue&label=Latest%20release&query=%24.0.name&url=https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%2Fprojects%2F22437260%2Frepository%2Ftags&style=flat-square)
Albatross is a command line tool for finding fonts that contain a given
(Unicode) glyph. It relies on [Fontconfig](https://www.fontconfig.org),
a library for configuring and customizing font access.
+> If you came here looking for a download option, please consider using your
+> TeX distribution (the tool comes with TeX Live and MikTeX) to install
+> Albatross. Alternatively, visit our [CTAN page](https://ctan.org/pkg/albatross)
+> for the latest release.
+
## Basic use
The tool is a typical command line application, so we need to invoke it by
@@ -27,9 +32,11 @@ Options:
-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]
+ -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
```
@@ -53,6 +60,33 @@ Albatross takes a list of glyphs as input. Three formats are supported:
`U+DF`. The `U+` prefix is mandatory. Be mindful that this notation expects
an uppercase `U`.
+It is worth noting that the tool also provides proper grapheme support. According
+to [this SO answer](https://stackoverflow.com/a/27331885) (reproduced verbatim):
+
+> A _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 `a` and `ä` are graphemes, but they may consist
+> of multiple code points (e.g. `ä` may be two code points, one for the base
+> character `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).
+
+Along these lines, in that same answer, we have a proper definition of a glyph is:
+
+> A _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 `ä` is a single code point, a font
+> may choose to render that as two separate, spatially overlaid glyphs.
+
+When providing a glyph, the tool will break it into multiple code points:
+
+```bash
+$ albatross y̆
+```
+
+Since `y̆` is composed of two code points, the tool will query all fonts that
+have both `U+79` and `U+306`.
+
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 `-o` flag (or `--or` for the long flag) to look for each glyph separately.
@@ -237,10 +271,18 @@ makes control characters to be displayed) or disable colours altogether
### Table styles
-Albatross provides 6 table styles. Include the `-b` option (or `--border-style`
+Albatross provides 7 table styles. Include the `-b` option (or `--border-style`
for the long option) followed by the corresponding border style. The following
styles are available:
+- Style 0 (basically no borders):
+
+ ```
+ Name: 3270Medium Nerd Font
+ Styles: Medium
+ ...
+ ```
+
- Style 1:
```
@@ -314,6 +356,7 @@ These are the keys to be used as option values:
| Key | Description |
|-----|-----------------------------------|
+| `0` | Style 0 (no borders) |
| `1` | Style 1 (ASCII) |
| `2` | Style 2 (rounded corners) |
| `3` | Style 3 (blank) |
@@ -321,6 +364,14 @@ These are the keys to be used as option values:
| `5` | Style 5 (square corners, default) |
| `6` | Style 6 (heavy lines) |
+### TeX fonts
+
+Albatross can include fonts from the TeX tree in the query via the `t` option
+(or `--include-tex-fonts` for the long option). Please note that the font indexing
+might take a while for the first time. For subsequent calls, the tool will use a
+cache instead. To clear this cache, use the `-c` option (or `--clear-cache` for the
+long option).
+
## License
This application is licensed under the
diff --git a/support/albatross/doc/albatross-manual.pdf b/support/albatross/doc/albatross-manual.pdf
index 8f69bd48d2..2230ac6664 100644
--- a/support/albatross/doc/albatross-manual.pdf
+++ b/support/albatross/doc/albatross-manual.pdf
Binary files differ
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
diff --git a/support/albatross/doc/albatross.1 b/support/albatross/doc/albatross.1
index bc866cc693..4a7b32397a 100644
--- a/support/albatross/doc/albatross.1
+++ b/support/albatross/doc/albatross.1
@@ -1,4 +1,4 @@
-.TH ALBATROSS 1 "27 November 2021" "v0.4.0"
+.TH ALBATROSS 1 "27 January 2023" "v0.5.0"
.
.SH NAME
albatross \- a tool for finding fonts that contain a given (Unicode) glyph.
@@ -38,7 +38,7 @@ Show available font styles
Show a detailed font list
.IP "\fB--ansi-level\fP [n|a16|a256|tc]"
Set the default ANSI level
-.IP "\fB--border-style\fP [1|2|3|4|5|6]"
+.IP "\fB--border-style\fP [0|1|2|3|4|5|6]"
Set the border style
.IP \fB--or\fP
Look for each glyph separately
diff --git a/support/albatross/doc/version.tex b/support/albatross/doc/version.tex
index 60a2d3e96c..79a2734bbf 100644
--- a/support/albatross/doc/version.tex
+++ b/support/albatross/doc/version.tex
@@ -1 +1 @@
-0.4.0 \ No newline at end of file
+0.5.0 \ No newline at end of file