googlefonts / gf-docs

Documentation for things related to github.com/google/fonts

This documentation is now deprecated.

This is the new GF documentation:

https://googlefonts.github.io/gf-guide/

gf-docs's Issues

Vertical metrics: include, or link?

The vertical metrics section had previously read "TO DO"

For now, I added a link to: https://github.com/googlefonts/gf-docs/tree/master/VerticalMetrics

Should we migrate that content to this doc, and update it as needed? Or keep it separate?

Spec: push designer to center caps in vertical metrics

Feedback from this user : Etcetera-Type-Co/Epilogue#15

METADATA documentation is missing information for variable fonts

The documentation here does not contain any information regarding variable font table names, file names, etc. Some of this info is implicitly be emitted through fontbakery tests, but it would be good to have a authoritative source for how it should be.

Require orthogonal designspaces for VFs

I've seen several VF projects which have non-orthogonal designspaces e.g:

Master setup

Master Name	wdth	wght
Condensed Thin	75	30
Condensed Regular	75	50
Condensed Black	75	80
Thin	100	30
Regular	100	55
Black	100	80

In the above example, the "Condensed Regular" and "Regular" have differing wght values (50 vs 55). By having differing values, it means the avar won't be able to map the "Condensed Regular" and "Regular" masters to the 400 usWeightClass (we need this!) correctly since it cannot map axes based on the values of other axes. Such functionality may happen if the avar table is upgraded in the future

Another approach is to add masters but this can increase the file size drastically. Imo, it is better to just design families so they are orthogonal from the start. If avar v2 appears, we can drop this requirement.

By map, I mean mapping user coordinates to fvar coordinates

cc@vv-monsalve, @tphinney, @davelab6 thoughts?

Use CI markdown formatter linter

In #33 @thundernixon wrote,

Opening markdown files incidentally formatted them with my editor's formatter. This was unintended, but seems like a plus. If a different formatting approach is prefered, I can set it to that markdown flavor instead.

This reminds me, we should have a markdown linter, and a 404 checker for all external links.

404 Error for ProjectChecklist.md URL

Link in MasteringNewFamiliesForGF is broken

Vertical Metrics recommendations: we need to update this.

This document started life in 2011.

Both Kalapi and Khaled discovered two schemes which work well in 2016. Both schemes involved enabling fsSelection bit 7 (Use_Typo_metrics). By doing this, tall scripts wont clip and the visual line space won't be too loose.

@davelab6 I wrote up a guide a while back, https://github.com/m4rc1e/gf-docs/blob/verticalmetrics/VerticalMetrics.md. Can I edit https://github.com/googlefonts/gf-docs/blob/master/VerticalMetricsRecommendations.md to comply with how we have been doing vertical metrics for the past two years?

What is style of a cursive type?

I'm designing a cursive Latin type and planning to collaborate by Google fonts, my question is, should my type's style be regular or italic? I'm facing with this confusion because my type is italic in all situation, also in this section stated that it is require to having Regular(400) style in family.

Write up font naming / style linking / etc

@m4rc1e says we should write some documentation covering Font naming, style linking and how this all fits in with the GF API

Gasp table set to 15

'The gasp should be set to 15'

Doesn't explain what ranges are needed etc.

Could you point me in the direction of a font which uses the correct values please?

Cheers,
Marc

Suggestions for GF glyphset

Currency
• Bitcoin (uni20BF)

To cover Mac Roman
• Omega (uni03A9)
• Delta (uni0394)

To cover Windows 1252
• mu (uni03BC)

OpenType file/tables overview?

So, the question is, given how developer-oriented the OpenType spec is, is there need/room for a brief guide to the OpenType spec for type designers? It would explain the tables and the like in plain English. It would not replace the spec, but be a first thing to read, prior to trying to tackle the full spec (or at least, the parts they need for whatever purpose).

Another question: if this is worth doing, should it be part of the main GF doc? Or a separate item?

Glyph clipping still exists in Win 10

Glyphs still get clipped in Win 10 if the OS/2 Win Ascent and OS/2 Win Descent are smaller than the font's bounding box.

Win 10 Version 1809 (Will try a newer version now)

Statement of purpose and target audience

I suggest the document could (and probably should) say who it is aimed at, and what it is trying to do. Something like:

