From 2ad3ccf6409d8113294295673049fbe999f0b82e Mon Sep 17 00:00:00 2001
From: Neil Jenkins <neil@nmjenkins.com>
Date: Wed, 10 Dec 2014 14:47:11 +1100
Subject: [PATCH] Update README API docs and add link to demo.

---
 README.md | 226 ++++++++++++++++++++++--------------------------------
 1 file changed, 92 insertions(+), 134 deletions(-)

diff --git a/README.md b/README.md
index 22cb6c3..f81bf75 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,8 @@ Squire
 
 Squire is an HTML5 rich text editor, which provides powerful cross-browser normalisation, whilst being supremely lightweight and flexible. It is built for the present and the future, and as such does not support truly ancient browsers. It should work fine back to around Opera 12, Firefox 3.5, Safari 5, Chrome 9 and IE9.
 
+An example UI integration can be tried at http://neilj.github.io/Squire/.
+
 Unlike other HTML5 rich text editors, Squire was written as a component for writing documents (emails, essays, etc.), not doing wysiwyg websites. If you are looking for support for inserting form controls or flash components or the like, you'll need to look elsewhere. However for many purposes, Squire may be just what you need, providing the power without the bloat. The key features are:
 
 ### Lightweight ###
@@ -10,15 +12,11 @@ Unlike other HTML5 rich text editors, Squire was written as a component for writ
 * Only 11.5KB of JS after minification and gzip (35KB before gzip).
 * Does not include its own XHR wrapper, widget library or lightbox overlays.
 * No dependencies.
-* No UI for a toolbar is supplied, allowing you to integrate seamlessly with the
-  rest of your application and lose the bloat of having two UI toolkits loaded.
-  Instead, you get a component you can drop in in place of a `<textarea>` and
-  manipulate programatically.
+* No UI for a toolbar is supplied, allowing you to integrate seamlessly with the rest of your application and lose the bloat of having two UI toolkits loaded. Instead, you get a component you can drop in in place of a `<textarea>` and manipulate programatically.
 
 ### Powerful ###
 
