(docs) update README.md

- consistent md formatting
- remove empty table row
- add code fences

docs/MakeOTFUserGuide.md

@@ -1,6 +1,7 @@
 # MakeOTF OpenType/CFF compiler - User Guide
 
 ## **Overview**
+
 MakeOTF is a tool designed to create an OpenType® font from a source font file and from a text file containing high-level descriptions of OpenType layout features. It is designed to run as a command line tool: a command typed into the Terminal window on Mac OS® X, or in the DOS window on Windows®. Note that MakeOTF is only a compiler of font data, not a font editor.
 
 MakeOTF requires a number of source files that can all be specified through options for the makeotf command:
@@ -19,6 +20,7 @@ In order to avoid having to enter the options to specify the necessary files eve
 Options can be added to the `makeotf` command to set parameters that change how MakeOTF builds an OpenType font. When options conflict, the last one on the command line will override any earlier conflicting options.
 
 ## **Using MakeOTF**
+
 MakeOTF comes in two parts which can actually be called independently:
   * **`makeotfexe`** is a program written in C, and is actually the tool that builds the OpenType font file. It requires, however, that all the source files be explicitly specified with options on the command line.
 
@@ -27,6 +29,7 @@ MakeOTF comes in two parts which can actually be called independently:
 In general, one should invoke **`makeotf.py`** with the makeotf command. This way, the last set of options used will always be recorded in a project file.
 
 The first step in using MakeOTF is to assemble the source files. It is often a good idea to organize the files in a directory tree, like this:
+
 ```
 MyFontFamily/
 ├── FontMenuNameDB
@@ -57,15 +60,15 @@ The idea is that some data, such as the files `FontMenuNameDB` and `GlyphOrderAn
 Usually, positioning rules such as kerning (`features.kern`) are specific to each font, but most (or all) of the substitution rules are likely to be the same for all fonts. A good practice is to have a feature file for each family member, in the same directory as the source font file, and then use an include statement to reference feature files located higher in the directory tree. In the example above, there are two separate `features.family` files, one for Roman and another for Italic. These can, in turn, be shared between all family members under each branch. The need for two different `features.family` files comes from the fact that Roman and Italic styles might not have the same number of substitution (GSUB) rules — Italic tends to have more.
 
 Once one has assembled all the necessary files, the next step is to open a command window — the Terminal program on Mac OS X, or the Command program on Windows —, and use the cd command to set the current working directory to the directory which contains the set of source files to compile the OpenType font:
-```
+```bash
 cd <path to font directory>
 ```
 and then type the `makeotf` command, with the options needed. For example:
-```
+```bash
 makeotf –f myfont.pfa –ff myfeatures –b –r
 ```
 or
-```
+```bash
 makeotf –fp myproject.fpr
 ```
 
@@ -109,13 +112,13 @@ makeotf –fp myproject.fpr
 |`-nga`| |Turn off applying the GlyphOrderAndAliasDB file|
 |`-naddn`| |Turn off adding a standard .notdef. Can be used to override a project file setting, otherwise has no effect.|
 |`-nadds`| |Turn off adding Apple symbol glyphs. Can be used to override a project file setting, otherwise has no effect.| 
-| | | |
 
 Options are applied in the order in which they are specified: `–r –nS` will not subroutinize a font, but `–nS –r` will subroutinize a font. Option values are read (in order of increasing priority) from first the fontinfo file keyword/value pairs, then the specified project file, if any, and then from the command line, in order from left to right. 
 
 Subroutinization is a process by which common elements in a set of glyphs are decomposed in separate subroutines. This can reduce the size of the final font but can require extreme amounts of memory and time for a large font, such as CID fonts. MakeOTF may need as much as 64 Mbytes of memory for large Roman fonts, and will do most with only 32 Mbytes, but it may need 768 Mbytes of memory to subroutinize a 5-Mbyte CID font. Subroutinizing is reasonably fast when done all in memory: a few minutes for a Roman font, half an hour to three hours for a CID font. However, if the system must use virtual memory, the time required can increase by a factor of 20 or more. Subroutinizing is likely to be useful for Roman fonts, and for Korean CID fonts. Japanese and Chinese CID fonts usually only yield a few percent size reduction with subroutinizing, due to fewer repeating path elements.
 
 ## FontMenuNameDB – Version 2
+
 Previous versions of MakeOTF used a different version of the `FontMenuNameDB` file, and wrote the Macintosh font menu names differently than the Windows font menu names, and not according to the OpenType spec. This is because of some history of the early efforts to get OpenType fonts working on the Mac OS. However, for some years Apple has been following the OpenType spec when making Apple OpenType fonts, and has fully supported the OpenType font menu names. As a result, this version of MakeOTF has implemented new syntax for the `FontMenuNameDB`, and will create the name table according to the OpenType spec when this new syntax is used.
 
 Fonts made with earlier versions of MakeOTF will not be disadvantaged, as all Adobe fonts to date and many third-party fonts were made this way, and all programs look first to the Windows font menu names when they exist, as this is where the style-linking names can most reliably be found.
@@ -153,6 +156,7 @@ The key `s=` only needs to be used when you want a style name which is different
 For complete description of these issues, please read the [OpenType specification section on the name table](https://docs.microsoft.com/en-us/typography/opentype/spec/name).
 
 ### **Examples**
+
 |**Regular font of Adobe® Garamond® Pro**|
 |----------------------------------------|
 |`[AGaramondPro-Regular]`|
@@ -199,11 +203,13 @@ This font needs to be part of a new style-linking subgroup. This means the key `
 This font is part of the same style-linking subgroup as the font in the previous example. In order to be style-linked, they share the same `l=` key, but the default style will be set to Italic in this case. The Macintosh compatible Full menu name was be built by appending the default style to the compatible family menu name.
 
 ### **Note on length restrictions**
