HTML 5.3: 4.6. Edits

4.6. Edits

The ins and del elements represent edits to the document.

4.6.1. 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>

4.6.2. 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>

4.6.3. 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 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 cite content attribute. The dateTime IDL attribute must reflect the element’s datetime content attribute.

4.6.4. 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.

4.6.5. 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>

4.6.6. 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).

4.6. Edits

4.6.1. The ins element

4.6.2. The del element

4.6.3. Attributes common to ins and del elements

4.6.4. Edits and paragraphs

4.6.5. Edits and lists

4.6.6. Edits and tables

4.6.1. The `ins` element

4.6.2. The `del` element

4.6.3. Attributes common to `ins` and `del` elements