writing improved release notes

fonts/Recursive-Beta_1.050/README.md

@@ -2,29 +2,31 @@
 
 Recursive is a typographic palette for code & UI. It includes sans-serif & mono fonts designed specifically for use in interactive applications and code editors. See https://recursive.design for more information.
 
-Recursive is an open-source project. Follow along and contribute at https://github.com/arrowtype/recursive. It is licensed under the OFL, so (in summary) you are free to make derivative versions, but these must also adopt the same OFL license (e.g. you cannot sell derivative works). See `LICENSE.txt` for full details.
+Recursive is an open-source project. Follow along and contribute at https://github.com/arrowtype/recursive. It is licensed under the OFL, so (in summary) you are free to make derivative versions, but these must also adopt the same OFL license (e.g. you cannot sell proprietary licenses for derivative fonts). See `LICENSE.txt` for full details.
 
 Do you have a question or have you found a bug? Please file an issue at https://github.com/arrowtype/recursive/issues. Thanks!
 
 ## Recommendations
 
+For design & usage recommendations, please see the project README at https://github.com/arrowtype/recursive/blob/master/README.
+
 Fonts in `Recursive_Desktop` and `Recursive_Code` are made so that it is possible to install all of these without experiencing conflicts in font menus. However, you may want to pick-and-choose which font files you wish to install, based on your needs.
 
-**General Desktop use (Word, PowerPoint, Keynote, InDesign, Illustrator, PhotoShop, Figma, etc)**
+### General Desktop use (Word, PowerPoint, Keynote, InDesign, Illustrator, PhotoShop, Figma, etc)
 
 - On Windows, install `Recursive_Desktop/recursive-statics.ttc` (This is a collection of all 64 static instances in TTF format)
 - On Mac, install `Recursive_Desktop/recursive-statics.otc` (This is a collection of all 64 static instances in OTF format)
 
-**Desktop web design (Sketch) & experimental use in Adobe apps**
+### Desktop web design (Sketch) & experimental use in Adobe apps
 
-- Install `Recursive_Desktop/Recursive_VF_1.042.ttf`
-- It may also be beneficial to install static fonts, as support of variable fonts is still growing
+- Install `Recursive_Desktop/Recursive_VF_1.0XX.ttf` (this is the full Recursive variable font)
+- It may also be beneficial to install static fonts, as OS & app support of variable fonts is still growing
 
-**Code (code editors such as VS Code, Atom, Sublime, etc etc)**
+### Code (code editors such as VS Code, Atom, Sublime, etc etc)
 
 - Install fonts in `Recursive_Code` (These are specifically simplified families for use in code editors. See README in that directory for further advice)
 
-**Web**
+### Web
 
 - Use the woff2 font files in `Recursive_Web`. This includes a few useful subsets for variable fonts, along with some starter `@font-face` CSS for the `woff2_variable_subsets`. 
 - If you only need a style or two on a site, it may be practical to just use static instances, but you may want to figure out subsetting with `pyftsubset` to make those even smaller.

fonts/Recursive-Beta_1.050/Recursive_Desktop/README.md

@@ -0,0 +1,13 @@
+# Installation recommendations
+
+Fonts in `Recursive_Desktop` and `Recursive_Code` are made so that it is possible to install all of these without experiencing conflicts in font menus. However, you may want to pick-and-choose which font files you wish to install, based on your needs.
+
+## General Desktop use (Word, PowerPoint, Keynote, InDesign, Illustrator, PhotoShop, Figma, etc)
+
+- On Windows, install `Recursive_Desktop/recursive-statics.ttc` (This is a collection of all 64 static instances in TTF format)
+- On Mac, install `Recursive_Desktop/recursive-statics.otc` (This is a collection of all 64 static instances in OTF format)
+
+## Desktop web design (Sketch) & experimental use in Adobe apps
+
+- Install `Recursive_Desktop/Recursive_VF_1.0XX.ttf` (this is the full Recursive variable font)
+- It may also be beneficial to install static fonts, as OS & app support of variable fonts is still growing

fonts/Recursive-Beta_1.050/Recursive_Web/README.md