+
 Because of limitations in operating systems and common applications, it is recommended that none of these keys contain names longer than 31 characters. This results in menu names for legacy environments being 31 characters or less.
 
 The OpenType menu name (used in Adobe InDesign® and future Adobe applications) may be thought of as the combination of the `f=` and `s=` keys. Since each of these can be up to 31 characters, the OpenType menu name can be up to 62 characters.
 
 ### **Note on accented/extended characters**
+
 To use accented characters in Latin menu names, one needs two `f=` entries: one for Windows, and one for Mac. The Windows entry specifies the character by Unicode. The Mac entry specifies it by the hex value of the Mac char code from the font’s mac cmap table, when different from the ASCII value. The Unicode/character code value is preceded by a backslash (`\`):
 
 |**Arnold Böcklin**     ||
@@ -236,6 +242,7 @@ Versions of MakeOTF prior to FDK 2.5 used a similar syntax in the FontMenuNameDB
 If the key `c=` is used, then MakeOTF will build the older style name table. If the keys `l=` or `m=` are present, it will build the newer style name table . If none of these are present, then there is no difference in how the name table is built.
 
 ## **GlyphOrderAndAliasDB** (GOADB)
+
 The GOADB file is used to rename and to establish an order for the glyphs in a font.
 It is a simple text file with one line per glyph name. Each line contains at least two fields,
 and optionally a third field.
@@ -279,6 +286,7 @@ Note that MakeOTF cannot re-order glyphs when the source font is a TrueType or O
 Note that MakeOTF no longer assigns glyphs Unicode values from the Private Use Area (PUA) block. If such Unicode values are needed, they must be specified in a `GOADB` file.
 
 ## **fontinfo**
+
 The fontinfo file is a simple text file containing key-value pairs. Each line contains two white-space separated fields. The first field is a keyword, and the second field is the value. makeotf will look for a fontinfo file in the same directory as the source font file, and, if found, use it to set some default values. These values will be overridden if they are also set by a project file, and then by any `makeotf` command line options. The keywords and values currently supported are:
 
 | Keyword | Values | Effect |
@@ -329,6 +337,7 @@ Each line contains three fields. Fields are separated by a semicolon followed by
   3) CID Value. A decimal value, prefixed by “CID+”.
 
 #### Example UVS file:
+
 ```
 # Registered Adobe-Japan1 sequences
 # Version 07/30/2007
@@ -345,34 +354,40 @@ The path to the variation sequence file must be specified with the option `-ci <
 The format for the UV and UVS sequence is the same. However, the Registry-Order field is omitted, and the glyph is identified by a glyph name from the GOADB file.
 
 #### Example UVS file for a nonCID-keyed font:
+
 ```
 3402 E0100; checkbox
 3402 E0101; checkedbox
 ```
 
 ## **New `OS/2.fsSelection` Bits**
+
 In 2006, Microsoft and Adobe began discussions to define three new bit values in the OS/2 table `fsSelection` field: bit 7 `USE_TYPO_METRICS`, bit 8 `WEIGHT_WIDTH_SLOPE_ONLY`, and bit 9, `OBLIQUE`.
 
 These bits have meaning only in OS/2 table version 4 and later; in earlier versions, they are reserved, and should be set off. The Adobe Type Department will set the bits in our new fonts.
 
 #### `USE_TYPO_METRICS`
+
 When bit 7 is on, programs are supposed to use the OS/2 table sTypoAscent/Descent/LineGap for vertical line spacing. This bit was defined because the Windows layout libraries have been using the OS/2 table winAscent/Descent values instead. The next release of Windows Presentation Foundation, on which new versions of Microsoft programs such as Word will be based, and which is due in late 2006, will use the sTypo values instead – but only if this bit is on. This bit certifies that the OS/2 sTypo values are good, and have the side effect of being present only in new fonts, so that reflow of documents will happen less often than if Microsoft just changed the behavior for all fonts. For example, it is rumored that some TrueType fonts have bad values for the sTypo values, making it undesirable to apply the sTypo values for all existing fonts.
 
 The next two bits have to do with the fact that future generations of Microsoft programs, and programs from other vendors that use the Windows Presentation Foundation (WPF) libraries, will use the Cascading Style Sheet (CSS) v.2 specification for specifying fonts. The provisions of this specification can be seen at https://www.w3.org/TR/css-fonts-3/. In brief, a CSS font declaration within a document will describe a font by specifying the family name, and one or more properties; there is no way to refer directly to a specific font. The possible styles are Regular, Italic and Oblique. Weight and width are specified with separate keywords, with a limited and defined set of possible values. An example (in a simplified syntax) is `font-family: TimesStd, style: italic, weight: 700, width: normal`. One requirement of a CSS family is that each font has to have a different set of properties. There cannot be two fonts in a CSS font family which both have the properties `style: italic, weight: 700, width: normal`. For OpenType fonts, the name table Preferred Family Name is used as the CSS family name. Nonetheless, OpenType font families may well contain more than one font with a particular set of properties, but this fact will create a conflict in a CSS-based environment. When WPF encounters one of such families, it will divide the family into groups, so that only one font in each group has a given set of properties. However, that will allow WPF to provide new family names for each group, and these might not correspond to the type designer’s initial intentions.
 
 Similarly, WPF will infer the font’s properties by analyzing its Preferred Family and Style names, and may mistakenly conclude that any two fonts in a family cannot be uniquely assigned different sets of font properties. In this case, WPF will also divide the family into groups, and generate new family names for them. The `WEIGHT_WIDTH_SLOPE_ONLY` bit was added to deal with this latter case. When this bit is set in a font’s OS/2 table fsSelection field, the application is requested to trust that all fonts sharing the same Preferred Family name, will differ from all the remaining with respect to their CSS properties. That given, the application can use the OpenType name table font menu names.
 
 #### `WEIGHT_WIDTH_SLOPE_ONLY`
+
 When bit 8 is on, a program can be confident that all the fonts which share the same Preferred Font Family Name will all differ only in weight, width, and slope. The Preferred Font Family Name is defined as name table Windows platform Name ID 16 Preferred Family Name, or, if name ID 16 is not present, then Windows platform Name ID 1 Family Name. If the OS/2 table version is 4 and this bit is not on, the program will use heuristics to divide the faces with the same Preferred Family Name into CSS family groups, and assign family and property names.
 
 Yet another issue is that WPF uses heuristics applied to the font menu names to determine if the font has the Oblique style. The Oblique style can be used for either a font that was designed as a slanted form of a typeface – as opposed to a true italic design – or for a font which has been created by a program by algorithmically slanting a base font. There is no information in current OpenType fonts to indicate whether a font is Oblique. The only way to know if a current OpenType font is Oblique is through the use of heuristics based on analyzing the font name. However, no set of heuristics will be perfect. The Oblique bit was proposed in order to solve this problem, thus providing a way to clearly indicate if the font should be assigned the CSS Oblique style. As an example from the CSS specification, a Regular font within a family could be classified as Oblique just because the word “Inclined” is used in its name.
 
 #### `OBLIQUE`
+
 When bit 9 is on, programs that support the CSS2 font specification standards will consider the font to have the Oblique style, otherwise not. If the document specifies an Oblique style font, and no Oblique font is present within the CSS font family, then the application may synthetically create an Oblique style by slanting the base font. This will occur even if there is an Italic font within the same CSS font family. However, if a document font specification requires an Italic style, but only an Oblique font is available, then the latter will be used. An additional proposal suggests that if this bit is not set and the OS/2 version is 4 or greater, then the application would look for Windows platform names ID 21 and 22. If present, name ID 21 would supply the CSS compatible family name, and name ID 22 would supply the CSS-compatible property name. As of the writing of this document, the status of this proposal is still uncertain – please check the latest OpenType specification. If this proposal is accepted, the additional names can be specified in the feature file.
 
 Note that if any of these three new bits is turned on, with the option `–osbOn <n>`, then `makeotf` will require that all three values be explicitly set to be on or off. This is because, if any of new the bits is set on, `makeotf` will by default set the OS/2 version number to 4. When the version number is 4, then both the on and the off setting has a specific meaning for each bit.
 
 ## **Synthetic Glyphs**
+
 MakeOTF includes two Multiple Master fonts built-in, one serif and one sans-serif. With these it can synthesize glyphs that match (more or less) the width and weight of the source font. It requires the glyphs zero and O to be present in the font, in order to determine the required weight and width. If the option `–adds` is used, the list of glyphs to generate will be derived from the concatenation of the following three groups of glyphs:
   1) Euro
   2) Apple Symbol glyphs. These glyphs were formerly supplied by the Macintosh ATM™ and the Laserwriter® drivers. This is no longer true for OpenType fonts.