From 20983f3643f60e4c9ac769bc11189491042aae4a Mon Sep 17 00:00:00 2001 From: Nicolas Mailhot Date: Nov 16 2019 17:10:11 +0000 Subject: [PATCH 1/14] Fonts packaging policy rewrite It should be clearer, more opiniated, and take into account: – updates of The OpenType standard – variable fonts – web fonts – upstream depreciation of non OpenType formats: final stages of the Harfbuzz consolidation decided at the 2006 Text Layout summit https://www.freedesktop.org/wiki/TextLayout/ – appstream & fonts – weak dependencies – and probably more I forget here It is based on the new fonts-rpm-macros project for automation: https://pagure.io/fonts-rpm-macros/ This project builds on tooling enhancements in redhat-rpm-config and rpm itself, done during the past two years for the Forge and Go sets of packaging macros. It started as a fork of fontpackages, which is the core of our current fonts packaging guidelines. It will require putting the fonts-srpm-macros package in the default build root, like is done for other domain-specific packaging macro sets. Major additions: – better documentation (clearer and more complete) – better automation (less packager hassle for better and more complete results) Major removals: – tools and scripts – fixing metadata with ttname Mostly because no one seems willing to maintain those scripts, or port ttname to python 3. --- diff --git a/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-0-simple.spec b/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-0-simple.spec new file mode 100644 index 0000000..9fed5b2 --- /dev/null +++ b/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-0-simple.spec @@ -0,0 +1,91 @@ +# Packaging template: basic single-family fonts packaging. +# +# SPDX-License-Identifier: MIT +# +# This template documents the minimal set of spec declarations, necessary to +# package a single font family, from a single dedicated source archive. +# +# It is part of the following set of packaging templates: +# “fonts-0-simple”: basic single-family fonts packaging +# “fonts-1-full”: less common patterns for single-family fonts packaging +# “fonts-2-multi”: multi-family fonts packaging +# “fonts-3-sub”: packaging fonts, released as part of something else +# +# A font family is composed of font files, that share a single design, and +# differ ONLY in: +# — Weight Bold, Black… +# – Width∕Stretch Narrow, Condensed, Expanded… +# — Slope/Slant Italic, Oblique +# Optical sizing Caption… +# +# Those parameters correspond to the default axes of OpenType variable fonts: +# https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg#registered-axis-tags +# The variable fonts model is an extension of the WWS model described in the +# WPF Font Selection Model whitepaper (2007): +# https://msdnshared.blob.core.windows.net/media/MSDNBlogsFS/prod.evol.blogs.msdn.com/CommunityServer.Components.PostAttachments/00/02/24/90/36/WPF%20Font%20Selection%20Model.pdf +# +# Do not rely on the naming upstream chose, to define family boundaries, it +# will often be wrong. +# +# Declaration order is chosen to limit divergence between those templates, and +# simplify cut and pasting. +# +Version: +Release: +URL: + +# The identifier of the entity, that released the font family. +%global foundry +# The font family license identifier. Adjust as necessary. The OFL is our +# recommended font license. +%global fontlicense OFL +# +# The following directives are lists of space-separated shell globs +# – matching files associated with the font family, +# – as they exist in the build root, +# — at the end of the %build stage: +# – legal files (licensing…) +%global fontlicenses OFL.txt +# – documentation files +%global fontdocs *.txt +# – exclusions from the ”fontdocs” list +%global fontdocsex %{fontlicenses} + +# The human-friendly font family name, whitespace included, restricted to the +# the Basic Latin Unicode block. +%global fontfamily +%global fontsummary +# +# More shell glob lists: +# – font family files +%global fonts *.otf +# – fontconfig files +%global fontconfs %{SOURCE10} +# +# A multi-line description block for the generated package. +%global fontdescription %{expand: +} + +Source0: +# Adjust as necessary. Keeping the filename in sync with the package name is a good idea. +# See the fontconfig templates in fonts-rpm-templates for information on how to +# write good fontconfig files and choose the correct priority [number]. +Source10: [number]-%{fontpkgname}.conf + +%fontpkg + +%prep +%setup + +%build +%fontbuild + +%install +%fontinstall + +%check +%fontcheck + +%fontfiles + +%changelog diff --git a/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-1-full.spec b/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-1-full.spec new file mode 100644 index 0000000..8c74b11 --- /dev/null +++ b/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-1-full.spec @@ -0,0 +1,95 @@ +# Packaging template: less common patterns for single-family fonts packaging. +# +# SPDX-License-Identifier: MIT +# +# This template documents less common spec declarations, used when packaging a +# single font family, from a single dedicated source archive. +# +# It is part of the following set of packaging templates: +# “fonts-0-simple”: basic single-family fonts packaging +# “fonts-1-full”: less common patterns for single-family fonts packaging +# “fonts-2-multi”: multi-family fonts packaging +# “fonts-3-sub”: packaging fonts, released as part of something else +# +Version: +Release: +URL: + +%global foundry +%global fontlicense OFL +# +# The following directives are lists of space-separated shell globs +# – matching files associated with the font family, +# – as they exist in the build root, +# — at the end of the %build stage: +# – legal files (licensing…) +%global fontlicenses OFL.txt +# – exclusions from the “fontlicenses” list +%global fontlicensesex +# – documentation files +%global fontdocs +# – exclusions from the “fontdocs” list +%global fontdocsex %{fontlicenses} + +%global fontfamily +%global fontsummary +# A container for additional subpackage declarations. +%global fontpkgheader %{expand: +Obsoletes: +} +# +# More shell glob lists: +# – font family files +%global fonts +# – exclusions from the “fonts” list) +%global fontsex +# – fontconfig files +%global fontconfs %{SOURCE10} +# – exclusions from the “fontconfs” list +%global fontconfsex +# – appstream files, if any (generated automatically otherwise) +%global fontappstreams +# – exclusions from the “fontappstreams” list +%global fontappstreamsex +# +%global fontdescription %{expand: +} + +Source0: +Source10: [number]-%{fontpkgname}.conf + +%fontpkg + +# Font creators love to bundle bulky documentation files, that show off their +# font (typically, as pdf specimens). Split those files in a dedicated optional +# doc package. +%package doc +Summary: %{name} optional documentation files +BuildArch: noarch +%description doc +This package provides optional documentation files shipped with %{name}. + +%prep +%setup +# Convert upstream files to UTF-8 and Unix end of lines if necessary +# Optional arguments: +# -e [encoding] source OS encoding (auto-detected otherwise) +# -n do not recode files, only adjust folding and end of lines +%linuxtext *.txt + +%build +%fontbuild + +%install +%fontinstall + +%check +%fontcheck + +%fontfiles + +%files doc +%license OFL.txt +%doc *.pdf + +%changelog diff --git a/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-2-multi.spec b/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-2-multi.spec new file mode 100644 index 0000000..a56646b --- /dev/null +++ b/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-2-multi.spec @@ -0,0 +1,132 @@ +# Packaging template: multi-family fonts packaging. +# +# SPDX-License-Identifier: MIT +# +# This template documents spec declarations, used when packaging multiple font +# families, from a single dedicated source archive. The source rpm is named +# after the first (main) font family). Look up “fonts-3-sub” when the source +# rpm needs to be named some other way. +# +# It is part of the following set of packaging templates: +# “fonts-0-simple”: basic single-family fonts packaging +# “fonts-1-full”: less common patterns for single-family fonts packaging +# “fonts-2-multi”: multi-family fonts packaging +# “fonts-3-sub”: packaging fonts, released as part of something else +# +Version: +Release: +URL: + +# The following declarations will be aliased to [variable]0 and reused for all +# generated *-fonts packages unless overriden by a specific [variable][number] +# declaration. +%global foundry +%global fontlicense +%global fontlicenses +%global fontlicensesex +%global fontdocs +%global fontdocsex %{fontlicenses} + +# A text block that can be reused as part of the description of each generated +# subpackage. +%global common_description %{expand: +} + +# Declaration for the subpackage containing the first font family. Also used as +# source rpm info. All the [variable]0 declarations are equivalent and aliased +# to [variable]. + +%global fontfamily0 +%global fontsummary0 +%global fontpkgheader0 %{expand: +} +%global fonts0 +%global fontsex0 +%global fontconfs0 %{SOURCE10} +%global fontconfsex0 +%global fontappstreams0 +%global fontappstreamsex0 +%global fontdescription0 %{expand: +%{common_description} +Additional text…} + +# Declaration for the subpackage containing the second font family. +%global fontfamily1 +%global fontsummary1 +%global fontpkgheader1 %{expand: +} +%global fonts1 +%global fontsex1 +%global fontconfs1 %{SOURCE11} +%global fontconfsex1 +%global fontappstreams1 +%global fontappstreamsex1 +%global fontdescription1 %{expand: +%{common_description} +Other Additional text…} +# +# Continue as necessary… + +Source0: +Source10: [number]-%{fontpkgname0}.conf +Source11: [number]-%{fontpkgname1}.conf + +# “fontpkg” will generate the font subpackage headers corresponding to the +# elements declared above. +# “fontpkg” accepts the following selection arguments: +# – “-a” process everything +# – “-z [number]” process a specific declaration block +# If no flag is specified it will only process the zero/nosuffix block. +%fontpkg -a + +# “fontmetapkg” will generate a font meta(sub)package header for all the font +# subpackages generated in this spec. Optional arguments: +# – “-n [name]” use [name] as metapackage name +# – “-s [variable]” use the content of [variable] as metapackage summary +# – “-d [variable]” use the content of [variable] as metapackage description +# – “-z [numbers]” restrict metapackaging to [numbers] comma-separated list +# of font package suffixes +%fontmetapkg + +%package doc +Summary: %{name} optional documentation files +BuildArch: noarch +%description doc +This package provides optional documentation files shipped with %{name}. + +%prep +%setup +%linuxtext *.txt + +%build +# “fontbuild” accepts the usual selection arguments: +# – “-a” process everything +# – “-z [number]” process a specific declaration block +# If no flag is specified it will only process the zero/nosuffix block. +%fontbuild -a + +%install +# “fontinstall” accepts the usual selection arguments: +# – “-a” process everything +# – “-z [number]” process a specific declaration block +# If no flag is specified it will only process the zero/nosuffix block. +%fontinstall -a + +%check +# “fontcheck” accepts the usual selection arguments: +# – “-a” process everything +# – “-z [number]” process a specific declaration block +# If no flag is specified it will only process the zero/nosuffix block. +%fontcheck -a + +# “fontfiles” accepts the usual selection arguments: +# – “-a” process everything +# – “-z [number]” process a specific declaration block +# If no flag is specified it will only process the zero/nosuffix block +%fontfiles -a + +%files doc +%license +%doc + +%changelog diff --git a/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-3-sub.spec b/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-3-sub.spec new file mode 100644 index 0000000..061db1d --- /dev/null +++ b/guidelines/modules/ROOT/examples/fonts/spectemplate-fonts-3-sub.spec @@ -0,0 +1,108 @@ +# Packaging template: packaging fonts, released as part of something else +# +# SPDX-License-Identifier: MIT +# +# This template documents spec declarations, used when packaging one or several +# font families from a source rpm which is not named after the first packaged +# font family: +# – either because the project name differs from the main font family name +# – or when the source archive and rpm are used to package more than fonts. +# +# It is part of the following set of packaging templates: +# “fonts-0-simple”: basic single-family fonts packaging +# “fonts-1-full”: less common patterns for single-family fonts packaging +# “fonts-2-multi”: multi-family fonts packaging +# “fonts-3-sub”: packaging fonts, released as part of something else +# +# The packaging style is identical to the one documented in “fonts-2-multi”, +# EXCEPT it should not use the zero/nosuffix declaration block, as this block +# will attempt to generate source rpm declarations by default. +# +# Usually appropriate for fonts-only packages +BuildArch: noarch + +Version: +Release: +License: +URL: + +%global foundry +# If different from the main License +%global fontlicense +%global fontlicenses +%global fontlicensesex +%global fontdocs +%global fontdocsex %{fontlicenses} + +%global common_description %{expand: +} + +%global fontfamily1 +%global fontsummary1 +%global fontpkgheader1 %{expand: +} +%global fonts1 +%global fontsex1 +%global fontconfs1 %{SOURCE11} +%global fontconfsex1 +%global fontappstreams1 +%global fontappstreamsex1 +%global fontdescription1 %{expand: +%{common_description} +Additional text…} + +%global fontfamily2 +%global fontsummary2 +%global fontpkgheader2 %{expand: +} +%global fonts2 +%global fontsex2 +%global fontconfs2 %{SOURCE12} +%global fontconfsex2 +%global fontappstreams2 +%global fontappstreamsex2 +%global fontdescription2 %{expand: +%{common_description} +Other Additional text…} +# +# Continue as necessary… + +Source0: +Source11: [number]-%{fontpkgname1}.conf +Source12: [number]-%{fontpkgname2}.conf + +Name: +Summary: +%description +%wordwrap -v common_description + +%fontpkg -a + +%fontmetapkg + +%package doc +Summary: %{name} optional documentation files +BuildArch: noarch +%description doc +This package provides optional documentation files shipped with %{name}. + +%prep +%setup +%linuxtext *.txt + +%build +%fontbuild -a + +%install +%fontinstall -a + +%check +%fontcheck -a + +%fontfiles -a + +%files doc +%license +%doc + +%changelog diff --git a/guidelines/modules/ROOT/pages/FontsPolicy.adoc b/guidelines/modules/ROOT/pages/FontsPolicy.adoc index 1ee7bb4..303d7b2 100644 --- a/guidelines/modules/ROOT/pages/FontsPolicy.adoc +++ b/guidelines/modules/ROOT/pages/FontsPolicy.adoc @@ -1,156 +1,810 @@ -=== Legal considerations += Fonts +:toc: +:toclevels: 4 + +<> lists requirements for packaging font files in Fedora, in a short and easy to check form. <> lists special requirements. <> documents how to implement those requirements with the minimum packager effort. <> explains some guideline requirements. + +== Checklist + +=== Legal + +* [x] Font files MUST comply with our https://fedoraproject.org/wiki/Licensing:Main?rd=Licensing#Font_Licenses[licensing rules]. +* [x] Trademark uses MUST be authorized by their owners, +** trademarks may occur in font naming or font content (logos…). +* [x] Registered names or trademarks MUST NOT prevent downstream modifications, +** requiring a rename on significant modification is acceptable. + +=== Packaging unit: an ideal font family + +Because fonts upstreams are, on average, extremely messy, a large part of packaging fonts involves sorting files and fixing font file metadata to produce the consistent and reliable font catalog expected by applications and users. + +[IMPORTANT] +==== +.Font family +A **font family** is composed of *font files, that share a single design, and differ ONLY in*: +[horizontal] +Weight:: Bold, Black… +Width∕Stretch:: Narrow, Condensed, Expanded… +Slope/Slant:: Italic, Oblique +https://developer.microsoft.com/en-us/microsoft-edge/testdrive/demos/variable-fonts/#font-optical-sizing[Optical sizing]:: Caption… + +Those parameters correspond to the https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg#registered-axis-tags[default axes] of OpenType variable fonts. The variable fonts model is an extension of the **WWS** model described in the https://msdnshared.blob.core.windows.net/media/MSDNBlogsFS/prod.evol.blogs.msdn.com/CommunityServer.Components.PostAttachments/00/02/24/90/36/WPF%20Font%20Selection%20Model.pdf[WPF Font Selection Model] whitepaper (2007). +==== + +* [x] Packagers MUST apply the definition provided in this section to determine font family boundaries, +** it takes precedence over application support concerns, over upstream and packager habits and practices. + +See also the <> section. + +=== Font file formats + +[NOTE] +==== +.OpenType: one standard, four formats +https://en.wikipedia.org/wiki/OpenType[OpenType] uses an _SFNT_ container around bitmaps and outlines in _TT_ (`+*.ttf+`) or _CFF_ (`+*.otf+`) formats. Multiple fonts can be consolidated in a single collection (`+*.ttc+` or `+*.otc+`). +==== + +* [x] Font packages MUST contain font files in OpenType formats. +* [x] Other font formats MUST be converted to OpenType, +** except for fonts, intended to be used in the console (NOT a terminal emulator): see <>. + +[NOTE] +==== +.Font packages +A *font package*, is an installation (RPM) package, containing OpenType font files. It MAY be produced by a source (SRPM) package, that also produces other (font or non-font) packages. Other kinds of font packages are out of scope for this document. +==== + +* [x] A font family MUST NOT be packaged in multiple or mixed OpenType formats, +** except for variable font data, +** except when mixing is required, to achieve full symbol (glyph) coverage, +** except as an application workaround; see <>. +* [x] Both variable and non-variable OpenType font files, SHOULD be packaged, for a given font family. +* [x] OpenType format mixing SHOULD be justified in a comment within the `spec` file. +* [x] OpenType collection formats SHOULD be avoided. + +=== Fontconfig + +* [x] Font packages SHOULD include the fontconfig files, that define the selection and substitution rules applying to their font files, +** written by the packager if upstream does not provide them. +* [x] Fontconfig rules MUST rewrite `family` and `style` when they are not compliant with https://docs.microsoft.com/en-us/typography/opentype/spec/name#name-ids[OpenType WWS] rules: +** `family` MUST NOT contain _Weight_, _Width_ or _Slope_ attributes (ideal WWS family name, Name ID 21), +** `style` MUST contain only _Weight_, _Width_ or _Slope_ attributes (ideal WWS subfamily name, Name ID 22), +** refer to the https://msdnshared.blob.core.windows.net/media/MSDNBlogsFS/prod.evol.blogs.msdn.com/CommunityServer.Components.PostAttachments/00/02/24/90/36/WPF%20Font%20Selection%20Model.pdf[WPF Font Selection Model] whitepaper for extensive WWS attribute documentation, +** Name ID 21 & 22 fields may exist or not in the packaged font files, and may be correct or not. The packager MUST set the correct value at the fontconfig level if the value fontconfig extracts from font files is incorrect. +* [x] Fontconfig rules MUST rewrite `family` to remove format attributes when they exist, +** for exemple: `OT`, `TT`, `Variable`, `Graphite`, `G`, etc, +** except when <>; in that case the removal MUST only be done for the font package providing the default format. +* [x] Fontconfig rules MUST rewrite `family` to remove coverage attributes when they exist, +** for exemple: `Math`, `Emoji`, `Color Emoji`, `Hebrew`, `Arabic`, `Thai`, `LGC`, etc, +** except when several font files provide the same coverage, requiring a qualifier to distinguish between them; in that case the removal MUST be done for the default file, and other files MUST be treated as parts of separate font families. +* [x] Fontconfig rules MUST rewrite `fullname` to `