Improve FontConfig documentation #27

Link to FontConfig doco. Better state that it's optional
pdf-raku · Aug 23, 2023 · aad685e · aad685e
1 parent e9f3879
commit aad685e
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 38 deletions.
diff --git a/docs/PDF/Font/Loader.md b/docs/PDF/Font/Loader.md
@@ -10,30 +10,33 @@ PDF::Font::Loader
 Synopsis
 ========
 
-    # load a font from a file
-    use PDF::Font::Loader :&load-font;
-    use PDF::Content::FontObj;
-
-    my PDF::Content::FontObj $deja;
-    $deja = PDF::Font::Loader.load-font: :file<t/fonts/DejaVuSans.ttf>;
-    -- or --
-    $deja = load-font( :file<t/fonts/DejaVuSans.ttf> );
-
-    # find/load system fonts; requires fontconfig
-    use PDF::Font::Loader :load-font, :find-font;
-    $deja = load-font( :family<DejaVu>, :slant<italic> );
-    my Str $file = find-font( :family<DejaVu>, :slant<italic> );
-    my PDF::Content::FontObj $deja-vu = load-font: :$file;
-
-    # use the font to add text to a PDF
-    use PDF::Lite;
-    my PDF::Lite $pdf .= new;
-    $pdf.add-page.text: {
-       .font = $deja, 12;
-       .text-position = [10, 600];
-       .say: 'Hello, world';
-    }
-    $pdf.save-as: "/tmp/example.pdf";
+```raku
+# load a font from a file
+use PDF::Font::Loader :&load-font;
+use PDF::Content::FontObj;
+
+my PDF::Content::FontObj $deja;
+$deja = PDF::Font::Loader.load-font: :file<t/fonts/DejaVuSans.ttf>;
+-- or --
+$deja = load-font( :file<t/fonts/DejaVuSans.ttf> );
+
+# find/load the best matching system font
+# *** requires FontConfig ***
+use PDF::Font::Loader :load-font, :find-font;
+$deja = load-font( :family<DejaVu>, :slant<italic> );
+my Str $file = find-font( :family<DejaVu>, :slant<italic> );
+my PDF::Content::FontObj $deja-vu = load-font: :$file;
+
+# use the font to add text to a PDF
+use PDF::Lite;
+my PDF::Lite $pdf .= new;
+$pdf.add-page.text: {
+   .font = $deja, 12;
+   .text-position = [10, 600];
+   .say: 'Hello, world';
+}
+$pdf.save-as: "/tmp/example.pdf";
+```
 
 Description
 -----------
@@ -110,9 +113,9 @@ parameters:
     my $vera = PDF::Font::Loader.load-font: :family<vera>;
     my $deja = PDF::Font::Loader.load-font: :family<Deja>, :weight<bold>, :stretch<condensed> :slant<italic>);
 