This document is aimed at taking people who already know type design, and telling them what they need to know to create fonts that meet the requirements of Google Fonts. It assumes general type design knowledge, but does not assume deep technical knowledge of font standards, nor does it assume software development background. We hope to make the creation of Google Fonts accessible to a wider audience than before, and make it easier for Google to bring new fonts to the service (“onboarding”).

Does that seem vaguely appropriate?

[spec] fvar – named instances and the contents of the "static" directory

I'm looking into updating Saira to VF https://github.com/Omnibus-Type/Saira/tree/master/Saira/fonts/gx

The VF family has 2 fonts: Saira[wdth,wght].ttf, Saira-Italic[wdth,wght].ttf
Each of it defines 63 named instances in fvar: (7 widths ✕ 9 weights)

On google/fonts we have 3 further families of the Saira super family (excluding Saira Stencil One): Extra Condensed, Condensed, Semi Condensed.

Thus, the VF version has the potential to replace all the width variant families on Google Fonts, plus adding more of its own width variants in one go, namely: Ultra Condensed, SemiExpanded and Expanded

Looking at the named instances in fvar, I'd expect the static directory to contain 126 fonts, 63 each for the upright plus italic VFs. (And I kind of think that makes sense)

However, looking into the (updated) spec:

Fvar instances

[...]
We only allow weight and italic particles. If a font contains additional axes, they must not be mentioned in the instance names and the coordinates for each instance must be set to reasonable default e.g if your font contains a wdth axis, you don't want every instance's wdth coordinate value to be set to Condensed (75) you would set it to Normal (100).

• Ok, so 18 fonts in static for upright plus italic.
• What does this mean for the other existing siblings of Saira? Should these be updated with the same Variable fonts, but with changed name tables and different fvar instances? However, then, wdth would be set to something else than Normal (100)!
• Will we ever replace Saira{WeightVariation}-sibling families with just one VF family?

Saira has other problems with named instances , but I believe these are off topic.

Add `version: x.yyy` field to `fonts` record

I realize that METADATA.json is primarily used for producing the Google Fonts website, so overloading it with other "useful" data is not an option. But one tremendously useful aspect would be introducing a version field inside the fonts list. The field would take a x.yyy string (or a float?). It should be taken from the font's head.fontRevision field.

It would be very useful to keep track of which version of a given font is deployed on Google Fonts.

PR GF and Dispatcher process / update docs ?

So I read these two documents:

1. How Gf Dispatcher works
2. GooglFonts Dispatch QA Process

Although they don't seem to be updated.
This is a report of what is causing confusion:

In doc 1)

• Checklist link is broken
• Browserstack link is broken
• Download gfdispatcher link doesn't work

In doc 2)

• confusion between all the "upstream" repos (hard to follow which one is the font source repo and which one is Google Fonts repo)
• "Package into dir on google/fonts"… using dispatcher or add-font.py script?
• "Regenerate METADATA.pb"… using dispatcher or add-font.py script ?

Makes me wonder:

• Shall I use dispatcher's platform, or install it locally as mentioned in Doc1 ? I didn't find the platform mentioned in the docs
• Is metadata.pb automatically generated by dispatcher or should I use gftools use add-fonts script as mention in Making Pull Requests to GF?
• Is the process described in Making PR to GFF up to date ? I don't see dispatcher mentioned.
• Is it even still necessary to PR Google Fonts (from terminal or source tree)?

Thank you very much for your help and future attempt to un-confuse me :)

Recommendation and limits for name table

I know this is built into fontbakery but I’m wondering if we could make a document of recommendations and limits on the name IDs.

I keep running issues trying to shorten really long names (Bananas ExtraExtended SemiBold Italic for example) and I’m not sure which name IDs needs are for GF requirements.

[Project Checklist] Copyright line in OFL if there is a RFN

If the copyright line is like this:

Copyright (c) 2011, The Francois One Project Authors ([email protected]),
with Reserved Font Names "Francois" and "Francois One".

and the checklist says:

The copyright notice on line 1 of the OFL.txt MUST match the copyright notice inside each font file.

https://github.com/googlefonts/gf-docs/blob/master/ProjectChecklist.md#ofltxt

Should I put inside the font:

 Copyright (c) 2011, The Francois One Project Authors ([email protected]),

including the trailing comma?

Spec: How to order font name particles?

For ordering font naming particles, I think

1. family
2. optical-size
3. weight
4. width
5. slant
6. italic
7. custom

