Update to latest tags

Author: JimBobSquarePants

articles/fonts/hinting.md

@@ -0,0 +1,100 @@
+# TrueType Hinting
+
+Font hinting is the use of instructions in a font to adjust outline glyphs for a raster grid. In TrueType fonts, those instructions are bytecode programs stored in the font. The rasterizer executes them at a given size and DPI to move outline points before the glyph is drawn.
+
+## Why Hinting Exists
+
+Outline fonts are scalable. Raster images are not. When a glyph is small, its outline has to be represented by a limited number of pixels. Without adjustment, similar stems can round to different widths, horizontal features can fall between pixel rows, and small counters or serifs can lose definition.
+
+Hinting changes the scaled outline before rasterization. It can improve:
+
+- stem thickness
+- counter shape
+- baseline alignment
+- x-height consistency
+- serif and bar visibility
+- mark attachment stability
+
+The effect is most visible for small UI text at ordinary screen DPI. At larger sizes or high-resolution outputs, the outline has more pixels available and hinting usually has less visible effect.
+
+## How Fonts Applies Hinting
+
+[`TextOptions.HintingMode`](xref:SixLabors.Fonts.TextOptions.HintingMode) controls whether Fonts applies TrueType hinting:
+
+- [`HintingMode.None`](xref:SixLabors.Fonts.HintingMode.None) leaves glyph outlines unhinted.
+- [`HintingMode.Standard`](xref:SixLabors.Fonts.HintingMode.Standard) applies the library's FreeType v40-compatible TrueType hinting behavior.
+
+```csharp
+using SixLabors.Fonts;
+
+Font font = SystemFonts.CreateFont("Segoe UI", 11);
+TextOptions options = new(font)
+{
+    Dpi = 96,
+    HintingMode = HintingMode.Standard
+};
+```
+
+The active font size and [`Dpi`](xref:SixLabors.Fonts.TextOptions.Dpi) matter because hinting targets a specific pixels-per-em scale.
+
+## Fonts' Hinting Approach
+
+Fonts uses a TrueType bytecode interpreter modeled on FreeType's v40 subpixel hinting behavior. In practical terms, that means Fonts preserves full vertical TrueType instruction processing while intentionally disabling horizontal hinting.
+
+This approach is designed for modern antialiased text rendering, where horizontal subpixel placement should remain smooth and glyph advances should not be forced into old bi-level grid-fitting behavior. It gives small text the vertical alignment benefits of TrueType hinting while avoiding legacy horizontal snapping that can make spacing and shapes less consistent in modern raster output.
+
+When hinting is active, Fonts:
+
+- executes the font program from `fpgm` to initialize TrueType function definitions
+- scales the Control Value Table from `cvt ` for the current size and DPI
+- executes the `prep` program to establish the graphics state for glyph programs
+- applies `cvar` deltas to control values for variable TrueType fonts before hinting
+- provides normalized variation coordinates for TrueType variation-aware instructions
+- adds the four TrueType phantom points used for horizontal and vertical metrics during glyph hinting
+- executes each glyph's TrueType instructions against the resolved outline
+- leaves the outline unhinted if a glyph has no instructions, hinting is inhibited by the font program, or instruction execution fails
+
+## TrueType Scope
+
+Fonts applies this hinting path to TrueType outlines. It does not turn CFF or CFF2 outlines into hinted TrueType outlines, and it does not change which glyphs are selected for the text.
+
+Within the TrueType path, Fonts supports:
+
+- TrueType glyph instruction execution.
+- Standard TrueType hinting tables such as `fpgm`, `prep`, and `cvt `.
+- Per-glyph hinting at the active size and DPI.
+- `cvar`-driven control-value adjustments for variable TrueType fonts before hinting runs.
+- Hinted contour-point resolution for GPOS anchor data when a font uses contour-point anchors.
+- Font-specific compatibility behavior for fonts known to require hinting.
+
+## When to Enable It
+
+Use [`HintingMode.Standard`](xref:SixLabors.Fonts.HintingMode.Standard) when rendering small TrueType UI text to a raster target and you want grid-fitted outlines.
+
+Use [`HintingMode.None`](xref:SixLabors.Fonts.HintingMode.None) when you want raw outline behavior, when you are rendering large display text, or when the text is being treated as artwork rather than screen UI.
+
+There is no universal best setting. Hinting is a raster-quality tradeoff: it can make small text clearer, but it can also move outlines away from their pure scaled design.
+
+## Common Misunderstandings
+
+Hinting does not:
+
+- fix missing glyphs
+- enable ligatures or OpenType features
+- choose fallback fonts
+- reorder complex scripts
+- resolve bidirectional text
+- change Unicode indexing or grapheme behavior
+
+Those are layout and shaping concerns. For those, see [Text Shaping](shaping.md).
+
+## Further Reading
+
+[The Raster Tragedy](http://rastertragedy.com/) is a useful deeper discussion of why rasterizing outline text is difficult and why hinting can matter for small text.
+
+## Related Topics
+
+- [Text Layout and Options](textlayout.md)
+- [Text Shaping](shaping.md)
+- [Font Metrics](fontmetrics.md)
+- [Custom Rendering](customrendering.md)

articles/fonts/hintingandshaping.md

@@ -18,7 +18,7 @@ The Unicode pages are part of the practical API story, not a side topic. Most re
 Fonts is licensed under the terms of the [Six Labors Split License, Version 1.0](https://github.com/SixLabors/Fonts/blob/main/LICENSE). See https://sixlabors.com/pricing for commercial licensing details.
 
 >[!IMPORTANT]
->Starting with Fonts 3.0.0, projects that directly depend on SixLabors.Fonts require a valid Six Labors license at build time. Add `sixlabors.lic` to your repository root, set `SixLaborsLicenseFile`, or set `SixLaborsLicenseKey`. This enforcement applies to direct dependencies only. See [License Enforcement Changes and a New Subscription Tier](https://sixlabors.com/posts/licence-enforcement-changes/) for details.
+>Starting with Fonts 3.0.0, projects that directly depend on SixLabors.Fonts require a valid Six Labors license at build time. This enforcement applies to direct dependencies only. See [License Enforcement Changes and a New Subscription Tier](https://sixlabors.com/posts/licence-enforcement-changes/) for details.
 
 ### Installation
 
@@ -55,9 +55,9 @@ paket add SixLabors.Fonts --version VERSION_NUMBER
 
 ### How to use the license file
 
-Add the supplied `sixlabors.lic` file to your repository root. Use the file as supplied; it already contains the complete license string required by the build.
+By default, the build searches from each project directory for `sixlabors.lic`. Place the supplied file in the directory that contains the project file, or in a subdirectory below it. Use the file as supplied; it already contains the complete license string required by the build.
 
-If you want to keep the file somewhere else, set `SixLaborsLicenseFile` in your project file or a shared props file:
+If you want to keep the file somewhere else, including a repository root that sits above the project directory, set `SixLaborsLicenseFile` in your project file or a shared props file:
 
 ```xml
 <PropertyGroup>
@@ -104,7 +104,8 @@ If you are new to Fonts, start with [Loading Fonts and Collections](gettingstart
 - [Selection and Bidi Drag](caretsandselection.md)
 - [Text Layout and Options](textlayout.md)
 - [OpenType Features](opentypefeatures.md)
-- [Hinting and Shaping](hintingandshaping.md)
+- [Text Shaping](shaping.md)
+- [TrueType Hinting](hinting.md)
 - [Color Fonts](colorfonts.md)
 - [Unicode, Code Points, and Graphemes](unicode.md)
 - [Fallback Fonts and Multilingual Text](fallbackfonts.md)

articles/fonts/index.md

@@ -126,7 +126,7 @@ Some OpenType features are especially relevant in vertical layout, such as [`Kno
 
 Those work alongside [`LayoutMode`](xref:SixLabors.Fonts.TextOptions.LayoutMode); they do not replace it.
 
-For the surrounding layout controls, see [Text Layout and Options](textlayout.md). For the broader shaping pipeline, see [Hinting and Shaping](hintingandshaping.md).
+For the surrounding layout controls, see [Text Layout and Options](textlayout.md). For the broader shaping pipeline, see [Text Shaping](shaping.md).
 
 ### Practical guidance