Skip to content

Commit

Permalink
Give clearer advice on hooks for standards
Browse files Browse the repository at this point in the history
Fixes #125.
  • Loading branch information
annevk committed Aug 30, 2018
1 parent 1c6f66a commit b579018
Showing 1 changed file with 19 additions and 8 deletions.
27 changes: 19 additions & 8 deletions encoding.bs
Original file line number Diff line number Diff line change
Expand Up @@ -842,14 +842,25 @@ different format here, to be able to represent ranges.)



<h2 id=specification-hooks>Specification hooks</h2>

<p class=note>The algorithms <a>decode</a>, <a>UTF-8 decode</a>,
<a>UTF-8 decode without BOM</a>, <a>UTF-8 decode without BOM or fail</a>,
<a for=/>encode</a>, and <a>UTF-8 encode</a> are intended for usage by other specifications.
<a>UTF-8 decode</a> is to be used by new formats. The
<a>get an encoding</a> algorithm can be used first to turn a
<a>label</a> into an <a for=/>encoding</a>.
<h2 id=specification-hooks>Hooks for standards</h2>

<div class=note>
<p>The algorithms defined below (<a>decode</a>, <a>UTF-8 decode</a>,
<a>UTF-8 decode without BOM</a>, <a>UTF-8 decode without BOM or fail</a>, <a for=/>encode</a>, and
<a>UTF-8 encode</a>) are intended for usage by other standards.

<p>For decoding, <a>UTF-8 decode</a> is to be used by new formats. For identifiers or byte
sequences within a format or protocol, use <a>UTF-8 decode without BOM</a> or
<a>UTF-8 decode without BOM or fail</a>.

<p>For encoding, <a>UTF-8 encode</a> is to be used.

<p>Standards are strongly discouraged from using <a>decode</a> and <a for=/>encode</a>, except as
needed for compatibility.

<p>The <a>get an encoding</a> algorithm is to be used to turn a <a>label</a> into an
<a for=/>encoding</a>.
</div>

<p>To <dfn export>decode</dfn> a byte stream <var>stream</var> using
fallback encoding <var>encoding</var>, run these steps:
Expand Down

0 comments on commit b579018

Please sign in to comment.