Update TTS extension API docs to reflect latest changes. Note that this

Update TTS extension API docs to reflect latest changes. Note that this
splits it into two modules, tts and tts_engine.

BUG=none
TEST=none
Committed: http://src.chromium.org/viewvc/chrome?view=rev&revision=92686

[kathyw, 2011-07-13 20:39:58]

Great doc. I love the detail that you provide and the task oriented flow of the
descriptions.

Most of my comments are picky grammar things, but a few are more substantive
(such as questioning the name/capitalization of onevent or correcting values in
the text).

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
File chrome/common/extensions/docs/experimental.tts.html (right):

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:356: module which allows an
extension to implement a speech engine.
which allows -> , which allows

In general, you should put a comma before "which" in a phrase like this,
so it's clear that it's a parenthetical phrase -- one that adds information
but could be removed without changing the meaning of the sentence.

The exception is when you could change the "which" to "that", in which
case you should just use "that". (But ", which" is what we want in this case.)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:398: <p>By default, each
call to <code>speak()</code> will interrupt any
will interrupt -> interrupts

(general rule: stick to present tense whenever you can)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:399: ongoing speech and
speak immediately. To determine if a call would be
speak -> speaks

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:400: interrupting anything,
you can call <code>isSpeaking()</code>, or
The "or" makes it sound like enqueue tells you when you're interrupting
something. How about instead:

...you can call isSpeaking.
Alternatively, you can use...

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:432: errors in your use of
the TTS API, not all possible errors that might occur
Needs parallelism:

not all -> not to all
or
not all -> not to catch all

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:457:
<li><code>'start'</code>: the engine has started speaking the utterance.
the -> The

[do the same for all the following list items -- capitalize the letter that
follows the ':']

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:479: <p>Four of the event
types, <code>'end'</code>, <code>'interrupted'</code>,
It'd be easier to read this list if it were set off by dashes. So:

event types, <code>
->
event types&mdash;<code>

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:480:
<code>'cancelled'</code>, and <code>'error'</code>, are <i>final</i>. After
, are
->
&mdash;are

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:485: support any events at
all. To require that the speech engine used sends
"used sends" is a little hard to parse. How about:

To require that the speech engine used sends
->
To make sure that the speech engine can send

It's not quite as precise, but maybe that's OK here in descriptive text. Or we
could spend a little more time and come up with something better.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:488: <code>getVoices</code>
to choose a voice that has the events you need.
getVoices -> getVoices()

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:491: </p><h2 id="ssml">SSML
markup</h2>
This looks like a generator-inserted </p>. Could you add/move it right after the
paragraph?

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:498: fragment.
Add a </p> here.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:500: For example:
Add <p>...</p> before and after this line.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:511: support and still speak
the underlying text.</p>
still speak -> to still speak

(a little easier to parse)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:515: <p>By default, Chrome
will choose the most appropriate voice for each
will choose -> chooses

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:522: the appropriate voice,
or present the user with a list of choices.</p>
present -> to present

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1022: <dd>The text to speak,
either plaintext or a complete well-formed SSML document. Speech engines that do
not support SSML will strip away the tags and speak the text. The maximum length
of the text is 32,768 characters.</dd>
plaintext -> plain text

complete well-formed -> complete, well-formed

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1271: <dd>The specific
extension ID of the speech engine to use, if known.</dd>
delete "specific"

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1339: <dd>The language to be
used for synthesis, in the form &lt;language&gt;-&lt;region&gt;. Examples: 'en',
'en-US', 'en-GB', 'zh-CN', etc.</dd>
It's hard to see the - when it's between ><. How about:

&lt;language&gt;-&lt;region&gt;
->
<em>language</em>-<em>region</em>

