Add guide about customizing fonts

platform/darwin/docs/guides/Customizing Fonts.md

@@ -0,0 +1,21 @@
+# Customizing Fonts
+
+The Mapbox Maps SDK can render text that is part of an `MGLSymbolStyleLayer` in a font of your choice. The font customization options discussed in this document do not apply to user interface elements such as the scale bar or annotation callout views.
+
+## Server-side fonts
+
+By default, the map renders characters using glyphs downloaded from the [Mapbox Fonts API](https://docs.mapbox.com/api/maps/#fonts). You apply fonts in [Mapbox Studio](https://studio.mapbox.com/), in the `text-font` layout property in style JSON, or in the `MGLSymbolStyleLayer.textFontNames` property at runtime. The values in these properties must be font display names, not font family names or PostScript names.
+
+Each font name in the list must match a font that is registered in Mapbox Studio; otherwise, the text will not load, even if one of the fonts is available. Each font name must be included in the `{fontstack}` portion of the JSON stylesheet’s [`glyphs`](https://docs.mapbox.com/mapbox-gl-js/style-spec/glyphs/) property.
+
+## Client-side fonts
+
+By default, Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) are rendered on the client side. Client-side text rendering uses less bandwidth than server-side text rendering, especially when viewing regions of the map that feature a wide variety of CJK characters.
+
+First, the map attempts to apply a font that you specify the same way as you would specify a server-side font: in [Mapbox Studio](https://studio.mapbox.com/), in the `text-font` layout property in style JSON, or in the `MGLSymbolStyleLayer.textFontNames` property at runtime. Instead of downloading the glyphs, the map tries to find a [system font](https://developer.apple.com/fonts/system-fonts/) or a font [bundled with your application](https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app) that matches one of these fonts based on its family name (for example, “PingFang TC”), display name (“PingFang TC Ultralight”), or PostScript name (“PingFangTC-Ultralight”).
+
+If the symbol layer does not specify an available font that contains the required glyphs, then the map tries to find a matching font in the [`MGLIdeographicFontFamilyName`](infoplist-keys.html#mglideographicfontfamilyname) Info.plist key. Like the `MGLSymbolStyleLayer.textFontNames` property, this key can contain a family name, display name, or PostScript name. This key is a global fallback that applies to all layers uniformly. It can either be a single string or an array of strings, which the map tries to apply in order from most preferred to least preferred.
+
+Each character is rendered in the first font you specify that has a glyph for the character. If the entire list of fonts is exhausted, the map uses the system’s font cascade list, which may vary based on the device model and system language.
+
+To disable client-side rendering of CJK characters, set the `MGLIdeographicFontFamilyName` key to the Boolean value `NO`. The map will revert to server-side font rendering.

platform/darwin/scripts/style-spec-overrides-v8.json

@@ -78,7 +78,7 @@
       "examples": "See the <a href=\"https://docs.mapbox.com/ios/maps/examples/clustering/\">Cluster point data</a> and <a href=\"https://docs.mapbox.com/ios/maps/examples/clustering-with-images/\">Use images to cluster point data</a> to learn how to use an expression to set this attribute to the number of markers within a cluster."
     },
     "text-font": {
-      "doc": "An array of font face names used to display the text.\n\nEach font name must be included in the `{fontstack}` portion of the JSON stylesheet’s <a href=\"https://www.mapbox.com/mapbox-gl-style-spec/#glyphs\"><code>glyphs</code></a> property. You can register a custom font when designing the style in Mapbox Studio. Fonts installed on the system are not used.\n\nThe first font named in the array is applied to the text. For each character in the text, if the first font lacks a glyph for the character, the next font is applied as a fallback, and so on."
+      "doc": "An array of font face names used to display the text.\n\nThe first font named in the array is applied to the text. For each character in the text, if the first font lacks a glyph for the character, the next font is applied as a fallback, and so on.\n\nSee the “[Customizing Fonts](../customizing-fonts.html)” guide for details on how this SDK chooses and renders fonts based on the value of this property."
     },
     "text-offset": {
       "doc": "Offset distance of text from its anchor."

platform/darwin/src/MGLSymbolStyleLayer.h

@@ -1232,16 +1232,13 @@ MGL_EXPORT
 /**
  An array of font face names used to display the text.
 
- Each font name must be included in the `{fontstack}` portion of the JSON
- stylesheet’s <a
- href="https://www.mapbox.com/mapbox-gl-style-spec/#glyphs"><code>glyphs</code></a>
- property. You can register a custom font when designing the style in Mapbox
- Studio. Fonts installed on the system are not used.
-
  The first font named in the array is applied to the text. For each character in
  the text, if the first font lacks a glyph for the character, the next font is
  applied as a fallback, and so on.
 
+ See the “[Customizing Fonts](../customizing-fonts.html)” guide for details on
+ how this SDK chooses and renders fonts based on the value of this property.
+
  The default value of this property is an expression that evaluates to the array
  `Open Sans Regular`, `Arial Unicode MS Regular`. Set this property to `nil` to
  reset it to the default value.

platform/ios/docs/guides/Info.plist Keys.md

@@ -22,13 +22,13 @@ If you have implemented custom opt-out of Mapbox Telemetry within the user inter
 
 ## MGLIdeographicFontFamilyName
 
-This key configures client-side text rendering of Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) that appear in text labels. Client-side text rendering uses less bandwidth than server-side text rendering, especially when viewing regions of the map that feature a wide variety of CJK characters.
+This key configures a global fallback font or fonts for [client-side text rendering](customizing-fonts.html#client-side-fonts) of Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) that appear in text labels.
 
-By default, the map renders CJK characters using locally installed fonts as specified by the system’s font cascade list, which may vary from device to device, and ignores the `MGLSymbolStyleLayer.textFont` property for these characters. To customize the displayed font, set this key to a string containing a font family name (for example, “PingFang TC”) or an individual font’s display name (“PingFang TC Ultralight”) or PostScript name (“PingFangTC-Ultralight”). The key can name a font that is installed system-wide or bundled with the application.
+If the fonts you specify in the `MGLSymbolStyleLayer.textFontNames` property are all unavailable or lack a glyph for rendering a given CJK character, the map uses the contents of this key to choose a [system font](https://developer.apple.com/fonts/system-fonts/) or a font [bundled with your application](https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app). This key specifies a fallback for all style layers in all map views and map snapshots. If you do not specify this key or none of the font names matches, the map applies a font from the system’s font cascade list, which may vary based on the device model and system language.
 
-In case your preferred font has glyphs for every character that may appear on the map, you can set this key to an array of font or font family names in order from most preferred to least preferred. Each character is rendered in the first font in the list that has a glyph for the character. If the entire font is exhausted, the map uses the system’s font cascade list.
+This key can either be set to a single string or an array of strings, which the map tries to apply in order from most preferred to least preferred. Each string can be a family name (for example, “PingFang TC”), display name (“PingFang TC Ultralight”), or PostScript name (“PingFangTC-Ultralight”).
 
-To disable client-side rendering of CJK characters, set this key to the Boolean value `NO`. Glyphs from the fonts specified by `MGLSymbolStyleLayer.textFont` will be downloaded and rendered instead.
+To disable client-side rendering of CJK characters in favor of [server-side rendering](customizing-fonts.html#server-side-fonts), set this key to the Boolean value `NO`.
 
 ## MGLCollisionBehaviorPre4_0
 

platform/ios/jazzy.yml

@@ -22,6 +22,7 @@ custom_categories:
       - Migrating to Expressions
       - For Style Authors
       - Tile URL Templates
+      - Customizing Fonts
       - Info.plist Keys
       - Gesture Recognizers
   - name: Maps

platform/macos/docs/guides/Info.plist Keys.md

@@ -18,13 +18,13 @@ The default value is `https://api.mapbox.com`.
 
 ## MGLIdeographicFontFamilyName
 
-This key configures client-side text rendering of Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) that appear in text labels. Client-side text rendering uses less bandwidth than server-side text rendering, especially when viewing regions of the map that feature a wide variety of CJK characters.
+This key configures a global fallback font or fonts for [client-side text rendering](customizing-fonts.html#client-side-fonts) of Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) that appear in text labels.
 
-By default, the map renders CJK characters using locally installed fonts as specified by the system’s font cascade list, which may vary from device to device, and ignores the `MGLSymbolStyleLayer.textFont` property for these characters. To customize the displayed font, set this key to a string containing a font family name (for example, “PingFang TC”) or an individual font’s display name (“PingFang TC Ultralight”) or PostScript name (“PingFangTC-Ultralight”). The key can name a font that is installed system-wide or bundled with the application.
+If the fonts you specify in the `MGLSymbolStyleLayer.textFontNames` property are all unavailable or lack a glyph for rendering a given CJK character, the map uses the contents of this key to choose a [system font](https://developer.apple.com/fonts/system-fonts/) or a font [bundled with your application](https://developer.apple.com/documentation/bundleresources/information_property_list/atsapplicationfontspath). This key specifies a fallback for all style layers in all map views and map snapshots. If you do not specify this key or none of the font names matches, the map applies a font from the system’s font cascade list, which may vary based on the system language and other installed applications.
 
-In case your preferred font has glyphs for every character that may appear on the map, you can set this key to an array of font or font family names in order from most preferred to least preferred. Each character is rendered in the first font in the list that has a glyph for the character. If the entire font is exhausted, the map uses the system’s font cascade list.
+This key can either be set to a single string or an array of strings, which the map tries to apply in order from most preferred to least preferred. Each string can be a family name (for example, “PingFang TC”), display name (“PingFang TC Ultralight”), or PostScript name (“PingFangTC-Ultralight”).
 
-To disable client-side rendering of CJK characters, set this key to the Boolean value `NO`. Glyphs from the fonts specified by `MGLSymbolStyleLayer.textFont` will be downloaded and rendered instead.
+To disable client-side rendering of CJK characters in favor of [server-side rendering](customizing-fonts.html#server-side-fonts), set this key to the Boolean value `NO`.
 
 ## MGLCollisionBehaviorPre4_0
 

platform/macos/jazzy.yml

@@ -22,6 +22,7 @@ custom_categories:
       - For Style Authors
       - Migrating to Expressions
       - Tile URL Templates
+      - Customizing Fonts
       - Info.plist Keys
   - name: Maps
     children: