From 86bdd167ccb9636da80a1ff9e0be84790005cd69 Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Fri, 8 Jun 2012 18:30:31 +0200
Subject: [PATCH] MINOR oEmbed documentation

---
 docs/en/reference/image.md          | 16 +++++++++++-----
 docs/en/topics/rich-text-editing.md | 21 +++++++++++++++++++++
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/docs/en/reference/image.md b/docs/en/reference/image.md
index 3e7c54ebb..48caca192 100644
--- a/docs/en/reference/image.md
+++ b/docs/en/reference/image.md
@@ -2,15 +2,21 @@
 
 ## Introduction
 
-Represents an image object, inheriting all base functionality from the [file](api:file) class with extra functionality
-including resizing.
+Represents an image object through the `[api:Image]` class, inheriting all base functionality from the `[api:File]` class with extra functionality including resizing.
 
 ## Usage
 
-### Form Fields
+### Managing images through form fields
 
-*  `[api:Image]`. Designed to provide a complex image uploader for the CMS.
-*  `[api:FileField]` and `[api:UploadField]`. Allows upload of images (through limiting file extensions with `setAllowedExtensions()`).
+Images can be uploaded like any other file, through `[api:FileField]`.
+More advanced usage is possible through `[api:UploadField]`,
+which provides thumbnails, a detail view of the image properties,
+and management of relationships to other DataObject instances.
+Allows upload of images through limiting file extensions with `setAllowedExtensions()`.
+
+### Inserting images into the WYSIWYG editor
+
+See [Topics: Rich Text Editing](/topics/rich-text-editing).
 
 ### Resizing Images in PHP
 
diff --git a/docs/en/topics/rich-text-editing.md b/docs/en/topics/rich-text-editing.md
index c33027afc..eb84cfba2 100644
--- a/docs/en/topics/rich-text-editing.md
+++ b/docs/en/topics/rich-text-editing.md
@@ -43,6 +43,27 @@ Example: Remove some buttons for more advanced formatting
 	// File: mysite/_config.php
 	HtmlEditorConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr');
 
+## Image and Media Insertion
+
+The `[api:HtmlEditorField]` API also handles inserting images and media 
+files into the managed HTML content. It can be used both for referencing
+files on the webserver filesystem (through the `[api:File]` and `[api:Image]` APIs),
+as well as hotlinking files from the web.
+
+## oEmbed: Embedding media through external services
+
+The ["oEmbed" standard](http://www.oembed.com/) is implemented by many media services
+around the web, allowing easy representation of files just by referencing a website URL.
+For example, a content author can insert a playable youtube video just by knowing
+its URL, as opposed to dealing with manual HTML code.
+
+oEmbed powers the "Insert from web" feature available through `[api:HtmlEditorField]`.
+Internally, it makes HTTP queries to a list of external services
+if it finds a matching URL. These services are described in the `Oembed.providers` configuration.
+Since these requests are performed on page rendering, they typically have a long cache time (multiple days). To refresh a cache, append `?flush=1` to a URL.
+
+To disable oEmbed usage, set the `Oembed.enabled` configuration property to "false".
+
 ## Recipes
 
 ### Customizing the "Insert" panels