From 6d702f4056142606693e1ba7272d579fa87659ec Mon Sep 17 00:00:00 2001 From: Nicolas Mailhot Date: Feb 08 2020 15:00:27 +0000 Subject: Fonts: add foreword to explain the guidelines structure --- diff --git a/guidelines/modules/ROOT/pages/FontsPolicy.adoc b/guidelines/modules/ROOT/pages/FontsPolicy.adoc index 55f5ffa..9864e3f 100644 --- a/guidelines/modules/ROOT/pages/FontsPolicy.adoc +++ b/guidelines/modules/ROOT/pages/FontsPolicy.adoc @@ -2,7 +2,24 @@ :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. +== Foreword + +The bulk of Fedora software relies on OpenType compliance and was tested against compliant fonts. + +Unfortunately, most font makers feel the OpenType specification is a document written by “software people” for “software people”. They spurn its recommendations. They can not be relied upon to release fonts in a clean state, nor to fix the resulting technical problems, nor to provide useful advice. + +To enable the packaging of fonts by non experts, <> provides a list of sanity rules. Most are short unambiguous one liners, easy to understand and apply. Do read the list, even if it feels long. Unless your upstream is a model of discipline, you WILL need it. Avoid <> if you do not feel ambitious – here be dragons. + +Once the sorting is done, the rpm-specific part of fonts packaging is simple: + +* take our spec templates, +* fill in the blanks with descriptions and the file lists resulting from the sorting. + +Fedora automation will do the rest. + +<> provides in-depth documentation of those templates, and other operational tips. The operational tips are useful. The spec templates documentation, not so much. The templates are commented and will usually be self-explanatory. + +Lastly, <> provides some help, in case a third party attempts to confuse you. A lot of upstreams are dead set against applying OpenType recommendations. They will provide elaborate argumentation, on why the common rule does not apply to them. == Checklist @@ -311,10 +328,12 @@ include::{examplesdir}/fonts/after-fontconfig-fixes.txt[] … ----- -=== Packaging a single font family +=== Spec template documentation The `fonts-rpm-templates` package contains `spec` templates, corresponding to common fonts packaging needs. +==== Packaging a single font family + This is the simplest packaging pattern, when upstream releases: * a single font family, @@ -322,7 +341,7 @@ This is the simplest packaging pattern, when upstream releases: * in a single dedicated source archive, * without any specific difficulty. -==== Macros and variables +===== Macros and variables [IMPORTANT] ==== @@ -332,7 +351,7 @@ Changing the proposed line order will more often than not result in a `spec` fil Be aware that this particular order was selected after reworking a large pool of test files, to maximize commonalities, and reduce divergence between packaging situations. Reordering may still work but the result will be harder to review, refactor, and copy in other `spec` files. ==== -===== SRPM generic declarations +====== SRPM generic declarations This pattern starts with a block of traditional `spec` declarations: @@ -344,7 +363,7 @@ Release: URL: ---- -===== Shared font declarations +====== Shared font declarations Then it declares elements, that will be shared by all the packaged font families. Here, we only process one of those, but the block will be at the same place in the other patterns. @@ -374,7 +393,7 @@ Those identifiers are followed by variables, containing: %global fontdocsex %{fontlicenses} ---- -===== Family-specific font declarations +====== Family-specific font declarations This is followed by a family-specific declaration block. @@ -407,7 +426,7 @@ on clear, easy-to-perceive letterforms that will not be readily confused with one another.} ---- -===== Source declarations +====== Source declarations Then package sources are declared the usual way. @@ -426,7 +445,7 @@ Keeping fontconfig file names in sync with the package name is a good idea. Take Font package names will be automatically computed from the previous declarations, and put into the `%{fontpkgname}` variable. You MAY override this variable at need. However, needing an override usually indicates that either the upstream font naming is broken, or you’re trying to do something wrong. ==== -===== Remainer of the spec file +====== Remainer of the spec file All those declarations are used and processed in the rest of the `spec` file by the following macros: @@ -459,7 +478,7 @@ All those declarations are used and processed in the rest of the `spec` file by %changelog ---- -==== Annotated spec template +===== Annotated spec template Putting it all together: @@ -469,20 +488,20 @@ Putting it all together: include::{examplesdir}/fonts/spectemplate-fonts-0-simple.spec[] ---- -=== Packaging a single font family (advanced) +==== Packaging a single font family (advanced) Sometimes, packaging a font family requires a little more work, with the associated automation. You may need to complete the previous pattern. -==== Macros and variables +===== Macros and variables -===== Shared font declarations +====== Shared font declarations One more shell glob list: [horizontal] %{fontlicensesex}:: exclusions from the *%{fontlicenses}* list -===== Family-specific font declarations +====== Family-specific font declarations [horizontal] %{fontpkgheader}:: multi-line container for package header directives @@ -514,7 +533,7 @@ from the Russian Federal Agency for Press and Mass Communications.} %{fontappstreams}:: the font family _appstream_ files, if any; those files are generated automatically if not specified %{fontappstreamsex}:: exclusions from the *%{fontappstreams}* list -===== Remainer of the spec file +====== Remainer of the spec file Bulky documentation can be split in a separate subpackage @@ -541,7 +560,7 @@ Text files published for other systems may need recoding. * `-e [encoding]` source OS encoding (automatically detected otherwise) * `-n` do not recode files, only adjust folding and end of lines -==== Annotated spec template +===== Annotated spec template Putting it all together: @@ -551,13 +570,13 @@ Putting it all together: include::{examplesdir}/fonts/spectemplate-fonts-1-full.spec[] ---- -=== Packaging multiple font families +==== Packaging multiple font families Those patterns can be extended the following way, when packaging multiple font families, from a project named after the main packaged family. -==== Macros and variables +===== Macros and variables -===== Shared font declarations +====== Shared font declarations `%{foundry}`, `%{fontlicense}`, `%{fontlicensex}`, `%{fontdocs}` and `%{fontdocsex}` are applied to all font families, @@ -601,7 +620,7 @@ This package provides the grotesque sans-serif fixed-width IBM Plex Mono, a little something for developers, because monospace does not need to be monotone.} ---- -===== Family-specific font declarations +====== Family-specific font declarations * each font family is declared in a separate family-specific block, * each block is identified by a number, suffixed to the corresponding block variables, @@ -609,7 +628,7 @@ little something for developers, because monospace does not need to be monotone. * the zero-suffix block is used to generate SRPM metadata, * all the zero-suffix variables are aliased to no-suffix variables of the same name, and vice versa. -===== Packaging macros +====== Packaging macros * `%fontpkg`, `%fontbuild`, `%fontinstall`, `%fontcheck` and `%fontfiles` accept the following arguments: ** `-a` process everything @@ -640,7 +659,7 @@ Cyrillic. %fontmetapkg -n dejavu-lgc-fonts-all -s lgcmetasummary -d lgcmetadescription -z 4,5,6 ---- -==== Annotated spec template +===== Annotated spec template Putting it all together: @@ -650,7 +669,7 @@ Putting it all together: include::{examplesdir}/fonts/spectemplate-fonts-2-multi.spec[] ---- -=== Packaging font families, released as part of something else +==== Packaging font families, released as part of something else The last pattern concerns the packaging one or several font families from a source rpm which is not named after the first packaged font family: @@ -659,13 +678,13 @@ The last pattern concerns the packaging one or several font families from a sour It is almost identical to the previous one. -==== Macros and variables +===== Macros and variables -===== Family-specific font declarations +====== Family-specific font declarations Do not declare a zero/no-suffix family-specific block, as it will attempt to generate SRPM metadata, and collide with existing SRPM declarations. -==== Annotated spec template +===== Annotated spec template Putting it all together: