From 261f52e7813eade06f278eda62023fda3d266980 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sat, 28 Jan 2023 03:02:00 +0000 Subject: CTAN sync 202301280301 --- support/albatross/README.md | 57 +++++++++++- support/albatross/doc/albatross-manual.pdf | Bin 80161 -> 86396 bytes support/albatross/doc/albatross-manual.tex | 140 +++++++++++++++++++++++------ support/albatross/doc/albatross.1 | 4 +- support/albatross/doc/version.tex | 2 +- 5 files changed, 172 insertions(+), 31 deletions(-) (limited to 'support/albatross') 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 Binary files a/support/albatross/doc/albatross-manual.pdf and b/support/albatross/doc/albatross-manual.pdf 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 -- cgit v1.2.3