Improved natural language voice commands using keywords

The point is to create better “natural language” commands, so you don’t interrupt your workflow when writing or editing. You’ll be surprised how much your wording may vary when you give a voice command in real time.

Suppose we want to act on a more general command where we say something like the following:

In today’s script, we’re not worried about the details of the Word macro that carries out this command. We’re trying to interpret a text version of the voice command and select the correct Word macro to run.

New command information

This new example command provides four pieces of information.

• The static part of the command “Select …” which indicates something should be selected.
• We want to select a “paragraph” document element as we did with the baby script above.
• The first bit of new information we need to interpret is an implied direction with “next”.
• The number of paragraphs was specified as “three”.

Fortunately, we’ve previously created several functions to facilitate the last three items (see Getting started section at the top).

The versus That

Our previous example command used “that” as the second word, but it is also quite natural to say “Select the …” as is done here. We need to allow these simple variations.

Which list variable

To solve this problem without creating duplicate commands, we can create a new list variable to allow any of several convenient articles or prepositions. I called my list variable <which> which contains words like:

the

those

these

that

by

to the

by the

of the

and several more variations. Each word or phrase should be placed on a separate line. We also don’t need to restrict ourselves to individual words as shown by “to the” and below. Some variations like “of the” apply more when the list variable is used later in a command (see earlier example commands).

List variables are nice but a little bit of a mixed bag in my opinion. They extend the utility of custom scripts without having to create redundant versions, but they are a little awkward to manage. See this previous article for more about using list variables in Dragon Professional advanced scripting.

Revised command name

The new custom voice command name is:

In the command editor, we literally type this as the voice command name.

The static part of the voice command must be stated exactly to run the script. Dragon will automatically detect any of these <which> variations as the next word(s) in the command. Then anything after that is stored as the <dictation> text.

Revised command phrase assignment

We previously stored the <dictation> command text in the sPhrase variable in order to parse it for the relevant information. One small change to the above baby script is <dictation> is now the second list variable. We need to revise the command phrase assignment to reference element (1) of the context values.

Remember the list variable context values are indexed starting from zero which is common in programming, so (1) is the second list variable. We do not care about which word was used for the <which> list variable. It’s just present to allow the natural variations at that position in the command.

We don’t get everything we want since we must state something at that position. We can’t omit a word in the command unless it falls within the <dictation> variable text.

Get document element with a function

As with the above baby script, we get the document element using the GetPhraseElement function from a previous article. We “pass” the function our command text sPhrase and store the result of the function in the sElement variable.

We decline to specify a default element type as a second argument since the document element is a required part of the command if we are to properly interpret the instruction.

Get the direction with a function

We also previously introduced a GetPhraseDirection function to automatically parse a stated or implied direction from the text version of the voice command. We’ll pass the function our command phrase and store the result in a String variable named sDirection.

The function normally returns “forward”, “backward”, or a default empty string “” if no direction was found in the command. We overrode the default value for clarity using the second function argument “forward”. It’s not strictly required, but we probably need at least an implied direction. Using forward as a default value makes sense in this script.

Get the stated number with a function

We previously introduced another function GetPhraseNumber to parse a stated number from a text command. We’ll store the result in a number variable named nElements.

We define nElements as a Long value (basically a bigger Integer or “counting number” in VBA) corresponding to the number type returned by the function.

We pass the command phrase to the function and store the value in the nElements variable.

If no number is stated or implied, the default value is zero. Any stated number is assumed to be positive in the function, but we’ll account for the direction next.

Account for direction with the number of elements

In Word VBA, backward in the document almost always corresponds to negative values and forward to positive in various VBA commands. This makes more sense when we remember the document grows (more characters) as we add content.

The sign of the above nElements number needs to be adjusted based on the direction specified in the document. If the user indicates forward direction in the document, our nElements variable is already positive, so we do nothing. On the other hand, if the user indicates a backward direction, we make nElements negative.