is good; this seems to roughly adhere to the English grammatical rule for order of adjectives, and perhaps $custom has to do so recursively as well.

Here's the rule:

a book called The Elements of Eloquence: How to Turn the Perfect English Phrase. Adjectives, writes the author, professional stickler Mark Forsyth, “absolutely have to be in this order:

1. opinion
2. size
3. age
4. shape
5. colour
6. origin
7. material
8. purpose
9. Noun

So you can have a lovely little old rectangular green French silver whittling knife. But if you mess with that order in the slightest you’ll sound like a maniac.”

– https://qz.com/773738/how-non-english-speakers-are-taught-this-crazy-english-grammar-rule-you-know-but-youve-never-heard-of/

Microsoft uses "WWS" for Weight, Width, Slope, and I think for families with both slant and italic, slant should be first, as slant is about shape, while italic is sort of more about 'material' (or even origin!)

Project Checklist > Glyphs Specific Steps specific steps

Project Checklist > Glyphs Specific Steps specific steps

Font Info, Font, Compact File Storage, enabled.

Please remove that step. It’s not necessary anymore according to recent changes on Github. (And it caused a severe file damage).
This Custom Parameter was never official and should not be asked to be used for that matter.

gftools and virtual environment

I would like to add informations in the gf docs about how to handle gftools/fontmake etc. with a virtual environment. I have a poor experience when it comes to that, and when I tried, I had conflicts with tools already installed locally. How do you proceed yourself? I saw in some threads that some of you are using one venv per project for example.

Panose

I wonder how you set up the PANOSE these days. I read you define one per instance and not a general one, but…

• How specific are you with it?
• What is your recommendations for multiscripts fonts ?
• Do you use a script ? Do you do it manually ? Or Fontmake does it?

Thx

F

https://www

Choose a mechanism for comments?

Just a suggestion from @tphinney.

VerticalMetrics.md "bbox ymax"

Does this mean the y value of the highest point in a font, it's not immediately clear to me what that term means?

METADATA.md file noticably out of date

The METADATA.md file in this repository describes the old JSON file, not the PB file currently in use.

I have an outside use case for storing metadata external to font binaries and would be interested in developing a solution that's aligned with, or at least compatible with, what Google Fonts is doing.

The existing protobuf docs I've seen all suggest that *.pb files are binary representations, so adding something here that describes what Google Fonts is doing in practice would be most helpful indeed.

Update docs once gftools builder is merged

Would be nice to get people using gftools builder once it is merged.

googlefonts/gftools#278

NULL and CR glyphs in GF Core

I've never added these glyphs before, is there any special instruction for these, conents, width, or unicode value?

Impallari.com

ProjectChecklist.md refers to http://www.impallari.com/familysteps and to http://impallari.com/testing

But the site is "Cuenta suspendida".

Refs:

You should plan and develop the weights of each instance early in the process. The Impallari Type Family Steps page helps to plan the weight progression on a curve, so that the weight of middle instances are suitably light. The master and instance interpolation values should be representative of stem weights. This makes it easier for people who want generate their own fonts in the future to do so.
http://www.impallari.com/familysteps

http://impallari.com/testing
either with a print layout application, or a web tester like the Impallari Testing page

Latin / CJK metrics recommendation

In reading the documentation for vertical metrics, I am seeing something of a gray zone in regards to CJK versus Latin.

The Latin documentation states:

TypoAscender and hheaAscender are set to height of tallest uppercase glyph with single accent (probably  or Å)
TypoDescender and hheaDescender set to lowest a-z letter (p, j, q)

This makes sense as it is intended to avoid undesirable clipping of the letters under certain conditions.

However, in the Spec it only sets universal vertical metrics requirements:

Attrib	Value	Example using 1000upm font
OS/2.sTypoAscender	0.88 * font upm	880
OS/2.sTypoDescender	-0.12 * font upm	-120
OS/2.sTypoLineGap	0	0
hhea.ascender	Set to look comfortable (~1.16 * upm)	1160
hhea.descender	Set to look comfortable (~0.288 * upm)	-288
hhea.lineGap	0	0
OS/2.usWinAscent	Same as hhea.ascent	1160
OS/2.usWinDescent	abs(value) of hhea.descent	288
OS/2.fsSelection bit 7	Do not set

