[libadwaita/wip/exalm/alpha3: 1/3] doc: A few migration guide fixes

[Alexander Mikhaylenko <alexm src gnome org>]

commit 70eaf01621db5a5d8e24be751639edb043e1e90a
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Tue Sep 28 13:15:30 2021 +0500

    doc: A few migration guide fixes

 doc/migrating-libhandy-1-4-to-libadwaita.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)
---
diff --git a/doc/migrating-libhandy-1-4-to-libadwaita.md b/doc/migrating-libhandy-1-4-to-libadwaita.md
index dc0578e8..49f379d9 100644
--- a/doc/migrating-libhandy-1-4-to-libadwaita.md
+++ b/doc/migrating-libhandy-1-4-to-libadwaita.md
@@ -81,10 +81,14 @@ replacement and you can instead create your own objects to store those values.
 
 If your application is setting [property@Gtk.Settings:gtk-application-prefer-dark-theme]
 to `TRUE` to request dark appearance, consider setting `HdyStyleManager:color-scheme`
-to `HDY_COLOR_SCHEME_DARK_FORCE_LIGHT` or `HDY_COLOR_SCHEME_FORCE_DARK` instead,
-as needed.
+to `HDY_COLOR_SCHEME_PREFER_DARK` and making sure the application can work with
+light appearance as well. If that's not possible, set it to 
+`HDY_COLOR_SCHEME_FORCE_DARK` instead.
 
-In libadwaita this will be the only way to request dark appearance.
+If your application is using light appearance, consider setting the color scheme
+to `HDY_COLOR_SCHEME_PREFER_LIGHT` and support dark appearance.
+
+In libadwaita color schemes will be the only way to request dark appearance.
 
 ## Changes that Need to Be Done at the Time of the Switch
 
@@ -297,7 +301,7 @@ and setter. It can be replaced by [property@Adw.Avatar:custom-image].
 The `hdy_avatar_draw_to_pixbuf()` and `hdy_avatar_draw_to_pixbuf_async()`
 functions have been removed, use the newly added
 [method@Adw.Avatar.draw_to_texture] instead. [class@Gdk.Texture] implements
-`[iface Gio Icon], so it should just work for that case.
+[iface Gio Icon], so it should just work for that case.
 
 [method@Adw.Avatar.draw_to_texture] does not have the `size` parameter. Instead,
 it uses the avatar's current size, with no replacement.
@@ -357,8 +361,6 @@ The following buttons keep default appearance:
 * Buttons with the `.suggested-action` or `.destructive-action` style classes.
 * Buttons with the `.raised` style class.
 
-The following adjustments can be done to ensure consistent button appearance.
-
 It's important to avoid ambiguous layouts, for example text-only buttons with
 no icon, since such a button would be indistinguishable from the window title
 without hovering it.