-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
a514e4d
commit b4d9e80
Showing
11 changed files
with
552 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
--- | ||
layout: docs | ||
--- | ||
|
||
= Usage | ||
|
||
Fontist can be used via its command-line interface (CLI), or as a | ||
Ruby library. This section describes how to use it with CLI. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
--- | ||
layout: docs | ||
--- | ||
|
||
= Which archives are supported by Fontist? | ||
|
||
Fontist uses https://github.com/fontist/excavate[Excavate] to extract archives. | ||
It allows to find fonts even deeply in nested archives of different types. | ||
|
||
The following archive types are supported: | ||
|
||
* cab (including "exe" files) | ||
* tar | ||
* gzip | ||
* cpio (both old and new formats) | ||
* ole ("msi" files) | ||
* rpm | ||
* 7z | ||
* xar | ||
* zip |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
--- | ||
layout: docs | ||
--- | ||
|
||
= How to use Fontist in CI systems? | ||
|
||
For example, in Github Actions you can create workflow with the following steps: | ||
|
||
[source,yaml] | ||
---- | ||
- uses: ruby/setup-ruby@v1 | ||
with: | ||
ruby-version: 2.7 | ||
- run: gem install fontist | ||
- run: fontist install --accept-all-licenses "arial" | ||
---- | ||
|
||
It would setup Ruby, install Fontist as a gem (a Ruby library), and install the | ||
Arial font. | ||
|
||
== Platform-specific fonts | ||
|
||
Some fonts are available only on specific platforms, because of license | ||
restrictions. For example, the Canela font can be installed only on macOS. To | ||
install it, just use an image with a proper OS: | ||
|
||
[source,yaml] | ||
---- | ||
runs-on: macos-10.15 | ||
steps: | ||
- uses: ruby/setup-ruby@v1 | ||
with: | ||
ruby-version: 2.7 | ||
- run: gem install fontist | ||
- run: fontist install --accept-all-licenses "canela" | ||
---- | ||
|
||
WARNING: Fontist does not allow installing macOS-specific fonts on non-macOS | ||
platforms due to font licensing of those fonts. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
--- | ||
layout: docs | ||
--- | ||
|
||
= How to change Fontist directory? | ||
|
||
By default Fontist uses the `~/.fontist` directory to store fonts and its | ||
files. It could be changed with the `FONTIST_PATH` environment variable. | ||
|
||
[source,sh] | ||
---- | ||
FONTIST_PATH=~/.fontist_new fontist update | ||
---- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
--- | ||
layout: docs | ||
--- | ||
|
||
= How to use Fontconfig with Fontist? | ||
|
||
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 `install`: | ||
|
||
[source,sh] | ||
---- | ||
fontist install --update-fontconfig 'courier prime' | ||
---- | ||
|
||
Or by calling a special command: | ||
|
||
[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 | ||
---- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,117 @@ | ||
--- | ||
layout: docs | ||
--- | ||
|
||
= How to create a new formula? | ||
|
||
Formula's purpose is to let fontist to determine where to download fonts. | ||
|
||
There is a command which can generate a formula by an archive's link: | ||
|
||
[source,sh] | ||
---- | ||
fontist create-formula https://quoteunquoteapps.com/courierprime/downloads/courier-prime.zip | ||
---- | ||
|
||
A result of its execution would be a yaml file. It can be changed with a text | ||
editor. | ||
|
||
You may need to change it manually when: | ||
|
||
- the script could not detect proper license text | ||
- you would like to change a name of a formula (may use the `--name` option) | ||
- the archive is private (see <<private-formula-authentication>>) | ||
|
||
The formula can be proposed to be merged to | ||
https://github.com/fontist/formulas[the main repository], or added to a private | ||
repository. | ||
|
||
== How to create a private repository | ||
|
||
Fontist supports additional formulas repositories, called "private". | ||
|
||
To create a new private repository, setup a new git repository, and place | ||
formulas there: | ||
|
||
[source,sh] | ||
---- | ||
mkdir acme | ||
cd acme | ||
git init | ||
cp ../courier_prime.yml . # from example above | ||
git add courier_prime.yml | ||
git commit -m "Add formula for Courier Prime" | ||
git remote add origin [email protected]:acme/formulas.git # use your git hosting | ||
git push origin main -u | ||
---- | ||
|
||
== How to add a private repository to Fontist | ||
|
||
In order to find the private repository, fontist should be called with its URL | ||
or path: | ||
|
||
[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 [email protected]:acme/formulas.git | ||
---- | ||
|
||
Then fonts from this repo can be installed: | ||
|
||
[source,sh] | ||
---- | ||
fontist install "courier prime" | ||
---- | ||
|
||
NOTE: A repository can be either an 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. | ||
|
||
== How to update a private repository | ||
|
||
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-formula-authentication]] | ||
== 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,96 @@ | ||
--- | ||
layout: docs | ||
--- | ||
|
||
= How to install a font? | ||
|
||
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. | ||
|
||
[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 | ||
---- | ||
|
||
If the font's formula requires license acceptable, then it will be asked. | ||
|
||
[source,sh] | ||
---- | ||
Do you accept all presented font licenses, and want Fontist to download these fonts for you? => TYPE 'Yes' or 'No': | ||
---- | ||
|
||
It can be accepted either by typing 'yes', or by the `-a, --accept-all-licenses` | ||
option. | ||
|
||
== How to install a whole formula? | ||
|
||
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 font's filename is not supported. | ||
|
||
== Way of searching for a formula | ||
|
||
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 | ||
(300 MB). This behavior can be changed with options. | ||
|
||
NOTE: If styles of a font are spread among several formulas, then all | ||
available formulas would be installed. | ||
|
||
== Supported options | ||
|
||
`-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. | ||
|
||
== How to uninstall fonts? | ||
|
||
To uninstall any font installed by Fontist: | ||
|
||
[source,sh] | ||
---- | ||
$ fontist uninstall "segoe ui" | ||
These fonts are removed: | ||
/Users/user/.fontist/fonts/SEGOEUII.TTF | ||
/Users/user/.fontist/fonts/SEGOEUIZ.TTF | ||
/Users/user/.fontist/fonts/SEGOEUIB.TTF | ||
/Users/user/.fontist/fonts/SEGOEUI.TTF | ||
---- | ||
|
||
Returns paths of an uninstalled font, or prints an error telling that the font | ||
isn't installed or could not be found in Fontist formulas. Aliased as `remove`. |
Oops, something went wrong.