This repository has been archived by the owner on Jun 21, 2023. It is now read-only.
Add guide about customizing fonts #292
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Split out a guide about customizing fonts, covering both server-side and client-side fonts.
1ec5
force-pushed
the
1ec5-local-font-names-docs
branch
from
323168f
to
dd7b4f0
Compare
chloekraw
approved these changes
Apr 30, 2020
|
|
||
| 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 none of the symbol layer’s fonts is available, or if these fonts do not contain 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. |
There was a problem hiding this comment.
Suggested change
| If none of the symbol layer’s fonts is available, or if these fonts do not contain 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. | |
| If none of the fonts specified on a symbol layer are available, or if the fonts do not contain 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. |
There was a problem hiding this comment.
Minor nitpicks:
- "none" should be followed by a plural verb because in this context, none refers to "if not any of the fonts are available". None is singular when it is used in reference to part of a single item, e.g., "none of my bread is yours."
- suggested a rewording of the first clause of the first sentence that I think is clearer
There was a problem hiding this comment.
This is an area where style guides differ. I’ve always followed the “not one” rule of thumb from a grade school English textbook, but it’s admittedly quite pedantic and it looks like some style guides like APA have gone the other way. Our internal style guide is silent on the matter. I’ll reword the sentence for clarity.
|
|
||
| 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 none of the symbol layer’s fonts is available, or if these fonts do not contain 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. |
There was a problem hiding this comment.
One thought I'm mulling over: instead of writing out the information about MGLIdeographicFontFamilyName here, what do you think about linking to that section of the Info.plist guide for the details? I am generally hesitant to repeat information in more than one place, because it's one more place to remember to update if the behavior changes, which increases the chance that the information will go stale.
That said, at the same time, I really like the way this documentation reads as-is, so I don't have strong feelings about this.
There was a problem hiding this comment.
The guide does link to the relevant section of the Info.plist documentation, but the idea was to draw a parallel between the two places that accept font names. Fortunately, since these details are now part of the public API, it’s unlikely that they’ll change in a minor release.
fabian-guerra
approved these changes
Apr 30, 2020
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Split out a guide about customizing fonts, covering both server-side and client-side fonts following the changes in #189.
/cc @mapbox/maps-ios @mapbox/docs (FYI)