From fbecabced2879d191d487f661e36dfa74f93f212 Mon Sep 17 00:00:00 2001
From: Benson Muite <benson_muite@emailplus.org>
Date: Aug 21 2025 15:47:45 +0000
Subject: [PATCH 1/2] Naming options when a foundry is not registered


https://github.com/weiweihuanghuang/fragment-mono/issues/9
---

diff --git a/guidelines/modules/ROOT/pages/FontsPolicy.adoc b/guidelines/modules/ROOT/pages/FontsPolicy.adoc
index 4f4bfca..f349013 100644
--- a/guidelines/modules/ROOT/pages/FontsPolicy.adoc
+++ b/guidelines/modules/ROOT/pages/FontsPolicy.adoc
@@ -366,7 +366,7 @@ URL:
 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.
 
 [horizontal]
-%\{foundry}:: an optional upstream identifier, when upstream publishes multiple font families, with consistent QA rules. Font families released by the same upstream will usually play well with one another. Marking them as such helps users choose good font package sets.
+%\{foundry}:: an optional upstream identifier, when upstream publishes multiple font families, with consistent QA rules. Font families released by the same upstream will usually play well with one another. Marking them as such helps users choose good font package sets.  If there is no registered foundry, the name or brandname of the typographer can be used instead provided it enables distinguishing the font.
 * for example, the https://fontlibrary.org/[Open Font Library] identifier is `oflb`.
 %\{fontlicense}:: the identifier of the font family license, according to our licensing rules.
 

From 086a16fca93ceea51fe0daff135f4b5fa55533ba Mon Sep 17 00:00:00 2001
From: Benson Muite <benson_muite@emailplus.org>
Date: Aug 21 2025 22:42:27 +0000
Subject: [PATCH 2/2] Break up long lines


---

diff --git a/guidelines/modules/ROOT/pages/FontsPolicy.adoc b/guidelines/modules/ROOT/pages/FontsPolicy.adoc
index f349013..9688c1e 100644
--- a/guidelines/modules/ROOT/pages/FontsPolicy.adoc
+++ b/guidelines/modules/ROOT/pages/FontsPolicy.adoc
@@ -4,9 +4,16 @@
 
 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 software-friendly state, nor to fix the resulting problems, nor to provide useful advice.
+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 software-friendly state,
+nor to fix the resulting problems, nor to provide useful advice.
 
-To enable the packaging of fonts by non experts, <<Checklist>> provides a list of sanity rules. Most are short unambiguous one liners, easy to understand and apply. Do read this list, even if it feels long. Unless your upstream is a model of discipline, you WILL need it. Avoid <<Exceptions>> if you do not feel ambitious – here be dragons.
+To enable the packaging of fonts by non experts, <<Checklist>> provides a list of sanity rules.
+Most are short unambiguous one liners, easy to understand and apply.
+Do read this list, even if it feels long.
+Unless your upstream is a model of discipline, you WILL need it.
+Avoid <<Exceptions>> if you do not feel ambitious – here be dragons.
 
 Once you sorted what to package using the checklist, the rpm-specific part of fonts packaging is simple:
 
@@ -15,9 +22,14 @@ Once you sorted what to package using the checklist, the rpm-specific part of fo
 
 Fedora automation will do the rest.
 
-<<Tooling>> 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.
+<<Tooling>> 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, <<Rationale>> 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.
+Lastly, <<Rationale>> 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
 
@@ -31,7 +43,9 @@ Lastly, <<Rationale>> provides some help, in case a third party attempts to conf
 
 === 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.
+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]
 ====
@@ -43,7 +57,9 @@ Width∕Stretch:: Narrow, Condensed, Expanded…
 Slope/Slant:: Italic, Oblique
 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.
+Those parameters correspond to the
+https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg#registered-axis-tags[default axes]
+of OpenType variable fonts.
 ====
 
 * [x] Packagers MUST apply the definition provided in this section to determine font family boundaries,
@@ -56,7 +72,9 @@ See also the <<Fontconfig>> section.
 [NOTE]
 ====
 .OpenType: one standard, five formats
-https://en.wikipedia.org/wiki/OpenType[OpenType] uses an _SFNT_ container around bitmaps (`+*.otb+`) and outlines in _TT_ (`+*.ttf+`) or _CFF_ (`+*.otf+`) formats. Multiple fonts can be consolidated in a single collection (`+*.ttc+` or `+*.otc+`).
+https://en.wikipedia.org/wiki/OpenType[OpenType] uses an _SFNT_ container around bitmaps (`+*.otb+`) and
+outlines in _TT_ (`+*.ttf+`) or _CFF_ (`+*.otf+`) formats.
+Multiple fonts can be consolidated in a single collection (`+*.ttc+` or `+*.otc+`).
 ====
 
 * [x] Other font formats MUST be converted to OpenType,
