Skip to content

Commit

Permalink
Usage
Browse files Browse the repository at this point in the history
  • Loading branch information
alexeymorozov committed Feb 23, 2022
1 parent a514e4d commit b4d9e80
Show file tree
Hide file tree
Showing 11 changed files with 552 additions and 0 deletions.
21 changes: 21 additions & 0 deletions _layouts/docs.html
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,27 @@
items:
- title: What is Fontist?
path: /
- title: Usage
path: /usage/
items:
- title: How to install a font?
path: /usage/install/
- title: How to use Fontist in CI?
path: /usage/ci/
- title: How to create a new formula?
path: /usage/formula/
- title: How to use Fontconfig with Fontist?
path: /usage/fontconfig/
- title: Which archives are supported by Fontist?
path: /usage/archives/
- title: How to find installed fonts?
path: /usage/status/
- title: How to install a bundle of fonts at once?
path: /usage/manifest/
- title: How to change Fontist directory?
path: /usage/directory/
- title: How to proxy servers with Fontist?
path: /usage/proxy/
---

{{ content }}
8 changes: 8 additions & 0 deletions docs/usage.adoc
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.
20 changes: 20 additions & 0 deletions docs/usage/archives.adoc
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
43 changes: 43 additions & 0 deletions docs/usage/ci.adoc
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.
13 changes: 13 additions & 0 deletions docs/usage/directory.adoc
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
----
33 changes: 33 additions & 0 deletions docs/usage/fontconfig.adoc
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
----
117 changes: 117 additions & 0 deletions docs/usage/formula.adoc
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.
96 changes: 96 additions & 0 deletions docs/usage/install.adoc
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`.
Loading

0 comments on commit b4d9e80

Please sign in to comment.