deprecate draw text on path in docs

Remove documentation, see also references, and examples
that rely on SkCanvas::drawTextOnPath(HV).

Move example that uses SkDrawTextOnPath into illustrations.
TBR=reed@google.com

Docs-Preview: https://skia.org/?cl=150020
Bug: skia:6898
Change-Id: I1d92f258b75a8a10a6aa89ebf9380871ba7ecac5
Reviewed-on: https://skia-review.googlesource.com/150020
Commit-Queue: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>

4 files changed, 125 insertions, 213 deletions

diff --git a/docs/SkCanvas_Reference.bmh b/docs/SkCanvas_Reference.bmh
index 8ec893dfab..08f1dd3f47 100644
--- a/docs/SkCanvas_Reference.bmh
+++ b/docs/SkCanvas_Reference.bmh
@@ -5107,7 +5107,7 @@ void draw(SkCanvas* canvas) {
 }
 ##
 
-#SeeAlso drawString drawPosText drawPosTextH drawTextBlob drawTextOnPath drawTextRSXform
+#SeeAlso drawString drawPosText drawPosTextH drawTextBlob drawTextRSXform
 
 ##
 
@@ -5143,7 +5143,7 @@ filled 12 point black Glyphs.
    canvas->drawString("a small hello", 20, 20, paint);
 ##
 
-#SeeAlso drawText drawPosText drawPosTextH drawTextBlob drawTextOnPath drawTextRSXform
+#SeeAlso drawText drawPosText drawPosTextH drawTextBlob drawTextRSXform
 
 ##
 
@@ -5177,7 +5177,7 @@ filled 12 point black Glyphs.
    canvas->drawString(string, 20, 20, paint);
 ##
 
-#SeeAlso drawText drawPosText drawPosTextH drawTextBlob drawTextOnPath drawTextRSXform
+#SeeAlso drawText drawPosText drawPosTextH drawTextBlob drawTextRSXform
 
 ##
 
@@ -5222,7 +5222,7 @@ void draw(SkCanvas* canvas) {
 }
 ##
 
-#SeeAlso drawText drawPosTextH drawTextBlob drawTextOnPath drawTextRSXform
+#SeeAlso drawText drawPosTextH drawTextBlob drawTextRSXform
 
 ##
 
@@ -5267,7 +5267,7 @@ baseline.
     }
 ##
 
-#SeeAlso drawText drawPosText drawTextBlob drawTextOnPath drawTextRSXform
+#SeeAlso drawText drawPosText drawTextBlob drawTextRSXform
 
 ##
 
@@ -5275,111 +5275,12 @@ baseline.
 
 #Method void drawTextOnPathHV(const void* text, size_t byteLength, const SkPath& path, SkScalar hOffset,
                           SkScalar vOffset, const SkPaint& paint)
-#In Draw_Text
-#In Draw
-#Line # draws text following Path with offsets ##
-
-Draws text on Path path, using Clip, Matrix, and Paint paint.
-
-Origin of text is at distance hOffset along the path, offset by a perpendicular
-vector of length vOffset. If the path section corresponding the glyph advance is
-curved, the glyph is drawn curved to match; control points in the glyph are
-mapped to projected points parallel to the path. If the text advance is larger
-than the path length, the excess text is clipped.
-
-text meaning depends on Paint_Text_Encoding; by default, text is encoded as
-UTF-8. Origin meaning depends on Paint_Text_Align and Paint_Vertical_Text; by
-default text positions the first glyph left side bearing and baseline relative
-to origin. Text size is affected by Matrix and Paint_Text_Size.
-
-All elements of paint: Path_Effect, Mask_Filter, Shader,
-Color_Filter, Image_Filter, and Draw_Looper; apply to text. By default, draws
-filled 12 point black Glyphs.
-
-#Param  text         character code points or Glyphs drawn ##
-#Param  byteLength   byte length of text array ##
-#Param  path         Path providing text baseline ##
-#Param  hOffset      distance along path to offset origin ##
-#Param  vOffset      offset of text above (if negative) or below (if positive) the path ##
-#Param  paint        text size, blend, color, and so on, used to draw ##
-
-#Example
-    void draw(SkCanvas* canvas) {
-        const char aero[] = "correo a" "\xC3" "\xA9" "reo";
-        const size_t len = sizeof(aero) - 1;
-        SkPath path;
-        path.addOval({43-26, 43-26, 43+26, 43+26}, SkPath::kCW_Direction, 3);
-        SkPaint paint;
-        paint.setTextSize(24);
-        for (auto offset : { 0, 10, 20 } ) {
-            canvas->drawTextOnPathHV(aero, len, path, 0, -offset, paint);
-            canvas->translate(70 + offset, 70 + offset);
-        }
-    }
+#Deprecated 
 ##
 
