From aad685eacbcd5c2c671f94a9c1a689cf0685731b Mon Sep 17 00:00:00 2001 From: David Warring Date: Thu, 24 Aug 2023 09:46:39 +1200 Subject: [PATCH] Improve FontConfig documentation #27 Link to FontConfig doco. Better state that it's optional --- docs/PDF/Font/Loader.md | 61 +++++++++++++++++++------------------ docs/index.md | 4 +-- lib/PDF/Font/Loader.rakumod | 18 ++++++----- 3 files changed, 45 insertions(+), 38 deletions(-) diff --git a/docs/PDF/Font/Loader.md b/docs/PDF/Font/Loader.md index 61cd999..be56e2f 100644 --- 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; - -- or -- - $deja = load-font( :file ); - - # find/load system fonts; requires fontconfig - use PDF::Font::Loader :load-font, :find-font; - $deja = load-font( :family, :slant ); - my Str $file = find-font( :family, :slant ); - 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; +-- or -- +$deja = load-font( :file ); + +# find/load the best matching system font +# *** requires FontConfig *** +use PDF::Font::Loader :load-font, :find-font; +$deja = load-font( :family, :slant ); +my Str $file = find-font( :family, :slant ); +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; my $deja = PDF::Font::Loader.load-font: :family, :weight, :stretch :slant); -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 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 will select monospace fonts. ```raku use PDF::Font::Loader; diff --git a/docs/index.md b/docs/index.md index 4e94a1d..aeb08d9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,9 +19,9 @@ $deja = PDF::Font::Loader.load-font: :file; -- or -- $deja = load-font( :file ); -# 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, :slant ); my Str $file = find-font( :family, :slant ); my PDF::Content::FontObj $deja-vu = load-font: :$file; diff --git a/lib/PDF/Font/Loader.rakumod b/lib/PDF/Font/Loader.rakumod index bffe497..c59df6d 100644 --- 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 # 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 ); - # 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, :slant ); my Str $file = find-font( :family, :slant ); @@ -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, rather t my $vera = PDF::Font::Loader.load-font: :family; my $deja = PDF::Font::Loader.load-font: :family, :weight, :stretch :slant); -Loads a font by a fontconfig name and attributes. +Finds and loads the best-matching system font via L. -Note: Requires fontconfig to be installed on the system. +Note: This method requires the Raku L 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, C, or C =begin item C<:$core-font> -Bypass fontconfig and load matching L objects, rather than L objects (both perform the L role). +Bypass L and load matching L objects, rather than L objects (both perform the L 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. +A RFC-3066-style language tag. L will select only fonts whose character set matches the preferred lang. See also L. =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 will select monospace fonts. +Any additional options are treated as a L pattern attributes. For example `:spacing will select monospace fonts. =begin code :lang use PDF::Font::Loader;