diff --git a/_layouts/docs.html b/_layouts/docs.html index 20dd8f4..804bb3b 100644 --- a/_layouts/docs.html +++ b/_layouts/docs.html @@ -28,6 +28,8 @@ path: /usage/directory/ - title: How to proxy servers with Fontist? path: /usage/proxy/ + - title: How to use Fontist Ruby library? + path: /usage/ruby/ --- {{ content }} diff --git a/docs/usage.adoc b/docs/usage.adoc index 11a6e75..cdda8e3 100644 --- a/docs/usage.adoc +++ b/docs/usage.adoc @@ -5,4 +5,4 @@ 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. +link:ruby/[Ruby library]. This section describes how to use it with CLI. diff --git a/docs/usage/ruby.adoc b/docs/usage/ruby.adoc new file mode 100644 index 0000000..bc37ca8 --- /dev/null +++ b/docs/usage/ruby.adoc @@ -0,0 +1,240 @@ +--- +layout: docs +--- + += How to use Fontist Ruby library? + +In addition to the command-line interface Fontist can be used as a Ruby library. + +=== `Fontist::Font` + +The `Fontist::Font` is your go-to place to deal with any font using Fontist. + +This interface allows you to find a font or install a font. + +==== Finding a font + +The `Fontist::Font.find` interface can be used a find a font in your system. + +It will look into the operating system specific font directories, and also the +fontist specific `~/.fontist` directory. + +[source,ruby] +---- +Fontist::Font.find(name) +---- + +* If Fontist finds a font, then it will return the paths. + +* Otherwise, it will either raise an unsupported font error, or trigger display +of installation instructions for that specific font. + +==== Install a font + +The `Fontist::Font.install` interface can be used to install any supported font. + +This interface first checks if you already have that font installed or not and +if you do then it will return the paths. + +If you don't have a font but that font is supported by Fontist, then it will +download the font and copy it to `~/.fontist` directory and also return the +paths. + +[source,ruby] +---- +Fontist::Font.install(name, confirmation: "no") +---- + +If there are issues detected with the provided font, such as the font is not +supported, those errors would be raised. + +==== List all fonts + +The `Fontist::Font` interface exposes an interface to list all supported fonts. + +This might be useful if want to know the name of the font or the available +styles. You can do that by using: + +[source,ruby] +---- +Fontist::Font.all +---- + +The return values are `OpenStruct` objects, so you can easily do any other +operation you would do in any ruby object. + +=== `Fontist::Formula` + +The `fontist` gem internally usages the `Fontist::Formula` interface to find a +registered formula or fonts supported by any formula. Unless, you need to do +anything with that you shouldn't need to work with this interface directly. But +if you do then these are the public interface it offers. + +==== Find a formula + +The `Fontist::Formula.find` interface allows you to find any of the registered +formula. This interface takes a font name as an argument and it looks through +each of the registered formula that offers this font installation. Usages: + +[source,ruby] +---- +Fontist::Formula.find("Calibri") +---- + +This method will search and return a Fontist formula for the provided keyword +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 + +Normally, each font name can be associated with multiple styles or collection, +for example the `Calibri` font might contains a `regular`, `bold` or `italic` +styles fonts and if you want a interface that can return the complete list then +this is your friend. + +You can use it as following: + +[source,ruby] +---- +Fontist::Formula.find_fonts("Calibri") +---- + +==== List all formulas + +The `Fontist::Formula` interface exposes an interface to list all registered +font formula. This might be useful if want to know the name of the formula or +what type fonts can be installed using that formula. Usages: + +[source,ruby] +---- +Fontist::Formula.all +---- + +The return values are `OpenStruct` objects, so you can easily do any other +operation you would do in any ruby object. + +=== `Fontist::Manifest` + +==== Global options + +Fontist can be switched to use the preferred family names. This format was +used prior to v1.10. + +[source,ruby] +---- +Fontist.preferred_family = true +---- + +[[fontist-locations]] +==== `Fontist::Manifest::Locations` + +Fontist lets you find font locations from a defined manifest Hash in the +following format: + +[source,ruby] +---- +{ + "Segoe UI"=>["Regular", "Bold"], + "Roboto Mono"=>["Regular"] +} +---- + +Calling the following code returns a nested Hash with font paths and names. +Font name is useful to choose a specific font in a font collection file (TTC). + +[source,ruby] +---- +Fontist::Manifest::Locations.from_hash(manifest) +---- + +[source,ruby] +---- +{ + "Segoe UI"=> { + "Regular"=>{ + "full_name"=>"Segoe UI", + "paths"=>["/Users/user/.fontist/fonts/SEGOEUI.TTF"] + }, + "Bold"=>{ + "full_name"=>"Segoe UI Bold", + "paths"=>["/Users/user/.fontist/fonts/SEGOEUIB.TTF"] + } + }, + "Roboto Mono"=> { + "Regular"=>{ + "full_name"=>nil, + "paths"=>[] + } + } +} +---- + +[[fontist-install]] +==== `Fontist::Manifest::Install` + +Fontist lets you not only to obtain font locations but also to install fonts +from the manifest: + +[source,ruby] +---- +Fontist::Manifest::Install.from_hash(manifest, confirmation: "yes") +---- + +It will install fonts and return their locations: + +[source,ruby] +---- +{ + "Segoe UI"=> { + "Regular"=>{ + "full_name"=>"Segoe UI", + "paths"=>["/Users/user/.fontist/fonts/SEGOEUI.TTF"]}, + "Bold"=>{ + "full_name"=>"Segoe UI Bold", + "paths"=>["/Users/user/.fontist/fonts/SEGOEUIB.TTF"] + } + }, + "Roboto Mono"=> { + "Regular"=>{ + "full_name"=>"Roboto Mono Regular", + "paths"=>["/Users/user/.fontist/fonts/RobotoMono-VariableFont_wght.ttf"] + } + } +} +---- + +==== Support of YAML format + +Both commands support a YAML file as an input with a `from_file` method. For +example, if there is a `manifest.yml` file containing: + +[source,yaml] +---- +--- +Segoe UI: +- Regular +- Bold +Roboto Mono: +- Regular +---- + +Then the following calls would return font names and paths, as from the +`from_hash` method (see <> and <>). + +[source,ruby] +---- +Fontist::Manifest::Locations.from_file("manifest.yml") +Fontist::Manifest::Install.from_file("manifest.yml", confirmation: "yes") +---- + +=== `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 +---- +