We’ve already identified the direction and stored the result in the sDirection variable. Since we assigned one of two possible text values to sDirection, “forward” or “backward”, we can check for a match directly without using a search comparison such as Like.

Using -nElements is the same thing as multiplying by -1. If no direction was given, then nElements is zero from the GetPhraseNumber function. “Negative zero” is still zero, so nothing happens if so.

Since the command is so short, we can shorten it into one brief line:

I tend to prefer this more concise notation when it’s clear.

Command keyword summary

Let’s collect the four keyword assignments based on the respective functions.

Based on keywords, we’ve parsed the command for a mentioned document element, any direction, a possible document location, and a stated number. These keywords account for many voice command variations without binding us to any specific command phrasings.

These short four steps do so much while also being easy to understand. They’re even more convenient when we reuse them in other scripts without having to reinvent the wheel every time.

Selecting the correct macro to run

There are several ways to select the correct Word macro to run. Assuming the command category is obvious (move, select, copy, etc.), we have three main pieces of information: the direction, a possible location, and how many elements (paragraphs, sentences, etc.) to select.

Messy macro selection … (not used)

The baby script above only considered the document element, which was stored in the sElement variable, to pick the correct Word macro to run. Our extended version is a little more complicated since the command might restrict the selection to a specified direction or only to the “start” or “end” of the stated document element. The command may further specify a number of elements.

Uhhh … where are you—

Hey! Get back here.

It’s not as bad as it sounds. Plus, I’m just making a point here about why I’m using simpler macro selection process below.

Start with the location for macro selection

A logically simple approach is to nest the decisions. That is, decide one part and then decide the specific macro based on that branch. There are a few ways to structure it, so we’ll start with the location and work toward the other elements.

Some of my Word macros are targeted specifically toward the beginning or end of a document element (paragraph, heading, etc.). This corresponds to our location variable sLocation.

We can use a basic If statement with the location whether it's the "start", "end", or anything else (usually an empty string ""). Our conditions look like:

These are intended to be True-False (Boolean) conditions as they’re used below. That is, does the plain text stored in sLocation exactly match “start” or “end”? It would be preferable if these two conditions didn’t read exactly like a variable assignment (store the text value “start” in the variable sLocation) even in isolation. Some languages instead use a double equals sign == for comparisons, but VBA distinguishes them by context. It's not the clearest approach, but we’re stuck with it.

We construct an If statement based on these two potential locations.

It’s not too bad so far. It’s no more complicated than what we’ve done in previous scripts or macros, but it gets messy quick.

Include the document element in the macro selection

Our previous decision based a macro decision on the document element. It used a Select Case statement something like:

Unfortunately, the correct element macro to run will be different for each location. We need to insert a copy of this skeleton into each part of the above location If statement:

Ughhh … see what I’m saying.

I don’t even like looking at that mess much less trying to figure out what it’s doing. Perhaps in another macro this lengthy blob of VBA might be the best solution, but let’s find a better way to solve our current problem.

Flattened Case Selection

The above macro selection process would’ve worked, but it would have “nested” the conditional statements into a two-level decision tree. If that’s the only solution, okay, but it’s a little confusing and harder to follow than just a sequential list of cases.

We can make it easier to read if we create our own little concise baby command using the various keywords we’ve identified above. Then we use that constructed command to choose the correct Word macro with a simple, albeit longer, "flattened" Select Case statement.

Command variable

We first create a plain text variable called sCommand to store our abbreviated command.

Create the simple abbreviated command

The main information to construct our command is the stated document element followed by the location, if available. The easiest thing to do is to just start the command with the identified element.

Now we check whether the location exists and add it to the command. If sLocation is not an empty string “” (the default value returned from the GetPhraseLocation function), then we add the location to the command.

Remember <> is the not equal symbol in VBA (literally less than or greater than). This symbol along with the equals = sign are used mostly with number comparisons, but they also work for exact text comparisons.

Alternative approach (just use one)