So my question is this, if a CJK contains Latin, should the Å and descending lowercase (p, j, q, y) fit within the TypoAscender and TypoDescender as to avoid any risk of clipping? (Or perhaps the WinAscent / WinDescent?)

I observe that Noto CJK extends both above and below the BBox:

Mention axis registry in specs

I looked up the specs and couldn't find any mention of the axis registry there under VF: https://github.com/google/fonts/tree/master/axisregistry

I think it should be linked there, as this knowledge is critical to produce acceptable VFs for Google.

Remove of Home, HowToGenerateWebNativeFonts* files

@m4rc1e please take a careful look over these ensure all the info in those docs is in the corresponding file, and then rm them :)

• HowToGenerateWebNativeFonts.md -> ProjectChecklist.md
• HowToGenerateWebNativeFontsWithFontForge.md -> ProjectChecklist.md
• Home.md -> google/fonts README.md

Familiy naming: include numbers

In Name Your Project:

Do not use non-ASCII alphabet characters in the family name: No dashes, numbers, or diacritics.

I'm currently mastering "VT323" also another example is "Mplus 1p" for names containing numbers.

I suggest relaxing this rule to allow numbers within the family name but not at the beginning:

Do not use non-ASCII alphanumeric characters in the family name: No dashes or diacritics. Family names must begin with alphabet characters: No dashes, numbers or diacritics.

This scheme is also often seen in the rules for variable names in programming, the reasons there are however better founded, i.e. tokenizing. The reasoning here would only be adopting to real world cases.

Also, VT323 is already in GF.

This change would have to be incorporated into Fontbakery and Marcs Glyphs scripts.

@m4rc1e @felipesanches @davelab6

pipeline: accept other git hosts than GitHub e.g. GitLab

Some projects don't host their font project repositories originally on GitHub. E.g. SMC host on GitLab and merely mirror to GitHub. Hence, the projects live on GitLab, so do issue trackers etc. I wonder if we should accept other hosts for projects. This could make tooling more complicated when automation expects the GitHub API to be available, e.g. could be when downloading attachments from tag releases (I'll file an issue for this in googlefonts/gftools#230).

For an introduction see also googlefonts/gftools#231

If we have a https:// url to the git repository, that works with git clone, this actually works already in gftools packager e.g. in upstream.yaml

repository_url: https://github.com/smc/Chilanka.git

can also be

repository_url: https://gitlab.com/smc/fonts/chilanka.git

and the result will be the same.

vertical metrics doc should be updated to Marc's recommendations

@m4rc1e, are you still confident in your recommendations at fonttools/fontbakery#2164 (comment) ?

