fontist 1.13.2 → 1.14.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e0bff9ea15b251c5c03206705574e12cfc9fc4bc779d197d73d20a05977e745
-  data.tar.gz: 33a6538507cc014c1fd4a0b1b11fa908560ae8319e9de13d33120c02a86953b4
+  metadata.gz: 0abf896ec5729e97a87970e63ada78682dfcf659275db957a61ee7330dc0330a
+  data.tar.gz: c9318ca81a41ea2431ab31fa99c19c75ca5b37664afb2e622865ff0ad9696131
 SHA512:
-  metadata.gz: bf17d3b2dd7a687f97db3bd24200d0bd07821bab47ac0c0ce8eeb1156ec1fc95b39660dfb75e6eb13e00080968de1168c83cca7d54caee0c09139d0a167651d6
-  data.tar.gz: 18b6c0294686dcf739b2d1654b8c3e8488d823cb2de1d62659f834c7f8ca443615170d29f3f3bb2b705b27b07cb8a79d80ca6a185d09979c8c0f2f37f8af547f
+  metadata.gz: 4f2d4ccfda0cca24dd812bc4f7a2146f0a6a98ab9d8296743f9a79e67fae4b362d283862bf3b79167a90469ea8d4114bd45cceeb10b63f0e4ea6ffdae5c686a6
+  data.tar.gz: 9d024da7976bb5cf3a14ad46869b623ba0c74f2d53b6b12b9abb17cc2958e9cb7885fc2a3234cba371771192c7d902214c2a001453b0f32be837583bc342526f

data/.github/workflows/metanorma.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: [ '2.5', '2.6', '2.7', '3.0' ]
+        ruby: [ '2.6', '2.7', '3.0' ]
         os: [ ubuntu-latest, windows-latest, macos-latest ]
         experimental: [ true ]
     steps:
@@ -27,9 +27,19 @@ jobs:
 
       - run: 'echo ''gem "fontist", path: "./fontist"'' > Gemfile.devel'
 
-      - uses: ruby/setup-ruby@v1
+      - if: matrix.ruby == '3.0'
+        uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
+          rubygems: latest
+
+      - if: matrix.ruby != '3.0'
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - uses: metanorma/metanorma-build-scripts/inkscape-setup-action@main
 
       - run: bundle exec rake

data/README.adoc

@@ -51,71 +51,70 @@ has the following requirements:
 
 These dependencies are generally present on all systems.
 
-=== Upgrading Fontist
-
-==== To v1.10+
-
-Fontist versions beyond v1.10 utilize a new formula format.
-After the upgrade, please run `fontist update` to fetch the latest formulas.
-
-Starting from v1.10, Fontist uses the "`default family`" instead of the "`preferred family`"
-when grouping styles.
-
-For example, a request for the "`Lato`" font prior to v1.10 will return all
-styles: "`Black`", "`Black Italic`", "`Bold`", and 15 other styles.
-
-From v1.10 onwards, Fontist will return _only_ the 4 default styles:
-"`Regular`", "`Italic`", "`Bold`" and "`Bold Italic`".
-
-In order to fetch other styles, you have to specify the exact font
-"`subfamily`", such as "`Lato Black`", or "`Lato Heavy`", or use
-the `--preferred-family` option with CLI and `Fontist.preferred_family = true`
-with the Ruby library.
-
-NOTE: Prior to v1.10 there was a bug with the "`Courier`" font formula, which
-allowed the font to be installed when requesting the font name "`Courier`", but
-its font location was only obtainable using the full "`Courier New`" font name.
-From v1.10 onwards the behavior has been made consistent -- only the proper
-"`Courier New`" name should be used.
 
+== Usage of the Fontist command-line interface
 
-== Usage of the `fontist` command
-
-=== Fontist command-line interface
+=== The `fontist` command
 
 These commands makes possible to operate with fonts via command line.
 
 The CLI properly supports exit status, so in a case of error it returns a status