@@ -66,7 +84,9 @@ https://en.wikipedia.org/wiki/OpenType[OpenType] uses an _SFNT_ container around
 [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.
+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,
@@ -79,18 +99,24 @@ A *font package*, is an installation (RPM) package, containing OpenType font fil
 
 === Fontconfig
 
-* [x] Font packages SHOULD include the fontconfig files, that define the selection and substitution rules applying to their font files,
+* [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:
+* [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),
 **  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 example: `OT`, `TT`, `Variable`, `Graphite`, `G`, etc,
-** except when <<Packaging a font family in multiple OpenType formats; application support>>; in that case the removal MUST only be done for the font package providing the default format.
+** except when <<Packaging a font family in multiple OpenType formats; application support>>;
+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 example: `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.
+** 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 `<family> <style>` if it has a different value,
 ** either natively or as a result of previous rewrites,
 ** except for the default style, usually `Regular`, for which `fullname` = `<family>`.
@@ -110,7 +136,9 @@ A *font package*, is an installation (RPM) package, containing OpenType font fil
 * [x] Packagers SHOULD attempt upstreaming those fixes,
 ** make the font naming correct in the upstream font files,
 ** contribute the other fontconfig rules upstream, so they are distributed with the font files.
-* [x] Packagers SHOULD consult the fontconfig https://src.fedoraproject.org/rpms/fontconfig/[maintainer] and https://lists.freedesktop.org/mailman/listinfo/fontconfig[mailing list] when in doubt,
+* [x] Packagers SHOULD consult the fontconfig
+https://src.fedoraproject.org/rpms/fontconfig/[maintainer] and
+https://lists.freedesktop.org/mailman/listinfo/fontconfig[mailing list] when in doubt,
 ** to get guidance and identify real-world tricky cases that call for fontconfig evolutions.
 
 See also the <<Tooling>> section for fontconfig syntax guidance.
@@ -130,10 +158,15 @@ See also the <<Tooling>> section for fontconfig syntax guidance.
 ** all the files that, after fontconfig fixing,
 *** share the same `family` value: `family` = `<common family>`
 *** or differ only in optical sizing: `family` = `<common family> <optical sizing attribute>`,
-** except when released as un-coordinated sources, that are easier to track in separate `spec` files,
-** except for huge families, that consume a lot of storage space; huge font families MAY be broken up in coverage-specific font packages,
+** except when released as un-coordinated sources,
+that are easier to track in separate `spec` files,
+** except for huge families, that consume a lot of storage space;
+huge font families MAY be broken up in coverage-specific font packages,
 ** see <<Assembling same-family font packages>>.
-* [x] Font packages MUST limit themsemselves to OpenType font files and their associated https://www.fontconfig.org/[fontconfig], https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Fonts.html[appstream], legal and documentation files,
+* [x] Font packages MUST limit themsemselves to OpenType font files and their associated
+https://www.fontconfig.org/[fontconfig],
+https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Fonts.html[appstream],
+legal and documentation files,
 ** for reasonable non-bulky interpretations of documentation files.
 
 See also the <<Tooling>> section.
@@ -142,9 +175,18 @@ See also the <<Tooling>> section.
 ====
 .Other upstream files
 
-Support for other font systems, for specific applications, non-OpenType font formats, bulky documentation, TEX, CSS, or JSON files… MUST be split in separate non-font packages, that SHOULD install outside `/usr/share/fonts`, and MUST NOT use `_<something>_-fonts` naming.
-
-For compatibility reasons, OpenType font files MAY be exposed outside `/usr/share/fonts`, with the rest of upstream files, using symbolic links. Those symbolic links SHOULD NOT be installed by the font package itself.
+Support for other font systems,
+for specific applications,
+non-OpenType font formats,
+bulky documentation, TEX, CSS, or JSON files…
+MUST be split in separate non-font packages,
+that SHOULD install outside `/usr/share/fonts`,
+and MUST NOT use `_<something>_-fonts` naming.
+
+For compatibility reasons,
+OpenType font files MAY be exposed outside `/usr/share/fonts`,
+with the rest of upstream files, using symbolic links.
+Those symbolic links SHOULD NOT be installed by the font package itself.
 ====
 
 === Building
@@ -155,30 +197,48 @@ For compatibility reasons, OpenType font files MAY be exposed outside `/usr/shar
 
 === Dependencies in font packages
 
-* [x] Font packages MAY require or supplement other font packages, when they contain the same font family,
+* [x] Font packages MAY require or supplement other font packages,
+when they contain the same font family,
 ** as defined in <<Assembling same-family font packages>>.
-* [x] Font packages SHOULD recommend other font packages, when they contain a reused font family,
+* [x] Font packages SHOULD recommend other font packages,
+when they contain a reused font family,
 ** as defined in <<Assembling different-family font packages: partial designs>>.
-* [x] Font packages SHOULD suggest other font packages, when they contain a better version of the same font family,
-** better: more complete coverage, later enhanced fork, canonical version of the design…
-* [x] Font packages MAY suggest or enhance font packages, containing other font families,
-** this should be used sparsely, to avoid imposing packager preferences on users.
-* [x] Font packages SHOULD depend on the basic font support package set, defined in the font packaging templates and macros.
-* [x] Except for the preceding, font packages MUST NOT depend, in any form, on any other package.
+* [x] Font packages SHOULD suggest other font packages,
+when they contain a better version of the same font family,
+** better: more complete coverage,
+later enhanced fork,
+canonical version of the design…
+* [x] Font packages MAY suggest or enhance font packages,
+containing other font families,
+** this should be used sparsely,
+to avoid imposing packager preferences on users.
+* [x] Font packages SHOULD depend on the basic font support package set,
+defined in the font packaging templates and macros.
+* [x] Except for the preceding,
+font packages MUST NOT depend,
+in any form,
+on any other package.
 
 === Dependencies to font packages in other packages
 
 * [x] Non-font packages MAY suggest or recommend font packages,
-** the weakest `Suggests` form is preferred over `Recommends`, except in presence of strong pre-existing user habits.
+** the weakest `Suggests` form is preferred over `Recommends`,
+except in presence of strong pre-existing user habits.
 * [x] Non-font packages SHOULD use the `font()` namespace to depend on font packages.
-* [x] Non-font packages SHOULD NOT require specific font packages, and leave font selection to end-users,
+* [x] Non-font packages SHOULD NOT require specific font packages,
+and leave font selection to end-users,
 ** except when the packaged software actually relies on those specific font packages,
-** except for convenience font metapackages, as defined in <<Assembling different-family font packages: font metapackages>>.
+** except for convenience font metapackages,
+as defined in <<Assembling different-family font packages: font metapackages>>.
 * [x] Non-font packages SHOULD require `font(:lang=en)` when they fail in the absence of system fonts,
 ** hardcoding specific font families is not future-proof.
-* [x] Non-font packages MAY require font packages by name, when relying on specific on-disk font file paths,
+* [x] Non-font packages MAY require font packages by name,
+when relying on specific on-disk font file paths,
 ** ie when software is not `fontconfig`-aware,
-** however, there is no obligation for font packagers to keep those paths stable between releases. Font file formats are flexible, making any on-disk file layout temporary. Converting applications to fontconfig use is best.
+** however, there is no obligation for font packagers to keep those paths stable between releases.
+Font file formats are flexible,
+making any on-disk file layout temporary.
+Converting applications to fontconfig use is best.
 
 === Assembling different-family font packages: partial designs
 
@@ -188,8 +248,11 @@ For compatibility reasons, OpenType font files MAY be exposed outside `/usr/shar
 
 Because font creation is hard work, font designers will often publish partial new designs:
 
-* they will copy part of an existing design, then add to it; this is common practice when designing a non-latin-oriented font family – the latin core is taken from an existing family,
-* or they will publish their additions as a separate font family, documenting it should be used with the original family; this is common practice when publishing alternate designs for part of a font.
+* they will copy part of an existing design, then add to it;
+this is common practice when designing a non-latin-oriented font family – the latin core is taken from an existing family,
+* or they will publish their additions as a separate font family,
+documenting it should be used with the original family;
+this is common practice when publishing alternate designs for part of a font.
 ====
 
 When packaging such a partial design:
@@ -222,18 +285,26 @@ When packaging such a partial design:
 [NOTE]
 ====
 .Console fonts
-As long as https://kbd-project.org/[kbd] and https://www.freedesktop.org/software/systemd/man/vconsole.conf.html[systemd-vconsole] can not use the same file formats as the rest of the system, bitmap console fonts are effectively private kbd resources. They will be ignored in the rest of this document. It does not apply to them.
+As long as https://kbd-project.org/[kbd] and
+https://www.freedesktop.org/software/systemd/man/vconsole.conf.html[systemd-vconsole]
+can not use the same file formats as the rest of the system,
+bitmap console fonts are effectively private kbd resources.
+They will be ignored in the rest of this document.
+It does not apply to them.
 ====
 
 === Assembling same-family font packages
 
-* [x] A font family MUST NOT be split over several font packages, unless one of the exceptions listed above applies.
+* [x] A font family MUST NOT be split over several font packages,
+unless one of the exceptions listed above applies.
 
 When a font family is split over a set of several font packages:
 
 * [x] Involved packagers MUST choose a core font package.
-* [x] This core package SHOULD contain the font files, necessary to provide a minimal scope of the font family.
-* [x] This core package MAY contain fontconfig rules, for all the font files composinng the font family,
+* [x] This core package SHOULD contain the font files,
+necessary to provide a minimal scope of the font family.
+* [x] This core package MAY contain fontconfig rules,
+for all the font files composinng the font family,
 ** fontconfig ignores rules that do not match installed files.
 * [x] This core package MUST be named as if it contained the whole font family.
 * [x] This core package MUST NOT require any other package in the set.
@@ -245,21 +316,33 @@ When a font family is split over a set of several font packages:
 
 === Packaging a font family in multiple OpenType formats; application support
 
-* [x] Packagers MUST make a reasonable effort, to get applications that do not support all OpenType formats, fixed upstream.
-* [x] If that fails, as a last ressort, packagers MAY request a https://pagure.io/fesco[FESCo exemption], to package a limited number of font families in multiple OpenType formats.
-* [x] Packagers MUST ensure that the resulting additional font data, is separated in distinct font packages,
+* [x] Packagers MUST make a reasonable effort,
+to get applications that do not support all OpenType formats,
+fixed upstream.
+* [x] If that fails, as a last ressort,
+packagers MAY request a https://pagure.io/fesco[FESCo exemption],
+to package a limited number of font families in multiple OpenType formats.
+* [x] Packagers MUST ensure that the resulting additional font data,
+is separated in distinct font packages,
 ** that the average Fedora user can install those font families in a single format,
-** that he is not left wondering, which package to install.
+** that he is not left wondering,
+which package to install.
 
 == Tooling
 
-Creating font packages by hand can be extremely repetitive, error-prone and labor-intensive. Therefore, fonts packaging is heavily automated. It relies on numerous macros and variables to define what goes where.
+Creating font packages by hand can be extremely repetitive,
+error-prone and labor-intensive.
+Therefore, fonts packaging is heavily automated.
+It relies on numerous macros and variables to define what goes where.
 
-Those macros and variables are defined in the `fonts-rpm-macros` package. The `fonts-rpm-templates` package contains `spec` and `fontconfig` templates, corresponding to common fonts packaging needs.
+Those macros and variables are defined in the `fonts-rpm-macros` package.
+The `fonts-rpm-templates` package contains `spec` and `fontconfig` templates,
+corresponding to common fonts packaging needs.
 
 === Fontconfig
 
-The `fonts-rpm-templates` package contains `fontconfig` templates, corresponding to common fonts packaging needs.
+The `fonts-rpm-templates` package contains `fontconfig` templates,
+corresponding to common fonts packaging needs.
 
 Using fontconfig, you can help users and software make sense of broken font files.
 
@@ -267,24 +350,60 @@ Using fontconfig, you can help users and software make sense of broken font file
 [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.
+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`.
+-  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`.
 
 ==== 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.
+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.
+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.
 
 Nevertheless, the OpenType specification requires correlating the new capabilities with the traditional keyword scale:
 
@@ -344,9 +463,13 @@ This is the simplest packaging pattern, when upstream releases:
 [IMPORTANT]
 ====
 .Declaration ordering
-Changing the proposed line order will more often than not result in a `spec` file that still works. That may be tempting, since the suggested order is far from traditional.
+Changing the proposed line order will more often than not result in a `spec` file that still works.
+That may be tempting, since the suggested order is far from traditional.
 
-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.
+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
@@ -363,10 +486,17 @@ URL:
 
 ====== 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.
+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.
 
 [horizontal]
-%\{foundry}:: an optional upstream identifier, when upstream publishes multiple font families, with consistent QA rules. Font families released by the same upstream will usually play well with one another. Marking them as such helps users choose good font package sets.  If there is no registered foundry, the name or brandname of the typographer can be used instead provided it enables distinguishing the font.
+%\{foundry}:: an optional upstream identifier,
+when upstream publishes multiple font families, with consistent QA rules.
+Font families released by the same upstream will usually play well with one another.
+Marking them as such helps users choose good font package sets.
+If there is no registered foundry,
+the name or brandname of the typographer can be used instead provided it enables distinguishing the font.
 * for example, the https://fontlibrary.org/[Open Font Library] identifier is `oflb`.
 %\{fontlicense}:: the identifier of the font family license, according to our licensing rules.
 
@@ -435,12 +565,18 @@ Source:
 Source10: [number]-%{fontpkgname}.conf
 ----
 
-Keeping fontconfig file names in sync with the package name is a good idea. Take a look at the templates in `fonts-rpm-templates` for information on how to write good fontconfig files and choose the correct priority `[number]`.
+Keeping fontconfig file names in sync with the package name is a good idea.
+Take a look at the templates in `fonts-rpm-templates` for information on how to write good fontconfig files
+and choose the correct priority `[number]`.
 
 [NOTE]
 ====
 .Font package names
-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.
+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
@@ -488,7 +624,8 @@ include::{examplesdir}/fonts/spectemplate-fonts-0-simple.spec[]
 
 ==== 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.
+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
 
@@ -554,7 +691,8 @@ This package provides optional documentation files shipped with %{name}.
 Text files published for other systems may need recoding.
 
 [horizontal]
-%linuxtext:: allows converting upstream files to UTF-8 and Unix end of lines if necessary. It takes the following optional arguments:
+%linuxtext:: allows converting upstream files to UTF-8 and Unix end of lines if necessary.
+It takes the following optional arguments:
 * `-e [encoding]` source OS encoding (automatically detected otherwise)
 * `-n`            do not recode files, only adjust folding and end of lines
 
@@ -570,7 +708,9 @@ include::{examplesdir}/fonts/spectemplate-fonts-1-full.spec[]
 
 ==== 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.
+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
 
@@ -669,7 +809,8 @@ include::{examplesdir}/fonts/spectemplate-fonts-2-multi.spec[]
 
 ==== 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:
+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:
 
 * 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.
@@ -680,7 +821,9 @@ It is almost identical to the previous one.
 
 ====== 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.
+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
 
@@ -696,7 +839,8 @@ include::{examplesdir}/fonts/spectemplate-fonts-3-sub.spec[]
 
 === Legal
 
-Fonts are subject to specific copyright, trademark and patent laws. Reading our https://fedoraproject.org/wiki/Legal_considerations_for_fonts[fonts legal page] is recommended.
+Fonts are subject to specific copyright, trademark and patent laws.
+Reading our https://fedoraproject.org/wiki/Legal_considerations_for_fonts[fonts legal page] is recommended.
 
 === Packaging unit: an ideal font family
 
@@ -708,9 +852,15 @@ Font upstreams will often deviate from the OpenType model in their naming:
 * because upstreams may attempt to workaround problems in the legacy proprietary applications available on their platform of choice,
 * because upstreams may be dormant, and miss changes in the OpenType specification, or use font creation tools that have still not implemented those changes.
 
-Those deviations occur in upstream file names and upstream font file metadata. Upstream choices in those elements can not be relied upon to define useful and consistent font family boundaries.
+Those deviations occur in upstream file names and upstream font file metadata.
+Upstream choices in those elements can not be relied upon to define useful and consistent font family boundaries.
 
-Shared font files, are no place to workaround application-specific problems. Fedora must apply the OpenType standard strictly, to enable the leveraging by Free Desktop applications, of the application capabilities this standard was designed to unlock. One can always find bits of code not updated to take into account decades-old changes in font standards. Waiting on this code to be fixed is being last, not _First_.
+Shared font files, are no place to workaround application-specific problems.
+Fedora must apply the OpenType standard strictly,
+to enable the leveraging by Free Desktop applications,
+of the application capabilities this standard was designed to unlock.
+One can always find bits of code not updated to take into account decades-old changes in font standards.
+Waiting on this code to be fixed is being last, not _First_.
 
 === Font file formats
 
@@ -718,75 +868,162 @@ Shared font files, are no place to workaround application-specific problems. Fed
 
 ===== Variable fonts
 
-Application support for variable fonts is sparse right now. They can not replace older OpenType formats yet.
+Application support for variable fonts is sparse right now.
+They can not replace older OpenType formats yet.
 
 ===== TT versus CFF
 
-* OpenType TT boasts https://en.wikipedia.org/wiki/Font_hinting[hinting] capabilities, but hinting is labor-intensive and does not scale to large-encoding fonts. In practice modern TT fonts are hinted using automated processes similar to the auto-hinter present in https://www.freetype.org/[freetype].
-* OpenType CFF lacks hinting but uses the excellent rasterizer Adobe https://opensource.googleblog.com/2013/05/got-cff.html[contributed] to freetype, achieving similar results.
+* OpenType TT boasts https://en.wikipedia.org/wiki/Font_hinting[hinting] capabilities,
+but hinting is labor-intensive and does not scale to large-encoding fonts.
+In practice modern TT fonts are hinted using automated processes similar to the auto-hinter present in
+https://www.freetype.org/[freetype].
+* OpenType CFF lacks hinting but uses the excellent rasterizer Adobe
+https://opensource.googleblog.com/2013/05/got-cff.html[contributed] to freetype,
+achieving similar results.
 * Low-resolution rendering is increasingly irrelevant with the replacement of 96dpi screens by 4K+ HiDPI hardware.
 
 Therefore, don’t use hinting as a format selection criterium, unless you’re sure a human actually proofed the result on a modern renderer, at the screen pixel densities exercised by Fedora users.
 
-Choose the OpenType format best supported upstream, typically the one produced by upstream’s preferred font creation toolchain. For historical reasons the math behind OpenType TT and OpenType CFF differs, converting from one to the other may introduce corner cases problems.
+Choose the OpenType format best supported upstream,
+typically the one produced by upstream’s preferred font creation toolchain.
+For historical reasons the math behind OpenType TT and OpenType CFF differs,
+converting from one to the other may introduce corner cases problems.
 
 ===== Collections
 
-While collection formats save some storage space, they introduce a high level of complexity packaging and application-side, make it impossible to install font families separately, and create a user-unfriendly environment.
+While collection formats save some storage space,
+they introduce a high level of complexity packaging and application-side,
+make it impossible to install font families separately,
+and create a user-unfriendly environment.
 
 Avoid packaging `+*.ttc+` and `+*.otc+` files unless left no choice by upstream.
 
 ==== Legacy deprecated formats
 
-Legacy formats are too limited to handle Unicode-level coverage, fail to declare their encoding, do not permit the kind of style selection expected in modern fonts, do not provide human-friendly naming layers, etc. They’re full of quirks and a source of (security) bugs in applications.
-
-In 2006, at the first https://www.freedesktop.org/wiki/TextLayout/[Text Layout] summit, all the major Free Desktop players agreed to converge on a unified text layout engine, built around the https://github.com/harfbuzz/harfbuzz[HarfBuzz] project and the OpenType format. As a result, modern Free Desktop applications and libraries https://bugzilla.redhat.com/show_bug.cgi?id=1753295[no] https://bugs.documentfoundation.org/show_bug.cgi?id=104701[longer] https://gitlab.gnome.org/GNOME/pango/issues/368[support] other formats.
-
-Use tools like https://fontforge.github.io/[fontforge] or https://fedoraproject.org/wiki/BitmapFontConversion[fonttosfnt] (provided by xorg-x11-font-utils) to https://gitlab.gnome.org/GNOME/pango/issues/386#note_568255[convert] legacy fonts to an OpenType format. Get it done upstream or script it within the `%build` section of your `spec` file.
-
-Like any other format conversion it will need some proofing. That’s why packaging fonts in a *single* *correct* format is a requisite for reliable text rendering.
+Legacy formats are too limited to handle Unicode-level coverage,
+fail to declare their encoding,
+do not permit the kind of style selection expected in modern fonts,
+do not provide human-friendly naming layers, etc.
+They’re full of quirks and a source of (security) bugs in applications.
+
+In 2006,
+at the first https://www.freedesktop.org/wiki/TextLayout/[Text Layout] summit,
+all the major Free Desktop players agreed to converge on a unified text layout engine,
+built around the https://github.com/harfbuzz/harfbuzz[HarfBuzz] project and the OpenType format.
+As a result,
+modern Free Desktop applications and libraries
+https://bugzilla.redhat.com/show_bug.cgi?id=1753295[no]
+https://bugs.documentfoundation.org/show_bug.cgi?id=104701[longer]
+https://gitlab.gnome.org/GNOME/pango/issues/368[support]
+other formats.
+
+Use tools like
+https://fontforge.github.io/[fontforge]
+or
+https://fedoraproject.org/wiki/BitmapFontConversion[fonttosfnt]
+(provided by xorg-x11-font-utils) to
+https://gitlab.gnome.org/GNOME/pango/issues/386#note_568255[convert]
+legacy fonts to an OpenType format.
+Get it done upstream or script it within the `%build` section of your `spec` file.
+
+Like any other format conversion it will need some proofing.
+That’s why packaging fonts in a *single* *correct* format is a requisite for reliable text rendering.
 
 ===== Web fonts
 
-Due to the limitations of the browsers that existed at the time, and due to the fear foundries had of widespread font piracy, initial support for web fonts used a hodgepole of obscure, broken and incomplete font formats (`svg`, `eot`, `woff`, etc).
+Due to the limitations of the browsers that existed at the time,
+and due to the fear foundries had of widespread font piracy,
+initial support for web fonts used a hodgepole of obscure,
+broken and incomplete font formats (`svg`, `eot`, `woff`, etc).
 
 All major browsers have been https://caniuse.com/#feat=ttf[fixed] long ago to accept OpenType fonts.
 
-Do not package web fonts except in OpenType format. If your upstream still religiously cargo-cults other formats in its CSS files, get those fixed.
-
-The only remotely useful web font format is `woff`. Its advantages compared to OpenType are marginal at best on a well-configured web server. The sole remaining reason for `woff` existence is to serve as a light form of DRM for proprietary fonts (Normal applications do not read `woff` files). That concern does not apply to Fedora. Fedora wants to _share_. Any so-called web font can be useful in https://fedoramagazine.org/tuning-your-bash-or-zsh-shell-in-workstation-and-silverblue/[other] parts of the distribution. That requires distributing fonts in a common generic format.
+Do not package web fonts except in OpenType format.
+If your upstream still religiously cargo-cults other formats in its CSS files,
+get those fixed.
+
+The only remotely useful web font format is `woff`.
+Its advantages compared to OpenType are marginal at best on a well-configured web server.
+The sole remaining reason for `woff` existence is to serve as a light form of DRM for proprietary fonts
+(Normal applications do not read `woff` files).
+That concern does not apply to Fedora.
+Fedora wants to _share_.
+Any so-called web font can be useful in
+https://fedoramagazine.org/tuning-your-bash-or-zsh-shell-in-workstation-and-silverblue/[other]
+parts of the distribution.
+That requires distributing fonts in a common generic format.
 
 ===== Postscript fonts
 
-The OpenType CFF outline format is derived from the one used in Postscript. It was designed by Adobe to permit lossless conversion of legacy Postscript fonts. The SFNT container used by OpenType is vastly more capable than the original PostScript format.
+The OpenType CFF outline format is derived from the one used in Postscript.
+It was designed by Adobe to permit lossless conversion of legacy Postscript fonts.
+The SFNT container used by OpenType is vastly more capable than the original PostScript format.
 
-Therefore, there’s no risk, and lots of advantages, in converting Postscript fonts. If their upstream does not want to bother, do not bother packaging the result.
+Therefore, there’s no risk, and lots of advantages, in converting Postscript fonts.
+If their upstream does not want to bother, do not bother packaging the result.
 
 ===== X11 core fonts
 
-Once upon a time every Linux GUI application used the so-called _Core fonts_ server-side X11 backend footnote:[Fonts accessed through the original _core_ X protocol, using tools like _mkfontdir_, _xfs_, _/etc/X11/fontpath.d/_, _XLFD_ strings, etc. See also this https://keithp.com/~keithp/talks/xtc2001/paper/[paper] written shortly before projects massively migrated to client-side fonts.]. It was riddled with problems. The FLOSS developers finally gave up on it, declared it legacy and broken by design, and moved to client-side font handling (fontconfig). Nowadays almost no modern Linux GUI application uses the _Core fonts_ backend. Few (if any) people are willing to fix its remaining bugs.
-
-Therefore, unless your font has previously been registered in _Core fonts_, and the problems triggered by this font hopefully fixed, you *SHOULD NOT* declare it there. This is especially true of fonts in modern OpenType formats.
-
-The users of this legacy backend won't thank you for destabilizing it with new fonts. They value stability. Otherwise they'd have moved to fontconfig like everyone else a long time ago.
+Once upon a time every Linux GUI application used the so-called _Core fonts_ server-side X11 backend
+footnote:[Fonts accessed through the original _core_ X protocol,
+using tools like _mkfontdir_, _xfs_, _/etc/X11/fontpath.d/_, _XLFD_ strings, etc.
+See also this https://keithp.com/~keithp/talks/xtc2001/paper/[paper]
+written shortly before projects massively migrated to client-side fonts.].
+It was riddled with problems.
+The FLOSS developers finally gave up on it, declared it legacy and broken by design,
+and moved to client-side font handling (fontconfig).
+Nowadays almost no modern Linux GUI application uses the _Core fonts_ backend.
+Few (if any) people are willing to fix its remaining bugs.
+
+Therefore, unless your font has previously been registered in _Core fonts_,
+and the problems triggered by this font hopefully fixed, you *SHOULD NOT* declare it there.
+This is especially true of fonts in modern OpenType formats.
+
+The users of this legacy backend won't thank you for destabilizing it with new fonts.
+They value stability.
+Otherwise they'd have moved to fontconfig like everyone else a long time ago.
 
 === Fontconfig
 
-Free Desktop systems rely on multiple upstreams to provide their fonts. They are heavily dependent on fontconfig to present a consistent user-friendly font pool in applications. High quality fontconfig rules are indispensable to permit easy substitution of font families, and to mask upstream messiness.
-
-Applying strict WWS rules helps applications identify all the parts of a font family, and makes selectors like bolder possible.
-
-Removing format attributes from `family` prevents breakage, when the technical format shipped by the distribution changes after an update. Because font technology continues to improve, format changes are bound to happen sooner or later. Applications can still request font format information via the fontconfig API if they need to.
-
-Removing coverage attributes from `family` enables merging all matching files in a single synthetic family. That is more user friendly, and prevents breakage when upstream decides to split the font family over different lines. Because creating a wide-coverage font family is a hard, long-term endeavour — Unicode is not finalized yet — such changes are common.
-
-The other decisions are just choosing good defaults for the font family. While fontconfig can take a guess at those, its guess will never be as accurate as packager decisions. Packagers can ask upstream for clarifications. Fontconfig can not.
-
-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.
+Free Desktop systems rely on multiple upstreams to provide their fonts.
+They are heavily dependent on fontconfig to present a consistent user-friendly font pool in applications.
+High quality fontconfig rules are indispensable to permit easy substitution of font families,
+and to mask upstream messiness.
+
+Applying strict WWS rules helps applications identify all the parts of a font family,
+and makes selectors like bolder possible.
+
+Removing format attributes from `family` prevents breakage,
+when the technical format shipped by the distribution changes after an update.
+Because font technology continues to improve,
+format changes are bound to happen sooner or later.
+Applications can still request font format information via the fontconfig API if they need to.
+
+Removing coverage attributes from `family` enables merging all matching files in a single synthetic family.
+That is more user friendly,
+and prevents breakage when upstream decides to split the font family over different lines.
+Because creating a wide-coverage font family is a hard,
+long-term endeavour — Unicode is not finalized yet — such changes are common.
+
+The other decisions are just choosing good defaults for the font family.
+While fontconfig can take a guess at those,
+its guess will never be as accurate as packager decisions.
+Packagers can ask upstream for clarifications.
+Fontconfig can not.
+
+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.
 
 === 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.
+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.
 
 Multi-source packages are difficult to maintain and confusing to users.
 
@@ -807,13 +1044,20 @@ Once all the preceding has been done, a font package should only contain:
 
 === Building
 
-Building from source ensures it will be possible to modify the font when problems are reported and upstream is not responsive. Sometimes that means working with upstream to sanitize its build processes.
+Building from source ensures it will be possible to modify the font when problems are reported and upstream is not responsive.
+Sometimes that means working with upstream to sanitize its build processes.
 
 === Packaging a font family in multiple OpenType formats; application support
 
-Fonts are comparatively bulky. Shipping fonts in multiple formats makes the situation worse on user systems, mirrors and live images. Every font family that ships in multiple formats, consumes space that could be used by another font package, enhancing the user experience.
+Fonts are comparatively bulky.
+Shipping fonts in multiple formats makes the situation worse on user systems, mirrors and live images.
+Every font family that ships in multiple formats,
+consumes space that could be used by another font package, enhancing the user experience.
 
-Because applications will make different choices in presence of multiple formats for the same font family, because different formats use different rasterization engines, because format conversions can introduce artefacts, shipping multiple formats reduces the effectiveness of Fedora QA.
+Because applications will make different choices in presence of multiple formats for the same font family,
+because different formats use different rasterization engines,
+because format conversions can introduce artefacts,
+shipping multiple formats reduces the effectiveness of Fedora QA.
 
 Most applications in Fedora support indifferently all OpenType formats,