Wiki page eo.md changed with summary [some beta transition hints] by Daniel Kolesa

pages/contrib/docs/eo.md.txt

@@ -647,4 +647,87 @@ You can find handy syntax highlighting config files for different editors [here]
             values {
                 smooth_scale: bool; [[Whether to use smooth scale or not.]]
             }
-        }
+        }
+
+## Beta-only features and transitioning old Eo files
+
+### Pointers
+
+Old Eolian had a pointer syntax `ptr(T)`. Example:
+
+```
+param: ptr(Some.Struct);
+```
+
+This syntax is currently working in beta-tagged APIs for transition purposes,
+but should not be used in stable API. What you should use instead is the new
+`@by_ref` tag. It applies in multiple contexts:
+
+```
+return: T @by_ref;
+@in param: T @by_ref;
+struct_field: T @by_ref;
+```
+
+### Enum legacy field
+
+Old Eolian used to allow the `legacy` keyword to be used in enums to set
+the C prefix. This was a misnomer.
+
+```
+enum Foo {
+    legacy: BAR;
+    ...
+}
+```
+
+There is no replacement for this feature.
+
+### Owning
+
+The old `@owned` tag is now called `@move`.
+
+### Freeing functions
+
+Old Eolian used to allow `free(T, func)` to specify freeing functions on
+arbitrary types. It also had default fallbacks for freeing certain builtins.
+This is not allowed by modern Eolian. No builtins are offered (the generator
+is supposed to know them) and specifying custom freeing functions is only
+allowed on structs (with the same old `@free(func)` syntax).
+
+### Disallowed types
+
+There are some types allowed in beta but not allowed in stable.
+These include `__undefined_type`, `hash<K, V>`, `void_ptr`.
+
+### Inheritance syntax
+
+Old Eolian specified inheritance all in a single section like this:
+
+```
+class Foo(Bar, Baz, ...)
+```
+
+New Eolian has sections:
+
+```
+class Foo extends Bar implements Baz, ... composites ...
+interface Foo extends Bar, Baz, ... composites ...
+mixin Foo requires Bar extends Baz, ... composites ...
+```
+
+### Composites section
+
+This is now specified in the inheritance part instead of a section in the
+class body. Putting an interface in the composites section also automatically
+puts it in implements/extends if it isn't already found in the inheritance tree.
+
+### Misc renames
+
+The `any_value_ptr` builtin is now called `any_value_ref`.
+
+### Other notes
+
+Generally, the Eolian parser will guide you through transitioning. You can
+more or less assume that if the parser does not error, your Eo file should
+be all right; otherwise, error messages should tell you what's wrong.