@@ -0,0 +1,41 @@
+# Web usage recommendations
+
+- `woff2_static` contains separate static fonts for 64 styles of Recursive
+- `woff2_variable` contains the full Recursive variable font, plus a "Google Fonts Latin Basic" subset which covers western European languages
+- `woff2_variable_subsets` contains a few useful subsets for variable fonts, along with some starter `@font-face` CSS which you can use as a starter to use these subsets in your own web projects.
+
+## Strategies for maximizing font performance on your website
+
+Generally, for web typography you want to use exactly as many font styles as you need to in order to deliver clear visual hierarchy and appropriate emotional impact, but not serve more data than is needed. Here are a few strategies you might consider in pursuit of that goal.
+
+### Premade variable subsets
+
+To usea wide range of styles on a website (all 5 variable axes of Recursive) in a way that will cover basically every character in the typical English or western-european language, you can simply use `woff2_variable/Recursive_VF_1.050--subset-GF_latin_basic.woff2`. This file is about 280kb.
+
+However, a slightly more-nuanced strategy for performant web font usage is utilizing `unicode-range`:
+
+> The unicode-range CSS descriptor sets the specific range of characters to be used from a font defined by @font-face and made available for use on the current page. If the page doesn't use any character in this range, the font is not downloaded; if it uses at least one, the whole font is downloaded.
+
+— source: https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range
+
+The fonts in `woff2_variable_subsets` are premade woff2 subsets, accompanied by a prewritten `@font-face` CSS in `woff2_variable_subsetsfonts.css`. You can use these fonts & CSS directly in a web project, and the browser will only download fonts as needed for the characters used on a given page. For example, if a page only includes English text, it will probably only download `Recursive_VF_1.050--subset_range_english_basic.woff2`, which is 195kb for all 5 variable axes. If another page also includes a character like the Yen (¥), Copyright (©), or the NE diagonal arrow (↗), the browser will then download `Recursive_VF_1.050--subset_range_latin_1_punc.woff2`, an additional 44kb (again, with 5 variable axes).
+
+### Static fonts & subsetting on your own
+
+If you only need a style or two on a site, it may be practical to just use static instances. These have a fairly large character set and are each about 100kb, so you may wish to also figure out subsetting with `pyftsubset` to make these even smaller. See https://css-tricks.com/three-techniques-performant-custom-font-usage/ for an introduction to this. 
+
+Here is a recipe you can use to make a "Google Fonts Latin Basic" subset via the command line – just be sure to replace the font filepath before running in a terminal:
+
+```bash
+pip install fonttools # you can use pip to install fonttools, which includes pyftsubset (https://pip.pypa.io/en/stable/installing/)
+
+fontPath="PLACE/THE/FONT/FILEPATH/HERE/IN/QUOTES" # replace this with the filepath to a woff2 font
+
+pyftsubset $fontPath --flavor="woff2" --output-file="${fontPath/'.woff2'/--subset-GF_latin_basic.woff2}" --unicodes="U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD"
+```
+
+### Taking it further
+
+This subsetting approach can be used directly on the full `woff2_variable/Recursive_VF_1.050.woff2` if you wish to custom-tailor the full variable font for your project.
+
+You can even make use of the FontTools Instacner (https://github.com/fonttools/fonttools/blob/master/Lib/fontTools/varLib/instancer.py) to instanciate your own custom instances or subset variable font (e.g. keeping only the `MONO` and `wght` axes).

src/build-scripts/make-release/00-prep-release.sh

@@ -97,8 +97,10 @@ python src/build-scripts/make-release/instantiate-code-fonts.py $dir/Variable_TT
 # copy metadata
 
 cp OFL.txt $outputDir/LICENSE.txt
-cp $(dirname $0)/data/release-notes.md $outputDir/README.md
-cp $(dirname $0)/data/rec_mono-for-code--notes.md $outputDir/$desktopCodeDir/README.md
+cp $(dirname $0)/data/release-notes--all.md $outputDir/README.md
+cp $(dirname $0)/data/release-notes--code.md $outputDir/$desktopCodeDir/README.md
+cp $(dirname $0)/data/release-notes--desktop.md $outputDir/$desktopDir/README.md
+cp $(dirname $0)/data/release-notes--web.md $outputDir/$webDir/README.md
 
 # ---------------------------------------------
 # make a zip of the outputDir, then move both dir & zip into "fonts/"

src/build-scripts/make-release/data/release-notes.md → src/build-scripts/make-release/data/release-notes--all.md

@@ -2,29 +2,31 @@
 
 Recursive is a typographic palette for code & UI. It includes sans-serif & mono fonts designed specifically for use in interactive applications and code editors. See https://recursive.design for more information.
 
-Recursive is an open-source project. Follow along and contribute at https://github.com/arrowtype/recursive. It is licensed under the OFL, so (in summary) you are free to make derivative versions, but these must also adopt the same OFL license (e.g. you cannot sell derivative works). See `LICENSE.txt` for full details.
+Recursive is an open-source project. Follow along and contribute at https://github.com/arrowtype/recursive. It is licensed under the OFL, so (in summary) you are free to make derivative versions, but these must also adopt the same OFL license (e.g. you cannot sell proprietary licenses for derivative fonts). See `LICENSE.txt` for full details.
 
 Do you have a question or have you found a bug? Please file an issue at https://github.com/arrowtype/recursive/issues. Thanks!
 
 ## Recommendations
 
+For design & usage recommendations, please see the project README at https://github.com/arrowtype/recursive/blob/master/README.
+
 Fonts in `Recursive_Desktop` and `Recursive_Code` are made so that it is possible to install all of these without experiencing conflicts in font menus. However, you may want to pick-and-choose which font files you wish to install, based on your needs.
 
-**General Desktop use (Word, PowerPoint, Keynote, InDesign, Illustrator, PhotoShop, Figma, etc)**
+### General Desktop use (Word, PowerPoint, Keynote, InDesign, Illustrator, PhotoShop, Figma, etc)
 
 - On Windows, install `Recursive_Desktop/recursive-statics.ttc` (This is a collection of all 64 static instances in TTF format)
 - On Mac, install `Recursive_Desktop/recursive-statics.otc` (This is a collection of all 64 static instances in OTF format)
 
-**Desktop web design (Sketch) & experimental use in Adobe apps**
+### Desktop web design (Sketch) & experimental use in Adobe apps
 
-- Install `Recursive_Desktop/Recursive_VF_1.042.ttf`
-- It may also be beneficial to install static fonts, as support of variable fonts is still growing
+- Install `Recursive_Desktop/Recursive_VF_1.0XX.ttf` (this is the full Recursive variable font)
+- It may also be beneficial to install static fonts, as OS & app support of variable fonts is still growing
 
-**Code (code editors such as VS Code, Atom, Sublime, etc etc)**
+### Code (code editors such as VS Code, Atom, Sublime, etc etc)
 
 - Install fonts in `Recursive_Code` (These are specifically simplified families for use in code editors. See README in that directory for further advice)
 
-**Web**
+### Web
 
 - Use the woff2 font files in `Recursive_Web`. This includes a few useful subsets for variable fonts, along with some starter `@font-face` CSS for the `woff2_variable_subsets`. 
 - If you only need a style or two on a site, it may be practical to just use static instances, but you may want to figure out subsetting with `pyftsubset` to make those even smaller.

src/build-scripts/make-release/data/release-notes--code.md

@@ -0,0 +1,24 @@
+# Rec Mono for Code
+
+Custom 4-style packages specifically made for code editors, each featuring:
+- Regular, Italic, Bold, & Bold Italic static fonts
+- An abbreviated family name to enable italic themes on macOS
+- Reduced-slant italics for easier readability in code (normal Recursive Italics have slnt=-15, which is pretty intense)
+- All the same OpenType features that are available in Recursive generally, including `dlig` for code ligatures and `ss01`-`ss11` to customize letterforms to your preference.
+
+
+## Packages
+
+Download the zip in this folder for an easy way to download these fonts. Then, install the fonts then call them from your favorite code editor with their relevant family name, e.g. `Rec Mono Duotone`.
+
+**`Rec Mono Linear`**
+- Everyday workhorse for code. Simplified shapes meant to help enhance focus in complex code.
+
+**`Rec Mono Casual`**
+- A party in a font. Fun & wacky shapes, simplified enough for small sizes but curvy enough to have plenty of character. Best in casual coding & non-primary terminals.
+
+**`Rec Mono SemiCasual`**
+- Sets the CASL axis at `0.5` for font that is serious but softened a little bit. This isn't the best choice for text at large sizes (like headlines on a website), but can be a really nice balance in code.
+
+**`Rec Mono Duotone`**
+- A personal favorite – this uses Linear styles for upright text and Casual styles for italic text. In many themes that use italic styles, this will give most code a utilitarian look, but set comments and some keywords in a more-handwritten style.

src/build-scripts/make-release/data/release-notes--desktop.md

@@ -0,0 +1,13 @@
+# Installation recommendations
+
+Fonts in `Recursive_Desktop` and `Recursive_Code` are made so that it is possible to install all of these without experiencing conflicts in font menus. However, you may want to pick-and-choose which font files you wish to install, based on your needs.
+
+## General Desktop use (Word, PowerPoint, Keynote, InDesign, Illustrator, PhotoShop, Figma, etc)
+
+- On Windows, install `Recursive_Desktop/recursive-statics.ttc` (This is a collection of all 64 static instances in TTF format)
+- On Mac, install `Recursive_Desktop/recursive-statics.otc` (This is a collection of all 64 static instances in OTF format)
+
+## Desktop web design (Sketch) & experimental use in Adobe apps
+
+- Install `Recursive_Desktop/Recursive_VF_1.0XX.ttf` (this is the full Recursive variable font)
+- It may also be beneficial to install static fonts, as OS & app support of variable fonts is still growing

src/build-scripts/make-release/data/release-notes--webfont.md

@@ -0,0 +1,41 @@
+# Web usage recommendations
+
+- `woff2_static` contains separate static fonts for 64 styles of Recursive
+- `woff2_variable` contains the full Recursive variable font, plus a "Google Fonts Latin Basic" subset which covers western European languages
+- `woff2_variable_subsets` contains a few useful subsets for variable fonts, along with some starter `@font-face` CSS which you can use as a starter to use these subsets in your own web projects.
+
+## Strategies for maximizing font performance on your website
+
+Generally, for web typography you want to use exactly as many font styles as you need to in order to deliver clear visual hierarchy and appropriate emotional impact, but not serve more data than is needed. Here are a few strategies you might consider in pursuit of that goal.
+
+### Premade variable subsets
+
+To usea wide range of styles on a website (all 5 variable axes of Recursive) in a way that will cover basically every character in the typical English or western-european language, you can simply use `woff2_variable/Recursive_VF_1.050--subset-GF_latin_basic.woff2`. This file is about 280kb.
+
+However, a slightly more-nuanced strategy for performant web font usage is utilizing `unicode-range`:
+
+> The unicode-range CSS descriptor sets the specific range of characters to be used from a font defined by @font-face and made available for use on the current page. If the page doesn't use any character in this range, the font is not downloaded; if it uses at least one, the whole font is downloaded.
+
+— source: https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range
+
+The fonts in `woff2_variable_subsets` are premade woff2 subsets, accompanied by a prewritten `@font-face` CSS in `woff2_variable_subsetsfonts.css`. You can use these fonts & CSS directly in a web project, and the browser will only download fonts as needed for the characters used on a given page. For example, if a page only includes English text, it will probably only download `Recursive_VF_1.050--subset_range_english_basic.woff2`, which is 195kb for all 5 variable axes. If another page also includes a character like the Yen (¥), Copyright (©), or the NE diagonal arrow (↗), the browser will then download `Recursive_VF_1.050--subset_range_latin_1_punc.woff2`, an additional 44kb (again, with 5 variable axes).
+
+### Static fonts & subsetting on your own
+
+If you only need a style or two on a site, it may be practical to just use static instances. These have a fairly large character set and are each about 100kb, so you may wish to also figure out subsetting with `pyftsubset` to make these even smaller. See https://css-tricks.com/three-techniques-performant-custom-font-usage/ for an introduction to this. 
+
+Here is a recipe you can use to make a "Google Fonts Latin Basic" subset via the command line – just be sure to replace the font filepath before running in a terminal:
+
+```bash
+pip install fonttools # you can use pip to install fonttools, which includes pyftsubset (https://pip.pypa.io/en/stable/installing/)
+
+fontPath="PLACE/THE/FONT/FILEPATH/HERE/IN/QUOTES" # replace this with the filepath to a woff2 font
+
+pyftsubset $fontPath --flavor="woff2" --output-file="${fontPath/'.woff2'/--subset-GF_latin_basic.woff2}" --unicodes="U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD"
+```
+
+### Taking it further
+
+This subsetting approach can be used directly on the full `woff2_variable/Recursive_VF_1.050.woff2` if you wish to custom-tailor the full variable font for your project.
+
+You can even make use of the FontTools Instacner (https://github.com/fonttools/fonttools/blob/master/Lib/fontTools/varLib/instancer.py) to instanciate your own custom instances or subset variable font (e.g. keeping only the `MONO` and `wght` axes).