Added p tags where needed

Author: joefeser

README.md

@@ -1,14 +1,14 @@
 <h1>Introduction</h1>
-
+<p>
 This proposal describes how support for "data linking" can be added to the jQuery core library. The term "data linking" is used here to mean "automatically linking the field of an object to another field of another object." That is to say, the two objects are "linked" to each other, where changing the value of one object (the 'source') automatically updates the value in the other object (the 'target').
-
+</p>
 <h2>Mutation Events</h2>
 In order to link a source to a target, it is necessary to be notified when a data associated with the source object changes, so that it can be pushed onto the target object. This plugin adds some special events to jQuery to facilitiate this, which are also useful on their own.
 
 <h3>attrChange</h3>
-
+<p>
 The 'attrChange' event fires when an attribute of a DOM element or object is changed through the jQuery.fn.attr or jQuery.attr methods. An interesting feature of this plugin is that it specifically allows for jQuery.fn.attr to be usable on plain objects or arrays. The data(), bind(), and trigger() methods all work with plain objects, so this is a natural extension which already mostly works. However, a small change was necessary to jQuery.attr to avoid the special cases applied when the target is a plain object, like class->className, and readonly->readOnly, and that negative values of "width" are ignored, etc. So this plugin also makes it officially possible to use attr() to set fields of an object as you would expect.
