Update Shaping checks documentation

Author: miguelsousa

examples/shaping.md

@@ -1,28 +1,35 @@
-Examples for the shaping check
-==============================
+# (Text) Shaping checks
 
-As well as finding structural issues with a font, openbakery contains a
-check profile (`openbakery.profiles.shaping`) which ensures that the
-font's OpenType layout rules behave as designed. To run this check, the
-designer must supply one or more test suites, which are represented as
-JSON files.
+In addition to helping you find structural issues in a font, OpenBakery contains
+a Shaping profile that can be used for validating that a font's OpenType layout
+features work as expected. To run the Shaping profile checks you need to provide
+one or more test suite files. These files are written in JSON format and include
+the parameters and values required by the checks.
 
-The `shaping/` directory contains a number of JSON files which
-illustrate the expected format and syntax of these test suites. They are also documented with comments to explain the intent of tests and how they can be customised. Copying and modifying these files can form a basis for your own shaping test suite.
+The [**shaping**](./shaping/) directory includes a few examples of such test suite
+files to illustrate the expected format and syntax the JSON files must follow.
+They are also annotated with comments that explain the intent of tests and how
+they can be customized. Copying and modifying these files can form the basis for
+your own text shaping test suite.
 
-To run the shaping check, you need to tell openbakery where to find your test suite. This can be done by creating a openbakery configuration file in YAML format and specifying the directory where the JSON files can be found:
+To run the Shaping checks, you first need to instruct `openbakery` where your test
+suite files are located. This can be done by creating a configuration file in YAML
+format. Its contents will specify the directory where the JSON files can be found:
 
 ```
 com.google.fonts/check/shaping:
     test_directory: examples/shaping
 ```
 
-If this file is saved as (e.g.) `openbakery.yml`, then the shaping check can be run with the following command:
+After saving this file — as `shaping.yml`, for example — you can then run
+the Shaping profile checks using the following command:
 
-```
-openbakery check-profile --config openbakery.yml openbakery.profiles.shaping Font.ttf
-```
+    openbakery shaping --config shaping.yml Font.ttf
+
+For best results, generate an HTML report using the `--html` option.
+
+    openbakery shaping --config shaping.yml --html shaping.html Font.ttf
 
-For best results, generate a HTML report using the `--html report.html` flag to openbakery, as this will contain SVG illustrations for failing tests.
+The report will include SVG illustrations for any failing tests.
 
-For more information on the shaping check, see https://simoncozens.github.io/tdd-for-otl/
+For more information on the Shaping checks, see https://simoncozens.github.io/tdd-for-otl/

examples/shaping/01-regression.json

@@ -1,33 +1,56 @@
 {
+  "configuration": {
+    "comment": "This is a basic configuration file for using with the Shaping profile.",
+    "comment2": "It contains examples of text shaping tests that can be used for validating",
+    "comment3": "that a font's OpenType layout features work as expected. A configuration",
+    "comment4": "file of this kind can also be assembled to represent a snapshot of a font's",
+    "comment5": "OpenType layout functionality, and be used to test if any changes occur",
+    "comment6": "whenever a new version of the font is produced.",
+    "comment7": "At a minimum, this file must contain a key named 'tests' whose value",
+    "comment8": "is an array of test blocks. Each of these blocks must include at least",
+    "comment9": "two keys named 'input' and 'expectation'.",
+    "comment10": "These comments as well as the whole 'configuration' block are not required",
+    "comment11": "for running the text shaping tests and can be removed."
+  },
   "tests": [
     {
+      "comment": "A simple test using only glyph names (without positions)",
       "input": "fi",
-      "expectation": "f_i",
-      "comment": "A simple test with only glyph names, not positions"
+      "expectation": "f_i"
     },
     {
+      "comment": "Expected positions may be specified using Harfbuzz's hb-shape syntax",
+      "comment2": "(see https://harfbuzz.github.io/utilities.html#utilities-command-line-hbshape)",
+      "input": "AVḲ",
+      "expectation": "A=0+679|V=1+676|K=2+707|dotbelowcomb.case=2@-250,0+0"
+    },
+    {
+      "comment": "Depending on your platform, the subshapers supported by",
+      "comment2": "'uharfbuzz' may be invoked using the 'shaper' key.",
+      "comment3": "'directwrite' and 'uniscribe' are available on Windows,",
+      "comment4": "and 'coretext' is available on macOS",
+      "input": "AVḲ",
+      "shaper": "coretext",
+      "expectation": "A=0+679|V=1+676|K=2+707|dotbelowcomb.case=2@-250,0+0"
+    },
+    {
+      "comment": "Features may be specified using the 'features' key",
+      "comment2": "(see https://learn.microsoft.com/typography/opentype/spec/featurelist)",
       "input": "pi",
       "features": { "smcp": true },
-      "expectation": "p.sc|i.sc",
-      "comment": "Features may be specified using the features key"
+      "expectation": "p.sc|i.sc"
     },
     {
+      "comment": "Languages may be specified using the 'language' key",
+      "comment2": "(see https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)",
+      "comment3": "It's also possible to specify the 'script'",
+      "comment4": "(see https://learn.microsoft.com/typography/opentype/spec/scripttags)",
+      "comment5": "and the 'direction'; supported values are 'LTR' (left-to-right),",
+      "comment6": "'RTL' (right-to-left), 'TTB' (top-to-bottom), and 'BTT'.",
       "input": "pi",
       "features": { "smcp": true },
       "language": "tr",
-      "expectation": "p.sc|i.sc.loclTRK",
-      "comment": "Languages may be specified using the language key"
-    },
-    {
-      "input": "AVḲ",
-      "expectation": "A=0+679|V=1+676|K=2+707|dotbelowcomb.case=2@-250,0+0",
-      "comment": "Expected positions may be specified using Harfbuzz hb-shape syntax"
-    },
-    {
-      "input": "AVḲ",
-      "expectation": "A=0+679|V=1+676|K=2+707|dotbelowcomb.case=2@-250,0+0",
-      "shaper": "coretext",
-      "comment": "If your uharfbuzz is compiled with other subshapers, these can be accessed through the shaper key."
+      "expectation": "p.sc|i.sc.loclTRK"
     }
   ]
 }