-#SeeAlso drawTextOnPath drawText drawPosTextH drawTextBlob drawTextRSXform
-
-##
-
-# ------------------------------------------------------------------------------
-
 #Method void drawTextOnPath(const void* text, size_t byteLength, const SkPath& path,
                         const SkMatrix* matrix, const SkPaint& paint)
-#In Draw_Text
-#In Draw
-#Line # draws text following Path contour ##
-
-Draws text on Path path, using Clip, Matrix, and Paint paint.
-
-Origin of text is at beginning of path offset by matrix, if not nullptr.
-matrix transforms text before text is mapped to path. If the path section
-corresponding the glyph advance is curved, the glyph is drawn curved to match;
-control points in the glyph are mapped to projected points parallel to the path.
-If the text advance is larger than the path length, the excess text is clipped.
-
-matrix does not effect paint Shader.
-
-text meaning depends on Paint_Text_Encoding; by default, text is encoded as
-UTF-8. Origin meaning depends on Paint_Text_Align and Paint_Vertical_Text; by
-default text positions the first glyph left side bearing and baseline relative
-to origin. Text size is affected by matrix parameter, Canvas Matrix,
-and Paint_Text_Size.
-
-All elements of paint: Path_Effect, Mask_Filter, Shader,
-Color_Filter, Image_Filter, and Draw_Looper; apply to text. By default, draws
-filled 12 point black Glyphs.
-
-#Param  text         character code points or Glyphs drawn ##
-#Param  byteLength   byte length of text array ##
-#Param  path         Path providing text baseline ##
-#Param  matrix       transform of Glyphs before mapping to path; may be nullptr
-                     to use identity Matrix
-##
-#Param  paint        text size, blend, color, and so on, used to draw ##
-
-#Example
-    void draw(SkCanvas* canvas) {
-        const char roller[] = "rollercoaster";
-        const size_t len = sizeof(roller) - 1;
-        SkPath path;
-        path.cubicTo(40, -80, 120, 80, 160, -40);
-        SkPaint paint;
-        paint.setTextSize(32);
-        paint.setStyle(SkPaint::kStroke_Style);
-        SkMatrix matrix;
-        matrix.setIdentity();
-        for (int i = 0; i < 3; ++i) {
-            canvas->translate(25, 60);
-            canvas->drawPath(path, paint);
-            canvas->drawTextOnPath(roller, len, path, &matrix, paint);
-            matrix.preTranslate(0, 10);
-        }
-    }
-##
-
-#SeeAlso drawTextOnPathHV drawText drawPosTextH drawTextBlob drawTextRSXform
-
+#Deprecated
 ##
 
 # ------------------------------------------------------------------------------
@@ -5431,7 +5332,7 @@ void draw(SkCanvas* canvas) {
 }
 ##
 
-#SeeAlso drawTextOnPath drawTextOnPathHV drawText drawPosText drawTextBlob
+#SeeAlso drawText drawPosText drawTextBlob
 
 ##
 
diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
index 8a5e87a5b2..f1cd26225a 100644
--- a/docs/SkPaint_Reference.bmh
+++ b/docs/SkPaint_Reference.bmh
@@ -3477,8 +3477,7 @@ Increments drawLooper Reference_Count by one.
 
 Align adjusts the text relative to the text position.
 Align affects Glyphs drawn with: SkCanvas::drawText, SkCanvas::drawPosText,