-
+</p>
 <pre>
 function report(ev) {
     alert("Change attr '" + ev.attrName + "' from '" +
@@ -36,9 +36,9 @@ $("#el").attrChange([ "x", "y" ], report)
     // Note no event for 'z' because the scope of 'x' and 'y' was passed in
     .attr( { x: "1", y: "2", z: "3" } );
 </pre>
-
+<p>
 The attrChange event can also be used to capture changes made through the val() and data() methods. Notice that special treatment is given to how the change is represented by the event. This consolidation of the different mutation methods causing the same event makes it simpler to handle and prevents the need for separate "dataChange" and "valChange" events. It would be nice, actually, if attr() was thought of as a general purpose mutation method and also supported this construct. For example, $(..).attr("data:foo", "bar") or $(..).attr("val", "123"). However, that is not implemented and open to discussion.
-
+</p>
 <pre>
 // works with data()
 $("#el").attrChange("data:foo", report)
@@ -55,7 +55,9 @@ $("#el").attrChange("val", report)
 
 <h3>attrChanging</h3>
 
+<p>
 The 'attrChanging' event fires when an attribute of a DOM element or object is about to be changed. The ev.preventDefault() method may be called in order to prevent the change from occuring.
+</p>
 
 <pre>
 $("#el")
@@ -74,7 +76,9 @@ $("#el")
 
 <h3>arrayChange</h3>
 
+<p>
 Like the attrChange event, but fires when an Array is mutated through any of the new array mutation APIs. Information about what the mutation was is available on the event object.
+</p>
 
 <pre>
 var arr = [1,2,3];
@@ -86,10 +90,12 @@ $([arr])
 $.push(arr, 4, 5);
 </pre>
 
+<p>
 The following array mutation events are available as static methods on the jQuery object: push, pop, splice, shift, unshift, reverse, sort. The arguments supported for each are exactly like their built-ins, except the array is passed as the first parameter.
-
+</p>
+<p>
 Like 'attrChange', the 'arrayChange' event supports filtering by the operation.
-
+</p>
 <pre>
 $([arr])
     .arrayChange(["push", "pop", "splice"], function(ev) {
@@ -105,16 +111,21 @@ $.splice(arr, 0, 1);
 
 <h3>arrayChanging</h3>
 
+<p>
 Exactly like the attrChanging event, but for arrays. Operation can be cancelled via the ev.preventDefault() method.
+</p>
 
+<h2>Linking Objects</h2>
 
-<h2>Linking Objects<h2>
-
+<p>
 When objects are linked, changes to one are automatically forwarded to another. For example, this allows you to very quickly and easily link fields of a form to an object. Any changes to the form fields are automatically pushed onto the object, saving you from writing retrieval code. Furthermore, built-in support for converters lets you modify the format or type of the value as it flows between objects (for example, formatting a phone number, or parsing a string to a number).
+</p>
 
 <h3>jQuery.link</h3>
 
+<p>
 Sets up a link that pushes changes to any of the source objects to all target objects.
+</p>
 
 <pre>
 var person = {};
@@ -128,13 +139,15 @@ alert(person.name); // foo
 alert(person.name); // <user typed value>
 </pre>
 
-The 'source' may be an object, DOM element, or string selector. 
-<strong>object</strong>
-Changes to that object through a jQuery set wrapping it will trigger the link. e.g.:
+<p>
+The 'source' may be an object, DOM element, or string selector.<br/> 
+<strong>object</strong><br/>
+Changes to that object through a jQuery set wrapping it will trigger the link. e.g.:<br/>
 <code>$(obj).attr("foo", "bar");</code>
-
-<strong>DOM element or selector</strong>
+<br/>
+<strong>DOM element or selector</strong><br/>
 This sets up a link from all the matching elements (if it is a selector) to all matching targets. For example, if there are 3 inputs and 3 spans on the page, 9 links are created, one from each input to each span.
+</p>
 
 <pre>
 $.link({
@@ -143,36 +156,42 @@ $.link({
 });
 </pre>
 
-<strong>Attributes and Microdata</strong>
+<strong>Attributes and Microdata</strong><br/>
 The 'sourceAttr' and 'targetAttr' fields are optional. If omitted, the attribute is determined automatically:
-
+<p>
 The source attribute is determined as follows:
 input, textarea, or select: "val"
 any other dom element: "text"
-
+</p>
+<p>
 The target attribute is determined as follows:
 Source is a DOM element, and has 'itemprop' microdata attribute? Use the value.
 Otherwise, use source.name or source.id.
 If source is not a DOM element, use the same rules as source attribute.
-
+</p>
+<p>
 This allows for simple links that target complex scenarios. For example, the following creates a link from all input elements inside #form1 to a single target object. The field set on the object is determined by first seeing if the input causing the event has an 'itemprop' attribute. If not, the input's name or id is used. In this example, the target's 'fullName' and 'birthday' fields would be set.
-
+</p>
 <pre>
 $.link({ source: "#form1 input", target: contact });
 
 <input type="text" itemprop="fullName" name="name" />
 <input type="text" name="birthday" />
 </pre>
 
+<p>
 For example, the following sets up a link that activates whenever the val() of the input changes, and reacts by setting the text() of the span.
+</p>
 
 <pre>
 $.link( { source: "#input1", target: "#span1" } );
 </pre>
 
-<strong>From/To Syntax</strong>
+<strong>From/To Syntax</strong><br/>
 
+<p>
 $.link supports creating multiple links with different rules at the same time. In this example, two form elements are mapped to two different fields of the same object.
+</p>
 
 <pre>
 $.link({
@@ -186,7 +205,9 @@ $.link({
 });
 </pre>
 
+<p>
 Each value specified can be an array, or not. If not, the one value is applied to all cases. If an array, corresponding indexes of each array are used to create each link. Note that each source may also still match multiple elements if it is a selector. The full syntax is:
+</p>
 
 <pre>
 $.link({
@@ -206,13 +227,17 @@ $.link({
 });
 </pre>
 
-<strong>twoWay</strong>
+<strong>twoWay</strong><br/>
 
+<p>
 The twoWay option sets up links in both directions -- from source to target, and target to source. Changes in either will be reflected in the other. This is the reason for the 'convert' option on the 'to' settings -- those converters would be used when pushing changes from a target to a source (reverse).
+</p>
 
-<strong>Updating immediately</strong>
+<strong>Updating immediately</strong><br/>
 
+<p>
 Sometimes it is desired that the target of a link reflect the source value immediately, even before the source is changed. You can tell link() to update the target immediately using the 'update' setting:
+</p>
 
 <pre>
 $.link({ source: source, target: target, update: true });
@@ -227,14 +252,16 @@ $.link({
 });
 </pre>
 
+<p>
 Note that this is particularly useful when relying on the automatic target attribute determination. You can quickly populate an object with a form's current values by relying on <code>itemprop</code> attributes or input <code>name</code>, and setting update to true to force an immediate update.
-
+</p>
+<p>
 Note that if you put 'update' on the 'from' settings, the source is updated with the target value, even though the link usually flows from the source to the target. This allows you, for example, to setup a link from an input to an object, but have the input initially reflect the value already in the target.
-
-<strong>Context</strong>
-
+</p>
+<strong>Context</strong><br/>
+<p>
 $.link in both direct and from/to forms allows a 2nd jQuery context parameter. This context is used if any selectors are given. For example, these are equivalent:
-
+</p>
 <pre>
 $.link({
     from: {
@@ -258,16 +285,20 @@ $.link({
 
 <h3>jQuery.unlink</h3>
 
+<p>
 This removes a link previously established with $.link. The syntax is exactly like $.link, including the from/to syntax, except that the 'convert' and 'update' parameters are not used. A link is identified by four pieces of data: source, sourceAttr, target, and targetAttr. Note that it is possible to remove only a portion of a link previously created. For example, assuming there are two elements on the page with css class "foo" (#foo1 and #foo2), the following creates two links -- one from each, then removes only one of them.
+</p>
 
 <pre>
 $.link( { source: ".foo", target: target, targetAttr: "field" } );
 $.unlink( { source: "#foo1", target: target, targetAttr: "field" } );
 </pre>
 
-<strong>Automatic unlinking</strong>
+<strong>Automatic unlinking</strong><br/>
 
+<p>
 Links are cleaned up when its target or source is a DOM element that is being destroyed. For example, the following setups a link between an input and a span, then destroys the span by clearing it's parent html. The link is automatically removed.
+</p>
 
 <pre>
 $.link( { source: "#input1", target: "#span1" } );
@@ -276,7 +307,9 @@ $("#span1").parent().html("");
 
 <h3>jQuery.linkLive</h3>
 
+<p>
 $.liveLink is a powerful tool that links multiple elements now or in the future. For example, to map all the input fields of a form to an object, even when form fields are dynamically added in the future:
+</p>
 
 <pre>
 $.liveLink({
@@ -289,18 +322,24 @@ $.liveLink({
 });
 </pre>
 
+<p>
 Note however that currently you cannot use 'twoWay' on a live link. You may use 'update'.
+</p>
 
 <h3>jQuery.unlinkLive</h3>
 
+<p>
 Removes a live link previously created with $.linkLive. Syntax is the same as unlink. Note that unlike regular links, live links do not expand into all the possible sources and targets when they are created. This means you cannot 'unliveLink' a portion of a live link, you may only remove the entire live link.
+</p>
 
 <h3>Conversion and jQuery.convertFn</h3>
 
+<p>
 Often times, it is necessary to modify the value as it flows from one side of a link to the other. For example, to convert null to "None", to format or parse a date, or parse a string to a number. The link APIs support specifying a converter function, either as a name of a function defined on jQuery.convertFn, or as a function itself.
-
+</p>
+<p>
 The plugin comes with one converter named "!" which negates the value.
-
+</p>
 <pre>
 var person = {};
 $.convertFn.round = function(value) {
@@ -311,7 +350,9 @@ $("#name").val("7.5");
 alert(person.age); // 8
 </pre>
 
+<p>
 It is nice to reuse converters by naming them this way. But you may also specified the converter directly as a function.
+</p>
 
 <pre>
 var person = {};
@@ -322,7 +363,9 @@ $("#name").val("7.5");
 alert(person.age); // 8
 </pre>
 
+<p>
 Converter functions receive the value that came from the source as the first parameter. They also receive a settings object which corresponds to the parameters given to the link API (if the from/to syntax was used, the settings are expanded into the more granular source/target form). This allows you to easily parameterize a converter.
+</p>
 
 <pre>
 var person = {};
@@ -336,7 +379,9 @@ $("#name").val("red");
 alert(person.age); // #FF0000
 </pre>
 
+<p>
 The settings object also contains the source and target parameters. Say you wanted to link two different fields on the source to one field the target, as in combining the first and last name fields of an object onto a single "full name" span.
+</p>
 
 <pre>
 var person = { firstName: "Some", lastName: "User" };
@@ -355,8 +400,8 @@ alert($("#fullname").text()); // "jQuery User"
 
 <h1>Revision History</h1>
 
-* 5/26/2010 -- Completely revised the API based on forum feedback.
-* 5/01/2010 -- Corrected comments about restricted scope -- event is suppressed, not the change.
-* 5/01/2010 -- Fixed glitches in comments and added info about restricted scope.
-* 4/29/2010 -- Expanded on converter samples.
-* 4/28/2010 -- Initial proposal published
+* 5/26/2010 -- Completely revised the API based on forum feedback.<br />
+* 5/01/2010 -- Corrected comments about restricted scope -- event is suppressed, not the change.<br />
+* 5/01/2010 -- Fixed glitches in comments and added info about restricted scope.<br />
+* 4/29/2010 -- Expanded on converter samples.<br />
+* 4/28/2010 -- Initial proposal published<br />