examples/shaping/02-forbidden-glyphs.json

@@ -1,16 +1,28 @@
 {
   "configuration": {
+    "comment": "(For context, read the comments in '01-regression.json' first)",
+    "comment1": "This is another example of a configuration file to be used with the Shaping profile.",
+    "comment2": "In this example, the 'forbidden_glyphs' mode is activated (by using the corresponding",
+    "comment3": "key and an array of glyph names as the value). This mode will mark as FAIL any tests",
+    "comment4": "whose shaping results include a forbidden glyph. In this mode the test blocks are not",
+    "comment5": "required to include a 'expectation' key to yield results.",
+    "comment6": "In sum, this kind of configuration can be used for checking if any glyphs declared as",
+    "comment7": "forbidden are found in the shaping results.",
     "forbidden_glyphs": [".notdef", "uni25CC"]
   },
   "tests": [
     {
+      "comment": "Basic tests will work as before...",
       "input": "fi",
-      "expectation": "f_i",
-      "comment": "Ordinary tests will be run as before..."
+      "expectation": "f_i"
     },
     {
-      "input": "世界",
-      "comment": "...but now any test (even without an expectation) which shapes a .notdef will fail"
+      "comment": "...but now any tests (even without an 'expectation') whose shaping results include",
+      "comment1": "a forbidden glyph, will be marked as FAIL. (NOTE: for this example to yield FAIL",
+      "comment2": "it's necessary to use a font that does NOT support the characters shown below.",
+      "comment3": "The FAIL occurs because the text shaper will render any unsupported characters",
+      "comment4": "as a '.notdef' glyph — which the configuration specifies as being forbidden)",
+      "input": "世界"
     }
   ]
 }

examples/shaping/03-collisions.json

@@ -1,20 +1,20 @@
 {
   "configuration": {
     "collidoscope": {
+      "comment": "The parameters in this block are passed to the Python 'collidoscope' module.",
+      "comment2": "The set of parameters specified below should detect all collisions.",
+      "comment3": "If these are too strict for your needs, try changing or removing them.",
       "area": 0,
       "marks": true,
-      "faraway": true,
-      "comment": "The parameters in this block are passed to the Python collidoscope module.",
-      "comment2": "The set of parameters specified above should detect all collisions.",
-      "comment3": "If these are too strict for your needs, try changing or removing them."
+      "faraway": true
     },
     "ingredients": {
       "vowel": "[aeiou]",
       "lowercase": "[a-z]",
       "accented_glyph": "[\u00e0-\u017e]"
     },
     "defaults": {
-      "comment": "The contents of the defaults block is added to every test dictionary",
+      "comment": "The contents of the 'defaults' block are added to all of the test blocks below",
       "allowedcollisions": [
         "medialYa-myanmar/aaSign-myanmar",
         "medialWa-myanmar/medialYa-myanmar.bt1"
@@ -23,27 +23,27 @@
   },
   "tests": [
     {
+      "comment": "Again, tests with expectations are treated as (basic) regression tests.",
       "input": "fi",
-      "expectation": "f_i",
-      "comment": "Again, tests with expectations are treated as regression tests."
+      "expectation": "f_i"
     },
     {
-      "input": "ïï",
-      "comment": "But tests (even without expectations) are now checked for collisions."
+      "comment": "But tests (even without expectations) are now checked for collisions.",
+      "input": "ïï"
     },
     {
+      "comment": "If the value of 'input_type' is 'pattern', the input is interpreted as a set of 'ingredients'.",
+      "comment2": "This means that all possible inputs matching the pattern are then checked for collisions.",
+      "comment3": "In this case, 'aa', 'ae', 'ai', 'ao', 'ao', 'au', 'ea', ... will be shaped and checked.",
       "input_type": "pattern",
-      "input": "vowel vowel",
-      "comment": "If input_type is set to pattern, the input is interpreted as a set of *ingredients*",
-      "comment2": "All possible inputs matching the pattern are then checked for collisions.",
-      "comment3": "In this case, 'aa', 'ae', 'ai', 'ao', 'ao', 'au', 'ea', ... will be shaped and checked."
+      "input": "vowel vowel"
     },
     {
+      "comment": "Ingredients are based on Python regular expressions.",
+      "comment2": "In this example all two- and three-character sequences of all accented glyphs will be checked.",
+      "comment3": "For more information see the Python 'stringbrewer' module.",
       "input_type": "pattern",
-      "input": "accented_glyph{2,3}",
-      "comment": "Ingredients are based on Python regular expressions",
-      "comment2": "This checks all two- and three-character sequences of all accented glyphs",
-      "comment3": "For more information see the Python stringbrewer module"
+      "input": "accented_glyph{2,3}"
     }
   ]
 }