-SkCanvas::drawPosTextH, SkCanvas::drawTextOnPath,
-SkCanvas::drawTextOnPathHV, SkCanvas::drawTextRSXform, SkCanvas::drawTextBlob,
+SkCanvas::drawPosTextH, SkCanvas::drawTextRSXform, SkCanvas::drawTextBlob,
 and SkCanvas::drawString;
 as well as calls that place text Glyphs like getTextWidths and getTextPath.
 
diff --git a/docs/SkPath_Reference.bmh b/docs/SkPath_Reference.bmh
index b41fe22ecf..23736fb5af 100644
--- a/docs/SkPath_Reference.bmh
+++ b/docs/SkPath_Reference.bmh
@@ -3023,15 +3023,11 @@ conicTo describes Arc of less than 180 degrees as a pair of tangent lines and Co
 conicTo can represent any Arc with a sweep less than 180 degrees at any rotation. All arcTo
 constructions are converted to Conic data when added to Path.
 
-#ToDo  allow example to hide source and not be exposed as fiddle since markdown / html can't
-       do the kind of table shown in the illustration.
-       example is spaced correctly on fiddle but spacing is too wide on pc
+#ToDo  example is spaced correctly on fiddle but spacing is too wide on pc
 ##
 
-#Example
-#Height 300
-#Width 600
-#Description
+#Illustration
+
 #List
 # <sup>1</sup> arcTo(const SkRect& oval, SkScalar startAngle, SkScalar sweepAngle, bool forceMoveTo) ##
 # <sup>2</sup> parameter sets force MoveTo  ##
@@ -3040,105 +3036,9 @@ constructions are converted to Conic data when added to Path.
 # <sup>5</sup> arcTo(SkScalar rx, SkScalar ry, SkScalar xAxisRotate, ArcSize largeArc,
                Direction sweep, SkScalar x, SkScalar y) ##
 #List ##
-#Description ##
-#Function
-###$
-struct data {
-   const char* name;
-   char super;
-   int yn[10];
-};
-
-const data dataSet[] = {
-{ "arcTo sweep",    '1', {1,  3, 1, 0, 0, 0, 0, 1, 0, 0 }},
-{ "drawArc",         0,  {1, -1, 1, 1, 1, 1, 1, 0, 0, 0 }},
-{ "addArc",          0,  {1,  1, 1, 4, 0, 1, 1, 1, 0, 0 }},
-{ "arcTo tangents", '4', {0,  0, 0, 0, 0, 0, 0, 1, 1, 0 }},
-{ "arcTo radii",    '5', {1,  0, 1, 0, 0, 0, 0, 1, 1, 0 }},
-{ "conicTo",         0,  {1,  1, 0, 0, 0, 0, 0, 1, 1, 1 }}
-};
-
-#define __degree_symbol__ "\xC2" "\xB0"
-
-const char* headers[] = {
-    "Oval part",
-    "force moveTo",
-    "can draw 180" __degree_symbol__,
-    "can draw 360" __degree_symbol__,
-    "can draw greater than 360" __degree_symbol__,
-    "ignored if radius is zero",
-    "ignored if sweep is zero",
-    "requires Path",
-    "describes rotation",
-    "describes perspective",
-};
-
-const char* yna[] = {
-     "n/a",
-     "no",
-     "yes"
-};
-$$$#
-##
-void draw(SkCanvas* canvas) {
-    SkPaint lp;
-    lp.setAntiAlias(true);
-    SkPaint tp(lp);
-    SkPaint sp(tp);
-    SkPaint bp(tp);
-    bp.setFakeBoldText(true);
-    sp.setTextSize(10);
-    lp.setColor(SK_ColorGRAY);
-    canvas->translate(0, 32);
-    const int tl = 115;
-    for (unsigned col = 0; col <= SK_ARRAY_COUNT(headers); ++col) {
-       canvas->drawLine(tl + col * 35, 100, tl + col * 35, 250, lp);
-       if (0 == col) {
-          continue;
-       }
-       canvas->drawLine(tl + col * 35, 100, tl + 100 + col * 35, 0, lp);
-       SkPath path;
-       path.moveTo(tl - 3 + col * 35, 103);
-       path.lineTo(tl + 124 + col * 35, -24);
-       canvas->drawTextOnPathHV(headers[col -1], strlen(headers[col -1]), path, 0, -9, bp);
-    }
-    for (unsigned row = 0; row <= SK_ARRAY_COUNT(dataSet); ++row) {
-        if (0 == row) {
-            canvas->drawLine(tl, 100, tl + 350, 100, lp);
-        } else {
-            canvas->drawLine(5, 100 + row * 25, tl + 350, 100 + row * 25, lp);
-        }
-        if (row == SK_ARRAY_COUNT(dataSet)) {
-            break;
-        }
-        canvas->drawString(dataSet[row].name, 5, 117 + row * 25, bp);
-        if (dataSet[row].super) {
-            SkScalar width = bp.measureText(dataSet[row].name, strlen(dataSet[row].name));
-            canvas->drawText(&dataSet[row].super, 1, 8 + width, 112 + row * 25, sp);
-        }
-        for (unsigned col = 0; col < SK_ARRAY_COUNT(headers); ++col) {
-            int val = dataSet[row].yn[col];
-            canvas->drawString(yna[SkTMin(2, val + 1)], tl + 5 + col * 35, 117 + row * 25, tp);
-            if (val > 1) {
-                char supe = '0' + val - 1;
-                canvas->drawText(&supe, 1, tl + 25 + col * 35, 112 + row * 25, sp);
-            }
-        }
-    }
-}
-#Example ##
 
 #Example
 #Height 128