If you don’t like using not equals <> to compare text strings, then you could just test for the value of sLocation. Notice “start” and “end” both have the same command structure. That is, either could be True, and we add the document element and the location variables. That corresponds to an Or compound conditional statement.

Only when sLocation is empty does the command change. Thus, we can construct an alternative abbreviated command assignment. Putting it into a conditional statement, we have:

But only use one of them. I prefer the former because it is more concise, but not everybody likes mint chocolate chip ice cream (yum) either.

Note also we could not just always add them. If no location is given, sLocation would be an empty string "" which would add nothing. That seems okay at first glance, but then our command phrase might be something like "paragraph ". The extra space at the end would not be an exact match for "paragraph" as listed in the Select Case statement below.

Leave out direction and number from abbreviated command

We don’t include number variable nElements or the direction variable sDirection in the above abbreviated command because we’ve already accounted for the effect of the direction by changing the sign of nElements when it’s used. Specifically, negative values of nElements correspond to backward selections, and positive values are forward in the document.

Example abbreviated commands

Suppose our document element is a paragraph. This will create three possible abbreviated commands:

Of course, we have variations for sentences, headings, etc. as desired.

Since we’ve set the sElement and sLocation variable values to specific values, we know what any valid abbreviated commands must look like. This allows us to construct a simpler decision tree below that is flat and easier to read than the nested version above.

This isn’t the only solution to the problem. It’s just clean and relatively easy to understand even if it takes a few extra steps to set up.

Parsed command examples

We also have more variations for sentences, words, and headings. Let’s practice a few examples to be clear.

Example 1

What if we stated the following voice command?

The variable sCommand would store the value “heading end”, and nElements would have a value of zero because no number was mentioned.

I’m not assigning these values here. I’m just illustrating what the values would be based on all the above steps.

A direction is implied with “end” in the voice command, but the selection macro handles that detail, and changing the sign of a zero in nElements would not matter.

Example 2

What about this command?

The command values are:

Here “word” is clearly mentioned, and the stated number 5 is negative because “previous” was given which is backward in the document.

Example 3

Another one:

The command values are:

Here paragraph is clearly stated, but no number was given so nElements defaults to zero.

Selecting the Word macro

We’ve constructed our command, so now we’ll use a Select Case statement to pick the appropriate Word macro to run. A Select Case statement is better than an If statement here because there are about a dozen options depending on which document elements you include. The code will still be long, but a Select Case statement allows us to organize them more clearly.

Select to Start of End of the current paragraph

For the start and end of the paragraph, we’ll assume we have a simple macro call to make.

These use the previously presented function RunWordMacro, or see the earlier section for brief explanation. We’re not covering the details of any Word macros mentioned in this article.

We needed to include “Call” because we’re providing (called “passing”) and argument to the macro. The returned function result (a Boolean value indicating whether the function ran successfully) is ignored since we don’t store it in a variable.

Select current paragraphs

The SelectParagraphs macro has a parameter to indicate the number of paragraphs to select. We previously stored that value in the nElements variable, so we add that as a second argument inside the RunWordMacro parentheses.

If you have more complicated macros with more parameters, we’ll cover that function in upcoming articles. It’s a little more complicated.

A similar set of macros are needed for the other options with sentences, headings, etc.

Skeleton to select a macro based on the abbreviated command

We chose the Case based on our constructed abbreviated sCommand.

Selecting correct Word macro to run using the abbreviated command

Now insert out possible constructed commands as cases:

We can add cases for “sentence”, “sentence start”, and “sentence end” as well as those for heading, words, etc. as desired. It stretches out, but the overall macro keeps our collection of voice commands relatively easy to read. The point was to flatten the Select Case statement into one level rather than it being nested two levels.

Gotchas

What could go wrong?

Command conflicts?

With more command variations, there are more chances for command conflicts where the same voice command inadvertently refers to two different scripts. For example, I had a command that overlapped one of the default Dragon Professional natural language commands. It took me a while to realize Dragon was preferring its own native command over mine.

Arghhh.

