fontist 1.13.0 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43f3bc7643cf7694fb753d9c62509f7134a26d68fb41a2e06c9c9e25f33ae2c5
-  data.tar.gz: 3269f7aedc78eed761697ff862701bf6ca27679e9be90972d8983e913a15beea
+  metadata.gz: 2c0b58f3af1125a6a560179502a5ce5845e76b4d4db1c466e5f63f9628203089
+  data.tar.gz: 2176708c4c71239768f8714cf21d393aae208b8a7757402b08ad369ec155ed25
 SHA512:
-  metadata.gz: a92d2d69bed9e8e33fc9785f198c9878d1a02dda4de65f290ecff30336adec6117cfd18cc09d52545f318a917b40e02b4d796049384b6b6c12fee05d2056283f
-  data.tar.gz: ffdb9a02c723a5a8c04c26c3f3d5a0d0bba4e875fd750bee67a3c68698d2f2e9057ff936019523d3eb9a359bbbf19de566c45acb99fff99b745952039add7e30
+  metadata.gz: c3875e506d599cfab2e7447e7a9f24518080a02f8bce0018f386b06c13a5048a78ce2e8fa61a4109e60e7445bb10164e84d45d33bcc109b4087ca3a2eeedac49
+  data.tar.gz: 61747670abc9194cba651cb01d5a69d46bbdc84ed99f9de50e0057606a24f2b2efb2b2df782d6cf9b3b99d1c678e33f20d665157655de460e9227075b3a28a0b

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:
@@ -32,4 +32,6 @@ jobs:
           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`.
 
-All searches are case-insensitive for ease of use.
+Searches are case-insensitive for ease of use.
 
-=== Global options
+All commands support the following global options:
 
-All commands support the following 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.)
 
-* `--preferred-family` Use the preferred family names when searching for fonts. This format was used prior to v1.10.
+NOTE: See <<preferred-family-change>> for the differences between
+"`preferred family`" and "`default family`".
 
-=== 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,17 +125,23 @@ available formulas would be installed.
 
 Supported options:
 
--f, [--force]:: Install even if it's already installed in system
--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
 
-=== Uninstall fonts
+
+NOTE: The `install` command is similar to the `Font.install` library call.
+
+
+=== Uninstall fonts: `fontist uninstall`
 
 Uninstalls any font supported by Fontist.
 
@@ -153,7 +158,7 @@ These fonts are removed:
 /Users/user/.fontist/fonts/SEGOEUI.TTF
 ----
 
-=== Status
+=== Status: `fontist status`
 
 Prints installed font paths grouped by formula and font.
 
@@ -168,7 +173,7 @@ segoe_ui
   Bold Italic (/Users/user/.fontist/fonts/SEGOEUIZ.TTF)
 ----
 
-=== List
+=== List: `fontist list`
 
 Lists installation status of fonts supported by Fontist.
 
@@ -192,7 +197,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.
 
@@ -243,7 +248,7 @@ Roboto Mono:
 
 Since "`Segoe UI`" is installed, but "`Roboto Mono`" is not.
 
-=== Install fonts from manifest
+=== Install fonts from manifest: `fontist manifest-install`
 
 Install fonts from a YAML Fontist manifest:
 
@@ -273,7 +278,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:
 
@@ -371,7 +400,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
@@ -516,7 +545,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.
 
@@ -575,7 +633,64 @@ https://github.com/evantoli[evantoli]).
 
 == Authoring Fontist formulas
 
-=== Creating a Fontist formula from a font archive
+=== Private Fontist formulas and font repositories
+
+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 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
+----
+
+[[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:
@@ -587,7 +702,7 @@ cp lato.yml ~/.fontist/formulas/Formulas/
 ----
 
 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.
+main repo for backward compatibility with Fontist versions prior to v1.9.x.
 
 A formula index should be rebuilt when a new formula is generated or an existing
 one changed:
@@ -607,6 +722,56 @@ git add Formulas/lato.yml index.yml filename_index.yml
 git commit -m "Add Lato formula"
 ----
 
+=== 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.
 
 
 
@@ -629,7 +794,7 @@ In case an update is found, it could be fetched to the library by:
 
 [source,sh]
 ----
-bin/fontist google import
+bin/fontist import google
 ----
 
 The script would update formulas which should be committed to a separate
@@ -658,7 +823,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"
@@ -668,8 +833,8 @@ 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`. When such font is requested,
+Fontist prints information on how to install it.
 
 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.
@@ -686,7 +851,7 @@ git push
 ----
 
 Here `--fonts-link` is a link to a page containing a list of available fonts
-in the Font Book app.
+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:
@@ -731,82 +896,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/lib/fontist/cli/class_options.rb

@@ -0,0 +1,14 @@
+module Fontist
+  class CLI < Thor
+    module ClassOptions
+      def handle_class_options(options)
+        Fontist.preferred_family = options[:preferred_family]
+        Fontist.log_level = options[:quiet] ? :fatal : :info
+
+        if options[:formulas_path]
+          Fontist.formulas_path = Pathname.new(options[:formulas_path])
+        end
+      end
+    end
+  end
+end

data/lib/fontist/cli.rb

@@ -1,10 +1,13 @@
 require "thor"
