From ddd110b264bb9f1ae7b51ead88ae6c23cc94018b Mon Sep 17 00:00:00 2001 From: Nicolas Mailhot Date: Jan 14 2020 19:28:49 +0000 Subject: restructure fontconfig doc a little --- diff --git a/guidelines/modules/ROOT/pages/FontsPolicy.adoc b/guidelines/modules/ROOT/pages/FontsPolicy.adoc index af7a9b5..55f5ffa 100644 --- a/guidelines/modules/ROOT/pages/FontsPolicy.adoc +++ b/guidelines/modules/ROOT/pages/FontsPolicy.adoc @@ -246,25 +246,28 @@ Those macros and variables are defined in the `fonts-rpm-macros` package. The `f The `fonts-rpm-templates` package contains `fontconfig` templates, corresponding to common fonts packaging needs. -To verify the metadata of font files installed by a package named `${pkg}`: +Using fontconfig, you can help users and software make sense of broken font files. -.Checking the fontconfig state -[source,bash] ----- -fc-scan -f \ - %{family[0]};%{style[0]};%{fullname[0]};%{width};%{weight};%{slant};%{fontversion};%{file}\n" \ - /usr/share/fonts/${pkg} | sort -t ';' -k1,1d -k4,4n -k5,5n -k6,6n -k2,2d -k7,7dr \ - | uniq | column --separator ';' -t ----- -.Command output, before fixes ------ -include::{examplesdir}/fonts/before-fontconfig-fixes.txt[] -… ------ +[NOTE] +==== +.On brokenness and interoperability +Fixing may imply behaviour differences, with entities that chose another mitigation strategy. The root cause of those differences is the upstream release of files in a broken state. Producing daring glyph shapes is the designer prerogative. That artistic license does not extend to flouting technical conventions, software relies on. + +Upstream should always be given the chance to fix its files. If it does not care about our needs, fixing downstream is second best. Inflicting intact breakage on our users is always worst. +==== + +==== Some applications + +- The Foo project releases `Foo Narrow Oblique`. Because the font maker remembers early font formats only allowed 4-style family grouping (https://docs.microsoft.com/en-us/typography/opentype/spec/name#name-ids[Name ID] 1 and 2), it declares it as `family: Foo Narrow` and `style: Oblique`. The fontconfig rules for `Foo Narrow Oblique` MUST rewrite it to the https://docs.microsoft.com/en-us/typography/opentype/spec/namesmp[recommended] https://docs.microsoft.com/en-us/typography/opentype/spec/name#nid21[WWS-compliant] `family: Foo` and `style: Narrow Oblique` (Name ID 16/17 or 21/22). +- The Foo project releases the `Universal Foo` wide-coverage font family. To allow installing only part of this family, it splits it in `Universal Foo`, `Universal Foo Hebrew` and `Universal Foo Thai`. The fontconfig rules for `Universal Foo` MUST rewrite the `family` (and therefore `fullname`) for all `Universal Foo Hebrew` and `Universal Foo Thai` font files, so they declare `Universal Foo` instead. Fontconfig will present the result as a single wide-encoding family to applications, even if the files remain split on-disk, even if all of them are not installed. +- The Foo project releases `Foo Sans`. The fontconfig rules for `Foo Sans` SHOULD declare any missing glyph can be taken from the `sans-serif` generic font family. +- The GNOME project releases the `Bitstream Vera` set of font families; later the `DejaVu` project forks and extends those fonts. The fontconfig rules for `DejaVu Sans` SHOULD declare it can be substituted for `Bitstream Vera Sans`. +- Microsoft ships Windows with the `Arial` font family. Due to its long and wide availability, `Arial` is now used in many documents. However it can not be included in Free Desktop systems for licensing reasons. Red Hat commissions an `Arial` substitute, `Liberation Sans`, for use on Linux. Google commissions another `Arial` substiture, `Arimo`, for use on ChromeOS. The fontconfig rules for `Liberation Sans` SHOULD declare it can be substituted for both `Arial` and `Arimo`. -Using fontconfig, you can fix problems, and help users and software make sense of broken font files. The https://docs.microsoft.com/en-us/typography/opentype/spec/os2#usweightclass[OpenType] https://docs.microsoft.com/en-us/typography/opentype/spec/os2#uswidthclass[specification], the https://www.w3.org/TR/css-fonts-4/#font-weight-prop[CSS] https://www.w3.org/TR/css-fonts-4/#font-stretch-prop[specification] and the https://www.freedesktop.org/software/fontconfig/fontconfig-user.html[fontconfig manual] document the canonical mappings of style keywords. +==== Style naming +The https://docs.microsoft.com/en-us/typography/opentype/spec/os2#usweightclass[OpenType] https://docs.microsoft.com/en-us/typography/opentype/spec/os2#uswidthclass[specification], the https://www.w3.org/TR/css-fonts-4/#font-weight-prop[CSS] https://www.w3.org/TR/css-fonts-4/#font-stretch-prop[specification] and the https://www.freedesktop.org/software/fontconfig/fontconfig-user.html[fontconfig manual] document the canonical mappings of style keywords. Those mappings are not absolute. The addition of variable capabilities enabled the creation of new keywords and axes values, including in non variable font files. @@ -282,9 +285,24 @@ Additionnally: * [x] keywords SHOULD be assembled in `width weight slant` order in style names, for historical reasons, ** with the default `Regular` ommited except when alone. -Honoring technical conventions is required to satisfy the expectations of applications and users, and make their font use easier. +==== Checking results + +To verify the metadata of font files installed by a package named `${pkg}`: + +.Check command +[source,bash] +---- +fc-scan -f \ + %{family[0]};%{style[0]};%{fullname[0]};%{width};%{weight};%{slant};%{fontversion};%{file}\n" \ + /usr/share/fonts/${pkg} | sort -t ';' -k1,1d -k4,4n -k5,5n -k6,6n -k2,2d -k7,7dr \ + | uniq | column --separator ';' -t +---- -We understand that this fixing may produce annoying divergences, with systems that keep the breakage intact. That’s no reason to keep things broken in Fedora. The root cause of those divergences is the upstream release of files in a broken state. Producing daring glyph shapes is the designer prerogative. That artistic license does not extend to flouting technical conventions, software relies on. +.Command output, before fixes +----- +include::{examplesdir}/fonts/before-fontconfig-fixes.txt[] +… +----- .Command output, once fixed [source,options="nowrap"] @@ -749,14 +767,6 @@ The other decisions are just choosing good defaults for the font family. While f Remember that a lot of upstream naming decisions are taken to accomodate systems, that are missing an automatic font substition / font merging layer. The format and coverage information in `family` names is intended to help manual selection of font files. Our guidelines ask packagers to convert those to information fontconfig understands. Free Desktop systems can do a lot more, as long as the information provided to fontconfig is correct. -Exemples: - -- The Foo project releases `Foo Narrow Oblique`. Because upstream remembers early font formats only allowed 4-style family grouping (Name ID 1 and 2), it declares it as `family: Foo Narrow` and `style: Oblique`. The fontconfig rules for `Foo Narrow Oblique` MUST rewrite it in `family: Foo` and `style: Narrow Oblique` (Name ID 21 and 22). -- The Foo project releases the `Universal Foo` wide-coverage font family. To allow installing only part of this family, it splits it in `Universal Foo`, `Universal Foo Hebrew` and `Universal Foo Thai`. The fontconfig rules for `Universal Foo` MUST rewrite the `family` (and therefore `fullname`) for all `Universal Foo Hebrew` and `Universal Foo Thai` font files, so they declare `Universal Foo` instead. Fontconfig will present the result as a single wide-encoding family to applications, even if the files remain split on-disk, even if all of them are not installed. -- The Foo project releases `Foo Sans`. The fontconfig rules for `Foo Sans` SHOULD declare any missing glyph can be taken from the `sans-serif` generic font family. -- The GNOME project releases the `Bitstream Vera` set of font families; later the `DejaVu` project forks and extends those fonts. The fontconfig rules for `DejaVu Sans` SHOULD declare it can be substituted for `Bitstream Vera Sans`. -- Microsoft ships Windows with the `Arial` font family. Due to its long and wide availability, `Arial` is now used in many documents. However it can not be included in Free Desktop systems for licensing reasons. Red Hat commissions an `Arial` substitute, `Liberation Sans`, for use on Linux. Google commissions another `Arial` substiture, `Arimo`, for use on ChromeOS. The fontconfig rules for `Liberation Sans` SHOULD declare it can be substituted for both `Arial` and `Arimo`. - === Source (SRPM) package break-up As noted in the xref:index.adoc#bundling[Packaging Guidelines], Fedora packages should make every effort to avoid having multiple, separate, upstream projects bundled together in a single package. This applies equally to font packages.