-#Description
-#ToDo make this a list or table ##
-1 describes an arc from an oval, a starting angle, and a sweep angle.
-2 is similar to 1, but does not require building a path to draw.
-3 is similar to 1, but always begins new Contour.
-4 describes an arc from a pair of tangent lines and a radius.
-5 describes an arc from Oval center, arc start Point and arc end Point.
-6 describes an arc from a pair of tangent lines and a Conic_Weight.
-##
 void draw(SkCanvas* canvas) {
     SkRect oval = {8, 8, 56, 56};
     SkPaint ovalPaint;
@@ -3180,6 +3080,15 @@ void draw(SkCanvas* canvas) {
 }
 #Example ##
 
+In the example above:
+#List
+# 1 describes an arc from an oval, a starting angle, and a sweep angle. ##
+# 2 is similar to 1, but does not require building a path to draw. ##
+# 3 is similar to 1, but always begins new Contour. ##
+# 4 describes an arc from a pair of tangent lines and a radius. ##
+# 5 describes an arc from Oval center, arc start Point and arc end Point. ##
+# 6 describes an arc from a pair of tangent lines and a Conic_Weight. ##
+#List ##
 
 #Method SkPath& arcTo(const SkRect& oval, SkScalar startAngle, SkScalar sweepAngle, bool forceMoveTo)
 #In Build
@@ -4500,6 +4409,11 @@ After appending, Path may be empty, or may contain: Rect, Oval, or Round_Rect.
 #Return reference to Path ##
 
 #Example
+###$
+$Function
+#include "SkTextOnPath.h"
+$$
+
 void draw(SkCanvas* canvas) {
     SkPaint paint;
     paint.setAntiAlias(true);
@@ -4511,9 +4425,12 @@ void draw(SkCanvas* canvas) {
     for (int start = 0; start < 8; ++start) {
         SkPath textPath;
         textPath.addRRect(rrect, SkPath::kCW_Direction, start);
-        canvas->drawTextOnPathHV(&"01234567"[start], 1, textPath, 0, -5, paint);
+        SkMatrix matrix;
+        matrix.setTranslate(0, -5);
+        SkDrawTextOnPath(&"01234567"[start], 1, paint, textPath, &matrix, canvas);
     }
 }
+$$$#
 ##
 
 #SeeAlso addRoundRect SkCanvas::drawRRect
diff --git a/docs/illustrations.bmh b/docs/illustrations.bmh
index 0558722029..49318df832 100644
--- a/docs/illustrations.bmh
+++ b/docs/illustrations.bmh
@@ -718,4 +718,99 @@ void draw(SkCanvas* canvas) {
 ##
 ##
 
+#Subtopic Path_Arc
+#Example
+#Height 300
+#Width 600
+#Function
+###$
+#include "SkTextOnPath.h"
+struct data {
+   const char* name;
+   char super;
+   int yn[10];
+};
+
+const data dataSet[] = {
+{ "arcTo sweep",    '1', {1,  3, 1, 0, 0, 0, 0, 1, 0, 0 }},
+{ "drawArc",         0,  {1, -1, 1, 1, 1, 1, 1, 0, 0, 0 }},
+{ "addArc",          0,  {1,  1, 1, 4, 0, 1, 1, 1, 0, 0 }},
+{ "arcTo tangents", '4', {0,  0, 0, 0, 0, 0, 0, 1, 1, 0 }},
+{ "arcTo radii",    '5', {1,  0, 1, 0, 0, 0, 0, 1, 1, 0 }},
+{ "conicTo",         0,  {1,  1, 0, 0, 0, 0, 0, 1, 1, 1 }}
+};
+
+#define __degree_symbol__ "\xC2" "\xB0"
+
+const char* headers[] = {
+    "Oval part",
+    "force moveTo",
+    "can draw 180" __degree_symbol__,
+    "can draw 360" __degree_symbol__,
+    "can draw greater than 360" __degree_symbol__,
+    "ignored if radius is zero",
+    "ignored if sweep is zero",
+    "requires Path",
+    "describes rotation",
+    "describes perspective",
+};
+
+const char* yna[] = {
+     "n/a",
+     "no",
+     "yes"
+};
+$$$#
+##
+void draw(SkCanvas* canvas) {
+    SkPaint lp;
+    lp.setAntiAlias(true);
+    SkPaint tp(lp);
+    SkPaint sp(tp);
+    SkPaint bp(tp);
+    bp.setFakeBoldText(true);
+    sp.setTextSize(10);
+    lp.setColor(SK_ColorGRAY);
+    canvas->translate(0, 32);
+    const int tl = 115;
+    for (unsigned col = 0; col <= SK_ARRAY_COUNT(headers); ++col) {
+       canvas->drawLine(tl + col * 35, 100, tl + col * 35, 250, lp);
+       if (0 == col) {
+          continue;
+       }
+       canvas->drawLine(tl + col * 35, 100, tl + 100 + col * 35, 0, lp);
+       SkPath path;
+       path.moveTo(tl - 3 + col * 35, 103);
+       path.lineTo(tl + 124 + col * 35, -24);
+       SkMatrix matrix;
+       matrix.setTranslate(0, -9);
+       SkDrawTextOnPath(headers[col -1], strlen(headers[col -1]), bp, path, &matrix, canvas);
+    }
+    for (unsigned row = 0; row <= SK_ARRAY_COUNT(dataSet); ++row) {
+        if (0 == row) {
+            canvas->drawLine(tl, 100, tl + 350, 100, lp);
+        } else {
+            canvas->drawLine(5, 100 + row * 25, tl + 350, 100 + row * 25, lp);
+        }
+        if (row == SK_ARRAY_COUNT(dataSet)) {
+            break;
+        }
+        canvas->drawString(dataSet[row].name, 5, 117 + row * 25, bp);
+        if (dataSet[row].super) {
+            SkScalar width = bp.measureText(dataSet[row].name, strlen(dataSet[row].name));
+            canvas->drawText(&dataSet[row].super, 1, 8 + width, 112 + row * 25, sp);
+        }
+        for (unsigned col = 0; col < SK_ARRAY_COUNT(headers); ++col) {
+            int val = dataSet[row].yn[col];
+            canvas->drawString(yna[SkTMin(2, val + 1)], tl + 5 + col * 35, 117 + row * 25, tp);
+            if (val > 1) {
+                char supe = '0' + val - 1;
+                canvas->drawText(&supe, 1, tl + 25 + col * 35, 112 + row * 25, sp);
+            }
+        }
+    }
+}
+#Example ##
+##
+
 #Topic Illustrations ##