+require "fontist/cli/class_options"
 require "fontist/repo_cli"
 require "fontist/import_cli"
-require "fontist/google_cli"
+require "fontist/fontconfig_cli"
 
 module Fontist
   class CLI < Thor
+    include ClassOptions
+
     STATUS_SUCCESS = 0
     STATUS_UNKNOWN_ERROR = 1
     STATUS_NON_SUPPORTED_FONT_ERROR = 2
@@ -18,6 +21,9 @@ module Fontist
     STATUS_REPO_COULD_NOT_BE_UPDATED = 10
     STATUS_MANUAL_FONT_ERROR = 11
     STATUS_SIZE_LIMIT_ERROR = 12
+    STATUS_FORMULA_NOT_FOUND = 13
+    STATUS_FONTCONFIG_NOT_FOUND = 14
+    STATUS_FONTCONFIG_FILE_NOT_FOUND = 15
 
     ERROR_TO_STATUS = {
       Fontist::Errors::UnsupportedFontError => [STATUS_NON_SUPPORTED_FONT_ERROR],
@@ -39,6 +45,10 @@ module Fontist
       Fontist::Errors::FontIndexCorrupted => [STATUS_FONT_INDEX_CORRUPTED],
       Fontist::Errors::RepoNotFoundError => [STATUS_REPO_NOT_FOUND],
       Fontist::Errors::MainRepoNotFoundError => [STATUS_MAIN_REPO_NOT_FOUND],
+      Fontist::Errors::FormulaNotFoundError => [STATUS_FORMULA_NOT_FOUND],
+      Fontist::Errors::FontconfigNotFoundError => [STATUS_FONTCONFIG_NOT_FOUND],
+      Fontist::Errors::FontconfigFileNotFoundError =>
+        [STATUS_FONTCONFIG_FILE_NOT_FOUND],
     }.freeze
 
     def self.exit_on_failure?
@@ -49,9 +59,18 @@ module Fontist
                  type: :boolean,
                  desc: "Use Preferred Family when available"
 
+    class_option :quiet,
+                 aliases: :q,
+                 type: :boolean,
+                 desc: "Hide all messages"
+
+    class_option :formulas_path, type: :string, desc: "Path to formulas"
+
     desc "install FONT", "Install font"
     option :force, type: :boolean, aliases: :f,
-                   desc: "Install even if it's already installed in system"
+                   desc: "Install even if already installed in system"
+    option :formula, type: :boolean, aliases: :F,
+                     desc: "Install whole formula instead of a font"
     option :accept_all_licenses, type: :boolean,
                                  aliases: ["--confirm-license", :a],
                                  desc: "Accept all license agreements"
@@ -62,13 +81,15 @@ module Fontist
     option :version, type: :string, aliases: :V,
                      desc: "Specify particular version of a font"
     option :smallest, type: :boolean, aliases: :s,
-                      desc: "Install the smallest formula if several"
+                      desc: "Install the smallest font by file size if several"
     option :newest, type: :boolean, aliases: :n,
                     desc: "Install the newest version of a font if several"
     option :size_limit,
            type: :numeric, aliases: :S,
-           desc: "Specify size limit for formula " \
+           desc: "Specify upper limit for file size of a formula to be installed" \
                  "(default is #{Fontist.formula_size_limit_in_megabytes} MB)"
+    option :update_fontconfig, type: :boolean, aliases: :u,
+                               desc: "Update fontconfig"
     def install(font)
       handle_class_options(options)
       confirmation = options[:accept_all_licenses] ? "yes" : "no"
@@ -134,8 +155,12 @@ module Fontist
     end
 
     desc "manifest-install MANIFEST", "Install fonts from MANIFEST (yaml)"
-    option :accept_all_licenses, type: :boolean, aliases: "--confirm-license", desc: "Accept all license agreements"
-    option :hide_licenses, type: :boolean, desc: "Hide license texts"
+    option :accept_all_licenses, type: :boolean,
+                                 aliases: ["--confirm-license", :a],
+                                 desc: "Accept all license agreements"
+    option :hide_licenses, type: :boolean,
+                           aliases: :h,
+                           desc: "Hide license texts"
     def manifest_install(manifest)
       handle_class_options(options)
       paths = Fontist::Manifest::Install.from_file(
@@ -178,28 +203,17 @@ module Fontist
       STATUS_SUCCESS
     end
 
-    desc "import-sil", "Import formulas from SIL"
-    def import_sil
-      handle_class_options(options)
-      require "fontist/import/sil_import"
-      Fontist::Import::SilImport.new.call
-    end
-
     desc "repo SUBCOMMAND ...ARGS", "Manage custom repositories"
     subcommand "repo", Fontist::RepoCLI
 
     desc "import SUBCOMMAND ...ARGS", "Manage imports"
     subcommand "import", Fontist::ImportCLI
 
-    desc "google SUBCOMMAND ...ARGS", "Manage Google formulas"
-    subcommand "google", Fontist::GoogleCLI
+    desc "fontconfig SUBCOMMAND ...ARGS", "Manage fontconfig"
+    subcommand "fontconfig", Fontist::FontconfigCLI
 
     private
 
-    def handle_class_options(options)
-      Fontist.preferred_family = options[:preferred_family]
-    end
-
     def success
       STATUS_SUCCESS
     end