I wish Dragon had a way to toggle individual commands to active or inactive, but I eventually disabled Dragon’s natural language commands entirely since I was writing my own (I like controlling the details).

As far as I can tell, Dragon Professional handles command conflicts well enough (except for the blip above), so it’s not a big deal, but it is something to keep in mind as you expand your command library. Having no conflicts is better than relying on Dragon to pick your intended command.

Number pronouns

The number “one” sometimes counts as a pronoun such as:

Three is the intended number of paragraphs, but one is a pronoun referring to the current paragraph. Our current number function would not distinguish between “three” and “one” in this phrase. It's not the biggest problem in the world, but a partial solution will be covered in upcoming articles.

Function results?

Some of the internal logic in the above script assumes specific standard values (such as “forward” or “backward” or “start” or “end”) or specific default values (such as 0 or an empty string “”) as the only possible results. The final script below doesn’t check for or validate every possible result before making decisions about which Word macro to run. This keeps this script smaller, but it does push us to make sure the possible function results and the script expectations are in sync. We guard ourselves against some mistakes by only running a macro when very specific abbreviated commands are detected.

A side lesson here is we should be clear and specific when we write functions. Clear input and output should also be explained in dedicated comments, so we can buttress our other scripts and macros against problems.

Final Keyword Command Script Using Like

The final script looks messier than it is logically. In this version, we use the above functions to parse the command phrase for specific information. Recall the main subroutine in a Dragon custom script is literally called Main.

The Getting started section at the top links to the functions used to parse the keywords. Breaking the script down into smaller pieces makes it more manageable and readable. The Word macros would be created separately, and this blog has several examples of such macros at different levels of difficulty.

Is it safe?

I get it. You don’t want something bad happen to your novel text. That sends shivers of fear through an author.

This final script is basically safe because the Select Case statement combined with the abbreviated commands only run a Word macro if one of the specific constructed commands is detected. Of course, this script does not guarantee the Word macro is correct.

What do we gain?

Exact wording is quite flexible

The nice thing about baking our own natural language command is just how flexible the phrasing can be starting from the <dictation> list variable.

We don’t have to worry about exact placements of the the’s, that’s, to’s, etc. except for the word immediately after “Select …” (that position is occupied by a list variable <which>, so it is required). Omitted words and even some word mangling will all work provided the proper keywords are present.

Other commands?

This script can easily be duplicated and modified to work for cutting, deleting, or copying the same document elements. You just need corresponding macros to exist in Word. Change the static part of the command to “Copy <which> …” for whichever variation you wish. Then make the trivial macro name changes in the Select Case statement of the script.

Controlling the details

I mentioned this at the top, but one of the best features in my opinion is we can control all the details of each respective task by using our own Word macros. We don’t need to rely on Dragon’s implementation of a natural language voice command.

Condensed voice commands

We could just create variations of the same macro for each phrase type, but this approach condenses the script variations into a smaller number of custom voice commands. This seems like “no big deal,” but your custom command list will grow faster than you think, and near-duplicate commands are annoying to keep up to date if you ever make changes.

Comments comment

I stretch the script with lots of comments because I like being extra clear. (Yes, I really do this in my own scripts and macros also but maybe not quite as many.) I try to include relevant information that might be important if I come back to the macro after months or more. Comments are more important for more obscure script steps, but I still recommend them for any significant step or related group of steps. The temptation exists to skip adding comments while you’re working on a script, but you will save yourself time in the long run if you or someone else ever returns to the macro or script.

One script to rule them all (natural language commands)?

Is this keyword approach the solution to all voice command problems?

No.

It’s just one attempt that is relatively easy to understand but also generalizes several voice command possibilities. I understand some may prefer dedicated commands for each type of document element, but as your list of voice commands grows, the consolidation is a nice side effect.

The above solution allows many more naturally stated command variations. We don’t have to worry as much about exact phrasing. Of course, this comes with a few issues, but it’s a win overall for improved natural language processing with less up front effort.