From 04338a5e52d19529e4fe77cd370d1235592ba7e1 Mon Sep 17 00:00:00 2001
From: Alexei Podtelezhnikov <apodtele@gmail.com>
Date: Tue, 12 Jun 2018 21:59:15 -0400
Subject: [PATCH] Doc fixes and improvements.

---
 include/freetype/freetype.h   |  6 +++---
 include/freetype/ftchapters.h |  2 +-
 include/freetype/ftlcdfil.h   | 23 +++++++++++------------
 3 files changed, 15 insertions(+), 16 deletions(-)

diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 2b413814e..56a9620df 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -64,9 +64,9 @@ FT_BEGIN_HEADER
    *
    *   A compiler and its preprocessor only needs an include path to find
    *   the file `ft2build.h'; the exact locations and names of the other
-   *   FreeType header files are hidden by preprocessor macro names,
-   *   loaded by `ft2build.h'.  The API documentation always gives the
-   *   header macro name needed for a particular function.
+   *   FreeType header files are hidden by @header_file_macros, loaded by
+   *   `ft2build.h'.  The API documentation always gives the header macro
+   *   name needed for a particular function.
    *
    */
 
diff --git a/include/freetype/ftchapters.h b/include/freetype/ftchapters.h
index f220e4b71..6ed66d69f 100644
--- a/include/freetype/ftchapters.h
+++ b/include/freetype/ftchapters.h
@@ -81,6 +81,7 @@
  *   pcf_driver
  *   properties
  *   parameter_tags
+ *   lcd_rendering
  *
  */
 
@@ -120,7 +121,6 @@
  *   gzip
  *   lzw
  *   bzip2
- *   lcd_rendering
  *
  */
 
diff --git a/include/freetype/ftlcdfil.h b/include/freetype/ftlcdfil.h
index 2989ceb63..0042f7601 100644
--- a/include/freetype/ftlcdfil.h
+++ b/include/freetype/ftlcdfil.h
@@ -73,10 +73,8 @@ FT_BEGIN_HEADER
    *   3) It should be normalized, meaning 2a~+ 2b~+ c~=~1.0 to maintain
    *      overall brightness.
    *
-   *   The distribution of density values by the color-balanced filter assumes
-   *   alpha blending is done in linear space; only then color artifacts
-   *   cancel out. Boxy 3-tap filter {0, 1/3, 1/3, 1/3, 0} is sharper but is
-   *   less forgiving of non-ideal gamma curves of a screen (viewing angles!),
+   *   Boxy 3-tap filter {0, 1/3, 1/3, 1/3, 0} is sharper but is less
+   *   forgiving of non-ideal gamma curves of a screen (and viewing angles),
    *   beveled filters are fuzzier but more tolerant.
    *
    *   Use the @FT_Library_SetLcdFilter or @FT_Library_SetLcdFilterWeights
@@ -93,10 +91,7 @@ FT_BEGIN_HEADER
    *
    *   The subpixel geometry must be specified by xy-coordinates for each
    *   subpixel. By convention they may come in the RGB order:
-   *
-   *   {{-1/3, 0}, {0, 0}, {1/3, 0}} for hRGB striped panel (default),
-   *   {{1/3, 0}, {0, 0}, {-1/3, 0}} for hBGR striped panel,
-   *   {{0, 1/3}, {0, 0}, {0, -1/3}} for vRGB striped panel,
+   *   {{-1/3, 0}, {0, 0}, {1/3, 0}} for standard RGB striped panel or
    *   {{-1/6, 1/4}, {-1/6, -1/4}, {1/3, 0}} for a certain PenTile panel.
    *
    *   Use the @FT_Library_SetLcdGeometry API to specify subpixel positions.
@@ -115,9 +110,13 @@ FT_BEGIN_HEADER
    *   glyph positioning code when enabling the filter.
    *
    *   The ClearType and Harmony rendering is applicable to glyph bitmaps
-   *   rendered through @FT_Render_Glyph, @FT_Load_Glyph, and @FT_Load_Char.
-   *   @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V and these technologies do
-   *   not apply to @FT_Outline_Render and @FT_Outline_Get_Bitmap directly.
+   *   rendered through @FT_Render_Glyph, @FT_Load_Glyph, @FT_Load_Char, and
+   *   @FT_Glyph_To_Bitmap, when @FT_RENDER_MODE_LCD or @FT_RENDER_MODE_LCD_V
+   *   is specified.  This API does not control @FT_Outline_Render and
+   *   @FT_Outline_Get_Bitmap.
+   *
+   *   The described algorithms can completely remove color artefacts when
+   *   combined with gamma-corrected alpha blending in linear space.
    *   Each of the 3~alpha values (subpixels) must by independently used to
    *   blend one color channel.  That is, red alpha blends the red channel of
    *   the text color with the red channel of the background pixel.
@@ -294,7 +293,7 @@ FT_BEGIN_HEADER
    * @note:
    *   Subpixel geometry examples:
    *
-   *   - {{-21, 0}, {0, 0}, {21, 0}} is the default, corresponding 3 color
+   *   - {{-21, 0}, {0, 0}, {21, 0}} is the default, corresponding to 3 color
    *   stripes shifted by a third of a pixel. This could be an RGB panel.
    *
    *   - {{21, 0}, {0, 0}, {-21, 0}} looks the same as the default but