They just helped me fix a bug in Inter (rsms/inter#141).

To do:

• If it looks good to Marc, I can update the vertical metrics specs.

• We should also verify that a gftools script exists to fix this properly.

Write up bracket layers workflow

I have to document the workflow for this as I have used it on a small scale for Expletus Sans. This should be useful for both existing families and new families until fontmake supports these layers out of the box.

Spec: Drop VF fvar tables. Use axis registry instead

The spec should use the google/fonts axisregistry, instead of the tables we're currently providing.

Static Supported Style names

Shouldn't the SubFamily Name (nameID 2) for Light be Regular?

FamilyName-Light.ttf | Family Name Light | Light | Family Name | Light | 300 | 64 | 0

And for ExtraBold and Black nameID 1 have the style name and nameID 2 be also Regular?

FamilyName-ExtraBold.ttf | Family Name | ExtraBold | Family Name | ExtraBold | 800 | 64 | 0
FamilyName-Black.ttf | Family Name | Black | Family Name | Black | 900 | 64

Update vertical metrics recommendations: illogical hypothetical font

A PR #106 is currently in its way to update the vertical metrics recommendations. I thought it was better to comment on it, but since this contributor prefers issues, so be it.

I think that despite the efforts of the PR, the specs will be still not clear.

Indeed, we are presented with an illogical hypothetical font (by the only information that is given): the taller presented glyph (À) in this font has yMax at 920, and the deepest presented glyph has yMax at −235, so it's impossible, with the available information, that the font could have yMax at 1116 and yMin at −320.

I see two explanations for this:

1. The redactors think head.yMax and head.yMin could be greater than the greatest value of the individual glyphs, which is wrong (unless proven otherwise).
2. Or, simply, there really is in this font a glyph with its yMax at 1116 and another (or the same, why not) which has yMin at −320, and it would suffice to mention it to make this hypothetical font credible.

The question is less academic than it seems, since it affects the calculation of other values.

Suggestions for GF docs structure

So I think we agree the docs and the spec are delivering a lot of useful informations, although it is kind of overwhelming and could need a bit more structure. As a first step of reviewing the docs I would like to suggest this structure:

.
├── 000 Spec
├── 100 Starter
│   ├── 110 Start with Google
│   │   ├── 111 Libre font philosophy
|   │   └── 112 Tools
│   ├── 120 Start with Github
|   └── 130 Start with a font editor software
├── 200 Design
│   ├── 210 Design tips and tricks
│   │   ├── 211 Design resources
|   │   └── 212 Latin diacritics
│   ├── 220 Get your masters ready for production
│   │   ├── 221 Contours
│   │   ├── 222 Components and anchors
|   │   └── 223 Charset and Glyphset
│   └── 230 Font info settings
└── 300 Get ready for GF
    ├── 310 Upgrading existing repository
    ├── 320 Set up a build script
    ├── 330 Mastering families
    │   ├── 331 Naming
    │   ├── 332 Vertical metrics and alignment zones
    │   └── etc
    ├── 340 Reviewing families / QA process
    ├── 350 Bug and hotfix
    ├── 360 Local testing
    └── 370 Packaging for GF

Agree, disagree, PR, not PR ?

Figure out a localization process for our docs

Eg, here is a Japanese translation of the QuickStartGlyphs/README.md

https://docs.google.com/document/d/1F8ix2Ur1yNgpkP6C6h6wjYCennbRFDeRq4rzuRcSp7w/edit?ts=5dde8fc7#

I am not sure how to best put this into the repo... Thoughts?

Consolidate desired upstream repo structure, provide golden exemplar

@graphicore reminded me that there have been a dozen attempts to define a desired upstream repo structure over the years, and this repo has 3-4 descriptions.

While it has been good to see different ideas bloom, we should consolidate all the good ideas and make a new "GF 2020 Upstream Model" with both a description and a golden exemplar.

I think we used Montserrat for this in the last couple of years, but perhaps a multi axis family would be better reference material.

Contradiction in gf-docs/Spec/README.md?

Family already exists on Google Fonts
(…)

• Every style that was already available on Google Fonts must be included as an fvar instance

and:

At the moment (2020-06-30), Google Fonts only allows the following named instances:
(…)
We only allow weight and italic particles.

The contradiction between the two should be resolved: specify the second statement is not valid when the "Family already exists on Google Fonts", for example.

Move fontbakery-build-metadata.py here

Looks to me like 1. this repo needs better name (eg googlefonts-metadata) or just invent a name for it. And that fontbakery-build-metadata.py should live here (and be improved as needed).

Vertical Metrics docs improvements

Following #45 then

• update the core recommendations
• include a few tips about bottom accents in extended-Latin designs
• let people know what considerations should go into other scripts

Link to trademark example is broken

Return 404 https://github.com/mooniak/yaldevi-fonts/blob/master/TRADEMARKS.md

[Vertical Metrics] Suggested Script Missing

The fontbakery-fix-vertical-metrics.py script is no longer available in the FontBakery repository (fontbakery/tools/).

Spec: let's mark the opsz default value "elidable" ?

To resume:

• Fvar table in the VF only contains weight style instances. eg. FontName-Bold (wght=700, wdth=100, opsz=14).
• Static instances which have a different style from the weight style (eg. width), have it appended to the family name. eg. FontNameCondensed-BoldItalic (familyname = FontNameCondensed, stylename = Bold Italic)
• The "Normal" width is "elidable" in the STAT of the VF, and not mentioned in the static instance name. For eg. FontName-Bold (wght=700, wdth=100). That's good, fvar instances and static instances have consistent naming.

Proposal starts here:

We need the statics with an optical size axis named this way: FontNameXXpt-Weight.
----> As for the width axis, should we have the default optical size value elidable as well ? For eg. static name then would be FontName-Bold instead of FontName14pt-Bold. It would be more consistent with the VF fvar instances, but we would have to assume that the "normal" optical size is the "text size" (in a range of 10 to 16pt)… or this is up to the designer?

Font bakery has no fontbakery-fix-dsig.py

It looks like this script may have been removed?

How do we handle the dsig now?