Edits

The <{ins}> and <{del}> elements represent edits to the document.

The ins element

Categories:
Flow content.
Phrasing content.
Palpable content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Transparent.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes.
cite - Link to the source of the edit to provide additional information.
datetime - Date and (optionally) time of the change.
[=Allowed ARIA role attribute values=]:
Any role value.
[=Allowed ARIA state and property attributes=]:
Global aria-* attributes.
Any aria-* attributes applicable to the default or allowed roles.
DOM interface:
Uses the {{HTMLModElement}} interface.
The <{ins}> element represents an addition to the document.
The following represents the addition of a single paragraph: <aside> <ins> <p> I like fruit. </p> </ins> </aside> As does the following, because everything in the <{aside}> element here counts as phrasing content and therefore there is just one paragraph: <aside> <ins> Apples are <em>tasty</em>. </ins> <ins> So are pears. </ins> </aside>
<{ins}> elements should not cross implied paragraph boundaries.
The following example represents the addition of two paragraphs, the second of which was inserted in two parts. The first <{ins}> element in this example thus crosses a paragraph boundary, which is considered poor form. <aside> <!-- don't do this --> <ins datetime="2005-03-16 00:00Z"> <p> I like fruit. </p> Apples are <em>tasty</em>. </ins> <ins datetime="2007-12-19 00:00Z"> So are pears. </ins> </aside> Here is a better way of marking this up. It uses more elements, but none of the elements cross implied paragraph boundaries. <aside> <ins datetime="2005-03-16 00:00Z"> <p> I like fruit. </p> </ins> <ins datetime="2005-03-16 00:00Z"> Apples are <em>tasty</em>. </ins> <ins datetime="2007-12-19 00:00Z"> So are pears. </ins> </aside>

The del element

Categories:
Flow content.
Phrasing content.
Contexts in which this element can be used:
Where phrasing content is expected.
Content model:
Transparent.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes.
cite - Link to the source of the edit to provide additional information.
datetime - Date and (optionally) time of the edit.
[=Allowed ARIA role attribute values=]:
Any role value.
[=Allowed ARIA state and property attributes=]:
Global aria-* attributes.
Any aria-* attributes applicable to the default or allowed roles.
DOM interface:
Uses the {{HTMLModElement}} interface.
The <{del}> element represents a removal from the document. <{del}> elements should not cross implied paragraph boundaries.
The following shows a "to do" list where items that have been done are crossed-off with the date and time of their completion. <h1>To Do</h1> <ul> <li>Empty the dishwasher</li> <li><del datetime="2009-10-11T01:25-07:00">Watch Walter Lewin's lectures</del></li> <li><del datetime="2009-10-10T23:38-07:00">Download more tracks</del></li> <li>Buy a printer</li> </ul>

Attributes common to ins and <{del}> elements

The cite attribute may be used to specify the address of a document that explains the change. When that document is long, for instance the minutes of a meeting, authors are encouraged to include a fragment pointing to the specific part of that document that discusses the change. If the <{edits/cite}> attribute is present, it must be a valid URL potentially surrounded by spaces that explains the change. To obtain the corresponding citation link, the value of the attribute must be parsed relative to the element's node document. User agents may allow users to follow such citation links, but they are primarily intended for private use (e.g., by server-side scripts collecting statistics about a site's use of quotations), not for readers. The datetime attribute may be used to specify the time and date of the change. If present, the datetime attribute's value must be a valid date string with optional time. User agents must parse the datetime attribute according to the parse a date or time string algorithm. If that doesn't return a date or a global date and time, then the modification has no associated timestamp (the value is non-conforming; it is not a valid date string with optional time). Otherwise, the modification is marked as having been made at the given date or global date and time. If the given value is a global date and time then user agents should use the associated time-zone offset information to determine which time zone to present the given datetime in. This value may be shown to the user, but it is primarily intended for private use. The <{ins}> and <{del}> elements must implement the {{HTMLModElement}} interface: 
    interface HTMLModElement : HTMLElement {
      attribute DOMString cite;
      attribute DOMString dateTime;
    };
The cite IDL attribute must reflect the element's <{edits/cite}> content attribute. The dateTime IDL attribute must reflect the element's <{edits/datetime}> content attribute.

Edits and paragraphs

