Grammar Guide

A guide to writing What Can I Say description files

The What Can I Say window dynamically displays phrases that Voice Manager will recognize. These phrases are not automatically generated from a grammar file but must be written by hand in a What Can I Say description file. This allows for more control over how a grammar is represented in the What Can I Say window. For example, the grammar writer may want to organize the What Can I Say information in a certain way, or may wish to elide specific phrases.

Syntax of the description file

Each line of the description file contains an 8 character prefix. Many of the character positions of this prefix are not used by Voice Manager (they are used by other applications). As a result, many of these positions contain a period (".") as a placeholder. The positions (from left to right) denote the following:

column 1: The possible values for this column are:
T denotes the title line. Each What Can I Say file must start with a title line and there can only be one title line per file.
H denotes a heading. Typically, headers are names of general categories of phrases that a user might say. For example, a header might be "move commands". A What Can I Say description file can be thought of as a simple outline. The headers are general topics with phrases listed as entries underneath them.
X denotes a phrase that can be said by a user.
D denotes the start of a definition sequence. This will be further explained in the section on the &&_ annotation.
column 2: The value of this column is always E
column 3: The possible values for this column are:
S if the line is to be shown in the What Can I Say Window.
H if the line is to be hidden in the What Can I Say Window. For example, the line may be intended as a comment when viewing the description file.
column 4: The value of this column is always a period (".").
column 5: The value of this column can be:
. (period), which is mandatory if the value of the first column is D. It is also mandatory if the first column is X and the line contains no &&_ sequences.
+ which indicates that the subentries of this line are collapsed.
- which indicates that subentries of this line are expanded. Either a + or - are required if the first column is a T or an H. One of them is also required if the first column is an X and the line contains an &&_ sequence.
column 6: The value of this column is always a period.
column 7: The value of this column is:
. if the line is to be displayed in the default font color (typically, black).
X if the line is to be displayed in blue.
column 8: The value of this column is always a period.

An Example

TES.+...Simple Example
HES.+...Alignment Commands
XES.....align left
XES.....align right
XES.....center
XES.....justify
HES.+...Insertion Commands
XES.....insert bullet
XES.....insert note
XES.....insert today's date
XES.....insert time
XES.....insert page break

Recall that the + in column five indicates that the line should be viewed with the subentries collapsed. Thus, this grammar will add the following line to the What Can I Say window:

+  Simple Example

If a user clicks on that line it will be expanded to

-  Simple Example
   + Alignment Commands
   + Insertion Commands

If a user clicks on the + Alignment Commands line the result will be:

-  Simple Example
   - Alignment Commands
       align left
       align right
       center
       justify
   + Insertion Commands

Suppose we change the first line of the description file from

TES.+...Simple Example

TES.-...Simple Example

replacing the + in column 5 with a -. Now, instead of initially displaying the single line

+  Simple Example

the following will be displayed:

-  Simple Example
   + Alignment Commands
   + Insertion Commands

The `&&_` annotation

Suppose you have the following two rules in your grammar file:

<color-command> = set the color to <colors> .
<colors> = red | orange | yellow | green | blue |
           indigo  | violet .

You may want the What Can I Say window to display the phrases allowed by these rules as follows:

- Example

   set the color to red
   set the color to orange
   set the color to yellow
   set the color to green
   set the color to blue
   set the color to indigo
   set the color to violet

However, there is another way of presenting this information, which may be more helpful to the users of your grammar. A single line might be displayed as in

- Example

  + set the color to colorname

A user can click on this line to expand it to:

  - set the color to colorname
    Possible values of colorname are
       red
       orange
       yellow
       green
       blue
       indigo
       violet

This format can easily be define in the What Can I say description file by using the &&_ annotation. The format of this annotation is

   &&_variable-name.annotation-name_&&

where annotation-name is the string that will be displayed to the user and variable-name is the name of a description sequence that occurs at the end of the What Can I Say description file. For example, the following description file generates the above example:

TES.-...Example
XES.+...set the color to &&_colorlist.colorname_&&
D.......colorlist
XES.....Possible values of colorname are
XES...C.   red
XES...C.   orange
XES...C.   yellow
XES...C.   blue
XES...C.   indigo
XES...C.   violet

The &&_Extern_counts._&& annotation

This annotation is a special case of the &&_ annotation mentioned above. It is typically used to describe phrases generated by a grammar that contains the line EXTERN <Extern_counts>. This annotation does not require a description sequence and it is used as follows.

TES.-...Example
XES.+...move up &&_Extern_counts.<count>_&& lines

The resulting What Can I Say display will be

- Example
  + move up <count> lines

When a user click on the + move up <count> lines line the following display will result:

- Example
  - move up <count> lines
    Count values
      one
      two
      three
      four
      five
      six
      seven
      eight
      nine
      ten
      eleven
      twelve
      thirteen
      fourteen
      fifteen
      sixteen
      seventeen
      eighteen
      nineteen
      twenty
      thirty
      forty
      fifty