delete ", etc"
(It's unnecessary)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1475: <dd>Speaking rate
relative to the default rate for this voice. 1.0 is the default rate, normally
around 180 to 220 words per minute, 2.0 would be twice as fast, and 0.5 would be
half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many
voices will constrain the minimum and maximum rates further - i.e. a particular
voice may not actually speak faster than 3 times normal even if you specify a
value larger than 3.0.</dd>
minute, -> minute.

2.0 would be -> 2.0 is

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1475: <dd>Speaking rate
relative to the default rate for this voice. 1.0 is the default rate, normally
around 180 to 220 words per minute, 2.0 would be twice as fast, and 0.5 would be
half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many
voices will constrain the minimum and maximum rates further - i.e. a particular
voice may not actually speak faster than 3 times normal even if you specify a
value larger than 3.0.</dd>
0.5 would be -> 0.5 is

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1475: <dd>Speaking rate
relative to the default rate for this voice. 1.0 is the default rate, normally
around 180 to 220 words per minute, 2.0 would be twice as fast, and 0.5 would be
half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many
voices will constrain the minimum and maximum rates further - i.e. a particular
voice may not actually speak faster than 3 times normal even if you specify a
value larger than 3.0.</dd>
further - i.e. a particular
->
further&mdash;for example, a particular

(i.e. means "that is", but I think this is more of an e.g. This illustrates why
it's usually better to avoid latin abbreviations!)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1543: <dd>Speaking pitch
between 0 and 2 inclusive, with 0 being lowest and 1 being highest, with 1.0
being the default pitch of this particular voice.</dd>
1 being highest -> 2 being highest

, with...voice
->
. The default pitch of this particular voice is 1.0.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1690: <dd>The TTS event
types the voice must support. If missing, this criteria will not be used to
filter voices.</dd>
"Criteria" is plural, so it'd be "these", but actually...

Couldn't we just delete the second sentence? It seems obvious. Or if you want to
keep it, clarify it -- for example, "If this field is missing, the voice might
support any set of event types, or none at all."

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1769: <dd>The TTS event
types that should be sent. If missing, all event types will be sent.</dd>
will be -> may be?

I'm not clear on why you'd use this. Is it just a way of saying "don't bother
sending events that aren't in this list, since I'm not listening for them"?

Also "all event types will be sent" makes it sound like every single possible
event type will be sent, but since speech engines don't all support every
possible event type, that doesn't make sense.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1809: <var>onevent</var>
onevent -> onEvent

or maybe -> eventHandler

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:2289: <dd>The message can be
'start' when this utterance is begun to be spoken, 'word' when a word boundary
is reached, 'sentence' when a sentence boundary is reached, 'marker' when an
SSML mark element is reached, 'end' when the end of the utterance is reached,
'interrupted' when the utterance is stopped or interrupted before reaching the
end, 'cancelled' when it's removed from the queue before ever being synthesized,
and 'error' when any other error occurs. Clients will always receive 'end',
'cancelled', 'interrupted', or 'error', and other events will depend on the
engine.</dd>
message -> type

is begun -> has begun
or
...as soon as speech has started...

and 'error' -> or 'error'

Clients...engine
->
The 'end', cancelled', interrupted', and 'error' messages
are supported for all speech engines;
support for other events depends on the engine.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:2425: <dd>The error message,
if the message is 'error'.</dd>
error message -> error description

message -> event type

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:2630: <dd>The language that
this voice supports, in the form &lt;language&gt;-&lt;region&gt;. Examples:
'en', 'en-US', 'en-GB', 'zh-CN', etc.</dd>
same <> -> <em>...</em> change as above.

delete ", etc"
(It's unnecessary)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
File chrome/common/extensions/docs/experimental.tts_engine.html (right):

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:399: with the same
name, a client can manually specify the extension id to
manually specify the extension id to
->
specify the ID of the extension that should

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:418: when speech is
finished is highly recommend, otherwise it's impossible
recommend, otherwise
->
recommended; otherwise

it's impossible...utterances.
Chrome cannot schedule...utterances.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:421: <p
class="note">If your TTS engine does not support the <code>'end'</code>
<p...>If
->
<p...>
<strong>Note:</strong>
If

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:422: event type,
Chrome will pass the <code>enqueue</code> option to
will pass -> passes

I don't understand how it can pass that option to onSpeak, and also it's a
little weird to talk about what sounds like a Chrome implementation detail.
Could you elaborate/clarify, from the developer's POV?

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:423: onSpeak, so that
your engine can implement its own queuing. However, this is
queuing -> queueing

(both are correct, but the latter is the commonly used spelling in science)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:424: discouraged
because it means that users cannot queue utterances that get
users -> extensions?

or maybe -> users of your speech engine?

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:427: <p>The possible
event types you can send correspond to the event types that
you -> that you

(missing 'that' tends to trip up non-English speakers... and sometimes English
speakers)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:431:
<li><code>'start'</code>: the engine has started speaking the utterance.
the -> The

[and do the same capitalization for every other description]

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:450: <p>The
information about your extensions's voices from your manifest
Turn this around to not have so much passive voice. Also:

extensions's -> extension's
also registered -> registered

How about:
Text-to-speech clients can get the voice information from your extension's
manifest by calling <a
href="experimental.tts.html#method-getVoices">getVoices()</a>, assuming ...

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:454: <h2
id="handling_speech_events">Handling Speech Events</h2>
Speech Events -> speech events

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:475: <p
class="warning">If an extension does not register listeners for both
<p ...>
->
<p ...><b>Important:</b>

an extension -> your extension

(not required, but it's nice to make clear that we're talking to YOU, buddy!)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:484: dynamically
decide whether to handle it or not.</p>
delete "or not". Or change "whether" to "whether or not".

(It's a little awkward but probably not incorrect to have "or not" at the end.)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:649: <p>Called when
the user makes a call to tts.speak and the options matches one of the tts_voices
from this extension's manifest.</p>
tts.speak -> tts.speak()

options matches -> options object matches

tts_voices -> voices

But what if multiple voices match? Or voices in multiple extensions? This
doesn't sound quite right.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:686: <dd>The text to
speak. This may include SSML, so if your engine does not support SSML, you
should strip out all XML markup and synthesize only the underlying text content.
This is guaranteed to be no more than 32,768 characters. If this engine does not
support speaking that many characters at a time, the utterance should be split
into smaller chunks and queued internally without returning an error.</dd>
speak.
->
speak, specified as either plain text or an SSML document. 

This may include SSML, so if
->
If

This is guaranteed
->
The value of this parameter is guaranteed

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:754: <dd>The speak
options.</dd>
The speak options -> Options specified to the tts.speak() method.

(It's a subset, and "speak options" sounds like a mistake.)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:867: <dd>The language
to be used for synthesis, in the form <language>-<region>, e.g. en-US, en-GB,
fr-CA, zh-CN, etc.</region></language></dd>
Ha, all that shows is -!

Please change to <em>language..., as before.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:1003: <dd>Speaking
rate relative to the default rate for this voice. 1.0 is the default rate,
normally around 180 to 220 words per minute, 2.0 would be twice as fast, and 0.5
would be half as fast.  This value is guaranteed to be between 0.1 and 10.0,
inclusive. When a voice does not support this full range of rates, the actual
rate should be clipped to the range that is supported without returning an
error.</dd>

See comments for tts.

Also, change the last sentence to be less passive. Maybe:

When a voice..., don't return an error if the rate is out of range. Instead,
clip the rate to the range that the voice supports.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:1071: <dd>Speaking
pitch between 0 and 2 inclusive, with 0 being lowest and 1 being highest, with
1.0 being the default pitch of this particular voice.</dd>
See comments for tts

[dmazzoni, 2011-07-14 06:50:55]

Thanks for the great review. It's great working with you, all of your
suggestions make perfect sense and help improve the writing, and you caught
several technical errors or ambiguities.

I chose the spelling onevent to match onclick from the contextMenus api - should
I stay consistent or go with onClick?

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
File chrome/common/extensions/docs/experimental.tts.html (right):

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:356: module which allows an
extension to implement a speech engine.
On 2011/07/13 20:39:58, kathyw wrote:
> which allows -> , which allows
> 
> In general, you should put a comma before "which" in a phrase like this,
> so it's clear that it's a parenthetical phrase -- one that adds information
> but could be removed without changing the meaning of the sentence.
> 
> The exception is when you could change the "which" to "that", in which
> case you should just use "that". (But ", which" is what we want in this case.)

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:398: <p>By default, each
call to <code>speak()</code> will interrupt any
On 2011/07/13 20:39:58, kathyw wrote:
> will interrupt -> interrupts
> 
> (general rule: stick to present tense whenever you can)

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:399: ongoing speech and
speak immediately. To determine if a call would be
On 2011/07/13 20:39:58, kathyw wrote:
> speak -> speaks

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:400: interrupting anything,
you can call <code>isSpeaking()</code>, or
On 2011/07/13 20:39:58, kathyw wrote:
> The "or" makes it sound like enqueue tells you when you're interrupting
> something. How about instead:
> 
> ...you can call isSpeaking.
> Alternatively, you can use...

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:432: errors in your use of
the TTS API, not all possible errors that might occur
On 2011/07/13 20:39:58, kathyw wrote:
> Needs parallelism:
> 
> not all -> not to all
> or
> not all -> not to catch all

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:457:
<li><code>'start'</code>: the engine has started speaking the utterance.
On 2011/07/13 20:39:58, kathyw wrote:
> the -> The
> 
> [do the same for all the following list items -- capitalize the letter that
> follows the ':']

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:479: <p>Four of the event
types, <code>'end'</code>, <code>'interrupted'</code>,
On 2011/07/13 20:39:58, kathyw wrote:
> It'd be easier to read this list if it were set off by dashes. So:
> 
> event types, <code>
> ->
> event types&mdash;<code>

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:480:
<code>'cancelled'</code>, and <code>'error'</code>, are <i>final</i>. After
On 2011/07/13 20:39:58, kathyw wrote:
> , are
> ->
> &mdash;are

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:485: support any events at
all. To require that the speech engine used sends
On 2011/07/13 20:39:58, kathyw wrote:
> "used sends" is a little hard to parse. How about:
> 
> To require that the speech engine used sends
> ->
> To make sure that the speech engine can send
> 
> It's not quite as precise, but maybe that's OK here in descriptive text. Or we
> could spend a little more time and come up with something better.

I tried to word it, how's this?

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:488: <code>getVoices</code>
to choose a voice that has the events you need.
On 2011/07/13 20:39:58, kathyw wrote:
> getVoices -> getVoices()

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:491: </p><h2 id="ssml">SSML
markup</h2>
On 2011/07/13 20:39:58, kathyw wrote:
> This looks like a generator-inserted </p>. Could you add/move it right after
the
> paragraph?

Strange, it doesn't look that way in the source. See
static/experimental.tts.html

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:498: fragment.
On 2011/07/13 20:39:58, kathyw wrote:
> Add a </p> here.

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:500: For example:
On 2011/07/13 20:39:58, kathyw wrote:
> Add <p>...</p> before and after this line.

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:511: support and still speak
the underlying text.</p>
On 2011/07/13 20:39:58, kathyw wrote:
> still speak -> to still speak
> 
> (a little easier to parse)

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:515: <p>By default, Chrome
will choose the most appropriate voice for each
On 2011/07/13 20:39:58, kathyw wrote:
> will choose -> chooses

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:522: the appropriate voice,
or present the user with a list of choices.</p>
On 2011/07/13 20:39:58, kathyw wrote:
> present -> to present

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1022: <dd>The text to speak,
either plaintext or a complete well-formed SSML document. Speech engines that do
not support SSML will strip away the tags and speak the text. The maximum length
of the text is 32,768 characters.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> plaintext -> plain text
> 
> complete well-formed -> complete, well-formed

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1271: <dd>The specific
extension ID of the speech engine to use, if known.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> delete "specific"

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1339: <dd>The language to be
used for synthesis, in the form &lt;language&gt;-&lt;region&gt;. Examples: 'en',
'en-US', 'en-GB', 'zh-CN', etc.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> It's hard to see the - when it's between ><. How about:
> 
> &lt;language&gt;-&lt;region&gt;
> ->
> <em>language</em>-<em>region</em>
> 
> delete ", etc"
> (It's unnecessary)

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1475: <dd>Speaking rate
relative to the default rate for this voice. 1.0 is the default rate, normally
around 180 to 220 words per minute, 2.0 would be twice as fast, and 0.5 would be
half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many
voices will constrain the minimum and maximum rates further - i.e. a particular
voice may not actually speak faster than 3 times normal even if you specify a
value larger than 3.0.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> minute, -> minute.
> 
> 2.0 would be -> 2.0 is

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1475: <dd>Speaking rate
relative to the default rate for this voice. 1.0 is the default rate, normally
around 180 to 220 words per minute, 2.0 would be twice as fast, and 0.5 would be
half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many
voices will constrain the minimum and maximum rates further - i.e. a particular
voice may not actually speak faster than 3 times normal even if you specify a
value larger than 3.0.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> 0.5 would be -> 0.5 is

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1475: <dd>Speaking rate
relative to the default rate for this voice. 1.0 is the default rate, normally
around 180 to 220 words per minute, 2.0 would be twice as fast, and 0.5 would be
half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many
voices will constrain the minimum and maximum rates further - i.e. a particular
voice may not actually speak faster than 3 times normal even if you specify a
value larger than 3.0.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> minute, -> minute.
> 
> 2.0 would be -> 2.0 is

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1475: <dd>Speaking rate
relative to the default rate for this voice. 1.0 is the default rate, normally
around 180 to 220 words per minute, 2.0 would be twice as fast, and 0.5 would be
half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many
voices will constrain the minimum and maximum rates further - i.e. a particular
voice may not actually speak faster than 3 times normal even if you specify a
value larger than 3.0.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> further - i.e. a particular
> ->
> further&mdash;for example, a particular
> 
> (i.e. means "that is", but I think this is more of an e.g. This illustrates
why
> it's usually better to avoid latin abbreviations!)

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1543: <dd>Speaking pitch
between 0 and 2 inclusive, with 0 being lowest and 1 being highest, with 1.0
being the default pitch of this particular voice.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> 1 being highest -> 2 being highest
> 
> , with...voice
> ->
> . The default pitch of this particular voice is 1.0.

I reworded it, is this okay?

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1690: <dd>The TTS event
types the voice must support. If missing, this criteria will not be used to
filter voices.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> "Criteria" is plural, so it'd be "these", but actually...
> 
> Couldn't we just delete the second sentence? It seems obvious. Or if you want
to
> keep it, clarify it -- for example, "If this field is missing, the voice might
> support any set of event types, or none at all."

You're right, it's clear enough without it.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1769: <dd>The TTS event
types that should be sent. If missing, all event types will be sent.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> will be -> may be?
> 
> I'm not clear on why you'd use this. Is it just a way of saying "don't bother
> sending events that aren't in this list, since I'm not listening for them"?
> 
> Also "all event types will be sent" makes it sound like every single possible
> event type will be sent, but since speech engines don't all support every
> possible event type, that doesn't make sense.

You're right, clarified.

It's true, this isn't necessary because you could just filter the events in the
client side, but it was requested in the review, as a convenience for
developers.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1809: <var>onevent</var>
On 2011/07/13 20:39:58, kathyw wrote:
> onevent -> onEvent
> 
> or maybe -> eventHandler

I made it all lowercase to be consistent with "onclick" in the contextMenus API:

  http://code.google.com/chrome/extensions/contextMenus.html

This may have been chosen because so many other HTML event handler properties
like "onclick" and "onkeydown" and "onreadystatechange" are all lowercase.

I can still change it to onEvent, what do you think?

In another context, eventHandler would be fine, but for web-based APIs I think
that onthis and onthat is more common.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:2289: <dd>The message can be
'start' when this utterance is begun to be spoken, 'word' when a word boundary
is reached, 'sentence' when a sentence boundary is reached, 'marker' when an
SSML mark element is reached, 'end' when the end of the utterance is reached,
'interrupted' when the utterance is stopped or interrupted before reaching the
end, 'cancelled' when it's removed from the queue before ever being synthesized,
and 'error' when any other error occurs. Clients will always receive 'end',
'cancelled', 'interrupted', or 'error', and other events will depend on the
engine.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> message -> type
> 
> is begun -> has begun
> or
> ...as soon as speech has started...
> 
> and 'error' -> or 'error'
> 
> Clients...engine
> ->
> The 'end', cancelled', interrupted', and 'error' messages
> are supported for all speech engines;
> support for other events depends on the engine.

Done, except I just deleted the last sentence because I realized it's not quite
correct. It's clearer to take it out; it's explained better in other places in
the docs.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:2425: <dd>The error message,
if the message is 'error'.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> error message -> error description
> 
> message -> event type

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:2630: <dd>The language that
this voice supports, in the form &lt;language&gt;-&lt;region&gt;. Examples:
'en', 'en-US', 'en-GB', 'zh-CN', etc.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> same <> -> <em>...</em> change as above.
> 
> delete ", etc"
> (It's unnecessary)

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
File chrome/common/extensions/docs/experimental.tts_engine.html (right):

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:399: with the same
name, a client can manually specify the extension id to
On 2011/07/13 20:39:58, kathyw wrote:
> manually specify the extension id to
> ->
> specify the ID of the extension that should

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:418: when speech is
finished is highly recommend, otherwise it's impossible
On 2011/07/13 20:39:58, kathyw wrote:
> recommend, otherwise
> ->
> recommended; otherwise
> 
> it's impossible...utterances.
> Chrome cannot schedule...utterances.

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:421: <p
class="note">If your TTS engine does not support the <code>'end'</code>
On 2011/07/13 20:39:58, kathyw wrote:
> <p...>If
> ->
> <p...>
> <strong>Note:</strong>
> If

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:422: event type,
Chrome will pass the <code>enqueue</code> option to
On 2011/07/13 20:39:58, kathyw wrote:
> will pass -> passes
> 
> I don't understand how it can pass that option to onSpeak, and also it's a
> little weird to talk about what sounds like a Chrome implementation detail.
> Could you elaborate/clarify, from the developer's POV?

I tried to reword it, is it more clear now?

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:424: discouraged
because it means that users cannot queue utterances that get
On 2011/07/13 20:39:58, kathyw wrote:
> users -> extensions?
> 
> or maybe -> users of your speech engine?

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:427: <p>The possible
event types you can send correspond to the event types that
On 2011/07/13 20:39:58, kathyw wrote:
> you -> that you
> 
> (missing 'that' tends to trip up non-English speakers... and sometimes English
> speakers)

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:431:
<li><code>'start'</code>: the engine has started speaking the utterance.
On 2011/07/13 20:39:58, kathyw wrote:
> the -> The
> 
> [and do the same capitalization for every other description]

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:450: <p>The
information about your extensions's voices from your manifest
On 2011/07/13 20:39:58, kathyw wrote:
> Turn this around to not have so much passive voice. Also:
> 
> extensions's -> extension's
> also registered -> registered
> 
> How about:
> Text-to-speech clients can get the voice information from your extension's
> manifest by calling <a
> href="experimental.tts.html#method-getVoices">getVoices()</a>, assuming ...

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:454: <h2
id="handling_speech_events">Handling Speech Events</h2>
On 2011/07/13 20:39:58, kathyw wrote:
> Speech Events -> speech events

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:475: <p
class="warning">If an extension does not register listeners for both
On 2011/07/13 20:39:58, kathyw wrote:
> <p ...>
> ->
> <p ...><b>Important:</b>
> 
> an extension -> your extension
> 
> (not required, but it's nice to make clear that we're talking to YOU, buddy!)

:)

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:484: dynamically
decide whether to handle it or not.</p>
On 2011/07/13 20:39:58, kathyw wrote:
> delete "or not". Or change "whether" to "whether or not".
> 
> (It's a little awkward but probably not incorrect to have "or not" at the
end.)

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:649: <p>Called when
the user makes a call to tts.speak and the options matches one of the tts_voices
from this extension's manifest.</p>
On 2011/07/13 20:39:58, kathyw wrote:
> tts.speak -> tts.speak()
> 
> options matches -> options object matches
> 
> tts_voices -> voices
> 
> But what if multiple voices match? Or voices in multiple extensions? This
> doesn't sound quite right.

Thanks, I reworded it to say this will be called if it's the *first* match.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:686: <dd>The text to
speak. This may include SSML, so if your engine does not support SSML, you
should strip out all XML markup and synthesize only the underlying text content.
This is guaranteed to be no more than 32,768 characters. If this engine does not
support speaking that many characters at a time, the utterance should be split
into smaller chunks and queued internally without returning an error.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> speak.
> ->
> speak, specified as either plain text or an SSML document. 
> 
> This may include SSML, so if
> ->
> If
> 
> This is guaranteed
> ->
> The value of this parameter is guaranteed

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:754: <dd>The speak
options.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> The speak options -> Options specified to the tts.speak() method.
> 
> (It's a subset, and "speak options" sounds like a mistake.)

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:867: <dd>The language
to be used for synthesis, in the form <language>-<region>, e.g. en-US, en-GB,
fr-CA, zh-CN, etc.</region></language></dd>
On 2011/07/13 20:39:58, kathyw wrote:
> Ha, all that shows is -!
> 
> Please change to <em>language..., as before.

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:1003: <dd>Speaking
rate relative to the default rate for this voice. 1.0 is the default rate,
normally around 180 to 220 words per minute, 2.0 would be twice as fast, and 0.5
would be half as fast.  This value is guaranteed to be between 0.1 and 10.0,
inclusive. When a voice does not support this full range of rates, the actual
rate should be clipped to the range that is supported without returning an
error.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> 
> See comments for tts.
> 
> Also, change the last sentence to be less passive. Maybe:
> 
> When a voice..., don't return an error if the rate is out of range. Instead,
> clip the rate to the range that the voice supports.

Done.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:1071: <dd>Speaking
pitch between 0 and 2 inclusive, with 0 being lowest and 1 being highest, with
1.0 being the default pitch of this particular voice.</dd>
On 2011/07/13 20:39:58, kathyw wrote:
> See comments for tts

Done.

[kathyw, 2011-07-14 16:13:23]

LGTM

Nice work!

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
File chrome/common/extensions/docs/experimental.tts.html (right):

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:485: support any events at
all. To require that the speech engine used sends
Good. I like the new text.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:491: </p><h2 id="ssml">SSML
markup</h2>
I was looking at old diffs, so you might have fixed it already.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1543: <dd>Speaking pitch
between 0 and 2 inclusive, with 0 being lowest and 1 being highest, with 1.0
being the default pitch of this particular voice.</dd>
> I reworded it, is this okay?

Yep, looks good.

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts.html:1809: <var>onevent</var>
I don't feel terribly strongly about this. It's just easy to read this
particular word as oneVent, and since "event" is generic in this case, it's a
little odd.

Fwiw, the context menu parameter aside, event titles in the extension APIs are
onXyz. (e.g. chrome.browserAction.onClicked).

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
File chrome/common/extensions/docs/experimental.tts_engine.html (right):

http://codereview.chromium.org/7282048/diff/1/chrome/common/extensions/docs/e...
chrome/common/extensions/docs/experimental.tts_engine.html:422: event type,
Chrome will pass the <code>enqueue</code> option to
> I tried to reword it, is it more clear now?

Yes, looks good.

[commit-bot: I haz the power, 2011-07-15 11:35:40]

Can't apply patch for file
chrome/renderer/resources/extension_process_bindings.js.
While running patch -p0 --forward --force;
patching file chrome/renderer/resources/extension_process_bindings.js
Hunk #1 FAILED at 1010.
1 out of 1 hunk FAILED -- saving rejects to file
chrome/renderer/resources/extension_process_bindings.js.rej

[commit-bot: I haz the power, 2011-07-15 12:07:33]

Presubmit check for 7282048-10001 failed and returned exit status 1.

Running presubmit commit checks ...

** Presubmit Warnings **
This change modifies the extension docs but the generated docs have not been
updated properly. See chrome/common/extensions/docs/README.txt for more info.
(Report problems to tessamac@chromium.org.)
 - Changes to chrome/common/extensions/docs/static/experimental.tts.html not
reflected in generated doc.
 - Changes to chrome/common/extensions/docs/static/experimental.ttsEngine.html
not reflected in generated doc.
First build DumpRenderTree, then update the docs by running:
  chrome/common/extensions/docs/build/build.py

Presubmit checks took 1.4s to calculate.