-Loads a font by a fontconfig name and attributes.
+Finds and loads the best-matching system font via [FontConfig](https://pdf-raku.github.io/FontConfig-raku/FontConfig).
 
-Note: Requires fontconfig to be installed on the system.
+Note: This method requires the Raku [FontConfig](https://pdf-raku.github.io/FontConfig-raku/FontConfig) module to be installed, unless the `:core-font` option is used, to load only PDF core fonts.
 
 parameters:
 
@@ -134,11 +137,11 @@ parameters:
 
   * `:$core-font`
 
-    Bypass fontconfig and load matching [PDF::Content::Font::CoreFont](https://pdf-raku.github.io/PDF-Content-raku/PDF/Content/Font/CoreFont) objects, rather than [PDF::Font::Loader::FontObj](https://pdf-raku.github.io/PDF-Font-Loader-raku/PDF/Font/Loader/FontObj) objects (both perform the [PDF::Content::FontObj](https://pdf-raku.github.io/PDF-Content-raku/PDF/Content/FontObj) role).
+    Bypass [FontConfig](https://pdf-raku.github.io/FontConfig-raku/FontConfig) and load matching [PDF::Content::Font::CoreFont](https://pdf-raku.github.io/PDF-Content-raku/PDF/Content/Font/CoreFont) objects, rather than [PDF::Font::Loader::FontObj](https://pdf-raku.github.io/PDF-Font-Loader-raku/PDF/Font/Loader/FontObj) objects (both perform the [PDF::Content::FontObj](https://pdf-raku.github.io/PDF-Content-raku/PDF/Content/FontObj) role).
 
   * `:$lang`
 
-    A RFC-3066-style language tag. `fontconfig` will select only fonts whose character set matches the preferred lang. See also [I18N::LangTags](https://modules.raku.org/dist/I18N::LangTags:cpan:UFOBAT).
+    A RFC-3066-style language tag. [FontConfig](https://pdf-raku.github.io/FontConfig-raku/FontConfig) will select only fonts whose character set matches the preferred lang. See also [I18N::LangTags](https://modules.raku.org/dist/I18N::LangTags:cpan:UFOBAT).
 
   * `*%props`
 
@@ -178,7 +181,7 @@ The `:all` option returns a sequence of all fonts, ordered best match first. Thi
 
 The `:limit($n)` is similar to `:all`, but returns at most the `$n` best matching fonts.
 
-Any additional options are treated as `FontConfig` pattern attributes. For example `:spacing<mono> will select monospace fonts.
+Any additional options are treated as a [FontConfig](https://pdf-raku.github.io/FontConfig-raku/FontConfig) pattern attributes. For example `:spacing<mono> will select monospace fonts.
 
 ```raku
 use PDF::Font::Loader;

diff --git a/docs/index.md b/docs/index.md
@@ -19,9 +19,9 @@ $deja = PDF::Font::Loader.load-font: :file<t/fonts/DejaVuSans.ttf>;
 -- or --
 $deja = load-font( :file<t/fonts/DejaVuSans.ttf> );
 
-# find/load system fonts; requires fontconfig
+# find/load the best matching system font
+# *** requires FontConfig ***
 use PDF::Font::Loader :load-font, :find-font;
-$deja = load-font( :family<DejaVu>, :slant<italic> );
 my Str $file = find-font( :family<DejaVu>, :slant<italic> );
 my PDF::Content::FontObj $deja-vu = load-font: :$file;
 

diff --git a/lib/PDF/Font/Loader.rakumod b/lib/PDF/Font/Loader.rakumod
@@ -63,7 +63,7 @@ class PDF::Font::Loader:ver<0.7.3> {
         $class.load-font: :$family, :$enc, |c;
     }
 
-    # resolve font name via fontconfig
+    # resolve font name via FontConfig
     multi method load-font($class is copy = $?CLASS: Str:D :$family!, PDF::COS::Dict :$dict, :$quiet, |c) is hidden-from-backtrace {
 	my Str:D $file = $class.find-font(:$family, |c)
 	    || do {
@@ -165,6 +165,7 @@ PDF::Font::Loader
 
 =head1 Synopsis
 
+ =begin code :lang<raku>
  # load a font from a file
  use PDF::Font::Loader :&load-font;
  use PDF::Content::FontObj;
@@ -174,7 +175,8 @@ PDF::Font::Loader
  -- or --
  $deja = load-font( :file<t/fonts/DejaVuSans.ttf> );
 
- # find/load system fonts; requires fontconfig
+ # find/load the best matching system font
+ # *** requires FontConfig ***
  use PDF::Font::Loader :load-font, :find-font;
  $deja = load-font( :family<DejaVu>, :slant<italic> );
  my Str $file = find-font( :family<DejaVu>, :slant<italic> );
@@ -189,6 +191,7 @@ PDF::Font::Loader
     .say: 'Hello, world';
  }
  $pdf.save-as: "/tmp/example.pdf";
+ =end code
 
 =head2 Description
 
@@ -274,9 +277,10 @@ Prefer to load simple Type1 objects as L<PDF::Content::Font::CoreFont>, rather t
  my $vera = PDF::Font::Loader.load-font: :family<vera>;
  my $deja = PDF::Font::Loader.load-font: :family<Deja>, :weight<bold>, :stretch<condensed> :slant<italic>);
 
-Loads a font by a fontconfig name and attributes.
+Finds and loads the best-matching system font via L<FontConfig>.
 
-Note: Requires fontconfig to be installed on the system.
+Note: This method requires the Raku L<FontConfig> module to be installed,
+unless the `:core-font` option is used, to load only PDF core fonts.
 
 parameters:
 =begin item
@@ -310,14 +314,14 @@ Font slant, one of: C<normal>, C<oblique>, or C<italic>
 =begin item
 C<:$core-font>
 
-Bypass fontconfig and load matching L<PDF::Content::Font::CoreFont> objects, rather than L<PDF::Font::Loader::FontObj> objects (both perform the L<PDF::Content::FontObj> role).
+Bypass L<FontConfig> and load matching L<PDF::Content::Font::CoreFont> objects, rather than L<PDF::Font::Loader::FontObj> objects (both perform the L<PDF::Content::FontObj> role).
 
 =end item
 
 =begin item
 C<:$lang>
 
-A RFC-3066-style language tag. `fontconfig` will select only fonts whose character set matches the preferred lang. See also L<I18N::LangTags|https://modules.raku.org/dist/I18N::LangTags:cpan:UFOBAT>.
+A RFC-3066-style language tag. L<FontConfig> will select only fonts whose character set matches the preferred lang. See also L<I18N::LangTags|https://modules.raku.org/dist/I18N::LangTags:cpan:UFOBAT>.
 
 =end item
 
@@ -362,7 +366,7 @@ The `:all` option returns a sequence of all fonts, ordered best match first. Thi
 
 The `:limit($n)` is similar to `:all`, but returns at most the `$n` best matching fonts.
 
-Any additional options are treated as `FontConfig` pattern attributes. For example `:spacing<mono> will select monospace fonts.
+Any additional options are treated as a L<FontConfig> pattern attributes. For example `:spacing<mono> will select monospace fonts.
 
 =begin code :lang<raku>
 use PDF::Font::Loader;