-code higher or equal than 1.
+code higher or equal than `1`.
+
+Searches are case-insensitive for ease of use.
 
-All searches are case-insensitive for ease of use.
+All commands support the following global options:
 
-=== Global options
+`--preferred-family`:: Search using the "`preferred family`" name of a font.
+(instead of the "`default family`" name, the default prior to Fontist v1.10.)
 
-All commands support the following options:
+NOTE: See <<preferred-family-change>> for the differences between
+"`preferred family`" and "`default family`".
 
-* `--preferred-family` Use the preferred family names when searching for fonts. This format was used prior to v1.10.
 
-=== Install fonts
+=== Install fonts: `fontist install`
 
 Fontist checks whether this font is already installed, and if not, then installs
 the font and returns its installed paths.
 
-The font name is the only argument to be supplied (the font family name).
+The font name is the only argument to be supplied.
 
 [source,sh]
 ----
 $ fontist install "segoe ui"
 These fonts are found or installed:
-/Users/user/.fontist/fonts/SEGOEUI.TTF
-/Users/user/.fontist/fonts/SEGOEUIB.TTF
-/Users/user/.fontist/fonts/SEGOEUII.TTF
-/Users/user/.fontist/fonts/SEGOEUIZ.TTF
+- /Users/user/.fontist/fonts/SEGOEUI.TTF
+- /Users/user/.fontist/fonts/SEGOEUIB.TTF
+- /Users/user/.fontist/fonts/SEGOEUII.TTF
+- /Users/user/.fontist/fonts/SEGOEUIZ.TTF
 ----
 
