[pango/pango2: 8/10] docs: Add a migration guide

[Matthias Clasen <matthiasc src gnome org>]

commit f99dd70d41024383ed483325ce559649163fe280
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Jun 15 19:53:21 2022 -0400

    docs: Add a migration guide

 docs/meson.build   |   1 +
 docs/migrating.md  | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/pango.toml.in |   1 +
 3 files changed, 112 insertions(+)
---
diff --git a/docs/meson.build b/docs/meson.build
index e331f67a..ee58c26a 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -9,6 +9,7 @@ pango_content_files = [
   'pango_cairo.md',
   'pango_user.md',
   'pango_layout.md',
+  'migrating.md',
   'pango-name.png',
   'layout-light.png',
   'layout-dark.png',
diff --git a/docs/migrating.md b/docs/migrating.md
new file mode 100644
index 00000000..05f50ce1
--- /dev/null
+++ b/docs/migrating.md
@@ -0,0 +1,110 @@
+---
+Title: Migrating from Pango 1.x to Pango 2
+---
+
+Pango 2 is a major new version of Pango that breaks both API and ABI
+compared to Pango 1.x. Thankfully, most of the changes are not hard
+to adapt to.
+
+## Preparation in Pango 1.x
+
+The steps outlined in the following sections assume that your
+application is working with a recent version of Pango 1.x, such
+as Pango 1.50. If you are using an older version of Pango, you
+should first get your application to build and work with
+Pango 1.50.
+
+### Do not use deprecated symbols
+
+Over the years, a number of functions and other APIs have been deprecated.
+These deprecations are clearly spelled out in the API reference, with hints
+about the recommended replacements.
+
+To verify that your program does not use any deprecated symbols,
+you can use the compiler flag
+
+    -Wdeprecated-declarations
+
+which will make the compiler warn for every use of a deprecated function.
+
+### Stop using non-cairo drawing APIs
+
+The platform-specific drawing APIs have been removed in favor of
+cairo. If you are using pango_win32_render_layout(), pango_ft2_render_layout()
+or similar APIs, you should port your application to use cairo for
+text rendering.
+
+## Changes that need to be done at the time of the switch
+
+### Build setup changes
+
+Pango 2 ships as a single shared library. If you've used libpangocairo,
+libpangoft2 or any of the other Pango 1.x libraries, you may be able to
+simplify your build setup by only linking against libpango. If you are
+using pkgconfig (as you should), just use pango2.pc, going forward.
+
+The cairo support is still optional, you can enable it with the `-Dcairo`
+meson option. But if it is enabled, it no longer requires linking against
+a separate shared library or using a separate pkgconfig file. Just include
+the `pangocairo.h` header, and use the APIs that are declared in it.
+
+### PangoFontMap changes
+
+The `PangoFontMap` class has seen some significant changes. It is now possible
+to instantiate a `PangoFontMap`, and populate it manually with `PangoFontFamily`
+and `PangoFontFace` objects. If you simply want to obtain the default fontmap
+that is populated with the native font enumeration APIs, use
+[func@Pango.FontMap.get_default]. It is no longer necessary to use cairo-specific
+APIs to obtain a suitable fontmap, and the resolution can now be set with
+[method@Pango.FontMap.set_resolution] (this used to be
+pango_cairo_font_map_set_resolution()).
+
+### PangoContext changes
+
+[ctor Pango Context new] creates a `PangoContext` that uses the default
+font map. To create a context with a custom font map, use
+[ctor@Pango.Context.new_with_font_map] (this used
+to be pango_font_map_create_context()).
+
+### PangoLayout changes
+
+Most APIs that provide information about the formatted output have been
+moved from `PangoLayout` to the new objects [class@Pango.Lines] and
+[struct@Pango.LineIter]. To obtain these from a `PangoLayout`, use
+[method@Pango.Layout.get_lines] and [method@Pango.Layout.get_iter].
+
+### PangoAttribute changes
+
+`PangoAttribute` is no longer defined with different structs. All supported
+value types can be accessed via a union in the [struct@Pango.Attribute] struct.
+The API to define your own attribute types has changed, use
+[func@Pango.AttrType.register].
+
+Some of the existing attribute types have seen changes as well. All the
+color-related attributes now take a [struct@PangoColor] argument in their
+constructor. The line-related attributes have been reorganized. There is now
+a [enum@Pango.LineStyle] enumeration that can be applied to underlines,
+and strikethroughs, and a separate [enum@Pango.UnderlinePosition] enumeration.
+Alpha attributes have been removed, since [struct@Pango.Color] now contains
+an alpha field.
+
+## New functionality to explore
+
+### Complex line breaking with PangoLineBreaker
+
+[class@Pango.LineBreaker] is the core of pango's line-breaking algorithm,
+broken out from `PangoLayout`. It gives applications more direct access to
+influence the operation of the line-breaking algorithm, and facilitates
+complex line breaking tasks such as shaped paragraphs or multi-column layout.
+
+### Application-specific fonts
+
+[class@Pango.HbFace] makes it easily possible to create fonts from font files
+that are shipped with an application or even from font data in memory. These
+custom faces can then be added to a fontmap, to make them available like any
+other font.
+
+### Custom fonts
+
+[class@Pango.UserFace] is a callback-based implementation of fonts that allows
+for entirely appication-defined font handling, including glyph drawing.
diff --git a/docs/pango.toml.in b/docs/pango.toml.in
index 77f73456..b1cf26ea 100644
--- a/docs/pango.toml.in
+++ b/docs/pango.toml.in
@@ -52,6 +52,7 @@ content_files = [
   "pango_cairo.md",
   "pango_user.md",
   "pango_layout.md",
+  "migrating.md",
 ]
 
 content_images = [