This section is non-normative. Since the ins and <{del}> elements do not affect paragraphing, it is possible, in some cases where paragraphs are implied (without explicit <{p}> elements), for an ins or <{del}> element to span both an entire paragraph or other non-phrasing content elements and part of another paragraph. For example: <section> <ins> <p> This is a paragraph that was inserted. </p> This is another paragraph whose first sentence was inserted at the same time as the paragraph above. </ins> This is a second sentence, which was there all along. </section> By only wrapping some paragraphs in <{p}> elements, one can even get the end of one paragraph, a whole second paragraph, and the start of a third paragraph to be covered by the same ins or <{del}> element (though this is very confusing, and not considered good practice): <section> This is the first paragraph. <ins> This sentence was inserted. <p>This second paragraph was inserted.</p> This sentence was inserted too. </ins> This is the third paragraph in this example. <!-- (don't do this) --> </section> However, due to the way implied paragraphs are defined, it is not possible to mark up the end of one paragraph and the start of the very next one using the same ins or <{del}> element. You instead have to use one (or two) p element(s) and two ins or <{del}> elements, as for example: <section> <p>This is the first paragraph. <del>This sentence was deleted.</del></p> <p><del>This sentence was deleted too.</del> That sentence needed a separate &lt;del&gt; element.</p> </section> Partly because of the confusion described above, authors are strongly encouraged to always mark up all paragraphs with the <{p}> element, instead of having ins or <{del}> elements that cross implied paragraphs boundaries.

Edits and lists

This section is non-normative. The content models of the ol and <{ul}> elements do not allow ins and <{del}> elements as children. Lists always represent all their items, including items that would otherwise have been marked as deleted. To indicate that an item is inserted or deleted, an ins or del element can be wrapped around the contents of the <{li}> element. To indicate that an item has been replaced by another, a single <{li}> element can have one or more <{del}> elements followed by one or more <{ins}> elements.
In the following example, a list that started empty had items added and removed from it over time. The bits in the example that have been emphasized show the parts that are the "current" state of the list. The list item numbers don't take into account the edits, though. <h1>Stop-ship bugs</h1> <ol> <li><ins datetime="2008-02-12T15:20Z">Bug 225: Rain detector doesn't work in snow</ins></li> <li><del datetime="2008-03-01T20:22Z"><ins datetime="2008-02-14T12:02Z">Bug 228: Water buffer overflows in April</ins></del></li> <li><ins datetime="2008-02-16T13:50Z">Bug 230: Water heater doesn't use renewable fuels</ins></li> <li><del datetime="2008-02-20T21:15Z"><ins datetime="2008-02-16T14:25Z">Bug 232: Carbon dioxide emissions detected after startup</ins></del></li> </ol>
In the following example, a list that started with just fruit was replaced by a list with just colors. <h1>List of <del>fruits</del><ins>colors</ins></h1> <ul> <li><del>Lime</del><ins>Green</ins></li> <li><del>Apple</del></li> <li>Orange</li> <li><del>Pear</del></li> <li><ins>Teal</ins></li> <li><del>Lemon</del><ins>Yellow</ins></li> <li>Olive</li> <li><ins>Purple</ins></li> </ul>

Edits and tables

This section is non-normative. The elements that form part of the table model have complicated content model requirements that do not allow for the ins and <{del}> elements, so indicating edits to a table can be difficult. To indicate that an entire row or an entire column has been added or removed, the entire contents of each cell in that row or column can be wrapped in ins or del elements (respectively).
Here, a table's row has been added: <table> <thead> <tr><th>Game name</th> <th>Game publisher</th> <th>Verdict</th></tr> </thead> <tbody> <tr><td>Diablo 2</td> <td>Blizzard</td> <td>8/10</td></tr> <tr><td>Portal</td> <td>Valve</td> <td>9/10</td></tr> <tr><td><ins>Portal 2</ins></td> <td><ins>Valve</ins></td> <td><ins>10/10</ins></tr> </tbody> </table> Here, a column has been removed (the time at which it was removed is given also, as is a link to the page explaining why): <table> <thead> <tr><th>Game name</th> <th>Game publisher</th> <th><del cite="/edits/r192" datetime="2011-05-02 14:23Z">Verdict</del></th></tr> </thead> <tbody> <tr><td>Diablo 2</td> <td>Blizzard</td> <td><del cite="/edits/r192" datetime="2011-05-02 14:23Z">8/10</del></td></tr> <tr><td>Portal</td> <td>Valve</td> <td><del cite="/edits/r192" datetime="2011-05-02 14:23Z">9/10</del></td></tr> <tr><td>Portal 2</td> <td>Valve</td> <td><del cite="/edits/r192" datetime="2011-05-02 14:23Z">10/10</del></td></tr> </tbody> </table>
Generally speaking, there is no good way to indicate more complicated edits (e.g., that a cell was removed, moving all subsequent cells up or to the left).