-NOTE: Specifying the formula's name or the font's filename is not supported.
+By default, all matching styles (according to the font's "`default family`" name)
+are installed.
 
-NOTE: The `install` command is similar to the `Font.install` library call.
+NOTE: Prior to v1.10, the font's "`preferred family`" name is used to match
+styles for search. See <<preferred-family-change>> for details of that change.
+
+To install all fonts specified in a Fontist formula, use the `-F, --formula`
+option.
+
+[source,sh]
+----
+$ fontist install --formula 'courier_prime'
+Downloading font ...
+Installing font "courier_prime".
+Fonts installed at:
+- /Users/user/.fontist/fonts/Courier Prime Bold Italic.ttf
+- /Users/user/.fontist/fonts/Courier Prime Bold.ttf
+- /Users/user/.fontist/fonts/Courier Prime Italic.ttf
+- /Users/user/.fontist/fonts/Courier Prime.ttf
+----
+
+Here, `courier_prime` is the filename of the formula located at the public
+Fontist Formula repository
+(https://github.com/fontist/formulas/blob/v3/Formulas/courier_prime.yml[`courier_prime.yml`]).
+
+NOTE: Specifying the formula's name or the font's filename is not supported.
 
 If there are several formulas with a requested font, then `fontist` searches
 for the newest version of the font among formulas with size below a limit
@@ -126,18 +125,23 @@ available formulas would be installed.
 
 Supported options:
 
--f, [--force]:: Install even if it's already installed in system
--F, [--formula]:: Install by formula instead of font
--a, [--accept-all-licenses]:: Accept all license agreements
--h, [--hide-licenses]:: Hide license texts
--p, [--no-progress]:: Hide download progress
--V, [--version=VERSION]:: Install particular version of a font
--s, [--smallest]:: Install the smallest formula
--n, [--newest]:: Install the newest version of a font
--S, [--size-limit=N]:: Specify size limit for a formula to be installed
+`-f, [--force]`:: Install even if already installed in system
+`-F, [--formula]`:: Install whole formula instead of a font
+`-a, [--accept-all-licenses]`:: Accept all license agreements
+`-h, [--hide-licenses]`:: Hide license texts
+`-p, [--no-progress]`:: Hide download progress
+`-V, [--version=VERSION]`:: Install particular version of a font
+`-s, [--smallest]`:: Install the smallest font by file size if several
+`-n, [--newest]`:: Install the newest version of a font if several
+`-S, [--size-limit=N]`:: Specify upper limit for file size of a formula to be installed
                        (default is 300 MB)
+`-u, [--update-fontconfig]`:: Update Fontconfig
+
+
+NOTE: The `install` command is similar to the `Font.install` library call.
 
-=== Uninstall fonts
+
+=== Uninstall fonts: `fontist uninstall`
 
 Uninstalls any font supported by Fontist.
 
@@ -154,22 +158,21 @@ These fonts are removed:
 /Users/user/.fontist/fonts/SEGOEUI.TTF
 ----
 
-=== Status
+=== Status: `fontist status`
 
-Prints installed font paths grouped by formula and font.
+Prints installed font paths with a corresponding formula.
 
 [source,sh]
 ----
 $ fontist status "segoe ui"
-segoe_ui
- Segoe UI
-  Regular (/Users/user/.fontist/fonts/SEGOEUI.TTF)
-  Bold (/Users/user/.fontist/fonts/SEGOEUIB.TTF)
-  Italic (/Users/user/.fontist/fonts/SEGOEUII.TTF)
-  Bold Italic (/Users/user/.fontist/fonts/SEGOEUIZ.TTF)
+Fonts found at:
+- /Users/user/.fontist/fonts/SEGOEUII.TTF (from segoe_ui formula)
+- /Users/user/.fontist/fonts/SEGOEUIZ.TTF (from segoe_ui formula)
+- /Users/user/.fontist/fonts/SEGOEUIB.TTF (from segoe_ui formula)
+- /Users/user/.fontist/fonts/SEGOEUI.TTF (from segoe_ui formula)
 ----
 
-=== List
+=== List: `fontist list`
 
 Lists installation status of fonts supported by Fontist.
 
@@ -193,7 +196,7 @@ google/roboto_mono
   Italic (uninstalled)
 ----
 
-=== List installed font paths
+=== List installed font paths: `fontist manifest-locations`
 
 Returns locations of fonts specified in a YAML file as an input.
 
@@ -238,13 +241,23 @@ Segoe UI:
     - "/Users/user/.fontist/fonts/SEGOEUIB.TTF"
 Roboto Mono:
   Regular:
-    full_name:
-    paths: []
+    full_name: Roboto Mono Regular
+    paths:
+    - "/Users/user/.fontist/fonts/RobotoMono-VariableFont_wght.ttf"
 ----
 
-Since "`Segoe UI`" is installed, but "`Roboto Mono`" is not.
+If one or more of requested fonts are missing, the "3" error code would be
+returned, and a message printed:
 
-=== Install fonts from manifest
+[source,sh]
+----
+$ fontist manifest-locations manifest.yml
+'Roboto Mono' 'Regular' font is missing, please run `fontist install 'Roboto Mono'` to download the font.
+$ echo $?
+3
+----
+
+=== Install fonts from manifest: `fontist manifest-install`
 
 Install fonts from a YAML Fontist manifest:
 
@@ -274,7 +287,31 @@ Roboto Mono:
     - "/Users/user/.fontist/fonts/RobotoMono-VariableFont_wght.ttf"
 ----
 
-=== Help
+=== Work with Fontconfig: `fontist fontconfig`
+
+Fontconfig is a software designed to provide fonts to other programs. It is
+typically used on Linux, but also available on macOS and Windows. Fontconfig is
+used by LibreOffice, GIMP, and many other programs.
+
+It order to find fontist fonts, Fontconfig should be updated to include fontist
+paths. It can be done with the `--update-fontconfig` option of the `install`
+command, or by calling a special one:
+
+[source,sh]
+----
+$ fontist fontconfig update
+----
+
+It would create a config in `~/.config/fontconfig/conf.d/10-fontist.conf`.
+
+To remove it, please use:
+
+[source,sh]
+----
+$ fontist fontconfig remove
+----
+
+=== Help: `fontist help`
 
 List of all commands could be seen by:
 
@@ -372,7 +409,7 @@ Fontist::Formula.find("Calibri")
 ----
 
 This method will search and return a Fontist formula for the provided keyword
-which allows for further processing, such as licence checks or proceeding with
+which allows for further processing, such as license checks or proceeding with
 installation of the font in your system.
 
 ==== List font styles supported by a formula
@@ -517,7 +554,36 @@ Fontist::Manifest::Locations.from_file("manifest.yml")
 Fontist::Manifest::Install.from_file("manifest.yml", confirmation: "yes")
 ----
 
-== Using Fontist with proxies
+=== `Fontist::Fontconfig`
+
+Fontist supports work with Fontconfig via the Ruby interface:
+
+[source,ruby]
+----
+Fontist::Fontconfig.update              # let detect fontist fonts
+Fontist::Fontconfig.remove              # disable detection
+Fontist::Fontconfig.remove(force: true) # do not fail if no config exists
+----
+
+== Installing macOS-specific add-on fonts
+
+The purpose of Fontist allowing macOS-specific add-on fonts is to allow CI jobs
+on macOS environments to use these specially licensed fonts that are not
+available on other platforms.
+
+The "Canela" font is a commercial font that comes free with macOS.
+
+Run this command to install Canela on macOS.
+
+[source,sh]
+----
+$ fontist install Canela
+----
+
+WARNING: Fontist does not allow installing macOS-specific fonts on non-macOS
+platforms due to font licensing of those fonts.
+
+== Using Fontist with proxy servers
 
 Fontist uses Git internally for fetching formulas and fonts.
 
@@ -576,38 +642,124 @@ https://github.com/evantoli[evantoli]).
 
 == Authoring Fontist formulas
 
-=== Creating a Fontist formula from a font archive
+=== Private Fontist formulas and font repositories
 
-A formula could be generated from a fonts archive. Just specify a URL to the
-archive:
+Fontist supports installing private fonts via private Fontist repositories.
+
+A Fontist repository is a Git repo which contains YAML Formula files.
+Formulas can be created manually
+(see https://github.com/fontist/formulas/tree/master/Formulas[examples]),
+or <<create-formula,auto-generated from an archive>>.
+
+A repository can be either a HTTPS or SSH Git repo. In case of SSH, a
+corresponding SSH key should be setup with `ssh-agent` in order to access this
+private repository.
+
+The `fontist repo setup` command fetches a repository's formulas, and saves the
+repository's name and URL for later use.
+
+Internally, all repositories are stored at
+`~/.fontist/formulas/Formulas/private`.
 
 [source,sh]
 ----
-fontist create-formula https://www.latofonts.com/download/lato2ofl-zip/
-cp lato.yml ~/.fontist/formulas/Formulas/
+fontist repo setup NAME URL
+----
+
+E.g.
+
+[source,sh]
+----
+fontist repo setup acme https://example.com/acme/formulas.git
+# or
+fontist repo setup acme git@example.com:acme/formulas.git
 ----
 
-Though indexes are auto-generated now, maintainers should rebuild indexes in the
-main repo for backward compatibility with Fontist versinos prior to 1.9.x.
+Then you can just install fonts from this repo:
 
-A formula index should be rebuilt when a new formula is generated or an existing
-one changed:
+[source,sh]
+----
+fontist install "private font"
+----
+
+If the private Fontist formula repository is updated, you can fetch the updates
+with the `repo update` command:
 
 [source,sh]
 ----
-fontist rebuild-index --main-repo
+fontist repo update acme
 ----
 
-Then, both the formula and the updated indexes should be committed and pushed to
-the formula repository:
+If there is a need to avoid using private formulas, the repo can be removed
+with:
+
+[source,sh]
+----
+fontist repo remove acme
+----
+
+[[create-formula]]
+=== Auto-generate a Fontist formula from a font archive
+
+A formula could be generated from a fonts archive. Just specify a URL to the
+archive:
 
 [source,sh]
 ----
-cd ~/.fontist/formulas
-git add Formulas/lato.yml index.yml filename_index.yml
-git commit -m "Add Lato formula"
+fontist create-formula https://www.latofonts.com/download/lato2ofl-zip/
+cp lato.yml ~/.fontist/formulas/Formulas/
+----
+
+=== Authentication for private formulas or private formula repositories
+
+Authorization of private archives in private formulas can be implemented with
+headers.
+
+Here is an example which works with Github releases:
+
+[source,yaml]
+----
+resources:
+  fonts.zip:
+    urls:
+    - url: https://example.com/repos/acme/formulas/releases/assets/38777461
+      headers:
+        Accept: application/octet-stream
+        Authorization: token ghp_1234567890abcdefghi
 ----
 
+A token can be obtained on the
+https://github.com/settings/tokens[GitHub Settings > Tokens page].
+This token should have at least the `repo` scope for access to these assets.
+
+
+=== Upgrading Fontist
+
+[[preferred-family-change]]
+==== To v1.10+
+
+Fontist versions beyond v1.10 utilize a new formula format.
+After the upgrade, please run `fontist update` to fetch the latest formulas.
+
+Starting from v1.10, Fontist uses the "`default family`" instead of the
+"`preferred family`" when grouping styles.
+
+For example, a request for the "`Lato`" font prior to v1.10 will return all
+styles: "`Black`", "`Black Italic`", "`Bold`", and 15 other styles.
+
+From v1.10 onwards, Fontist will return _only_ the 4 default styles:
+"`Regular`", "`Italic`", "`Bold`" and "`Bold Italic`".
+
+In order to fetch other styles, you have to specify the exact font
+"`subfamily`", such as "`Lato Black`", or "`Lato Heavy`", or use
+the `--preferred-family` option with CLI and `Fontist.preferred_family = true`
+with the Ruby library.
+
+NOTE: Prior to v1.10 there was a bug with the "`Courier`" font formula, which
+allowed the font to be installed when requesting the font name "`Courier`", but
+its font location was only obtainable using the full "`Courier New`" font name.
+From v1.10 onwards the behavior has been made consistent -- only the proper
+"`Courier New`" name should be used.
 
 
 
@@ -620,29 +772,13 @@ WARNING: This section is only for Fontist maintainers.
 https://fonts.google.com[Google Fonts] provides probably the largest collection
 of widely-used, freely and openly licensed fonts.
 
-Fontist's https://github.com/fonitist/formula[formula library] includes support
+Fontist's https://github.com/fontist/formulas[formula library] includes support
 for all openly-licensed fonts provided through Google Fonts, and maintains
 Fontist formulas for all such fonts.
 
-A GHA workflow checks for updated fonts on Google Fonts daily.
-
-In case an update is found, it could be fetched to the library by:
-
-[source,sh]
-----
-bin/fontist google import
-----
-
-The script would update formulas which should be committed to a separate
-repository https://github.com/fontist/formulas[formulas]:
-
-[source,sh]
-----
-cd ~/.fontist/versions/{last_version}/formulas
-git add Formulas/google
-git commit -m "Google Fonts update"
-git push
-----
+https://github.com/fontist/formulas/blob/v3/.github/workflows/google.yml[A GHA
+workflow] checks for updated fonts on Google Fonts daily. In case an update is
+found, it's added to the repo by the workflow.
 
 === Dynamically importing formulas from SIL
 
@@ -659,7 +795,7 @@ They can be updated with:
 
 [source,sh]
 ----
-fontist import-sil
+fontist import sil
 cd ~/.fontist/versions/{last_version}/formulas
 git add Formulas/sil
 git commit -m "SIL fonts update"
@@ -669,35 +805,19 @@ git push
 === Dynamically importing formulas from macOS
 
 macOS provides https://support.apple.com/en-om/HT211240#download[fonts] which
-can be manually downloaded with the Font Book app. When such font is requested,
-fontist prints information on how to install it.
+can be manually downloaded with `Font Book.app`.
 
-In order to know which fonts are available in a current version of macOS,
-for each version there is a formula containing all supported fonts.
-
-A new formula can be generated with:
+To update macOS formulas:
 
 [source,sh]
 ----
-fontist import macos --name "Big Sur" --fonts-link "https://support.apple.com/en-om/HT211240#download"
+fontist import macos
 cd ~/.fontist/versions/{last_version}/formulas
 git add Formulas/macos
-git commit -m "Add Big Sur macOS formula"
+git commit -m "Update macOS formulas"
 git push
 ----
 
-Here `--fonts-link` is a link to a page containing a list of available fonts
-in the Font Book app.
-
-If the import is run on a different version of macOS, then a proper version
-should be set in the `platforms` attribute of the generated formula:
-
-[source,yaml]
-----
-platforms:
-- macos-20
-----
-
 
 == Development
 
@@ -732,82 +852,6 @@ https://github.com/fontist/formulas[formulas] repository.
 If you'd like to add a new formula repository or change settings for an existing
 one, please refer to its documentation.
 
-=== Private Fontist formulas and font repositories
-
-There is an ability to use private fonts via private Fontist repositories.
-
-A Fontist repository is a Git repo which contains YAML formula files. Formulas can be created
-manually (see https://github.com/fontist/formulas/tree/master/Formulas[examples]),
-or xref:Authoring Fontist formulas[auto-generated from an archive].
-
-A repository can be either a HTTPS or SSH Git repo. In case of SSH, a
-corresponding SSH key should be setup with `ssh-agent` in order to access this
-private repository.
-
-The `fontist repo setup` command fetches a repository's formulas, and saves the
-repository's name and URL for later use.
-
-Internally, all repositories are stored at
-`~/.fontist/formulas/Formulas/private`.
-
-[source,sh]
-----
-fontist repo setup NAME URL
-----
-
-E.g.
-
-[source,sh]
-----
-fontist repo setup acme https://example.com/acme/formulas.git
-# or
-fontist repo setup acme git@example.com:acme/formulas.git
-----
-
-Then you can just install fonts from this repo:
-
-[source,sh]
-----
-fontist install "private font"
-----
-
-If the private Fontist formula repository is updated, you can fetch the updates
-with the `repo update` command:
-
-[source,sh]
-----
-fontist repo update acme
-----
-
-If there is a need to avoid using private formulas, the repo can be removed
-with:
-
-[source,sh]
-----
-fontist repo remove acme
-----
-
-=== Private formulas
-
-Authorization of private archives in private formulas can be implemented with
-headers.
-
-Here is an example which works with Github releases:
-
-[source,yaml]
-----
-resources:
-  fonts.zip:
-    urls:
-    - url: https://example.com/repos/acme/formulas/releases/assets/38777461
-      headers:
-        Accept: application/octet-stream
-        Authorization: token ghp_1234567890abcdefghi
-----
-
-A token can be obtained on the
-https://github.com/settings/tokens[GitHub Settings > Tokens page].
-This token should have at least the `repo` scope for access to these assets.
 
 === Releasing
 

data/fontist.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "down", "~> 5.0"
   spec.add_runtime_dependency "extract_ttc", "~> 0.1"
   spec.add_runtime_dependency "nokogiri", "~> 1.0"
+  spec.add_runtime_dependency "mime-types", "~> 3.0"
   spec.add_runtime_dependency "sys-uname", "~> 1.2"
   spec.add_runtime_dependency "thor", "~> 1.0.1"
   spec.add_runtime_dependency "git", "~> 1.0"