# 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

to

    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

[ Top of Page | Previous Page | Next Page | Back to Grammar Guide ]