-Squire provides an engine that handles the heavy work for you, making it easy to
-add extra features. With the `changeFormat` method you can easily add or remove any inline formatting you wish. And the `modifyBlocks` method can be used to make complicated block-level changes in a relatively easy manner.
+Squire provides an engine that handles the heavy work for you, making it easy to add extra features. With the `changeFormat` method you can easily add or remove any inline formatting you wish. And the `modifyBlocks` method can be used to make complicated block-level changes in a relatively easy manner.
 
 If you need more commands than in the simple API, I suggest you check out the source code (it's not very long), and see how a lot of the other API methods are implemented in terms of these two methods.
 
@@ -28,8 +26,8 @@ Installation and usage
 ----------------------
 
 1. Copy the contents of the `build/` directory onto your server.
-2. Edit the `<style>` block in document.html to add the default styles you would
-   like the editor to use (or link to an external stylesheet).
+2. Edit the `<style>` block in document.html to add the default styles you
+   would like the editor to use (or link to an external stylesheet).
 3. In your application, instead of a `<textarea>`, use an
    `<iframe src="path/to/document.html">`.
 4. In your JS, attach an event listener to the `load` event of the iframe. When
@@ -41,21 +39,17 @@ Installation and usage
 Advanced usage
 --------------
 
-If you load the library into a top-level document (rather than an iframe), it
-will not turn the page into an editable document, but will instead add a
-function named `Squire` to the global scope. Call `new Squire( document )`, with
-the `document` from an iframe to instantiate multiple rich text areas on the
-same page efficiently.
+If you load the library into a top-level document (rather than an iframe), it will not turn the page into an editable document, but will instead add a function named `Squire` to the global scope. Call `new Squire( document )`, with the `document` from an iframe to instantiate multiple rich text areas on the same page efficiently.
 
 License
 -------
 
-Squire is released under the MIT license. See License.txt for full license.
+Squire is released under the MIT license. See LICENSE for full license.
 
 API
 ---
 
-### addEventListener ###
+### addEventListener
 
 Attach an event listener to the editor. The handler can be either a function or an object with a `handleEvent` method. This function or method will be called whenever the event fires, with an event object as the sole argument. The following events may be observed:
 
@@ -70,308 +64,272 @@ Attach an event listener to the editor. The handler can be either a function or
 * **undoStateChange**: The availability of undo and/or redo has changed. The event object has two boolean properties, `canUndo` and `canRedo` to let you know the new state.
 * **willPaste**: The user is pasting content into the document. The content that will be inserted is available as the `fragment` property on the event object. You can modify this fragment in your event handler to change what will be pasted. You can also call the `preventDefault` on the event object to cancel the paste operation.
 
-#### Parameters ####
+The method takes two arguments:
 
 * **type**: The event to listen for. e.g. 'focus'.
 * **handler**: The callback function to invoke
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### removeEventListener ###
+### removeEventListener
 
 Remove an event listener attached via the addEventListener method.
 
-#### Parameters ####
+The method takes two arguments:
 
 * **type**: The event type the handler was registered for.
 * **handler**: The handler to remove.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### focus ###
+### focus
 
 Focuses the editor.
 
-#### Returns ####
+The method takes no arguments.
 
-Returns self.
+Returns self (the Squire instance).
 
-### blur ###
+### blur
 
-Removes focus from the editor
+Removes focus from the editor.
 
-#### Returns ####
+The method takes no arguments.
 
-Returns self.
+Returns self (the Squire instance).
 
-### getDocument ###
+### getDocument
 
 Returns the `document` object of the editable area. May be useful to do transformations outside the realm of the API.
 
-### getHTML ###
+### getHTML
 
 Returns the HTML value of the editor in its current state. This value is equivalent to the contents of the `<body>` tag and does not include any surrounding boilerplate.
 
-### setHTML ###
+### setHTML
 
 Sets the HTML value for the editor. The value supplied should not contain `<body>` tags or anything outside of that.
 
-#### Parameters ####
+The method takes one argument:
 
 * **html**: The html to set.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### getSelectedText ###
+### getSelectedText
 
 Returns the text currently selected in the editor.
 
-#### insertImage ####
+#### insertImage
 
 Inserts an image at the current cursor location.
 
-#### Parameters ####
+The method takes one argument:
 
 * **src**: The source path for the image.
 
-#### Returns ####
-
 Returns a reference to the newly inserted image element.
 
-### getPath ###
+### getPath
 
 Returns the path through the DOM tree from the `<body>` element to the current current cursor position. This is a string consisting of the tag, id and class names in CSS format. For example `BODY>BLOCKQUOTE>DIV#id>STRONG>SPAN.font>EM`. If a selection has been made, so different parts of the selection may have different paths, the value will be `(selection)`. The path is useful for efficiently determining the current formatting for bold, italic, underline etc, and thus determining button state. If a selection has been made, you can has the `hasFormat` method instead to get the current state for the properties you care about.
 
-### getSelection ###
+### getSelection
 
 Returns a W3C Range object representing the current selection/cursor position.
 
-### setSelection ###
+### setSelection
 
 Changes the current selection/cursor position.
 
-#### Parameters ####
+The method takes one argument:
 
 * **range**: The W3C Range object representing the desired selection.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### undo ###
+### undo
 
 Undoes the most recent change.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### redo ###
+### redo
 
 If the user has just undone a change, this will reapply that change.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### hasFormat ###
+### hasFormat
 
 Queries the editor for whether a particular format is applied anywhere in the current selection.
 
-#### Parameters ####
+The method takes two arguments:
 
 * **tag**: The tag of the format
 * **attributes**: (optional) Any attributes the format.
 
-#### Returns ####
-
 Returns `true` if any of the selection is contained within an element with the specified tag and attributes, otherwise returns `false`.
 
-### bold ###
+### bold
 
-Makes any non-bold currently selected text bold (by wrapping it in a `<strong>` tag).
+Makes any non-bold currently selected text bold (by wrapping it in a `<b>` tag).
 
-Returns self.
+Returns self (the Squire instance).
 
-### italic ###
+### italic
 
-Makes any non-italic currently selected text italic (by wrapping it in an `<em>` tag).
+Makes any non-italic currently selected text italic (by wrapping it in an `<i>` tag).
 
-Returns self.
+Returns self (the Squire instance).
 
-### underline ###
+### underline
 
 Makes any non-underlined currently selected text underlined (by wrapping it in a `<u>` tag).
 
-Returns self.
+Returns self (the Squire instance).
 
-### removeBold ###
+### removeBold
 
 Removes any bold formatting from the selected text.
 
-Returns self.
+Returns self (the Squire instance).
 
-### removeItalic ###
+### removeItalic
 
 Removes any italic formatting from the selected text.
 
 Returns self.
 
-### removeUnderline ###
+### removeUnderline
 
 Removes any underline formatting from the selected text.
 
 Returns self.
 
-### makeLink ###
+### makeLink
 
 Makes the currently selected text a link. If no text is selected, the URL or email will be inserted as text at the current cursor point and made into a link.
 
-#### Parameters ####
+This method takes one argument:
 
 * **url**: The url or email to link to.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### removeLink ###
+### removeLink
 
 Removes any link that is currently at least partially selected.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### setFontFace ###
+### setFontFace
 
 Sets the font face for the selected text.
 
-#### Parameters ####
+This method takes one argument:
 
 * **font**: A comma-separated list of fonts (in order of preference) to set.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### setFontSize ###
+### setFontSize
 
 Sets the font size for the selected text.
 
-#### Parameters ####
+This method takes one argument:
 
 * **size**: A size to set. Any CSS size value is accepted, e.g. '13px', or 'small'.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### setTextColour ###
+### setTextColour
 
 Sets the colour of the selected text.
 
-#### Parameters ####
+This method takes one argument:
 
 * **colour**: The colour to set. Any CSS colour value is accepted, e.g. '#f00', or 'hsl(0,0,0)'.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### setHighlightColour ###
+### setHighlightColour
 
 Sets the colour of the background of the selected text.
 
-#### Parameters ####
+This method takes one argument:
 
 * **colour**: The colour to set. Any CSS colour value is accepted, e.g. '#f00', or 'hsl(0,0,0)'.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### setTextAlignment ###
+### setTextAlignment
 
 Sets the text alignment in all blocks at least partially contained by the selection.
 
-#### Parameters ####
+This method takes one argument:
 
 * **alignment**: The direction to align to. Can be 'left', 'right', 'center' or 'justify'.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### setTextDirection ###
+### setTextDirection
 
 Sets the text direction in all blocks at least partially contained by the selection.
 
-#### Parameters ####
+This method takes one argument:
 
 * **direction**: The text direction. Can be 'ltr' or 'rtl'.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### forEachBlock ###
+### forEachBlock
 
 Executes a function on each block in the current selection, or until the function returns a truthy value.
 
-#### Parameters ####
+This method takes two arguments:
 
 * **fn** The function to execute on each block node at least partially contained in the current selection. The function will be called with the block node as the only argument.
 * **mutates** A boolean indicating whether your function may modify anything in the document in any way.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### modifyBlocks ###
+### modifyBlocks
 
 Extracts a portion of the DOM tree (up to the block boundaries of the current selection), modifies it and then reinserts it and merges the edges. See the code for examples if you're interested in using this function.
 
-#### Parameters ####
+This method takes one argument:
 
-* **modify** The function to apply to the extracted DOM tree; gets a document fragment as a sole argument. Should return the node or fragment to be reinserted in the DOM.
+* **modify** The function to apply to the extracted DOM tree; gets a document fragment as a sole argument. `this` is bound to the Squire instance. Should return the node or fragment to be reinserted in the DOM.
 
-#### Returns ####
+Returns self (the Squire instance).
 
-Returns self.
-
-### increaseQuoteLevel ###
+### increaseQuoteLevel
 
 Increases by 1 the quote level (number of `<blockquote>` tags wrapping) all blocks at least partially selected.
 
-Returns self.
+Returns self (the Squire instance).
 
-### decreaseQuoteLevel ###
+### decreaseQuoteLevel
 
 Decreases by 1 the quote level (number of `<blockquote>` tags wrapping) all blocks at least partially selected.
 
-Returns self.
+Returns self (the Squire instance).
 
-### makeUnorderedList ###
+### makeUnorderedList
 
 Changes all at-least-partially selected blocks to be part of an unordered list.
 
-Returns self.
+Returns self (the Squire instance).
 
-### makeOrderedList ###
+### makeOrderedList
 
 Changes all at-least-partially selected blocks to be part of an ordered list.
 
-Returns self.
+Returns self (the Squire instance).
 
-### removeList ###
+### removeList
 
 Changes any at-least-partially selected blocks which are part of a list to no longer be part of a list.
 
-Returns self.
+Returns self (the Squire instance).