Usage

_layouts/docs.html

@@ -7,6 +7,13 @@
   items:
   - title: What is Fontist?
     path: /
+  - title: Usage
+    path: /usage/
+    items:
+    - title: How to use Fontist in CI
+      path: /usage/ci/
+    - title: How to create a new formula
+      path: /usage/formula/
 ---
 
 {{ content }}

docs/usage.adoc

@@ -0,0 +1,39 @@
+---
+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.
+
+== Install a font
+
+[source,sh]
+----
+fontist install "segoe ui"
+----
+
+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':
+----
+
+== Install a formula
+
+Formula is a recipe how to download a particular font. In general, a formula
+contains several fonts.
+
+To install a whole formula with all fonts it contains, use its
+https://github.com/fontist/formulas/tree/v3/Formulas[filename] (or path if it's
+in a subdirectory) without the ".yml" extension:
+
+[source,sh]
+----
+fontist install --formula google/noto_sans
+----
+
+For more information please see the project
+https://github.com/fontist/fontist#usage-of-the-fontist-command-line-interface[README].

docs/usage/ci.adoc

@@ -0,0 +1,40 @@
+---
+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"
+----

docs/usage/formula.adoc

@@ -0,0 +1,71 @@
+---
+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 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"
+----